auto-model-router 0.2.21 → 0.2.22

package/.claude/skills/agentdox/SKILL.md

@@ -180,12 +180,29 @@ while memory, docs, or the brief for the area you touched is stale.
 | Architecture / conventions | `docs_update {id, content}` | `PATCH /docs/:id {title?, content?, tags?}` |
 | A genuinely new doc | `docs_write {slug, title, content, scope}` | `POST /docs {slug, title, content, scope}` |
 | List / read docs | `docs_read` · `docs_search` | `GET /docs?scope=<scope>` · `GET /docs/search?q=…` · `GET /docs/slug/:slug` |
+| Find the *part* of a doc that answers something | `docs_passages` | `GET /docs/passages?q=…&scope=<scope>` |
 | A decision you made | `context_brief_record {scope, title, decision, rationale}` | `POST /context/brief/decision {scope, title, decision, rationale}` |
 | Edit brief sections | — | `PUT /context/brief {scope, overview?, repoLayout?, codeStyle?, buildTest?, assetConventions?, gotchas?}` |
 
 **Search before you add.** Update the existing entry rather than leaving two contradictory
 facts. Record the *why* of a decision, not just the *what*.
 
+## Searching well
+
+Retrieval is hybrid — keyword *and* meaning — so you do not have to guess the stored wording.
+Ask in your own words; exact identifiers (`SettlementLayout.Build`, `AGENTDOX_TOKEN`) work too.
+
+**Prefer `docs_passages` over `docs_search`** when you want the part of a doc that answers a
+question. `docs_search` hands back whole documents, which then get truncated — and the
+truncation is rarely the relevant part. A passage arrives with its slug and heading, so
+`docs_read` the full doc when the passage is not enough.
+
+If results look thin or stale, check `index_stats {scope}` before concluding the store is
+empty: it reports how much of the scope is indexed and whether the embedding provider is
+reachable. `embedded` far below `total`, or an unreachable provider, means you are getting
+keyword-only results. `index_rebuild` fixes an index that has drifted; ordinary writes index
+themselves, so you should rarely need it.
+
 ## Two inconsistencies that cause silent mistakes
 
 1. **Memory uses `category`; everything else uses `scope`.** `memory_add` / `memory_search` /

package/CLAUDE.md

@@ -28,6 +28,18 @@ another project. Getting `omp-router` right is on you, not on RBAC.
 | Server | `http://localhost:3003` — Docker container `agentdox-server` |
 | Admin token (to re-mint the global PAT) | `E:/projects/agentdox/deploy/.env` |
 
+**Searching agentdox.** Retrieval is hybrid — BM25 keyword matching fused with embeddings — and
+runs over *passages* of docs, not whole files. So ask in your own words; exact identifiers work
+too. Two habits worth having:
+
+- **Prefer `docs_passages` over `docs_search`.** It returns the section that answers the
+  question. `docs_search` returns whole documents, which then get truncated, and the truncation
+  is rarely the relevant part.
+- **If results look thin, run `index_stats {scope}` before concluding the store is empty.** It
+  reports how much of the scope is indexed and whether the embedding provider is reachable;
+  `embedded` far below `total`, or an unreachable provider, means you are getting keyword-only
+  results.
+
 `.env.agentdox` is the durable record; the environment variable is what Claude Code actually
 substitutes into `.mcp.json` at MCP-server startup. If agentdox MCP returns **401**, the
 variable is missing from the environment — re-set it from `.env.agentdox` and restart Claude

package/docs/context-optimization.md

@@ -130,14 +130,14 @@ request → classify (on ORIGINAL turn)
   valid — the same reason `injectContextBlock` appends instead of inserts. Phase 2,
   which changes message count, MUST return adjusted indices (see Phase 2).
 
-## Trigger (locked: fit + cost budget)
+## Trigger (locked: fit + cost budget), and plan hysteresis
 
-Two conditions arm compaction; both compact to the same safe floor, they differ only
-in *whether* to bother:
+Two conditions arm compaction; they differ only in *whether* to bother:
 
-- **Budget:** `estimateTokens(promptBytes + injectedBlockBytes) > compaction.budgetTokens`.
-  The injected agentdox block counts toward the budget (it is resolved before render
-  and bounded by `context.maxBlockChars`).
+- **Budget:** the **compacted** estimate — i.e. the prompt as it would be dispatched
+  with the plan already carried from the previous turn — exceeds
+  `compaction.budgetTokens`. The injected agentdox block counts toward the budget (it
+  is resolved before render and bounded by `context.maxBlockChars`).
 - **Fit:** the estimate exceeds `model.contextLength × filters.contextHeadroom` (minus
   expected completion) for a model under consideration — so the `context_too_small`
   filter tests each model against the compacted floor rather than the raw size.
@@ -145,6 +145,32 @@ in *whether* to bother:
 Requests below `budgetTokens` and within every viable window are dispatched untouched —
 the common small-prompt path allocates nothing.
 
+### The plan is state, not a per-turn derivation
+
+A prompt cache is a **byte-prefix** cache: change any byte and everything after it is
+a miss. That makes the compaction plan cache-visible state, subject to two rules.
+
+1. **A dispatched edit is permanent and verbatim.** `ConversationState.compactionPlan`
+   persists the plan (schema v13, `conversations.compaction_plan`); `select()` re-emits
+   it every turn and the planner is *seeded* with it (`planCompaction(..., carried)`),
+   so an existing edit is never re-derived into a different shape and never dropped
+   when the turn alone would not have triggered compaction. `validatePlan` first checks
+   each edit still lands on a tool message of the recorded byte length, so a
+   client-side history rewrite invalidates the edit instead of corrupting the prompt.
+   Re-applying is safe because omp re-sends the original bytes every turn.
+2. **Re-planning is rationed.** The trigger compares the **compacted** size against the
+   budget, and when it fires the planner targets `budgetTokens × compaction.floorRatio`
+   rather than stopping just under the budget. Comparing the *raw* size re-planned every
+   single turn, so the plan gained one more edit per turn — a cache invalidation per turn
+   for a marginal saving.
+
+Measured (`tools/verify-plan-persist.ts`, 20-turn agentic conversation): `floorRatio`
+1.0 changes the plan on **10 of 10** compacting turns, 0.75 on **3**, 0.6 on **2**. On
+live ledger data (7 long conversations, 894 compacted dispatches) a changed-plan
+dispatch ran **15.4% cold** vs **8.9%** when the plan held, and a cold prompt costs
+**4.34x** a warm one per token ($0.1839 vs $0.0424 per Mtok). `floorRatio` ships at 1
+(today's behaviour, elision is never implicit); 0.75 is the recommended setting.
+
 ## Interaction with the agentdox bridge
 
 The router already has a shipped context subsystem (`src/context/`, see

package/package.json

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

package/src/config/defaults.ts

@@ -193,6 +193,20 @@ export const DEFAULT_CONFIG: RouterConfig = {
 		enabled: false,
 		// ~40k tokens: above this the prompt is dominated by re-sent tool output.
 		budgetTokens: 40_000,
+		// Once compaction fires, compact down to this fraction of the budget
+		// instead of stopping just under it. Below 1 the plan overshoots and then
+		// holds for several turns; at 1 it gains an edit almost every turn, and
+		// every plan change rewrites already-cached prompt bytes.
+		//
+		// Measured (tools/verify-plan-persist.ts, 20-turn agentic conversation):
+		// 1.0 changes the plan on 10 of 10 compacting turns, 0.75 on 3, 0.6 on 2.
+		// Live ledger: a changed-plan dispatch runs 15.4% cold vs 8.9% when the
+		// plan holds, and a cold prompt costs 4.34x a warm one per token.
+		//
+		// Ships at 1 because elision is lossy and compaction is never implicit
+		// here — the same reason `enabled` is false. 0.75 is the recommended
+		// setting once a deployment has watched its own ledger.
+		floorRatio: 1,
 		fitToWindow: true,
 		protectRecentTurns: 4,
 		maxToolResultBytes: 4_096,

package/src/config/schema.ts

@@ -151,6 +151,7 @@ const context = z.strictObject({
 const compaction = z.strictObject({
 	enabled: z.boolean().optional(),
 	budgetTokens: z.number().int().positive().optional(),
+	floorRatio: z.number().positive().max(1).optional(),
 	fitToWindow: z.boolean().optional(),
 	protectRecentTurns: z.number().int().positive().optional(),
 	maxToolResultBytes: z.number().int().positive().optional(),

package/src/config/types.ts

@@ -432,6 +432,13 @@ export interface CompactionConfig {
 	enabled: boolean;
 	/** Compact when the estimated prompt exceeds this many tokens. */
 	budgetTokens: number;
+	/**
+	 * Target fraction of `budgetTokens` to compact DOWN to once compaction
+	 * fires. Below 1 the plan overshoots, so it stays byte-stable for several
+	 * turns instead of gaining an edit per turn; every plan change rewrites
+	 * already-cached prompt bytes, and a cold prompt costs ~4.3x a warm one.
+	 */
+	floorRatio: number;
 	/** Also compact when the prompt would overflow the profile's context window. */
 	fitToWindow: boolean;
 	/** Never touch the last N user/assistant turns or the volatile tail. */

package/src/router/compaction.ts

@@ -37,6 +37,27 @@ export function compactedBytes(originalBytes: number, edit: CompactionEdit | und
 	return Math.min(originalBytes, kept);
 }
 
+/**
+ * Validates a persisted compaction plan against this turn's messages before it
+ * is re-applied. Every edit must land on a tool-role message whose string
+ * content still has the original byte length the edit was planned against.
+ * A failed check means the client rewrote or truncated its history — the edit
+ * is dropped rather than applied to the wrong bytes.
+ */
+export function validatePlan(
+	plan: readonly CompactionEdit[],
+	messages: readonly NormMessage[],
+): CompactionEdit[] {
+	const valid: CompactionEdit[] = [];
+	for (const e of plan) {
+		const m = messages[e.index];
+		if (m === undefined || m.role !== "tool") continue;
+		if (m.textBytes !== e.bytes) continue;
+		valid.push(e);
+	}
+	return valid;
+}
+
 /**
  * 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
@@ -81,6 +102,16 @@ interface ToolResult {
 	key: string | null;
 }
 
+/**
+ * Result for a turn that adds nothing: the carried plan alone, with its
+ * savings recomputed against this turn's messages.
+ */
+function carriedOnly(carried: readonly CompactionEdit[]): CompactionResult {
+	const edits = [...carried].sort((a, b) => a.index - b.index);
+	const savedBytes = edits.reduce((sum, e) => sum + (e.bytes - compactedBytes(e.bytes, e)), 0);
+	return { edits, savedBytes };
+}
+
 /**
  * Plans compaction for a turn's messages toward `targetBytes` of total prompt.
  * Duplicate and superseded elisions (pure stale-data wins) are always applied;
@@ -96,17 +127,27 @@ interface ToolResult {
  * 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).
+ *
+ * `carried` is the plan already applied to this conversation on a previous
+ * dispatch (validated by `validatePlan`). It is re-emitted verbatim and its
+ * savings count toward the target, so an existing edit is never re-derived
+ * differently and the planner only ever ADDS. Re-applying it costs nothing:
+ * the client re-sends the original bytes every turn, so the same edit produces
+ * the same output.
  */
 export function planCompaction(
 	messages: readonly NormMessage[],
 	cfg: CompactionConfig,
 	targetBytes: number,
 	promptBytes: number,
+	carried: readonly CompactionEdit[] = [],
 ): CompactionResult {
 	if (!cfg.enabled) return EMPTY;
 
 	const protectStart = protectFromIndex(messages, cfg.protectRecentTurns);
-	if (protectStart <= 0) return EMPTY;
+	// Carried edits still apply even when nothing new is eligible this turn:
+	// dropping them would re-inflate bytes the upstream has already cached.
+	if (protectStart <= 0) return carriedOnly(carried);
 
 	// Assistant tool_call id → name/args, to key tool results by their call.
 	const callById = new Map<string, { name: string; args: string }>();
@@ -128,16 +169,19 @@ export function planCompaction(
 			key: call === undefined ? null : primaryArg(call.args),
 		});
 	}
-	if (tools.length === 0) return EMPTY;
-
-	const edits: CompactionEdit[] = [];
-	const done = new Set<number>();
-	let saved = 0;
+	if (tools.length === 0) return carriedOnly(carried);
+
+	// Seed with the carried plan: those indices are settled, and their savings
+	// already count against the target, so the target math asks "how much MORE
+	// is needed" rather than re-deriving the whole plan.
+	const edits: CompactionEdit[] = [...carried];
+	const done = new Set<number>(carried.map((e) => e.index));
+	let saved = carried.reduce((sum, e) => sum + (e.bytes - compactedBytes(e.bytes, e)), 0);
 	const stub = (t: ToolResult, note: string): void => {
 		if (done.has(t.index)) return;
 		const gain = t.bytes - BREADCRUMB_BYTES;
 		if (gain <= 0) return; // already smaller than a breadcrumb
-		edits.push({ index: t.index, mode: "stub", keepHead: 0, keepTail: 0, note });
+		edits.push({ index: t.index, mode: "stub", keepHead: 0, keepTail: 0, note, bytes: t.bytes });
 		done.add(t.index);
 		saved += gain;
 	};
@@ -172,7 +216,7 @@ export function planCompaction(
 	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` });
+		edits.push({ index: t.index, mode: "truncate", keepHead: cfg.keepHeadBytes, keepTail: cfg.keepTailBytes, note: `large ${t.name || "tool"} result`, bytes: t.bytes });
 		done.add(t.index);
 		saved += t.bytes - keepBudget;
 	}

package/src/router/select.ts

@@ -12,7 +12,7 @@ import { priceAt } from "../cost/forecast.ts";
 import type { Ledger } from "../cost/types.ts";
 import { explorationDraw } from "./explore.ts";
 import type { CompactionEdit, NormRequest, ReasoningLevel } from "../wire/types.ts";
-import { planCompaction } from "./compaction.ts";
+import { compactedBytes, planCompaction, validatePlan, type CompactionResult } from "./compaction.ts";
 import { planCacheBreakpoints } from "./cache-control.ts";
 import { buildCandidates } from "./candidates.ts";
 import {
@@ -153,28 +153,54 @@ export function select(args: SelectArgs): Decision {
 	//     Deterministic and content-only (never removes a message), so downstream
 	//     forecasting, the context_too_small filter, cache breakpoints, and the
 	//     agentdox block append all operate on the compacted size / stay valid.
+	//
+	//     Two properties make this cache-safe, and both are load-bearing:
+	//
+	//     1. The plan is PERSISTED per conversation and re-applied verbatim. omp
+	//        re-sends the original bytes every turn, so a re-applied edit yields
+	//        byte-identical output; a plan re-derived from scratch could differ
+	//        (a looser target, a re-tuned knob) and rewrite already-cached bytes.
+	//     2. Compaction is triggered on the COMPACTED size and then overshoots
+	//        to `floorRatio` of the budget. Comparing the RAW prompt against the
+	//        budget re-planned on every single turn, so the plan gained one more
+	//        edit per turn — and each plan change rewrites cached prompt bytes.
+	//        Measured on live ledger data (7 long conversations, 894 compacted
+	//        dispatches): a turn whose plan changed ran 15.4% cold vs 8.9% when
+	//        the plan held, and a cold prompt costs 4.34x a warm one per token.
+	//        Overshooting buys several byte-stable turns per plan change.
 	let compactionPlan: CompactionEdit[] = [];
 	let promptTokensSaved = 0;
 	let effFeatures = features;
 	if (cfg.compaction.enabled && req.promptBytes > 0 && features.promptTokens > 0) {
+		const bytesPerToken = req.promptBytes / features.promptTokens;
+		const carried = validatePlan(state.compactionPlan ?? [], req.messages);
+		const carriedSavedBytes = carried.reduce((sum, e) => sum + (e.bytes - compactedBytes(e.bytes, e)), 0);
+		const tokensOf = (savedBytes: number): number =>
+			Math.min(features.promptTokens - 1, Math.round(features.promptTokens * (savedBytes / req.promptBytes)));
+		// What the upstream would actually receive if nothing new were planned.
+		const compactedTokens = features.promptTokens - tokensOf(carriedSavedBytes);
+
 		const headroom = cfg.filters.contextHeadroom;
-		const overBudget = features.promptTokens > cfg.compaction.budgetTokens;
+		const overBudget = compactedTokens > cfg.compaction.budgetTokens;
 		const overWindow =
-			cfg.compaction.fitToWindow && features.promptTokens * headroom + EXPECTED_COMPLETION_TOKENS > profile.contextWindow;
+			cfg.compaction.fitToWindow && compactedTokens * headroom + EXPECTED_COMPLETION_TOKENS > profile.contextWindow;
+		let plan: CompactionResult = { edits: carried, savedBytes: carriedSavedBytes };
 		if (overBudget || overWindow) {
 			const targets: number[] = [];
-			if (overBudget) targets.push(cfg.compaction.budgetTokens);
+			// Overshoot the budget so the next re-plan is several turns away.
+			if (overBudget) targets.push(Math.max(1, Math.floor(cfg.compaction.budgetTokens * cfg.compaction.floorRatio)));
 			if (overWindow) targets.push(Math.max(1, Math.floor((profile.contextWindow - EXPECTED_COMPLETION_TOKENS) / headroom)));
-			const targetBytes = Math.min(...targets) * (req.promptBytes / features.promptTokens);
-			const plan = planCompaction(req.messages, cfg.compaction, targetBytes, req.promptBytes);
-			if (plan.edits.length > 0) {
-				compactionPlan = plan.edits;
-				promptTokensSaved = Math.min(features.promptTokens - 1, Math.round(features.promptTokens * (plan.savedBytes / req.promptBytes)));
-				effFeatures = { ...features, promptTokens: features.promptTokens - promptTokensSaved };
-				reasons.push(
-					`compaction: ${plan.edits.length} tool result(s) shrunk, ~${promptTokensSaved} tokens saved (prompt ${features.promptTokens}→${effFeatures.promptTokens})`,
-				);
-			}
+			const targetBytes = Math.min(...targets) * bytesPerToken;
+			plan = planCompaction(req.messages, cfg.compaction, targetBytes, req.promptBytes, carried);
+		}
+		if (plan.edits.length > 0) {
+			compactionPlan = [...plan.edits];
+			promptTokensSaved = tokensOf(plan.savedBytes);
+			effFeatures = { ...features, promptTokens: features.promptTokens - promptTokensSaved };
+			const added = plan.edits.length - carried.length;
+			reasons.push(
+				`compaction: ${plan.edits.length} tool result(s) shrunk (${carried.length} carried, ${added} new), ~${promptTokensSaved} tokens saved (prompt ${features.promptTokens}→${effFeatures.promptTokens})`,
+			);
 		}
 	}
 

package/src/router/state.ts

@@ -11,8 +11,10 @@
 
 import type { Database, Statement } from "bun:sqlite";
 
+import type { CompactionEdit } from "../wire/types.ts";
 import type { ConversationState, ConversationStore, Tier } from "./types.ts";
 
+
 /** Row shape as stored; column names are snake_case per the schema. */
 interface Row {
 	key: string;
@@ -28,6 +30,7 @@ interface Row {
 	cache_warm_at_ms: number;
 	context_version: string | null;
 	context_fetched_at_ms: number;
+	compaction_plan: string | null;
 	updated_at_ms: number;
 }
 
@@ -47,6 +50,7 @@ function toState(row: Row): ConversationState {
 		cacheWarmAtMs: row.cache_warm_at_ms,
 		contextVersion: row.context_version,
 		contextFetchedAtMs: row.context_fetched_at_ms,
+		compactionPlan: row.compaction_plan === null ? null : (JSON.parse(row.compaction_plan) as CompactionEdit[]),
 		updatedAtMs: row.updated_at_ms,
 	};
 }
@@ -65,10 +69,10 @@ export function createConversationStore(db: Database): ConversationStore {
 		INSERT INTO conversations (
 			key, session_id, turn, current_slug, current_tier, sticky_until_turn,
 			last_prompt_tokens, cache_warm_slug, cache_warm_at_ms,
-			context_version, context_fetched_at_ms, updated_at_ms
+			context_version, context_fetched_at_ms, compaction_plan, updated_at_ms
 		) VALUES ($key, $sessionId, $turn, $currentSlug, $currentTier, $stickyUntilTurn,
 			$lastPromptTokens, $cacheWarmSlug, $cacheWarmAtMs,
-			$contextVersion, $contextFetchedAtMs, $updatedAtMs)
+			$contextVersion, $contextFetchedAtMs, $compactionPlan, $updatedAtMs)
 		ON CONFLICT(key) DO UPDATE SET
 			session_id = excluded.session_id,
 			turn = excluded.turn,
@@ -80,6 +84,7 @@ export function createConversationStore(db: Database): ConversationStore {
 			cache_warm_at_ms = excluded.cache_warm_at_ms,
 			context_version = excluded.context_version,
 			context_fetched_at_ms = excluded.context_fetched_at_ms,
+			compaction_plan = excluded.compaction_plan,
 			updated_at_ms = excluded.updated_at_ms
 	`);
 	// Read-modify-write in JS lost money: an aborted or failed dispatch is still
@@ -127,6 +132,7 @@ export function createConversationStore(db: Database): ConversationStore {
 				$currentTier: state.currentTier,
 				$stickyUntilTurn: state.stickyUntilTurn,
 				$lastPromptTokens: state.lastPromptTokens,
+				$compactionPlan: state.compactionPlan === null ? null : JSON.stringify(state.compactionPlan),
 				$cacheWarmSlug: state.cacheWarmSlug,
 				$cacheWarmAtMs: state.cacheWarmAtMs,
 				$contextVersion: state.contextVersion,

package/src/router/types.ts

@@ -170,6 +170,13 @@ export interface ConversationState {
 	 * cache survives; refreshed only when the cache is already cold.
 	 */
 	contextVersion: string | null;
+	/**
+	 * The compaction plan applied on the previous dispatch. Re-applied verbatim
+	 * each turn (after byte-length validation) so already-shrunk tool results
+	 * stay shrunk: dropping them re-inflates mid-prefix bytes, which both breaks
+	 * the prompt cache and un-saves the tokens. Fresh planning only extends it.
+	 */
+	compactionPlan: CompactionEdit[] | null;
 	/** When that block was fetched, for the staleness TTL. */
 	contextFetchedAtMs: number;
 	updatedAtMs: number;

package/src/server/turn.ts

@@ -457,6 +457,10 @@ export async function runTurn(
 		state.spentUsd += reportedUsd ?? decision.forecast.expectedUsd;
 		state.escalations += escalations;
 		state.lastPromptTokens = usage.promptTokens;
+		// Persist the plan that was actually dispatched. The next turn re-applies
+		// it verbatim (after byte-length validation), keeping shrunk tool results
+		// shrunk so the prompt cache survives and the savings compound.
+		state.compactionPlan = decision.compactionPlan.length > 0 ? decision.compactionPlan : null;
 		if (usage.cachedTokens > 0 || usage.cacheWriteTokens > 0) {
 			// Non-zero cache traffic is direct evidence the upstream cache exists.
 			state.cacheWarmSlug = servedSlug ?? decision.slug;

package/src/util/sqlite.ts

@@ -18,7 +18,7 @@ import { mkdirSync } from "node:fs";
 import { dirname } from "node:path";
 
 /** Bump when a migration is added; guarded below so reopening never regresses it. */
-const USER_VERSION = 12;
+const USER_VERSION = 13;
 
 const MIGRATIONS = `
 CREATE TABLE IF NOT EXISTS catalog_cache (
@@ -211,6 +211,14 @@ const MIGRATE_V12 = `
 ALTER TABLE ledger ADD COLUMN prompt_tokens_saved INTEGER;
 `;
 
+// v13: conversations persist the last compaction plan (JSON array of
+// CompactionEdit). Re-applying it verbatim each turn keeps already-shrunk tool
+// results shrunk — without it, protectRecentTurns drift drops edits and
+// re-inflates mid-prefix bytes, breaking the prompt cache for zero savings.
+const MIGRATE_V13 = `
+ALTER TABLE conversations ADD COLUMN compaction_plan TEXT;
+`;
+
 // v9: benchmark_cache holds the external benchmark feeds (Artificial Analysis,
 // BenchLM) that backfill quality scores OpenRouter leaves unpublished. It is a
 // whole new table, created idempotently by the MIGRATIONS block above, so there
@@ -242,9 +250,10 @@ export function openDb(path: string): Database {
 		if (!ledgerCols.some((c) => c.name === "features")) db.exec(MIGRATE_V6);
 		if (!ledgerCols.some((c) => c.name === "explored_from")) db.exec(MIGRATE_V7);
 		if (!ledgerCols.some((c) => c.name === "hold_arm")) db.exec(MIGRATE_V8);
+		if (!ledgerCols.some((c) => c.name === "prompt_tokens_saved")) db.exec(MIGRATE_V12);
 		const convCols = db.query("PRAGMA table_info(conversations)").all() as { name: string }[];
 		if (!convCols.some((c) => c.name === "context_version")) db.exec(MIGRATE_V11);
-		if (!ledgerCols.some((c) => c.name === "prompt_tokens_saved")) db.exec(MIGRATE_V12);
+		if (!convCols.some((c) => c.name === "compaction_plan")) db.exec(MIGRATE_V13);
 		db.exec(`PRAGMA user_version = ${USER_VERSION}`);
 	}
 	return db;

package/src/wire/types.ts

@@ -148,6 +148,14 @@ export interface CompactionEdit {
 	keepHead: number;
 	keepTail: number;
 	note: string;
+	/**
+	 * Original (pre-edit) byte length of the targeted message's string content,
+	 * captured when the edit was planned. Persisted with the plan so a later
+	 * turn can verify the history it is re-applying to is byte-identical before
+	 * re-applying — a client-side rewrite or an upstream difference invalidates
+	 * the edit instead of corrupting the prompt.
+	 */
+	bytes: number;
 }
 
 export type FinishReason = "stop" | "length" | "tool_calls" | "content_filter" | "error";

package/test/compaction.test.ts

@@ -1,13 +1,14 @@
 import { describe, expect, test } from "bun:test";
 
 import type { CompactionConfig } from "../src/config/types.ts";
-import { planCompaction } from "../src/router/compaction.ts";
+import { planCompaction, validatePlan } from "../src/router/compaction.ts";
 import { parseChatRequest } from "../src/wire/openai/request.ts";
 import type { NormMessage } from "../src/wire/types.ts";
 
 const CFG: CompactionConfig = {
 	enabled: true,
 	budgetTokens: 1,
+	floorRatio: 1,
 	fitToWindow: false,
 	protectRecentTurns: 2,
 	maxToolResultBytes: 50,
@@ -159,7 +160,7 @@ describe("renderUpstreamBody applies compaction", () => {
 			{ role: "tool", tool_call_id: "c1", content: "HEAD" + "x".repeat(500) + "TAIL" },
 		];
 		const req = parseChatRequest(bodyWith(raw), new Headers());
-		const out = req.renderUpstreamBody({ ...MUT, compactionPlan: [{ index: 2, mode: "truncate", keepHead: 4, keepTail: 4, note: "large read result" }] });
+		const out = req.renderUpstreamBody({ ...MUT, compactionPlan: [{ index: 2, mode: "truncate", keepHead: 4, keepTail: 4, note: "large read result", bytes: 508 }] });
 		const messages = out.messages as { role: string; content: unknown }[];
 		expect(messages).toHaveLength(3); // no message removed → pairing intact
 		const content = messages[2]?.content;
@@ -178,8 +179,93 @@ describe("renderUpstreamBody applies compaction", () => {
 			{ role: "tool", tool_call_id: "c1", content: "a".repeat(300) },
 		];
 		const req = parseChatRequest(bodyWith(raw), new Headers());
-		const out = req.renderUpstreamBody({ ...MUT, compactionPlan: [{ index: 2, mode: "stub", keepHead: 0, keepTail: 0, note: "identical repeated read result" }] });
+		const out = req.renderUpstreamBody({ ...MUT, compactionPlan: [{ index: 2, mode: "stub", keepHead: 0, keepTail: 0, note: "identical repeated read result", bytes: 300 }] });
 		const messages = out.messages as { content: string }[];
 		expect(messages[2]?.content).toBe("[omp-router: identical repeated read result elided to save context; re-run the tool to restore]");
 	});
 });
+
+describe("plan byte-stability across turns", () => {
+	// The prompt cache is a byte-prefix cache: changing any already-sent byte
+	// invalidates everything after it. So an edit, once dispatched, must be
+	// re-emitted identically on every later turn — which means the planner has
+	// to be told what it already did rather than re-deriving it.
+	test("edits carry their original byte length for persistence", () => {
+		const msgs = [user("go"), asst("c1", "read", '{"path":"a.ts"}'), toolMsg("c1", "read", big("A")), ...PAD];
+		const { edits } = planCompaction(msgs, CFG, 1, 10_000);
+		expect(edits).toHaveLength(1);
+		expect(edits[0]?.bytes).toBe(Buffer.byteLength(big("A")));
+	});
+
+	test("validatePlan keeps edits whose target is byte-identical and role-correct", () => {
+		const msgs = [user("go"), asst("c1", "read", '{"path":"a.ts"}'), toolMsg("c1", "read", big("A")), ...PAD];
+		const { edits } = planCompaction(msgs, CFG, 1, 10_000);
+		expect(validatePlan(edits, msgs)).toEqual(edits);
+	});
+
+	test("validatePlan drops edits when history changed under them", () => {
+		const msgs = [user("go"), asst("c1", "read", '{"path":"a.ts"}'), toolMsg("c1", "read", big("A")), ...PAD];
+		const { edits } = planCompaction(msgs, CFG, 1, 10_000);
+		// Client re-wrote history: the tool result is a different length now.
+		const rewritten = [user("go"), asst("c1", "read", '{"path":"a.ts"}'), toolMsg("c1", "read", "short"), ...PAD];
+		expect(validatePlan(edits, rewritten)).toEqual([]);
+	});
+
+	test("validatePlan drops edits that fall off the message array", () => {
+		const msgs = [user("go"), asst("c1", "read", '{"path":"a.ts"}'), toolMsg("c1", "read", big("A")), ...PAD];
+		const { edits } = planCompaction(msgs, CFG, 1, 10_000);
+		// Conversation compacted away client-side: index 2 no longer exists.
+		expect(validatePlan(edits, [user("go"), ...PAD.slice(1)])).toEqual([]);
+	});
+
+	test("a carried plan produces identical edits to a fresh plan over the same bytes", () => {
+		// Determinism contract: re-planning over unchanged bytes re-derives the
+		// persisted plan, so the merge in select.ts is a no-op, not a rewrite.
+		const msgs = [
+			user("go"),
+			asst("c1", "read", '{"path":"a.ts"}'),
+			toolMsg("c1", "read", big("A")),
+			asst("c2", "read", '{"path":"b.ts"}'),
+			toolMsg("c2", "read", big("B")),
+			...PAD,
+		];
+		const first = planCompaction(msgs, CFG, 1, 10_000);
+		const again = planCompaction(msgs, CFG, 1, 10_000);
+		expect(again.edits).toEqual(first.edits);
+	});
+
+	test("a carried edit is re-emitted verbatim even when nothing new is eligible", () => {
+		const msgs = [user("go"), asst("c1", "read", '{"path":"a.ts"}'), toolMsg("c1", "read", big("A")), ...PAD];
+		const carried = planCompaction(msgs, CFG, 1, 10_000).edits;
+		// Target already met, so a stateless planner would emit nothing at all.
+		const next = planCompaction(msgs, CFG, 1_000_000, 10_000, carried);
+		expect(next.edits).toEqual(carried);
+		expect(next.savedBytes).toBeGreaterThan(0);
+	});
+
+	test("carried savings count toward the target, so the planner only adds what is still needed", () => {
+		const msgs = [
+			user("go"),
+			asst("c1", "read", '{"path":"a.ts"}'),
+			toolMsg("c1", "read", big("A")),
+			asst("c2", "read", '{"path":"b.ts"}'),
+			toolMsg("c2", "read", big("B")),
+			...PAD,
+		];
+		const promptBytes = 10_000;
+		// Carry the first edit, then re-plan with a target the carried edit alone
+		// already satisfies: no second edit may be added.
+		const carried = [planCompaction(msgs, CFG, 1, promptBytes).edits[0]!];
+		const target = promptBytes - (carried[0]!.bytes - CFG.keepHeadBytes - CFG.keepTailBytes - 120);
+		const next = planCompaction(msgs, CFG, target, promptBytes, carried);
+		expect(next.edits.map((e) => e.index)).toEqual(carried.map((e) => e.index));
+	});
+
+	test("a carried edit is never re-planned into a different shape", () => {
+		const msgs = [user("go"), asst("c1", "read", '{"path":"a.ts"}'), toolMsg("c1", "read", big("A")), ...PAD];
+		// Carried as a stub; a fresh plan would have chosen truncate.
+		const carried = [{ index: 2, mode: "stub" as const, keepHead: 0, keepTail: 0, note: "carried", bytes: Buffer.byteLength(big("A")) }];
+		const next = planCompaction(msgs, CFG, 1, 10_000, carried);
+		expect(next.edits.filter((e) => e.index === 2)).toEqual(carried);
+	});
+});

package/test/exploration.test.ts

@@ -56,6 +56,7 @@ function state(over: Partial<ConversationState> = {}): ConversationState {
 		cacheWarmAtMs: 0,
 		contextVersion: null,
 		contextFetchedAtMs: 0,
+		compactionPlan: null,
 		updatedAtMs: NOW,
 		...over,
 	};

package/test/failover.test.ts

@@ -70,7 +70,7 @@ function mkConfig(escalation: Partial<EscalationConfig> = {}): RouterConfig {
 		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, 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 },
+		compaction: { enabled: false, budgetTokens: 40_000, floorRatio: 1, fitToWindow: true, protectRecentTurns: 4, maxToolResultBytes: 4_096, keepHeadBytes: 512, keepTailBytes: 512, elideSupersededReads: true, collapseDuplicateResults: true },
 		budget: { onExceeded: "downgrade" },
 		profiles: [],
 		ledger: { path: ":memory:", blendWindowDays: 7, blendMinSamples: 20, fallbackBlend: { inputPerMtok: 1, outputPerMtok: 4 }, conversationTtlMs: 86_400_000 },
@@ -267,6 +267,7 @@ function mkConversations(): { store: ConversationStore; map: Map<string, Convers
 				cacheWarmAtMs: 0,
 				contextVersion: null,
 				contextFetchedAtMs: 0,
+				compactionPlan: null,
 				updatedAtMs: 0,
 			};
 			map.set(k, fresh);

package/test/select.test.ts

@@ -66,6 +66,7 @@ function state(over: Partial<ConversationState> = {}): ConversationState {
 		cacheWarmAtMs: 0,
 		contextVersion: null,
 		contextFetchedAtMs: 0,
+		compactionPlan: null,
 		updatedAtMs: Date.now(),
 		...over,
 	};
@@ -601,6 +602,7 @@ describe("context compaction", () => {
 		compaction: {
 			enabled: true,
 			budgetTokens: 1_000,
+			floorRatio: 1,
 			fitToWindow: false,
 			protectRecentTurns: 1,
 			maxToolResultBytes: 100,
@@ -664,4 +666,80 @@ describe("context compaction", () => {
 		expect(d.compactionPlan).toEqual([]);
 		expect(d.promptTokensSaved).toBe(0);
 	});
+
+	test("a carried plan is re-applied even when the turn is now under budget", () => {
+		// The prompt cache is a byte-prefix cache: dropping an edit that was
+		// already dispatched rewrites history the upstream had cached, and
+		// re-sends the tokens the edit saved. So a carried plan survives a turn
+		// that would not have triggered compaction on its own.
+		const req = loopReq();
+		const over = extractFeatures(req, 5_000);
+		const first = select({
+			req,
+			features: over,
+			classification: scoreHeuristic(over, COMPACT_CFG),
+			profile: PROFILE,
+			state: state(),
+			snapshot: SNAPSHOT,
+			ledger: null,
+			cfg: COMPACT_CFG,
+			nowMs: Date.now(),
+		});
+		expect(first.compactionPlan.length).toBeGreaterThan(0);
+
+		const under = extractFeatures(req, 500); // under budgetTokens=1000
+		const second = select({
+			req,
+			features: under,
+			classification: scoreHeuristic(under, COMPACT_CFG),
+			profile: PROFILE,
+			state: state({ compactionPlan: first.compactionPlan }),
+			snapshot: SNAPSHOT,
+			ledger: null,
+			cfg: COMPACT_CFG,
+			nowMs: Date.now(),
+		});
+		expect(second.compactionPlan).toEqual(first.compactionPlan);
+		expect(second.promptTokensSaved).toBeGreaterThan(0);
+	});
+
+	test("floorRatio below 1 compacts strictly past the budget so the plan holds longer", () => {
+		// Each plan change rewrites cached prompt bytes, so compaction overshoots
+		// deliberately: eliding more now buys byte-stable turns later.
+		const req = parseChatRequest(
+			{
+				model: "auto",
+				tools: TOOLS,
+				messages: [
+					{ role: "system", content: "You are a coding agent." },
+					{ role: "user", content: "read the files" },
+					...[1, 2, 3, 4, 5, 6].flatMap((n) => [
+						{ role: "assistant", content: null, tool_calls: [{ id: `c${n}`, type: "function", function: { name: "read", arguments: `{"path":"f${n}.ts"}` } }] },
+						{ role: "tool", tool_call_id: `c${n}`, content: `F${n}${"x".repeat(2000)}` },
+					]),
+					{ role: "user", content: "continue" },
+				],
+			},
+			new Headers(),
+		);
+		// Prompt is ~12k bytes; claim 4000 tokens against a 1000-token budget, so
+		// floorRatio 1 targets 1000 and floorRatio 0.5 targets 500.
+		const features = extractFeatures(req, 4_000);
+		const run = (floorRatio: number) =>
+			select({
+				req,
+				features,
+				classification: scoreHeuristic(features, COMPACT_CFG),
+				profile: PROFILE,
+				state: state(),
+				snapshot: SNAPSHOT,
+				ledger: null,
+				cfg: { ...COMPACT_CFG, compaction: { ...COMPACT_CFG.compaction, floorRatio } },
+				nowMs: Date.now(),
+			});
+		const tight = run(0.5);
+		const loose = run(1);
+		expect(tight.compactionPlan.length).toBeGreaterThan(loose.compactionPlan.length);
+		expect(tight.promptTokensSaved).toBeGreaterThan(loose.promptTokensSaved);
+	});
 });

package/test/trust-attribution.test.ts

@@ -244,11 +244,11 @@ describe("v4 migration", () => {
 		}
 	});
 
-	test("schema is at user_version 12", () => {
+	test("schema is at user_version 13", () => {
 		const db = openDb(":memory:");
 		try {
 			const row = db.query("PRAGMA user_version").get() as { user_version: number };
-			expect(row.user_version).toBe(12);
+			expect(row.user_version).toBe(13);
 		} finally {
 			db.close();
 		}

package/test/turn.test.ts

@@ -71,7 +71,7 @@ function mkConfig(escalation: Partial<EscalationConfig> = {}): RouterConfig {
 		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, 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 },
+		compaction: { enabled: false, budgetTokens: 40_000, floorRatio: 1, fitToWindow: true, protectRecentTurns: 4, maxToolResultBytes: 4_096, keepHeadBytes: 512, keepTailBytes: 512, elideSupersededReads: true, collapseDuplicateResults: true },
 		budget: { onExceeded: "downgrade" },
 		profiles: [],
 		ledger: { path: ":memory:", blendWindowDays: 7, blendMinSamples: 20, fallbackBlend: { inputPerMtok: 1, outputPerMtok: 4 }, conversationTtlMs: 86_400_000 },
@@ -268,6 +268,7 @@ function mkConversations(): {
 				cacheWarmAtMs: 0,
 				contextVersion: null,
 				contextFetchedAtMs: 0,
+				compactionPlan: null,
 				updatedAtMs: 0,
 			};
 			map.set(k, fresh);

package/tools/verify-plan-persist.ts

@@ -0,0 +1,127 @@
+/**
+ * End-to-end verification of compaction plan stability.
+ *
+ * Two properties, both measured against a real router process over a growing
+ * agentic conversation:
+ *
+ *  1. STABILITY — an edit applied on one turn is re-applied byte-identically on
+ *     every later turn. Any change to already-sent bytes invalidates the
+ *     upstream prompt cache from that message onward.
+ *  2. CHURN — how many turns change the plan at all. Each change is a cache
+ *     invalidation; live ledger data puts a changed-plan turn at 15.4% cold vs
+ *     8.9% when the plan holds, and a cold prompt costs 4.34x a warm one per
+ *     token. `compaction.floorRatio` trades a little extra elision for far
+ *     fewer changes.
+ *
+ * Run: bun tools/verify-plan-persist.ts [floorRatio]
+ */
+import { mkdtempSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { loadConfig } from "../src/config/load.ts";
+import { startServer } from "../src/server/http.ts";
+import { startMockOpenRouter } from "./mock-openrouter.ts";
+
+const floorRatio = Number.parseFloat(process.argv[2] ?? "0.75");
+const home = mkdtempSync(join(tmpdir(), "verify-plan-persist-"));
+const mock = await startMockOpenRouter("test/fixtures/openrouter-models.json");
+
+const cfg = loadConfig({});
+cfg.server = { host: "127.0.0.1", port: 0 };
+cfg.openrouter.baseUrl = `${mock.url}/api/v1`;
+cfg.openrouter.apiKey = "sk-mock";
+cfg.ledger.path = join(home, "router.db");
+cfg.logLevel = "error";
+cfg.classifier.ambiguityThreshold = 0;
+cfg.benchmarks.enabled = false;
+cfg.context.enabled = false;
+// Scaled-down budget so the fixture behaves like a 40k-budget real conversation.
+cfg.compaction.enabled = true;
+cfg.compaction.budgetTokens = 1_500;
+cfg.compaction.floorRatio = floorRatio;
+cfg.compaction.maxToolResultBytes = 256;
+cfg.compaction.keepHeadBytes = 16;
+cfg.compaction.keepTailBytes = 16;
+
+const app = startServer(cfg);
+const base = `http://127.0.0.1:${app.server.port}`;
+
+const big = (marker: string): string => `${marker}: ${"payload ".repeat(60)}`;
+const call = (id: string, name: string, args: unknown): unknown => ({
+	role: "assistant",
+	content: null,
+	tool_calls: [{ id, type: "function", function: { name, arguments: JSON.stringify(args) } }],
+});
+const result = (id: string, content: string): unknown => ({ role: "tool", tool_call_id: id, content });
+const cycle = (n: number): unknown[] => [
+	call(`c${n}`, "read", { path: `src/file${n}.ts` }),
+	result(`c${n}`, big(`READ${n}`)),
+	{ role: "assistant", content: `read file${n}` },
+];
+
+async function dispatch(messages: unknown[]): Promise<{ role: string; content: unknown }[]> {
+	const res = await fetch(`${base}/v1/chat/completions`, {
+		method: "POST",
+		headers: { "content-type": "application/json" },
+		body: JSON.stringify({ model: "auto", messages, stream: true }),
+	});
+	await res.text();
+	const body = mock.requests.at(-1)?.body as Record<string, unknown>;
+	return body.messages as { role: string; content: unknown }[];
+}
+
+const fail = (label: string, detail?: unknown): never => {
+	console.error(`FAIL ${label}`, detail === undefined ? "" : JSON.stringify(detail).slice(0, 500));
+	process.exit(1);
+};
+const shrunkOf = (msgs: { content: unknown }[]): Map<number, string> => {
+	const out = new Map<number, string>();
+	msgs.forEach((m, i) => {
+		if (typeof m.content === "string" && m.content.includes("omp-router: elided")) out.set(i, m.content);
+	});
+	return out;
+};
+
+// A 20-cycle conversation, dispatched turn by turn exactly as omp would: the
+// full history every time, one cycle longer each turn.
+const TURNS = 20;
+let history: unknown[] = [{ role: "user", content: "audit the project" }];
+let prev = new Map<number, string>();
+let changes = 0;
+let firstPlanTurn = 0;
+
+for (let n = 1; n <= TURNS; n++) {
+	history = [...history, ...cycle(n)];
+	const msgs = await dispatch(history);
+	const shrunk = shrunkOf(msgs);
+
+	// STABILITY: every previously-shrunk message must still be shrunk, with the
+	// same bytes. A dropped or altered edit rewrites the cached prefix.
+	for (const [i, content] of prev) {
+		const now = shrunk.get(i);
+		if (now === undefined) fail(`turn ${n}: edit at message ${i} was DROPPED (bytes re-inflated)`, { turn: n, i });
+		if (now !== content) fail(`turn ${n}: edit at message ${i} changed bytes`, { was: content.slice(0, 90), now: now.slice(0, 90) });
+	}
+
+	const added = [...shrunk.keys()].filter((i) => !prev.has(i));
+	if (added.length > 0) {
+		changes++;
+		if (firstPlanTurn === 0) firstPlanTurn = n;
+		console.log(`turn ${String(n).padStart(2)}: plan CHANGED (+${added.length} edits, ${shrunk.size} total)`);
+	} else if (shrunk.size > 0) {
+		console.log(`turn ${String(n).padStart(2)}: plan held (${shrunk.size} edits)`);
+	} else {
+		console.log(`turn ${String(n).padStart(2)}: no compaction`);
+	}
+	prev = shrunk;
+}
+
+const planningTurns = TURNS - firstPlanTurn + 1;
+console.log(`\nfloorRatio ${floorRatio}`);
+console.log(`PASS stability: no edit was ever dropped or rewritten across ${TURNS} turns`);
+console.log(`plan changes: ${changes} over ${planningTurns} compacting turns (${((changes / planningTurns) * 100).toFixed(0)}% of turns invalidate cache)`);
+
+app.stop(true);
+await mock.stop();
+process.exit(0);