auto-model-router 0.3.2 → 0.3.4

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.3.2",
+    "version": "0.3.4",
     "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.3.2",
+      "version": "0.3.4",
       "author": {
         "name": "drewappling",
         "email": "drewappling@gmail.com"

package/CLAUDE.md

@@ -11,108 +11,28 @@ It presents one keyless OpenAI-compatible provider and picks a concrete OpenRout
 
 ## agentdox — shared context/memory (**MANDATORY to keep updated**)
 
-agentdox is this repo's memory + docs + live-conversation system. The project slug is
-**`omp-router`** — ALWAYS scope agentdox writes to it. The HTTP MCP server in `.mcp.json`
-uses **`AGENTDOX_TOKEN`**, one **global** bearer token shared by every agentdox-wired repo.
-The scope comes from *this folder* (`AGENTDOX_SCOPE` in `.env.agentdox`), not from the token:
-the token grants every scope, so a wrong slug is **not** rejected — it silently writes into
-another project. Getting `omp-router` right is on you, not on RBAC.
+agentdox is this repo's memory + docs + live-conversation store. The project slug is
+**`omp-router`** — ALWAYS scope agentdox writes to it. The bearer token (`AGENTDOX_TOKEN`)
+is one global PAT that grants every scope, so a wrong slug is **not** rejected: it silently
+files this project's data under another project. Getting `omp-router` right is on you.
 
-**Where the credentials live:**
+**Full protocol: `.claude/skills/agentdox/SKILL.md`** (on connect, before asking the user,
+batching writes to the end of the session, the REST fallback with request shapes, search
+tips). Read it before using agentdox; do not improvise from this summary.
 
 | What | Where |
 | --- | --- |
-| Token + URL + scope | `.env.agentdox` in this repo root (**gitignored** via `.env.*` — never commit) |
-| What `.mcp.json` reads | the `AGENTDOX_TOKEN` **environment variable**, not the file |
-| Persisted env value | Windows **User** environment (`[Environment]::GetEnvironmentVariable('AGENTDOX_TOKEN','User')`) |
-| 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
-Code (substitution happens once, at startup). Re-mint instructions are in `.env.agentdox`.
-
-**Requirement: keeping agentdox current is part of completing any task, not optional.**
-Do NOT close out a task while memory, docs, or conversation history for the area you touched
-is stale or incomplete.
-
-Concrete duties (all scoped to `omp-router`):
-
-- **On connect:** run `project_ensure` with `slug: "omp-router"` before any memory/docs work.
-- **On startup:** read `context_brief` to onboard on decisions, conventions, and gotchas
-  before rediscovering them.
-- **Memory** (`memory_add` / `memory_update` / `memory_search`): record user-stated
-  preferences and corrections. When a fact changes, UPDATE the existing entry — never leave
-  contradictory facts. Keep entries compact and high-signal.
-- **Docs** (`docs_write` / `docs_update`): keep architecture and decisions current as reality
-  changes; writing once is not enough.
-- **Sessions** (`session_start` / `session_append`): append messages in real time, not as an
-  end-of-task summary.
-- **Context** (`context_assemble`): consult it (with a query) before re-asking the user about
-  anything already captured.
-- **Decisions** (`context_brief_record`): record decisions and conventions as they are made.
-
-### How to actually call it (MCP tools vs REST)
-
-The duties above name the **MCP tools** (`memory_add`, `docs_write`, `context_brief_record`, …),
-served from this repo's `.mcp.json`.
-
-**omp gets these tools too** — verified 2026-08-28. omp reads `.mcp.json` (repo root),
-`.omp/mcp.json`, `.claude/mcp.json`, and `~/.omp/agent/mcp.json`, and it expands `${VAR}` in
-headers. It mounts them **prefixed**: `agentdox_memory_add`, `agentdox_context_assemble`, …
-(fully qualified `mcp__agentdox_*`). All 17 tools load.
-
-The one prerequisite is `AGENTDOX_TOKEN` being present in the **launching shell's**
-environment. It is persisted at Windows *User* scope, so only shells started afterwards
-inherit it — an already-open terminal will show no agentdox tools until restarted.
-
-**A harness genuinely without those tools (e.g. Hermes, or omp before the env var is
-inherited) MUST use the REST API directly** — same live store, same RBAC. Don't skip recording
-just because the MCP tools are absent.
-
-REST basics: base `http://localhost:3003`, header `Authorization: Bearer <token>` where the token
-is `AGENTDOX_TOKEN` from `.env.agentdox` (global; grants every scope). **memory uses
-`category`, everything else uses `scope`; both are always `"omp-router"`.** MCP-tool → REST map:
-
-| Duty / MCP tool | REST |
-| --- | --- |
-| `project_ensure` | `POST /projects` `{slug,name}` (idempotent; re-ensure returns the project) |
-| `memory_search` | `GET /memory?category=omp-router&limit=N` · `GET /memory/search?q=…&category=omp-router` |
-| `memory_add` | `POST /memory` `{content, category:"omp-router", importance:0..1}` |
-| `memory_update` | `PATCH /memory/:id` `{content?, importance?, …}` (edit in place — never pile on dupes) |
-| `docs_write` | `POST /docs` `{slug, title, content, scope:"omp-router", tags?}` |
-| `docs_update` | `PATCH /docs/:id` `{title?, content?, tags?}` · list `GET /docs?scope=omp-router` |
-| read `context_brief` | `GET /context/brief?scope=omp-router` (404 `no_brief` until seeded) |
-| seed the brief | `PUT /context/brief` `{scope, overview?, repoLayout?, codeStyle?, buildTest?, assetConventions?, gotchas?}` |
-| `context_brief_record` | `POST /context/brief/decision` `{scope, title, decision, rationale}` |
-| `context_assemble` | `POST /context/assemble` `{scope, query}` · baseline `GET /context/snapshot?scope=` · `POST /context/refresh` `{scope}` |
-| `session_start` / `session_append` | `POST /sessions` `{scope, title}` → `POST /sessions/:id/messages` `{role, content, refs?}` → `POST /sessions/:id/end` |
-
-Cleanest call path (avoids Windows PowerShell mangling `$` in inline JSON): a throwaway
-`bun` script that reads the token and `fetch`es —
-
-```ts
-const tok = /AGENTDOX_TOKEN=(.+)/.exec(await Bun.file(".env.agentdox").text())?.[1]?.trim() ?? "";
-const H = { Authorization: `Bearer ${tok}`, "content-type": "application/json" };
-await fetch("http://localhost:3003/memory", { method: "POST", headers: H,
-  body: JSON.stringify({ content: "…", category: "omp-router", importance: 0.9 }) });
-```
-
-Endpoints are defined in `E:/projects/agentdox/packages/server/src/index.ts`; the router's own
-read/write client is `src/context/agentdox.ts` (assemble / createSession / append only).
+| Token, URL, scope | `.env.agentdox` in this repo root (gitignored — never commit) |
+| What `.mcp.json` reads | the `AGENTDOX_TOKEN` **environment variable** (Windows *User* scope; shells opened before it was set lack it) |
+| Server | `http://localhost:3003` — Docker container `agentdox-server`; endpoints in `E:/projects/agentdox/packages/server/src/index.ts` |
+| Admin token (re-mint) | `E:/projects/agentdox/deploy/.env` |
+
+Two rules that cause silent mistakes: **memory calls take `category`, everything else takes
+`scope`** (both always `"omp-router"`); and a **401 means the env var is missing** from the
+launching shell — re-set it from `.env.agentdox` and restart the harness. omp mounts the
+tools prefixed (`agentdox_memory_add`, …); a harness without them MUST use REST (the skill
+has the map) rather than skip recording. Cleanest REST call path is a throwaway `bun`
+script reading the token from `.env.agentdox`.
 
 ## This repo also *implements* an agentdox client
 

package/README.md

@@ -709,6 +709,7 @@ event has already arrived is treated as a completed turn, not an error.
 | `holdTurnsAfterEscalation` | `4` | Hold longer after an escalation. |
 | `switchMargin` | `1.3` | Switching must beat the warm-cache discount by this factor. Lower = switch away from a warm model more readily. |
 | `switchHorizonTurns` | `1` | Turns the stay/switch comparison is amortised over: `H × stayWarm` vs `switchCold + (H − 1) × newWarm`. `1` is the one-turn comparison, which can keep a dear model warm indefinitely when the cheaper winner is itself dear cold; a small `H` lets a switch that pays for itself within a few turns go ahead. |
+| `confirmUpgradesBelowConfidence` | `0.6` | A heuristic tier upgrade classified below this confidence waits one turn while the current model's cache is warm; a second consecutive upgrade classification confirms it. Escalations, explicit high reasoning and failing tool loops bypass the wait. `0` disables. Measured: 65 of 67 moderate→hard upgrades in a week bounced back within 3 turns, each paying a cold hard-tier read of a ~120k prompt. |
 | `cacheWarmTtlMs` | `300000` (5 min) | How long a model's prompt cache is considered warm. |
 | `maxDowngradePerTurn` | `1` | Max tiers a turn may drop in one step (avoids quality cliffs). |
 | `breakHoldOnMechanical` | `false` | Let a tool-result continuation that classifies *below* the held tier escape the hold (still bounded by `maxDowngradePerTurn`). Worth enabling when the held tier is expensive. |

package/docs/AGENTDOX-BRIDGE.md

@@ -175,8 +175,14 @@ would fix that, at the cost of one credential reaching every project.
   so router test turns feed back into the next block. The omp-router scope had accumulated 19
   sessions of which 18 were noise (`hi`, `say hello`, `Reply with exactly the word: PONG`,
   injection probes, `bridge e2e …`); they were deleted, and `tools/agentdox-e2e.ts` writes two
-  more every run. Consider a `sessionLimit` override for the bridge, or excluding
-  router-authored sessions.
+  more every run. **Done 2026-09-07:** recent sessions ride only on a conversation's FIRST
+  block (`ContextResolveInput.firstFetch`); refreshes ask for `sessionLimit: 0`, since by then
+  the section was this conversation's own turns (1.4-1.9k chars per block, changing every
+  refresh). In the same change the relevance query became `context/query.ts`
+  `relevanceQuery`: the last user message with real content after omp's wrapper elements
+  (`<system-reminder>`, `<recap>`, `<chat>`, image stubs) are stripped, capped at 400 chars —
+  live blocks had been queried with those wrappers verbatim, one header running to 2k chars.
+  Recorded user turns use the same cleaner.
 - **`context.timeoutMs` is 3000ms** and failures degrade silently at `debug` level by design.
   If agentdox is cold this can no-op invisibly. Consider logging the first failure at `warn`.
 - **Four copies of this project exist** on this machine: this repo, the research checkout,

package/package.json

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

package/src/cli/config-wizard.ts

@@ -232,6 +232,7 @@ export const WIZARD_SECTIONS: readonly SectionSpec[] = [
 			{ path: "hysteresis.holdTurnsAfterEscalation", label: "Hold turns after escalation", kind: "number", min: 0 },
 			{ path: "hysteresis.switchMargin", label: "Switch margin", kind: "number", min: 0 },
 			{ path: "hysteresis.switchHorizonTurns", label: "Switch horizon", kind: "number", min: 1, hint: "turns amortised" },
+			{ path: "hysteresis.confirmUpgradesBelowConfidence", label: "Confirm upgrades below confidence", kind: "number", min: 0, max: 1, hint: "0=off; low-confidence tier-ups wait a turn" },
 			{ path: "hysteresis.cacheWarmTtlMs", label: "Cache-warm TTL", kind: "number", min: 0, hint: "ms" },
 			{ path: "hysteresis.maxDowngradePerTurn", label: "Max downgrade per turn", kind: "number", min: 0, hint: "tiers" },
 			{ path: "hysteresis.breakHoldOnMechanical", label: "Break hold on mechanical turns", kind: "boolean" },

package/src/config/defaults.ts

@@ -174,6 +174,9 @@ export const DEFAULT_CONFIG: RouterConfig = {
 		// 1 = the shipped one-turn comparison. Raise to amortise a switch over the
 		// turns that follow it; see HysteresisConfig.switchHorizonTurns.
 		switchHorizonTurns: 1,
+		// Low-confidence heuristic upgrades from a warm model wait one turn; see
+		// HysteresisConfig.confirmUpgradesBelowConfidence for the measurement.
+		confirmUpgradesBelowConfidence: 0.6,
 		// OpenRouter sticky sessions expire in 5-10 minutes.
 		cacheWarmTtlMs: 300_000,
 		maxDowngradePerTurn: 1,

package/src/config/schema.ts

@@ -136,6 +136,7 @@ const hysteresis = z.strictObject({
 	holdTurnsAfterEscalation: z.number().int().nonnegative().optional(),
 	switchMargin: z.number().positive().optional(),
 	switchHorizonTurns: z.number().int().positive().optional(),
+	confirmUpgradesBelowConfidence: z.number().min(0).max(1).optional(),
 	cacheWarmTtlMs: z.number().nonnegative().optional(),
 	maxDowngradePerTurn: z.number().int().nonnegative().optional(),
 	breakHoldOnMechanical: z.boolean().optional(),

package/src/config/types.ts

@@ -392,6 +392,19 @@ export interface HysteresisConfig {
 	 * dispatches per user-visible turn, so single digits are conservative.
 	 */
 	switchHorizonTurns: number;
+	/**
+	 * A heuristic tier UPGRADE whose classification confidence is below this
+	 * waits one turn when the current model's cache is warm; a second
+	 * consecutive upgrade classification confirms it. 0 disables. Escalations,
+	 * explicit high reasoning and failing tool loops bypass the wait.
+	 *
+	 * Measured on 7 days of live traffic: 65 of 67 moderate→hard upgrades
+	 * bounced back within 3 turns, 50 of them below 0.6 confidence, costing
+	 * $17.90 in cold hard-tier prompt reads against $0.23 for staying warm.
+	 * The stay/switch comparison never sees these because the warm cheap
+	 * model is below the new tier's floor.
+	 */
+	confirmUpgradesBelowConfidence: number;
 	/** Assume a warm cache expires after this long. OpenRouter sticky sessions: 5-10 min. */
 	cacheWarmTtlMs: number;
 	/** Downgrade at most this many tiers per turn, so quality never falls off a cliff. */

package/src/context/bridge.ts

@@ -121,7 +121,15 @@ export function createContextBridge(opts: BridgeOptions): ContextBridge {
 				return { ...pinned, fetchedAtMs: input.pinnedFetchedAtMs };
 			}
 
-			const raw = await client.assemble(input.scope, input.query, { memoryLimit, docsLimit, sessionLimit, briefChars });
+			// Recent sessions only on a conversation's first block: after that they
+			// are this conversation's own recorded turns, duplicating the prompt
+			// and changing on every refresh (measured 1.4-1.9k chars per block).
+			const raw = await client.assemble(input.scope, input.query, {
+				memoryLimit,
+				docsLimit,
+				sessionLimit: input.firstFetch ? sessionLimit : 0,
+				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/query.ts

@@ -0,0 +1,58 @@
+/**
+ * What to tell agentdox this turn is about.
+ *
+ * The relevance query biases which memories and docs the assembled block
+ * carries, and agentdox echoes it verbatim into the block's header. Taking
+ * the last user-role message literally sent omp's own machinery instead of
+ * the user's ask: `<system-reminder>` nudges, `<system-notice>` job results,
+ * `<recap>` prompts, "Attached image(s) from tool result:" continuations.
+ * Measured on the live ledger: the three most recent blocks for one scope
+ * were queried with `<chat>`, `<system-reminder>` and an image notice, one
+ * header alone ran to 2k chars, and every refresh re-ranked memory against
+ * noise — different bytes each time, at the head of the cached prefix.
+ *
+ * The query is the last user message with real content once wrapper blocks
+ * are stripped, falling back to the conversation's opening ask, capped so the
+ * header stays a line rather than a message.
+ */
+
+import type { NormRequest } from "../wire/types.ts";
+
+/** Longest query worth sending: enough to rank on, short enough to stay stable. */
+export const MAX_QUERY_CHARS = 400;
+
+/**
+ * Harness wrapper tags whose whole element is machinery, not the user's ask.
+ * Stripped before judging whether a message has content.
+ */
+const WRAPPER_TAGS = ["system-reminder", "system-notice", "system-directive", "recap", "chat", "checkpoint-active-reminder", "interrupted-thinking"];
+
+const WRAPPER_RE = new RegExp(`<(${WRAPPER_TAGS.join("|")})(\\s[^>]*)?>[\\s\\S]*?</\\1>`, "gi");
+/** An unclosed wrapper at the start swallows the rest: treat the message as machinery. */
+const OPEN_WRAPPER_RE = new RegExp(`^\\s*<(${WRAPPER_TAGS.join("|")})(\\s[^>]*)?>`, "i");
+/** omp's tool-result image continuation and similar auto-generated stubs. */
+const STUB_RE = /^(attached image\(s\)(\s.*)?|\[image\]|\(no output\)|continue[.!]?)$/i;
+
+/** The user's own words in a message, or "" when it is all harness machinery. */
+export function userContent(text: string): string {
+	let t = text.replace(WRAPPER_RE, " ");
+	if (OPEN_WRAPPER_RE.test(t)) return "";
+	t = t.replace(/\s+/g, " ").trim();
+	if (t === "" || STUB_RE.test(t)) return "";
+	return t;
+}
+
+function cap(text: string): string {
+	return text.length > MAX_QUERY_CHARS ? `${text.slice(0, MAX_QUERY_CHARS - 1)}…` : text;
+}
+
+/** The relevance query for this turn: last real user message, else the opening ask, else "". */
+export function relevanceQuery(req: Pick<NormRequest, "messages">): string {
+	for (let i = req.messages.length - 1; i >= 0; i--) {
+		const m = req.messages[i];
+		if (m === undefined || m.role !== "user") continue;
+		const content = userContent(m.text);
+		if (content !== "") return cap(content);
+	}
+	return "";
+}

package/src/context/types.ts

@@ -38,8 +38,15 @@ export interface ContextResolveInput {
 	modelSwitching: boolean;
 	/** An escalation or failover retry — the prefix is cold either way. */
 	retrying: boolean;
-	/** Latest user text, used to bias agentdox relevance ranking. */
+	/** The user's ask this turn (see `context/query.ts`), used to bias agentdox relevance ranking. */
 	query: string;
+	/**
+	 * This conversation has not been given a block before. Recent sessions
+	 * are included only then: they carry a previous conversation forward, but
+	 * on a refresh they would mostly be this conversation's own turns, which
+	 * the prompt already holds.
+	 */
+	firstFetch: boolean;
 }
 
 /** One settled turn, recorded to agentdox with the model that served it. */

package/src/router/select.ts

@@ -102,6 +102,12 @@ function wideningOrder(tier: Tier, minTier: Tier, maxTier: Tier): Tier[] {
 	return out;
 }
 
+/** Evidence that an upgrade will stick: the conversation is failing or asked for deep reasoning. */
+function hardSignal(f: Features): boolean {
+	const reasoning: string = f.requestedReasoning ?? "";
+	return f.lastToolFailed || f.circularToolCall || f.repeatedToolCall || reasoning === "high" || reasoning === "xhigh" || reasoning === "max";
+}
+
 export function select(args: SelectArgs): Decision {
 	const { req, features, classification, profile, state, snapshot, ledger, cfg, nowMs } = args;
 	const reasons: string[] = [];
@@ -161,6 +167,42 @@ export function select(args: SelectArgs): Decision {
 	// exploration (2c) and candidate building (3) so both agree on the term.
 	const cacheWarm = state.cacheWarmSlug !== null && nowMs - state.cacheWarmAtMs <= cfg.hysteresis.cacheWarmTtlMs;
 
+	// 2a. Cache-aware upgrade confirmation. A low-confidence heuristic upgrade
+	//     from a warm model waits one turn; the next turn's classification
+	//     confirms or forgets it. Measured on 7 days of live traffic: 65 of 67
+	//     moderate→hard upgrades bounced back within 3 turns, 50 of them below
+	//     0.6 confidence, and each paid a cold hard-tier read of a ~120k prompt
+	//     ($17.90 in total against $0.23 for staying warm). Step 4's stay/switch
+	//     comparison never sees these — the warm cheap model is below the new
+	//     tier's floor, so it is not a candidate there. Escalations, explicit
+	//     high reasoning and failing tool loops bypass the wait: those are the
+	//     upgrades that stick.
+	let upgradeDeferred: Tier | null = null;
+	const confirmBelow = cfg.hysteresis.confirmUpgradesBelowConfidence;
+	if (
+		confirmBelow > 0 &&
+		cls.source === "heuristic" &&
+		classification.confidence < confirmBelow &&
+		state.currentTier !== null &&
+		state.currentSlug !== null &&
+		tierIdx(effective) > tierIdx(clampTier(state.currentTier)) &&
+		cacheWarm &&
+		state.cacheWarmSlug === state.currentSlug &&
+		(args.excludeSlugs === undefined || args.excludeSlugs.length === 0) &&
+		!hardSignal(features)
+	) {
+		const held = clampTier(state.currentTier);
+		if (state.upgradeDeferredTier !== undefined && state.upgradeDeferredTier !== null) {
+			reasons.push(`upgrade ${held} → ${effective} confirmed: classified above ${held} on consecutive turns`);
+		} else {
+			reasons.push(
+				`upgrade ${held} → ${effective} deferred one turn: heuristic confidence ${classification.confidence.toFixed(2)} < ${confirmBelow} with ${state.currentSlug} warm`,
+			);
+			upgradeDeferred = effective;
+			effective = held;
+		}
+	}
+
 	// 2b. Context compaction: shrink stale tool output before dispatch when the
 	//     prompt exceeds the token budget (or would overflow the profile window).
 	//     Deterministic and content-only (never removes a message), so downstream
@@ -531,5 +573,6 @@ export function select(args: SelectArgs): Decision {
 		reasons,
 		explored,
 		budgetDowngraded,
+		upgradeDeferred,
 	};
 }

package/src/router/state.ts

@@ -32,6 +32,7 @@ interface Row {
 	context_fetched_at_ms: number;
 	compaction_plan: string | null;
 	compaction_plan_tokens: number;
+	upgrade_deferred_tier: string | null;
 	updated_at_ms: number;
 }
 
@@ -53,6 +54,7 @@ function toState(row: Row): ConversationState {
 		contextFetchedAtMs: row.context_fetched_at_ms,
 		compactionPlan: row.compaction_plan === null ? null : (JSON.parse(row.compaction_plan) as CompactionEdit[]),
 		compactionPlanTokens: row.compaction_plan_tokens,
+		upgradeDeferredTier: row.upgrade_deferred_tier as Tier | null,
 		updatedAtMs: row.updated_at_ms,
 	};
 }
@@ -71,10 +73,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, compaction_plan, compaction_plan_tokens, updated_at_ms
+			context_version, context_fetched_at_ms, compaction_plan, compaction_plan_tokens, upgrade_deferred_tier, updated_at_ms
 		) VALUES ($key, $sessionId, $turn, $currentSlug, $currentTier, $stickyUntilTurn,
 			$lastPromptTokens, $cacheWarmSlug, $cacheWarmAtMs,
-			$contextVersion, $contextFetchedAtMs, $compactionPlan, $compactionPlanTokens, $updatedAtMs)
+			$contextVersion, $contextFetchedAtMs, $compactionPlan, $compactionPlanTokens, $upgradeDeferredTier, $updatedAtMs)
 		ON CONFLICT(key) DO UPDATE SET
 			session_id = excluded.session_id,
 			turn = excluded.turn,
@@ -88,6 +90,7 @@ export function createConversationStore(db: Database): ConversationStore {
 			context_fetched_at_ms = excluded.context_fetched_at_ms,
 			compaction_plan = excluded.compaction_plan,
 			compaction_plan_tokens = excluded.compaction_plan_tokens,
+			upgrade_deferred_tier = excluded.upgrade_deferred_tier,
 			updated_at_ms = excluded.updated_at_ms
 	`);
 	// Read-modify-write in JS lost money: an aborted or failed dispatch is still
@@ -137,6 +140,7 @@ export function createConversationStore(db: Database): ConversationStore {
 				$lastPromptTokens: state.lastPromptTokens,
 				$compactionPlan: state.compactionPlan === null ? null : JSON.stringify(state.compactionPlan),
 				$compactionPlanTokens: state.compactionPlanTokens ?? 0,
+				$upgradeDeferredTier: state.upgradeDeferredTier ?? null,
 				$cacheWarmSlug: state.cacheWarmSlug,
 				$cacheWarmAtMs: state.cacheWarmAtMs,
 				$contextVersion: state.contextVersion,

package/src/router/types.ts

@@ -186,6 +186,13 @@ export interface ConversationState {
 	compactionPlanTokens?: number;
 	/** When that block was fetched, for the staleness TTL. */
 	contextFetchedAtMs: number;
+	/**
+	 * The tier a low-confidence upgrade was deferred to on the previous turn
+	 * (`hysteresis.confirmUpgradesBelowConfidence`), or null. One-turn memory:
+	 * every turn overwrites it, so a second consecutive upgrade classification
+	 * confirms the switch and anything else forgets it.
+	 */
+	upgradeDeferredTier?: Tier | null;
 	updatedAtMs: number;
 }
 
@@ -270,6 +277,8 @@ export interface Decision {
 	explored: Exploration | null;
 	/** Budget guard forced a cheaper tier than the classifier asked for. */
 	budgetDowngraded: boolean;
+	/** A low-confidence upgrade to this tier was deferred one turn to keep the warm model. */
+	upgradeDeferred: Tier | null;
 }
 
 /** Why a guarded probe rejected an attempt. */

package/src/server/turn.ts

@@ -9,6 +9,7 @@
  */
 
 import type { CatalogSource } from "../catalog/types.ts";
+import { relevanceQuery, userContent } from "../context/query.ts";
 import type { ContextBridge } from "../context/types.ts";
 import type { RouterConfig } from "../config/types.ts";
 import { estimateUnreportedCache } from "../cost/cache-estimate.ts";
@@ -159,7 +160,8 @@ export async function runTurn(
 				pinnedFetchedAtMs: state.contextFetchedAtMs,
 				modelSwitching: state.currentSlug !== null && state.currentSlug !== decision.slug,
 				retrying: attempt > 0,
-				query: lastUserText(req),
+				query: relevanceQuery(req),
+				firstFetch: state.contextVersion === null,
 			});
 			if (pin !== null) {
 				contextBlock = pin.block;
@@ -565,6 +567,8 @@ export async function runTurn(
 		// shrunk so the prompt cache survives and the savings compound.
 		state.compactionPlan = decision.compactionPlan.length > 0 ? decision.compactionPlan : null;
 		state.compactionPlanTokens = decision.compactionPlanTokens;
+		// One-turn memory: a deferred upgrade is confirmed or forgotten next turn.
+		state.upgradeDeferredTier = decision.upgradeDeferred;
 		if (usage.cachedTokens > 0 || usage.cacheWriteTokens > 0) {
 			// Non-zero cache traffic is direct evidence the upstream cache exists.
 			state.cacheWarmSlug = servedSlug ?? decision.slug;
@@ -589,7 +593,8 @@ export async function runTurn(
 		// tool-less session is therefore not transcribed: silence beats garbage,
 		// because every junk record is re-injected into every later turn.
 		if (doxActive && req.tools.length > 0) {
-			const userText = lastUserText(req);
+			// Record the user's words, not omp's wrappers (recap prompts, reminders).
+			const userText = userContent(lastUserText(req));
 			const turnEnded = finishReason !== "tool_calls";
 			log.debug("agentdox record turn", {
 				conversationKey: req.conversationKey.slice(0, 8),

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 = 16;
+const USER_VERSION = 17;
 
 const MIGRATIONS = `
 CREATE TABLE IF NOT EXISTS catalog_cache (
@@ -243,6 +243,12 @@ ALTER TABLE conversations ADD COLUMN compaction_plan_tokens INTEGER NOT NULL DEF
 DELETE FROM token_calibration;
 `;
 
+// v17: one-turn memory of a deferred low-confidence upgrade
+// (hysteresis.confirmUpgradesBelowConfidence).
+const MIGRATE_V17 = `
+ALTER TABLE conversations ADD COLUMN upgrade_deferred_tier 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
@@ -288,6 +294,7 @@ export function openDb(path: string): Database {
 		if (!convCols.some((c) => c.name === "context_version")) db.exec(MIGRATE_V11);
 		if (!convCols.some((c) => c.name === "compaction_plan")) db.exec(MIGRATE_V13);
 		if (!convCols.some((c) => c.name === "compaction_plan_tokens")) db.exec(MIGRATE_V16);
+		if (!convCols.some((c) => c.name === "upgrade_deferred_tier")) db.exec(MIGRATE_V17);
 		db.exec(`PRAGMA user_version = ${USER_VERSION}`);
 	}
 	return db;

package/test/context-bridge.test.ts

@@ -72,11 +72,23 @@ function input(over: Partial<ContextResolveInput> = {}): ContextResolveInput {
 		modelSwitching: false,
 		retrying: false,
 		query: "movement rules",
+		firstFetch: true,
 		...over,
 	};
 }
 
 describe("context bridge refresh policy", () => {
+	test("recent sessions ride only on a conversation's first block; refreshes ask for none", async () => {
+		const client = mkClient();
+		const { bridge } = mkBridge(client, { sessionLimit: 6 });
+		await bridge.resolve(input({ firstFetch: true }));
+		expect(client.lastLimits?.sessionLimit).toBe(6);
+		// A refresh (model switch) on a conversation that already had a block.
+		await bridge.resolve(input({ firstFetch: false, modelSwitching: true, pinnedVersion: "stale", pinnedFetchedAtMs: 1 }));
+		expect(client.lastLimits?.sessionLimit).toBe(0);
+		expect(client.assembleCalls).toBe(2);
+	});
+
 	test("fetches on the first turn, then pins without re-fetching", async () => {
 		const client = mkClient();
 		const { bridge, db } = mkBridge(client);

package/test/context-query.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, test } from "bun:test";
+
+import { MAX_QUERY_CHARS, relevanceQuery, userContent } from "../src/context/query.ts";
+
+/**
+ * The agentdox relevance query must be the user's ask, not omp's wrappers:
+ * live blocks were queried with `<chat>`, `<system-reminder>` and an image
+ * notice, re-ranking memory against noise on every refresh.
+ */
+
+const msg = (role: "user" | "assistant" | "system" | "tool", text: string) => ({ role, text }) as never;
+
+describe("userContent", () => {
+	test("strips wrapper elements and keeps the user's words", () => {
+		expect(userContent("<system-reminder>\n5 todo items still open.\n</system-reminder>\nplease fix the water tests")).toBe("please fix the water tests");
+		expect(userContent("<recap>User stepped away; returning.</recap>")).toBe("");
+		expect(userContent("<system-notice>Background job bg_43 completed.</system-notice>")).toBe("");
+	});
+
+	test("an unclosed wrapper at the start is all machinery", () => {
+		expect(userContent("<chat>\nassistant said things\nuser said things")).toBe("");
+		expect(userContent("<system-reminder>Today: 2026-09-07")).toBe("");
+	});
+
+	test("auto-generated stubs are not content", () => {
+		expect(userContent("Attached image(s) from tool result:")).toBe("");
+		expect(userContent("(no output)")).toBe("");
+		expect(userContent("continue")).toBe("");
+	});
+
+	test("ordinary text passes through with whitespace collapsed", () => {
+		expect(userContent("  why does   the\n\nrouter pick glm?  ")).toBe("why does the router pick glm?");
+	});
+});
+
+describe("relevanceQuery", () => {
+	test("takes the last user message with real content, skipping wrapper-only turns", () => {
+		const req = {
+			messages: [
+				msg("system", "You are omp."),
+				msg("user", "add a /router command with reports"),
+				msg("assistant", "done"),
+				msg("user", "<system-reminder>5 todo items still open.</system-reminder>"),
+				msg("tool", "Attached image(s) from tool result:"),
+				msg("user", "Attached image(s) from tool result:"),
+			],
+		};
+		expect(relevanceQuery(req)).toBe("add a /router command with reports");
+	});
+
+	test("prefers the newest real ask over the opening one", () => {
+		const req = { messages: [msg("user", "first ask"), msg("assistant", "ok"), msg("user", "<recap>x</recap> now fix the report window")] };
+		expect(relevanceQuery(req)).toBe("now fix the report window");
+	});
+
+	test("caps long asks so the block header stays a line", () => {
+		const long = "x".repeat(5_000);
+		const q = relevanceQuery({ messages: [msg("user", long)] });
+		expect(q.length).toBe(MAX_QUERY_CHARS);
+		expect(q.endsWith("…")).toBe(true);
+	});
+
+	test("nothing usable yields an empty query", () => {
+		expect(relevanceQuery({ messages: [msg("user", "<chat>\nlog"), msg("assistant", "hi")] })).toBe("");
+		expect(relevanceQuery({ messages: [] })).toBe("");
+	});
+});

package/test/failover.test.ts

@@ -70,7 +70,7 @@ function mkConfig(escalation: Partial<EscalationConfig> = {}): RouterConfig {
 			escalateOnLengthStop: false,
 			...escalation,
 		},
-		hysteresis: { holdTurns: 2, holdTurnsAfterEscalation: 4, switchMargin: 1.5, cacheWarmTtlMs: 600_000, maxDowngradePerTurn: 1, breakHoldOnMechanical: false, switchHorizonTurns: 1 },
+		hysteresis: { holdTurns: 2, holdTurnsAfterEscalation: 4, switchMargin: 1.5, cacheWarmTtlMs: 600_000, maxDowngradePerTurn: 1, breakHoldOnMechanical: false, switchHorizonTurns: 1, confirmUpgradesBelowConfidence: 0.6 },
 		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 },
@@ -160,6 +160,7 @@ function mkDecision(tier: Tier, slug: string, probe: Partial<ProbePlan> = {}): D
 		reasons: ["test decision"],
 		explored: null,
 		budgetDowngraded: false,
+		upgradeDeferred: null,
 	};
 }
 

package/test/select.test.ts

@@ -996,3 +996,57 @@ describe("compaction.replanGrowthRatio (review 2026-09-05 §7)", () => {
 	});
 });
 
+
+describe("hysteresis.confirmUpgradesBelowConfidence", () => {
+	// A low-confidence heuristic upgrade from a warm model waits one turn.
+	// Measured: 65 of 67 moderate→hard upgrades in a week bounced back within
+	// 3 turns, each paying a cold hard-tier read of a ~120k prompt.
+	const warmSlug = run({ tier: "moderate" }).slug;
+	function upgrade(opts: { confidence?: number; source?: "heuristic" | "escalation"; st?: Partial<ConversationState>; cfg?: RouterConfig; lastToolFailed?: boolean }) {
+		const cfg = opts.cfg ?? BASE;
+		const req = request("now rework the whole scheduler");
+		const base = extractFeatures(req, 120_000);
+		const features = opts.lastToolFailed === true ? { ...base, lastToolFailed: true } : base;
+		const heuristic = scoreHeuristic(features, cfg);
+		return select({
+			req,
+			features,
+			classification: { ...heuristic, tier: "hard", confidence: opts.confidence ?? 0.45, source: opts.source ?? "heuristic" },
+			profile: PROFILE,
+			state: state({ turn: 4, currentTier: "moderate", currentSlug: warmSlug, cacheWarmSlug: warmSlug, cacheWarmAtMs: Date.now(), lastPromptTokens: 110_000, ...opts.st }),
+			snapshot: SNAPSHOT,
+			ledger: null,
+			cfg,
+			nowMs: Date.now(),
+		});
+	}
+
+	test("a low-confidence upgrade from a warm model is deferred to the held tier", () => {
+		const d = upgrade({});
+		expect(d.tier).toBe("moderate");
+		expect(d.upgradeDeferred).toBe("hard");
+		expect(d.reasons.some((r) => r.includes("upgrade moderate → hard deferred one turn"))).toBe(true);
+	});
+
+	test("a second consecutive upgrade classification confirms it", () => {
+		const d = upgrade({ st: { upgradeDeferredTier: "hard" } });
+		expect(d.tier).toBe("hard");
+		expect(d.upgradeDeferred).toBeNull();
+		expect(d.reasons.some((r) => r.includes("upgrade moderate → hard confirmed"))).toBe(true);
+	});
+
+	test("confident classifications, cold caches, escalations, failing tools and the off switch all upgrade at once", () => {
+		expect(upgrade({ confidence: 0.9 }).tier).toBe("hard");
+		expect(upgrade({ st: { cacheWarmAtMs: Date.now() - 3_600_000 } }).tier).toBe("hard");
+		expect(upgrade({ source: "escalation" }).tier).toBe("hard");
+		expect(upgrade({ lastToolFailed: true }).tier).toBe("hard");
+		const off: RouterConfig = { ...BASE, hysteresis: { ...BASE.hysteresis, confirmUpgradesBelowConfidence: 0 } };
+		expect(upgrade({ cfg: off }).tier).toBe("hard");
+		for (const d of [upgrade({ confidence: 0.9 }), upgrade({ source: "escalation" })]) expect(d.upgradeDeferred).toBeNull();
+	});
+
+	test("a downgrade or a same-tier turn is never deferred", () => {
+		const d = run({ tier: "simple", st: state({ turn: 4, currentTier: "moderate", currentSlug: warmSlug, cacheWarmSlug: warmSlug, cacheWarmAtMs: Date.now() }) });
+		expect(d.upgradeDeferred).toBeNull();
+	});
+});

package/test/trust-attribution.test.ts

@@ -3,6 +3,7 @@ import { describe, expect, test } from "bun:test";
 import { loadConfig } from "../src/config/load.ts";
 import { createLedger, LATENCY_WINDOW_ROWS } from "../src/cost/ledger.ts";
 import { EMPTY_USAGE, type LedgerEntry } from "../src/cost/types.ts";
+import { createConversationStore } from "../src/router/state.ts";
 import { openDb } from "../src/util/sqlite.ts";
 
 const cfg = loadConfig({});
@@ -244,11 +245,24 @@ describe("v4 migration", () => {
 		}
 	});
 
-	test("schema is at user_version 16", () => {
+	test("a deferred upgrade tier survives a save/load round trip", () => {
+		const db = openDb(":memory:");
+		const store = createConversationStore(db);
+		const st = store.load("conv-defer");
+		st.upgradeDeferredTier = "hard";
+		store.save(st);
+		expect(store.load("conv-defer").upgradeDeferredTier).toBe("hard");
+		st.upgradeDeferredTier = null;
+		store.save(st);
+		expect(store.load("conv-defer").upgradeDeferredTier).toBeNull();
+		db.close();
+	});
+
+	test("schema is at user_version 17", () => {
 		const db = openDb(":memory:");
 		try {
 			const row = db.query("PRAGMA user_version").get() as { user_version: number };
-			expect(row.user_version).toBe(16);
+			expect(row.user_version).toBe(17);
 		} finally {
 			db.close();
 		}

package/test/turn.test.ts

@@ -70,7 +70,7 @@ function mkConfig(escalation: Partial<EscalationConfig> = {}): RouterConfig {
 			escalateOnLengthStop: false,
 			...escalation,
 		},
-		hysteresis: { holdTurns: 2, holdTurnsAfterEscalation: 4, switchMargin: 1.5, cacheWarmTtlMs: 600_000, maxDowngradePerTurn: 1, breakHoldOnMechanical: false, switchHorizonTurns: 1 },
+		hysteresis: { holdTurns: 2, holdTurnsAfterEscalation: 4, switchMargin: 1.5, cacheWarmTtlMs: 600_000, maxDowngradePerTurn: 1, breakHoldOnMechanical: false, switchHorizonTurns: 1, confirmUpgradesBelowConfidence: 0.6 },
 		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 },
@@ -160,6 +160,7 @@ function mkDecision(tier: Tier, slug: string, probe: Partial<ProbePlan> = {}): D
 		reasons: ["test decision"],
 		explored: null,
 		budgetDowngraded: false,
+		upgradeDeferred: null,
 	};
 }
 

package/tools/agentdox-e2e.ts

@@ -58,6 +58,7 @@ function input(over: Partial<ContextResolveInput> = {}): ContextResolveInput {
 		modelSwitching: false,
 		retrying: false,
 		query: "cache prompt context injection",
+		firstFetch: true,
 		...over,
 	};
 }