@alexeiled/claude-router 0.6.0 → 0.6.1

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "router",
   "displayName": "jev-router",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Auto-picks the right Claude model for each turn — small models for quick edits, mid-tier for code, frontier for hard problems. Uses Jev to classify each request.",
   "author": { "name": "Alexei Ledenev", "url": "https://github.com/alexei-led" },
   "repository": "https://github.com/alexei-led/claude-router",

package/README.md

@@ -7,11 +7,17 @@
 
 A Claude Code plugin that auto-picks the right model and effort for each turn.
 
-A local gateway on `127.0.0.1` receives each request from Claude Code. For a
-new user turn, the gateway asks Jev (TypeSafe) which tier the turn needs. Then
-the gateway rewrites `model`, `effort` and `thinking` in the request and sends
-it to Anthropic. All other data goes through unchanged. The gateway has no
-runtime dependencies and needs Node 22 or later.
+**Status: experimental.** I built this to dogfood Jev, TypeSafe's routing
+model, inside Claude Code. It works for me; I don't know yet if it holds up
+outside my setup. Try it and open an issue with what you find.
+
+## Why
+
+One model for every turn is a compromise: strong enough for the hard turns
+and it burns your limits on "rename this variable"; cheap enough for the easy
+turns and it struggles on the hard ones. Switching models by hand works, but
+it is friction you pay on every message. This plugin asks a small router
+model which tier a turn needs and switches for you, automatically.
 
 ## How it works
 
@@ -26,20 +32,23 @@ only requests for `jev-router`:        ├─ facts.mjs    prompt, continuation,
    responses go through unchanged; the gateway reads `usage` (context size, cache TTL)
 ```
 
+A local gateway on `127.0.0.1` receives each request from Claude Code. For a
+new user turn, the gateway asks Jev which tier the turn needs, then rewrites
+`model`, `effort` and `thinking` and sends the request to Anthropic. All other
+data goes through unchanged. No runtime dependencies; Node 22 or later.
+
 The tiers are `micro` (Haiku), `low` (Sonnet, the baseline), `medium` (Opus at
 high effort) and `high` (Opus at xhigh effort). The exact model IDs are in
 `~/.claude/router.json` and default to the current generation of each family.
 
 A tool continuation keeps the route of its turn — the gateway does not ask Jev.
 Side requests, for example session titles, get the baseline tier. A subagent
-that inherits the model gets routing with its own memory. A request for
-any other model goes through unchanged. This is how `/router:<tier>` pins and
+that inherits the model gets routing with its own memory. A request for any
+other model goes through unchanged; this is how `/router:<tier>` pins and
 subagents with their own `model` work.
 
-Module dependencies point in one direction: `gateway.mjs` (HTTP) →
-`router.mjs` (orchestration) → `facts`, `jev`, `policy` → `cost`, `rewrite`,
-`store`. The modules `facts`, `cost`, `rewrite`, `sse` and `policy` are pure.
-Only `store` writes files. The Jev transport is injected.
+See [Architecture](docs/architecture.md) for the module map, the switching
+policy, and a real-usage evaluation.
 
 ## Install
 
@@ -79,14 +88,11 @@ plugin never replaces a newer gateway. The Jev API key stays in the macOS
 Keychain. Run `/router:setup` once after an update: the status line command
 path contains the plugin version.
 
-Updating from 0.3.0 or earlier: these gateways cannot hand over, so stop the
-old one once with `pkill -f scripts/gateway.mjs`.
-
 ## Documentation
 
 - [User guide](docs/user-guide.md): daily use, pins, decision log, troubleshooting.
 - [Configuration](docs/configuration.md): each key, and where the API key and the configuration file are.
-- [Design](docs/design.md): decisions, the switching policy, test results.
+- [Architecture](docs/architecture.md): how the gateway works, the switching policy, a real-usage evaluation.
 
 ## Develop
 
@@ -102,4 +108,4 @@ claude --plugin-dir . --model jev-router   # with ANTHROPIC_BASE_URL and TYPESAF
 Releases: push a signed tag `v<version>` that matches `package.json`. The
 release workflow publishes `@alexeiled/claude-router` to npm with trusted
 publishing and creates the GitHub release. See
-[docs/design.md](docs/design.md#release).
+[docs/architecture.md](docs/architecture.md#release).

package/docs/{design.md → architecture.md}

@@ -1,4 +1,4 @@
-# Design record
+# Architecture
 
 Each decision has the date when the owner took it.
 
@@ -21,12 +21,17 @@ get the context size, the cache reads and the cache TTL.
 For a model without thinking (Haiku), the gateway also removes the
 `clear_thinking_*` edits from `context_management`, because the API rejects
 them without thinking. The gateway never changes `system`, `tools` or
-`messages`. Thus preserved
-thinking and prompt caching work as if Claude Code talked to Anthropic. Claude
-Code documents this gateway mode, including the OAuth value for a claude.ai
-login. See [llm-gateway](https://code.claude.com/docs/en/llm-gateway) and
+`messages`. Thinking and prompt caching work as if Claude Code talked to
+Anthropic directly. Claude Code documents this gateway mode, including the
+OAuth value for a claude.ai login. See
+[llm-gateway](https://code.claude.com/docs/en/llm-gateway) and
 [protocol](https://code.claude.com/docs/en/llm-gateway-protocol).
 
+Module dependencies point in one direction: `gateway.mjs` (HTTP) →
+`router.mjs` (orchestration) → `facts`, `jev`, `policy` → `cost`, `rewrite`,
+`store`. The modules `facts`, `cost`, `rewrite`, `sse` and `policy` are pure.
+Only `store` writes files. The Jev transport is injected.
+
 The `SessionStart` hook of the plugin starts the gateway when the port does not
 answer. `/router:setup` writes `model`, `ANTHROPIC_BASE_URL` and the picker row to
 the user settings once. A plugin cannot set them by itself.
@@ -38,22 +43,14 @@ is the only place where the real model of the turn is visible.
 
 ### Why not the native skill path
 
-The first design used a `UserPromptSubmit` hook. The hook asked Claude to call
-a tier skill. The frontmatter `model:` and `effort:` of the skill were to serve
-the rest of the turn.
-
-The test on Claude Code 2.1.278 gave this result. A skill that the user types
-(`/router:medium …`) changes the model for the turn. The same skill,
-called by Claude through the Skill tool, does not change the model. The
-transcript records `attributionSkill`, but the session model answers. The test
-ran in three sessions, in auto mode and in `acceptEdits` mode, with Opus and
-Fable targets. The documentation says "when this skill is active". The
-behavior is user invocation only. A feedback report is filed. The skills stay
-as manual pins.
-
-This result also removed the "Sonnet session model" argument from the peer
-review. The gateway has no bootstrap request and no cache drop for a turn that
-keeps its route. The baseline is a configuration value.
+The first design used a `UserPromptSubmit` hook that asked Claude to call a
+tier skill, relying on the skill's frontmatter `model:` and `effort:` to serve
+the rest of the turn. On Claude Code 2.1.278 that only works for a skill the
+user types (`/router:medium …`); the same skill called by Claude through the
+Skill tool does not change the model — the transcript records
+`attributionSkill`, but the session model answers. So `/router:<tier>` skills
+stay as manual pins, and the gateway is the only path that routes turns Claude
+calls on its own.
 
 ## Tiers
 
@@ -64,10 +61,9 @@ keeps its route. The baseline is a configuration value.
 | low    | sonnet | as sent | claude-sonnet-5      |
 | micro  | haiku  | none    | claude-haiku-4-5     |
 
-The gateway lowers the effort to a level that the model family accepts. Sonnet
-4.6 has no `xhigh`. Haiku gets no effort and no adaptive thinking. The ids are
-configuration. `sonnet` is 4.6 because the alias resolved to 4.6 on the test
-account.
+The gateway lowers the effort to a level the model's `efforts` list accepts
+(see [configuration](configuration.md#models)); Haiku accepts none, so it gets
+no effort and no adaptive thinking. The ids are configuration.
 
 ## Request classes
 
@@ -86,6 +82,10 @@ account.
   429, a 529 or a dropped connection.
 - A side endpoint with the alias, such as `/v1/messages/count_tokens`: the
   model of the session's last route. Only `POST /v1/messages` is a turn.
+- A history break: a main request with fewer messages than the last one (a
+  compaction or a rewind), or the header `x-claude-code-context-compacted`.
+  The gateway drops the cached prefixes, the votes and the escalation hold,
+  then routes the request as usual. The route stays until the next decision.
 
 ## Failure handling
 
@@ -103,7 +103,7 @@ request must not reach the others.
   logged. The routing decision stands.
 - Jev: one retry on a network error or a transient status, after
   `Retry-After` when it fits the 1.5 s budget. After three failures in a row,
-  new turns skip Jev for a minute, then try once.
+  new turns skip Jev for a minute, then try once per pause.
 - The daemon logs a stray exception instead of exiting. On `SIGTERM` it
   releases the port at once and finishes open streams for up to 10 minutes.
   A second daemon on a busy port exits quietly.
@@ -127,18 +127,20 @@ request must not reach the others.
 All inputs come from the traffic of the gateway. The gateway does not read
 transcripts.
 
-| Input                                            | Source                                                                                                                          |
-| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- |
-| Context of the last request, cache reads, output | `usage` in the response (`message_start` and `message_delta`)                                                                   |
-| Granted TTL                                      | `usage.cache_creation.ephemeral_1h_input_tokens` or the `5m` field                                                              |
-| Cache warmth of a model                          | The time of the last response of that model, plus the TTL, minus 30 s                                                           |
-| Reusable prefix of a model                       | The context plus the output at the last response of that model. Cleared by `x-claude-code-context-compacted`, or when the context shrinks by more than 20% (compaction).|
-| Failure signal                                   | Two `tool_result` blocks with `is_error` and the same signature, with an edit tool call between them                            |
-| Continuation                                     | The last message contains a `tool_result`. For a new prompt, a Jev Noul answers "does this prompt continue the task".           |
-
-Prices are a list-price table in the configuration. `modelPricing` is a
-managed setting and is not readable. The switching tax for a candidate `c`
-against the current route `i` is:
+| Input                                            | Source                                                                                                                                                                   |
+| ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Context of the last request, cache reads, output | `usage` in the response (`message_start` and `message_delta`)                                                                                                            |
+| Granted TTL                                      | `usage.cache_creation.ephemeral_1h_input_tokens` or the `5m` field                                                                                                       |
+| Cache identity                                   | The model id and the effort the gateway sent (`claude-opus-5-5@xhigh`). An effort change rewrites the messages cache, so each effort is its own cache.                  |
+| Cache warmth                                     | The time of the last response for that cache, plus the TTL, minus 30 s. `unknown` when no response since the session started or the history broke.                      |
+| Reusable prefix                                  | The context plus the output at the last response for that cache. Cleared by a history break, or when the context shrinks by more than 20% (context editing).             |
+| Failure signal                                   | Two `tool_result` blocks with `is_error` and the same signature, with an edit tool call between them                                                                     |
+| Continuation                                     | The last message contains a `tool_result`. For a new prompt, a Jev Noul answers "does this prompt continue the task".                                                    |
+
+Prices are a list-price table in the configuration (see
+[configuration](configuration.md#models)). `modelPricing` is a managed setting
+and is not readable. The switching tax for a candidate `c` against the current
+route `i` is:
 
 ```
 input_cost(m) = P_read(m) * W_m + P_write(m) * (N - W_m)
@@ -148,11 +150,13 @@ tax = max(0, input_cost(c) - input_cost(i))
 The subscription economics are not symmetric. Every default model uses the plan
 limits, and dollars give the order between them. A model with `billing:
 "credits"` bills cash, on the 5m TTL, and behind the gateway without the
-consent prompt of Claude Code. `policy.cashCapUsd` ($2 by default) caps the
-cold cache write that the gateway will pay for an automatic route to such a
-model. A Claude Code turn starts at about 100k tokens (system prompt and 159
-tool definitions), so the gate binds on the first switch, not later. No default
-model bills credits; the gate stays for configurations that add one.
+consent prompt of Claude Code. `policy.cashCapUsd` is a cold-write guard: it
+caps the estimated first cache write of an automatic route to such a model
+when its cache is not warm. It is not a budget: a warm cache passes, and
+output is not counted. A Claude Code turn starts at about 100k tokens (system
+prompt and tool definitions), so the guard binds on the first switch, not
+later. No default model bills credits; the guard stays for configurations that
+add one.
 
 ## Switching policy v0
 
@@ -171,8 +175,9 @@ Agreed with Codex on 2026-09-22. The thresholds are start values.
    `U >= 0.75 + 0.15 * tax / (tax + 0.5)`. A jump of two tiers with
    `U >= 0.95` skips the delay. A downgrade needs `D >= 0.90` and two
    consecutive votes.
-5. Cash gate. An automatic route to a `credits` model needs a warm cache, or a
-   cold write below the cap. Otherwise the strongest `plan` tier serves.
+5. Cold-write guard (reason `cash-gate`). An automatic route to a `credits`
+   model needs a warm cache, or a cold write below the cap. Otherwise the
+   strongest `plan` tier serves.
 6. No cooldown on upgrades. Plan, then execute, then hard again is sometimes
    the correct routing. The log separates reversals from real changes in the
    required capability.
@@ -180,19 +185,64 @@ Agreed with Codex on 2026-09-22. The thresholds are start values.
    and cache reads of each routed response. The memory changes only from
    responses that the gateway sent.
 
-## Test results (2026-09-22, Max plan, Claude Code 2.1.278)
-
-- Easy prompt: Jev gave `micro` at confidence 1. It was the first vote, so
-  `low` served (`claude-sonnet-5`, 103,799 context tokens on the first
-  request).
-- Hard prompt: Jev gave `high` at 0.66. A cold Fable write cost $1.30 against
-  the cap of $0.50 at that time, so `medium` served (`claude-opus-5`). Four
-  tool continuations kept the route, with cache reads within 1% of the
-  context.
-- Claude Code accepted `message_start.model` with the real model. The status
-  line showed the alias at all times.
-- Cold start: the `SessionStart` hook started the gateway before the first
-  request.
+## Cache identity, history breaks and shadow economics (2026-09-23)
+
+From a design review with the architect of pi-model-router, the Pi router
+that uses the same Jev tiers.
+
+- Cache identity is the model and the effort. A top-level effort change
+  invalidates the messages cache; the cache-preserving per-message effort is
+  not available on Opus 5.5. Before 0.6.1 the key was the model alone, so
+  `medium` ↔ `high` (Opus at `high` and `xhigh`) looked like a free switch
+  between warm caches.
+- A history break (fewer messages, or the compaction header) drops the cached
+  prefixes, the votes and the escalation hold: they were about turns that are
+  gone. Context editing shrinks the context but keeps the messages; it drops
+  only the prefixes. The gateway has no branch id, so it does not restore state
+  from before a rewind; `unknown` is the honest cache state after one.
+- `/router:status` and the status line show the reason; the report adds the
+  estimate. The dollars are list prices, a list-price equivalent for plan
+  models.
+- Shadow economics in `decisions.jsonl`, not read by the policy: for a turn
+  where Jev's choice differs from the current route, the extra cost of the
+  next turn, the difference for each later turn (input and output), and the
+  turns until a cheaper route repays its cache write. The owner's first
+  request (2026-09-22) was to stay while the model works on a warm cache and
+  to step down once the thinking is done. Rule 2 covers the first half; the
+  shadow estimate measures the second before any rule acts on it.
+- The default prices match `test/fixtures/list-prices.json`, which names its
+  source and date. A test pins how a tenfold cache-read error changes one
+  decision: the bar moves within `upgradeBase` and `upgradeBase +
+  upgradeSlope`, and a confident jump ignores it. That error happened once
+  (a838f7c).
+
+Not taken: the agent type as a routing signal; a payback check on downgrades
+before shadow data; removing the switching tax from the upgrade bar before a
+replay of the logs. The Pi router rejects the tax-to-confidence formula
+because it mixes dollars with an uncalibrated probability; the replay decides.
+
+## Real-world evaluation (2026-09-23)
+
+A day of dogfooding this repository on the installed plugin: 31 Claude Code
+sessions, 1,578 routed requests, one machine. `decisions.jsonl` holds the
+tier, the reason and the token counts for every request — no prompt text.
+
+![Share of requests by tier, and the input-token cost of the same traffic repriced at Opus's rates](tier-share.svg)
+
+82% of turns never needed more than Sonnet, 10% stayed on Haiku, and 8% needed
+Opus. `medium` (Opus at `high` effort) fired once: a confident vote jumps two
+tiers straight to `high` instead of stopping at `medium` (switching policy,
+rule 4).
+
+Repricing that same traffic — same tokens, same observed cache reads — at
+Opus's rates puts the input-token bill 18.8% above what the router actually
+spent. That number covers input tokens only: the price table has no output
+price (see [Cache and cost inputs](#cache-and-cost-inputs)), so it cannot say
+how much of the real saving is left out — likely more, since Haiku and Sonnet
+also bill less per output token than Opus. Answer quality isn't measured
+here either.
+
+One developer, one day: a dogfood snapshot, not a benchmark.
 
 ## Layout
 
@@ -209,7 +259,7 @@ Agreed with Codex on 2026-09-22. The thresholds are start values.
   lib/config.mjs               defaults, user file, validation
   lib/facts.mjs                request body and memory -> facts (pure)
   lib/jev.mjs                  request, injected transport, parse
-  lib/cost.mjs                 warmth, input cost, switching tax
+  lib/cost.mjs                 cache key, warmth, input cost, switching tax, shadow economics
   lib/policy.mjs               switching policy v0
   lib/rewrite.mjs              model, effort, thinking per model family
   lib/sse.mjs                  usage reader for SSE and JSON bodies
@@ -232,8 +282,16 @@ Agreed with Codex on 2026-09-22. The thresholds are start values.
 - The gateway reads the configuration once. A reload without a restart is not
   implemented.
 - Without `CLAUDE_CODE_GATEWAY_HINT_HEADERS=1`, the gateway guesses side
-  requests and compactions from the body; the guesses miss some.
+  requests from the body; the guesses miss some. A missed side request with
+  a short history also counts as a history break.
 - `x-claude-code-agent-type` is logged, not used: no policy rule reads it yet.
+- Does a downgrade that the shadow estimate says never repays deserve a rule,
+  and does the switching tax belong in the upgrade bar? A replay of
+  `decisions.jsonl` against the `shadow` and `observed` lines decides.
+- Effort changes how much a model writes. The shadow estimate uses the last
+  output size for both routes.
+- Whether tools and system survive an effort change is model-specific; the
+  gateway counts the whole prefix as lost, an upper bound.
 
 ## Release
 

package/docs/configuration.md

@@ -77,7 +77,7 @@ If you agree, it also wraps the status line command:
 ```
 
 The wrapper runs the command after it, then adds one line for a routed
-session, for example `jev-router ▸ opus-5-5 · xhigh`. Without a command
+session, for example `jev-router ▸ opus-5-5 · xhigh · upgrade`. Without a command
 after it, it prints only that line. The path contains the plugin version, so
 run `/router:setup` again after a plugin update.
 
@@ -88,12 +88,16 @@ hint headers:
   get routing. `auxiliary` and `compaction` are side requests and get
   `gateway.auxiliaryTier`.
 - `x-claude-code-context-compacted` on the first request after a compaction.
-  The gateway then drops the cached prefixes of every model.
+  The gateway then drops the cached prefixes of every model, the pending
+  votes and the escalation hold.
 - `x-claude-code-agent-type`, for example `Explore` or `Plan`. It goes to
   `decisions.jsonl` only.
 
-Without the headers, the gateway identifies side requests by their shape and
-a compaction by a context that shrank by more than 20%.
+Without the headers, the gateway identifies side requests by their shape. A
+main request with fewer messages than the last one is a compaction or a
+rewind, with or without the headers: the gateway drops the same state. A
+context that shrank by more than 20% with no fewer messages is context
+editing; it drops only the cached prefixes.
 
 A subagent with `model: inherit` sends `x-claude-code-agent-id` even without
 the hint headers. Each subagent keeps its own routing memory, so its turns do
@@ -123,6 +127,7 @@ path. Nested objects merge.
     "sonnet": {
       "id": "claude-sonnet-5",
       "input": 2,
+      "output": 10,
       "cacheRead": 0.2,
       "contextWindow": 1000000,
       "billing": "plan",
@@ -156,14 +161,18 @@ frontmatter of `skills/<tier>/SKILL.md`. A test makes sure that they agree.
 
 ### models
 
-| Alias    | ID                 | Input | Cache Read | Window | Max output | Billing | Efforts       |
-| -------- | ------------------ | ----- | ---------- | ------ | ---------- | ------- | ------------- |
-| `opus`   | `claude-opus-5-5`  | $4    | $0.2       | 1M     | as sent    | plan    | all           |
-| `sonnet` | `claude-sonnet-5`  | $2    | $0.2       | 1M     | as sent    | plan    | low–xhigh–max |
-| `haiku`  | `claude-haiku-4-5` | $1    | $0.1       | 200k   | 64k        | plan    | none          |
-
-`id` is the model id that the gateway sends to Anthropic. `input` and
-`cacheRead` are list prices in USD per million tokens. `contextWindow` is the
+| Alias    | ID                 | Input | Output | Cache Read | Window | Max output | Billing | Efforts       |
+| -------- | ------------------ | ----- | ------ | ---------- | ------ | ---------- | ------- | ------------- |
+| `opus`   | `claude-opus-5-5`  | $4    | $20    | $0.2       | 1M     | as sent    | plan    | all           |
+| `sonnet` | `claude-sonnet-5`  | $2    | $10    | $0.2       | 1M     | as sent    | plan    | low–xhigh–max |
+| `haiku`  | `claude-haiku-4-5` | $1    | $5     | $0.1       | 200k   | 64k        | plan    | none          |
+
+`id` is the model id that the gateway sends to Anthropic. `input`, `output`
+and `cacheRead` are list prices in USD per million tokens. `output` is
+optional and feeds only the `shadow` estimate in `decisions.jsonl`; the policy
+does not read it. The defaults match `test/fixtures/list-prices.json`, which
+names its source and the date it was checked; a test fails when the two
+differ. `contextWindow` is the
 size of the context window in tokens. `maxOutput`, when set, caps the
 `max_tokens` that Claude Code sends; the API rejects a request above the
 model's output limit. `billing` is `plan` for models that use
@@ -180,12 +189,12 @@ effort and thinking from the request.
 | `gateway.auxiliaryTier`                          | The tier for side requests, for example session titles.                                                                                      |
 | `gateway.idleShutdownMs`                         | The gateway exits after this long without requests, when no turn waits for a tool result. Two hours by default; `0` keeps it running.        |
 | `upgradeVotes`                                   | The number of consecutive votes above the current tier before an upgrade of one tier.                                                        |
-| `upgradeBase`, `upgradeSlope`, `upgradePivotUsd` | The required probability mass: `base + slope * tax / (tax + pivot)`. The `tax` is the extra input cost to read the context on the new model. |
+| `upgradeBase`, `upgradeSlope`, `upgradePivotUsd` | The required probability mass: `base + slope * tax / (tax + pivot)`. The `tax` is the extra input cost to read the context on the new route; the cache is per model and effort. |
 | `jumpConfidence`                                 | The mass that lets a jump of two tiers skip the vote delay.                                                                                  |
 | `downgradeVotes`, `downgradeMass`                | The number of consecutive votes, and the mass at or below the candidate, for a downgrade.                                                    |
 | `continuationMass`                               | The Jev probability for "this prompt continues the task" that keeps the current route.                                                       |
 | `escalationHoldTurns`                            | The number of turns to hold one tier up after two failed repairs of the same error.                                                          |
-| `cashCapUsd`                                     | The cold cache-write cost above which the gateway refuses an automatic route to a `credits` model.                                           |
+| `cashCapUsd`                                     | The cold-write guard: the estimated first cache write above which the gateway refuses an automatic route to a `credits` model whose cache is not warm. Not a budget for the turn: output is not counted. |
 
 ## Environment variables
 

package/docs/tier-share.svg

@@ -0,0 +1,44 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 720 500" font-family="system-ui, -apple-system, 'Segoe UI', sans-serif">
+  <rect width="720" height="500" fill="#fcfcfb"/>
+  <text x="24" y="34" font-size="18" font-weight="700" fill="#0b0b0b">Where the router sent the calls</text>
+  <text x="24" y="56" font-size="13" fill="#898781">one developer, 31 sessions, one day of dogfooding (2026-09-23) — 1578 routed requests</text>
+
+  <text x="24" y="74" font-size="12" font-weight="600" fill="#52514e">SHARE OF REQUESTS BY TIER</text>
+
+  <text x="196" y="111" text-anchor="end" font-size="13" fill="#52514e">micro · Haiku</text>
+  <rect x="210" y="96" width="50.07299270072993" height="22" rx="4" fill="#86b6ef"/>
+  <text x="268.0729927007299" y="111"
+        text-anchor="start" font-size="13" font-weight="600"
+        fill="#0b0b0b">9.8%</text>
+
+  <text x="196" y="157" text-anchor="end" font-size="13" fill="#52514e">low · Sonnet</text>
+  <rect x="210" y="142" width="420" height="22" rx="4" fill="#3987e5"/>
+  <text x="620" y="157"
+        text-anchor="end" font-size="13" font-weight="600"
+        fill="#ffffff">82.2%</text>
+
+  <text x="196" y="203" text-anchor="end" font-size="13" fill="#52514e">medium · Opus (high)</text>
+  <rect x="210" y="188" width="3" height="22" rx="4" fill="#1c5cab"/>
+  <text x="221" y="203"
+        text-anchor="start" font-size="13" font-weight="600"
+        fill="#0b0b0b">0.1%</text>
+
+  <text x="196" y="249" text-anchor="end" font-size="13" fill="#52514e">high · Opus (xhigh)</text>
+  <rect x="210" y="234" width="40.87591240875912" height="22" rx="4" fill="#0d366b"/>
+  <text x="258.8759124087591" y="249"
+        text-anchor="start" font-size="13" font-weight="600"
+        fill="#0b0b0b">8%</text>
+
+  <line x1="24" y1="300" x2="696" y2="300" stroke="#e1e0d9" stroke-width="1"/>
+  <text x="24" y="320" font-size="12" font-weight="600" fill="#52514e">INPUT-TOKEN COST, LIST PRICE — SAME TRAFFIC, REPRICED AT OPUS RATES</text>
+
+  <text x="196" y="355" text-anchor="end" font-size="13" fill="#52514e">router (actual)</text>
+  <rect x="210" y="340" width="341.043219076006" height="22" rx="4" fill="#2a78d6"/>
+  <text x="559.0432190760059" y="355" font-size="13" font-weight="600" fill="#0b0b0b">$114.42</text>
+
+  <text x="196" y="401" text-anchor="end" font-size="13" fill="#52514e">same traffic, Opus prices</text>
+  <rect x="210" y="386" width="420" height="22" rx="4" fill="#c3c2b7"/>
+  <text x="638" y="401" font-size="13" font-weight="600" fill="#0b0b0b">$140.91</text>
+  <text x="24" y="448" font-size="12" fill="#898781">−18.8% on input tokens alone. Output-token price isn't in the model, so real savings are likely larger, not smaller.</text>
+  <text x="24" y="468" font-size="12" fill="#898781">Not measured: answer quality. One machine, one day — a dogfood snapshot, not a benchmark.</text>
+</svg>

package/docs/user-guide.md

@@ -29,13 +29,20 @@ ANTHROPIC_BASE_URL=http://127.0.0.1:43170 claude --plugin-dir . --model jev-rout
   route stays there for two turns. A repair is an edit between the two errors.
 - An upgrade needs two consecutive votes for a higher tier. A jump of two
   tiers with high confidence happens at once. The required confidence goes up
-  with the cost to read the context again on the new model.
+  with the cost to read the context again on the new model. Opus at `high` and
+  Opus at `xhigh` are two caches: a change of effort rewrites the cached
+  conversation, so `medium` to `high` is not free.
 - A downgrade needs two consecutive confident votes.
-- A cold switch to a model that bills usage credits is refused when the cache
-  write costs more than `policy.cashCapUsd`. Then the strongest plan tier
-  serves the turn. Behind the gateway, Claude Code does not show its consent
-  prompt for these credits, so the cap is the only guard. No default model
-  bills credits; this applies once you add one in `router.json`.
+- When the conversation gets shorter, after a compaction or a rewind, the
+  gateway forgets the cached prefixes, the pending votes and the escalation
+  hold. They were about turns that are no longer in the conversation.
+- The cold-write guard: an automatic switch to a model that bills usage
+  credits is refused when that model's cache is not warm and the first cache
+  write would cost more than `policy.cashCapUsd`. Then the strongest plan tier
+  serves the turn. The guard limits that one estimated write, not the cost of
+  the turn: output is not counted. Behind the gateway, Claude Code does not
+  show its consent prompt for these credits. No default model bills credits;
+  this applies once you add one in `router.json`.
 - When Jev fails or times out, or when there is no key, the baseline tier
   serves the turn. After three failures in a row, new turns skip Jev for one
   minute and then try it once, so an outage costs one slow turn a minute, not
@@ -64,12 +71,19 @@ The gateway sends the real model id unchanged.
 ## See the current route
 
 `/router:status` shows the gateway, the routes, and the model, effort and
-reason of the last turn in this session.
+reason of the last turn in this session. It also says why in words, and for
+a vote it shows the estimate: the probability mass, the bar it had to reach,
+the switching tax and whether each cache was `warm`, `expired` or `unknown`.
+`unknown` means no response for that cache since the session started or the
+conversation got shorter. The dollars are list prices. For plan models they
+are a list-price equivalent, not a charge.
 
 The status line wrapper from `/router:setup` adds one line to your status line
 while the session uses the router:
 
-- `jev-router ▸ opus-5-5 · xhigh`: the model and the effort of the last turn.
+- `jev-router ▸ opus-5-5 · xhigh · upgrade`: the model, the effort and the
+  reason of the last turn. `upgrade-pending` means that Jev asked for a higher
+  tier and the policy held the route back.
 - `router: no turn yet`: the session has no routed turn.
 - `router: gateway off, the next prompt starts it`: the gateway stopped after
   idle time, or it crashed. Either way the next prompt starts it.
@@ -84,7 +98,7 @@ the plugin data directory. The directory is
 by hand, the directory is `$TMPDIR/router/`.
 
 ```sh
-tail -n 20 ~/.claude/plugins/data/router-*/decisions.jsonl | jq -c '{tier, reason, estimate, observed}'
+tail -n 20 ~/.claude/plugins/data/router-*/decisions.jsonl | jq -c '{tier, reason, estimate, shadow, observed}'
 ```
 
 `tier` is the selected tier. `reason` is the rule that decided. The `observed`
@@ -92,6 +106,12 @@ lines carry the model that answered, the context tokens and the cache reads
 from the response. Compare the estimated and the observed cache reads to tune
 the thresholds.
 
+`shadow` is what following Jev's choice instead of the current route would
+cost, at list prices: the next turn, each later turn, and the number of turns
+until a cheaper route repays its cache write. The policy does not read it.
+`historyBreak` lines mark a compaction or a rewind; `cacheReset` lines mark a
+context that shrank by more than a fifth.
+
 `scripts/transcript-models.sh <transcript.jsonl>` shows the model for each
 assistant message in a Claude Code transcript.
 
@@ -115,3 +135,6 @@ assistant message in a Claude Code transcript.
 - Rate limits and overload errors from Anthropic (429, 529) reach Claude Code
   unchanged. Claude Code waits and retries; the gateway does not add a second
   layer of retries.
+- Updating from 0.3.0 or earlier: those gateways cannot hand over to a newer
+  one. Stop the old one once with `pkill -f scripts/gateway.mjs`; the next
+  prompt starts the new version.

package/lib/config.mjs

@@ -20,12 +20,14 @@ export const DEFAULTS = {
     micro: { model: 'haiku' },
   },
   // `id` is sent upstream verbatim. List prices in USD per million tokens; `cacheRead` is absolute,
-  // not a multiplier (Opus 5.5 reads at 0.05x input, the rest at the standard 0.1x — verify when prices move).
+  // not a multiplier (Opus 5.5 reads at 0.05x input, the rest at the standard 0.1x). A price change must also change
+  // test/fixtures/list-prices.json, with its source and date. `output` feeds only the shadow estimate in the log.
   // `efforts` lists what the model accepts; an empty list means no effort field and no adaptive thinking.
   models: {
     opus: {
       id: 'claude-opus-5-5',
       input: 4,
+      output: 20,
       cacheRead: 0.2,
       contextWindow: 1_000_000,
       billing: 'plan',
@@ -34,6 +36,7 @@ export const DEFAULTS = {
     sonnet: {
       id: 'claude-sonnet-5',
       input: 2,
+      output: 10,
       cacheRead: 0.2,
       contextWindow: 1_000_000,
       billing: 'plan',
@@ -43,6 +46,7 @@ export const DEFAULTS = {
     haiku: {
       id: 'claude-haiku-4-5',
       input: 1,
+      output: 5,
       cacheRead: 0.1,
       contextWindow: 200_000,
       maxOutput: 64_000,
@@ -116,6 +120,8 @@ function validate(config) {
       if (!Number.isFinite(model[field]) || model[field] < 0)
         throw new Error(`models.${alias}.${field} must be a non-negative number`);
     }
+    if (model.output !== undefined && !(Number.isFinite(model.output) && model.output >= 0))
+      throw new Error(`models.${alias}.output must be a non-negative number`);
     if (typeof model.id !== 'string' || !model.id) throw new Error(`models.${alias}.id is required`);
     if (model.maxOutput !== undefined && !(Number.isInteger(model.maxOutput) && model.maxOutput > 0))
       throw new Error(`models.${alias}.maxOutput must be a positive integer`);

package/lib/cost.mjs

@@ -1,22 +1,46 @@
-// Cache-aware input cost of the next request. Pure arithmetic over configured prices and the gateway's memory.
+// Cache-aware cost of the next request. Pure arithmetic over configured prices and the gateway's memory.
+import { clampEffort } from './rewrite.mjs';
+
+// The prompt cache belongs to a model, and its messages part to the effort too: a top-level effort change rewrites
+// the messages cache. Opus at `high` and Opus at `xhigh` are two caches, not one.
+export function cacheKey(modelId, effort) {
+  return effort ? `${modelId}@${effort}` : modelId;
+}
+
+// The cache a request routed to `tier` uses. `sentEffort` is what Claude Code sent, for a route that keeps it.
+export function routeCacheKey(config, tier, sentEffort) {
+  const model = modelOf(config, tier);
+  return cacheKey(model.id, clampEffort(config.routes[tier].effort ?? sentEffort, model.efforts));
+}
 
 export function isWarm(modelState, now, cache) {
   if (!modelState) return false;
   return now < modelState.lastAt + cache.ttlMs[modelState.ttl] - cache.warmMarginMs;
 }
 
+// For the logs: `unknown` means no response for this cache since the session started or its history broke. The cost
+// arithmetic treats `unknown` and `expired` alike, as a full write.
+export function cacheState(modelState, now, cache) {
+  if (!modelState) return 'unknown';
+  return isWarm(modelState, now, cache) ? 'warm' : 'expired';
+}
+
+function modelOf(config, tier) {
+  return config.models[config.routes[tier].model];
+}
+
 function ttlFor(config, alias, facts) {
   if (config.models[alias].billing === 'credits') return '5m';
   return facts.lastRequest?.ttl ?? '5m';
 }
 
-// USD for the input side of one request on `alias` with `tokens` of context.
-export function inputCostUsd(config, alias, tokens, facts, now) {
+// USD for the input side of one request routed to `tier` with `tokens` of context.
+export function inputCostUsd(config, tier, tokens, facts, now) {
+  const alias = config.routes[tier].model;
   const model = config.models[alias];
-  const state = facts.models[model.id];
+  const state = facts.models[routeCacheKey(config, tier, facts.effort)];
   const reusable = isWarm(state, now, config.cache) ? Math.min(state.prefixTokens, tokens) : 0;
-  const ttl = ttlFor(config, alias, facts);
-  const write = model.input * config.cache.writeMultiplier[ttl];
+  const write = model.input * config.cache.writeMultiplier[ttlFor(config, alias, facts)];
   return (model.cacheRead * reusable + write * (tokens - reusable)) / 1e6;
 }
 
@@ -31,9 +55,30 @@ export function nextContextTokens(facts) {
   return last ? last.tokens + last.outputTokens : 0;
 }
 
-export function switchingTaxUsd(config, candidateAlias, incumbentAlias, facts, now) {
+export function switchingTaxUsd(config, candidateTier, incumbentTier, facts, now) {
   const tokens = nextContextTokens(facts);
   return (
-    inputCostUsd(config, candidateAlias, tokens, facts, now) - inputCostUsd(config, incumbentAlias, tokens, facts, now)
+    inputCostUsd(config, candidateTier, tokens, facts, now) - inputCostUsd(config, incumbentTier, tokens, facts, now)
   );
 }
+
+// Shadow estimate for the decision log; the policy does not read it. At list prices, so for `plan` models it is a
+// list-price equivalent, not a charge. Output uses the last observed output size for both routes, although effort
+// changes how much a model writes.
+// - nextTurnUsd: candidate minus incumbent for the next request, input at the current cache state plus output.
+// - laterTurnUsd: the same difference for each later turn, once both caches are warm.
+// - paybackTurns: 0 when the switch is cheaper at once, n when later turns repay it after n turns, null when never.
+export function shadowEconomics(config, candidateTier, incumbentTier, facts, now) {
+  const candidate = modelOf(config, candidateTier);
+  const incumbent = modelOf(config, incumbentTier);
+  if (candidate.output === undefined || incumbent.output === undefined) return null;
+  const tokens = nextContextTokens(facts);
+  const outputTokens = facts.lastRequest?.outputTokens ?? 0;
+  const outputUsd = ((candidate.output - incumbent.output) * outputTokens) / 1e6;
+  const nextTurnUsd = switchingTaxUsd(config, candidateTier, incumbentTier, facts, now) + outputUsd;
+  const laterTurnUsd = ((candidate.cacheRead - incumbent.cacheRead) * tokens) / 1e6 + outputUsd;
+  let paybackTurns = null;
+  if (nextTurnUsd <= 0 && laterTurnUsd <= 0) paybackTurns = 0;
+  else if (nextTurnUsd > 0 && laterTurnUsd < 0) paybackTurns = Math.ceil(nextTurnUsd / -laterTurnUsd);
+  return { nextTurnUsd, laterTurnUsd, paybackTurns, outputTokens };
+}

package/lib/facts.mjs

@@ -32,6 +32,8 @@ export function factsFromRequest(body, memory, { recentTurns, maxTextChars }) {
     // The same history length and the same last message: Claude Code resent the request (429, 529, a dropped stream).
     turnKey: last?.role === 'user' ? `${messages.length}:${hash(JSON.stringify(last.content))}` : null,
     failure: repeatedFailure(errors, edits, messages.length - 1),
+    // The effort Claude Code sent: a route without its own effort keeps it, and it is part of the cache key.
+    effort: body.output_config?.effort ?? null,
     lastRoute: memory.lastRoute,
     lastRequest: memory.lastRequest,
     models: memory.models,

package/lib/gateway.mjs

@@ -113,7 +113,7 @@ export function createGateway({
       if (reader.stopReason === 'tool_use') activity.turnPaused(session);
       if (!routed || routed.auxiliary) return;
       try {
-        router.recordResponse(session, routed.tier, usage);
+        router.recordResponse(session, routed.tier, usage, routed.effort);
       } catch (recordError) {
         onError(recordError);
       }

package/lib/policy.mjs

@@ -1,6 +1,6 @@
-// Switching policy v0 (docs/design.md): stickiness, escalation floor, cost-gated votes.
+// Switching policy v0 (docs/architecture.md): stickiness, escalation floor, cost-gated votes.
 import { rank, TIERS } from './config.mjs';
-import { coldWriteUsd, isWarm, nextContextTokens, switchingTaxUsd } from './cost.mjs';
+import { cacheState, coldWriteUsd, isWarm, nextContextTokens, routeCacheKey, switchingTaxUsd } from './cost.mjs';
 
 export function initialState() {
   return { turn: 0, votes: [], holdUntilTurn: 0, escalatedSignature: null };
@@ -34,15 +34,13 @@ export function decide({ config, facts, advice, state, baseline, now }) {
       if (rank(gated.fallback) <= rank(incumbent)) return stay('cash-gate', gated.estimate);
       return result(gated.fallback, 'cash-gate', next, gated.estimate);
     }
-    const tax = Math.max(
-      0,
-      switchingTaxUsd(config, config.routes[choice].model, config.routes[incumbent].model, facts, now),
-    );
+    const tax = Math.max(0, switchingTaxUsd(config, choice, incumbent, facts, now));
     const threshold =
       config.policy.upgradeBase + config.policy.upgradeSlope * (tax / (tax + config.policy.upgradePivotUsd));
     const jump = rank(choice) - rank(incumbent) >= 2 && upgrade >= config.policy.jumpConfidence;
     const streak = trailing(next.votes, (v) => rank(v.tier) > rank(incumbent));
-    const estimate = { taxUsd: tax, threshold, upgradeMass: upgrade, streak };
+    const cache = { candidate: cacheOf(config, choice, facts, now), incumbent: cacheOf(config, incumbent, facts, now) };
+    const estimate = { taxUsd: tax, threshold, upgradeMass: upgrade, streak, cache };
     if (jump || (streak >= config.policy.upgradeVotes && upgrade >= threshold))
       return result(choice, jump ? 'jump' : 'upgrade', next, estimate);
     return stay('upgrade-pending', estimate);
@@ -73,16 +71,22 @@ export function fitTier(config, tier, tokens) {
   );
 }
 
-// Automatic routing to a credits-billed model must fit the cash cap unless its cache is warm.
+// Cold-write guard: an automatic route to a credits-billed model whose cache is not warm must not start with a cache
+// write above `cashCapUsd`. It bounds that one estimated write, not the spend of the turn: a warm cache passes, and
+// output is not counted.
 function cashGate(config, tier, facts, now) {
   const alias = config.routes[tier].model;
-  const model = config.models[alias];
-  if (model.billing !== 'credits') return { blocked: false };
-  if (isWarm(facts.models[model.id], now, config.cache)) return { blocked: false };
+  if (config.models[alias].billing !== 'credits') return { blocked: false };
+  if (isWarm(facts.models[routeCacheKey(config, tier, facts.effort)], now, config.cache)) return { blocked: false };
   const cold = coldWriteUsd(config, alias, nextContextTokens(facts), facts);
   if (cold <= config.policy.cashCapUsd) return { blocked: false };
   const fallback = [...TIERS].reverse().find((t) => config.models[config.routes[t].model].billing === 'plan');
-  return { blocked: true, fallback, estimate: { coldUsd: cold, cap: config.policy.cashCapUsd } };
+  const estimate = { coldUsd: cold, cap: config.policy.cashCapUsd, cache: cacheOf(config, tier, facts, now) };
+  return { blocked: true, fallback, estimate };
+}
+
+function cacheOf(config, tier, facts, now) {
+  return cacheState(facts.models[routeCacheKey(config, tier, facts.effort)], now, config.cache);
 }
 
 function trailing(votes, predicate) {

package/lib/router.mjs

@@ -1,6 +1,6 @@
 // Per-request orchestration: facts -> advice -> policy -> rewritten body. Knows nothing about HTTP.
-import { LEGACY_ALIAS } from './config.mjs';
-import { nextContextTokens } from './cost.mjs';
+import { LEGACY_ALIAS, TIERS } from './config.mjs';
+import { cacheKey, nextContextTokens, shadowEconomics } from './cost.mjs';
 import { factsFromRequest } from './facts.mjs';
 import { askJev } from './jev.mjs';
 import { decide, fitTier, initialState } from './policy.mjs';
@@ -20,14 +20,23 @@ export function emptyMemory() {
   return {
     lastRoute: null,
     lastReason: null,
+    lastEstimate: null,
     lastEffort: null,
     lastRequest: null,
     lastTurnKey: null,
+    lastMessageCount: null,
     models: {},
     state: null,
   };
 }
 
+// The history the gateway saw is gone: a compaction or a rewind. The cached prefixes are unknown, and the votes and
+// the escalation hold were about turns that are no longer in it. The route stays until the next decision.
+function restartHistory(memory) {
+  memory.models = {};
+  if (memory.state) memory.state = { ...memory.state, votes: [], holdUntilTurn: 0, escalatedSignature: null };
+}
+
 export class Router {
   constructor({ config, fetchFn, dataDir, now = Date.now, onError = () => {} }) {
     this.config = config;
@@ -49,10 +58,16 @@ export class Router {
   // The hints come from Claude Code's gateway headers (CLAUDE_CODE_GATEWAY_HINT_HEADERS=1); each may be missing.
   async route(body, { sessionId, requestClass = null, agentType = null, contextCompacted = null }) {
     const memory = this.memory(sessionId);
-    // The compaction rewrote the conversation: no model has its prefix cached any more.
-    if (contextCompacted) memory.models = {};
-    const facts = factsFromRequest(body, memory, this.config.context);
     const auxiliary = requestClass ? SIDE_REQUEST_CLASSES.has(requestClass) : isAuxiliaryShape(body);
+    // Messages only grow within one history. Fewer than the last main request: Claude Code compacted the conversation
+    // or the user rewound it. Context editing clears tool results but keeps the messages, so it is not a break.
+    const messageCount = Array.isArray(body.messages) ? body.messages.length : 0;
+    const rewound = !auxiliary && memory.lastMessageCount !== null && messageCount < memory.lastMessageCount;
+    if (contextCompacted || rewound) {
+      restartHistory(memory);
+      this.log({ session: sessionId, historyBreak: contextCompacted ? 'compaction' : 'shorter-history' });
+    }
+    const facts = factsFromRequest(body, memory, this.config.context);
     let decision;
     if (auxiliary) decision = { tier: this.config.gateway.auxiliaryTier, reason: 'auxiliary', state: memory.state };
     else if (facts.continuation && memory.lastRoute)
@@ -66,11 +81,16 @@ export class Router {
       if (tier !== decision.tier) decision = { ...decision, tier, reason: 'context-fit' };
     }
     const rewritten = rewriteRequest(body, decision.tier, this.config);
+    const effort = rewritten.output_config?.effort ?? null;
     if (!auxiliary) {
       memory.lastRoute = decision.tier;
-      memory.lastEffort = rewritten.output_config?.effort ?? null;
+      memory.lastEffort = effort;
       memory.lastTurnKey = facts.turnKey;
-      if (!REUSED_ROUTE.has(decision.reason)) memory.lastReason = decision.reason;
+      memory.lastMessageCount = messageCount;
+      if (!REUSED_ROUTE.has(decision.reason)) {
+        memory.lastReason = decision.reason;
+        memory.lastEstimate = decision.estimate ?? null;
+      }
       memory.state = decision.state;
       this.persist(sessionId, memory);
     }
@@ -81,6 +101,7 @@ export class Router {
       tier: decision.tier,
       reason: decision.reason,
       estimate: decision.estimate ?? null,
+      shadow: decision.shadow ?? null,
       advice: decision.advice ?? null,
       adviceError: decision.adviceError ?? null,
       contextTokens: memory.lastRequest?.tokens ?? 0,
@@ -88,6 +109,7 @@ export class Router {
     return {
       body: rewritten,
       tier: decision.tier,
+      effort,
       reason: decision.reason,
       auxiliary,
     };
@@ -130,15 +152,15 @@ export class Router {
         }
       }
     }
-    const decision = decide({
-      config: this.config,
-      facts,
-      advice,
-      state,
-      baseline: gateway.baselineTier,
-      now: this.now(),
-    });
-    return { ...decision, advice, adviceError };
+    const now = this.now();
+    const decision = decide({ config: this.config, facts, advice, state, baseline: gateway.baselineTier, now });
+    // Shadow only: what following Jev's choice instead of staying would cost at list prices. The policy ignores it.
+    const incumbent = TIERS.includes(facts.lastRoute) ? facts.lastRoute : gateway.baselineTier;
+    const shadow =
+      TIERS.includes(advice?.choice) && advice.choice !== incumbent
+        ? shadowEconomics(this.config, advice.choice, incumbent, facts, now)
+        : null;
+    return { ...decision, advice, adviceError, shadow };
   }
 
   jevSucceeded() {
@@ -160,15 +182,19 @@ export class Router {
       );
   }
 
-  // Called with the usage the gateway read from a forwarded main-conversation response.
-  recordResponse(sessionId, tier, usage) {
+  // Called with the usage the gateway read from a forwarded main-conversation response, and the effort the gateway
+  // sent with that request: the cache is keyed by both.
+  recordResponse(sessionId, tier, usage, effort = null) {
     if (!usage) return;
     const memory = this.memory(sessionId);
     const modelId = usage.model ?? this.config.models[this.config.routes[tier].model].id;
     const at = this.now();
-    // A context that shrank is a compaction: every model's cached prefix is gone. Without the hint headers this is
-    // the only sign of a compaction.
-    if (memory.lastRequest && usage.tokens < memory.lastRequest.tokens * COMPACTION_SHRINK) memory.models = {};
+    // A context that shrank by more than a fifth: a compaction, or context editing that cleared old tool results.
+    // Either way the cached prefixes no longer match. The votes stay: a shorter history in messages resets them.
+    if (memory.lastRequest && usage.tokens < memory.lastRequest.tokens * COMPACTION_SHRINK) {
+      memory.models = {};
+      this.log({ session: sessionId, cacheReset: 'context-shrink' });
+    }
     memory.lastRequest = {
       model: modelId,
       tokens: usage.tokens,
@@ -177,7 +203,11 @@ export class Router {
       ttl: usage.ttl,
       at,
     };
-    memory.models[modelId] = { lastAt: at, prefixTokens: usage.tokens + usage.outputTokens, ttl: usage.ttl };
+    memory.models[cacheKey(modelId, effort)] = {
+      lastAt: at,
+      prefixTokens: usage.tokens + usage.outputTokens,
+      ttl: usage.ttl,
+    };
     this.persist(sessionId, memory);
     this.log({ session: sessionId, observed: { ...usage, model: modelId, tier } });
   }

package/lib/status.mjs

@@ -34,6 +34,7 @@ export function statusSnapshot(config, memory) {
       ? {
           tier: memory.lastRoute,
           reason: memory.lastReason ?? null,
+          estimate: memory.lastEstimate ?? null,
           effort: memory.lastEffort ?? null,
           model: memory.lastRequest?.model ?? null,
           tokens: memory.lastRequest?.tokens ?? null,
@@ -51,14 +52,32 @@ function routeRow(config, tier) {
   return { tier, model: model.id, effort };
 }
 
-// One status-line segment, e.g. "router ▸ opus-5-5 · xhigh".
+// Why the route of the last turn is what it is, for /router:status.
+const REASONS = {
+  upgrade: 'Jev voted above the current tier often enough, with enough mass for the switching tax',
+  jump: 'Jev was confident enough to skip a tier and the vote delay',
+  downgrade: 'Jev voted for a lower tier often enough, with enough mass',
+  'upgrade-pending': 'Jev asked for a higher tier; the route stays until the votes and the mass are enough',
+  'downgrade-pending': 'Jev asked for a lower tier; the route stays until the votes and the mass are enough',
+  'same-tier': 'Jev agreed with the current tier',
+  continuation: 'the prompt continues the task, so the route stays',
+  uncertain: 'Jev abstained, so the route stays',
+  'no-advice': 'no Jev answer (no key, a failure or a pause), so the route stays',
+  escalation: 'the same error came back after an edit: one tier up',
+  hold: 'the tier stays up for a few turns after an escalation',
+  'cash-gate':
+    'cold-write guard: the first cache write on a credits model would cost more than policy.cashCapUsd, so the strongest plan tier served',
+  'context-fit': "the chosen model's window does not hold the context",
+  forced: 'ROUTER_FORCE_TIER is set',
+};
+
+// One status-line segment, e.g. "router ▸ opus-5-5 · xhigh · upgrade".
 export function statusSegment(status) {
   if (!status) return 'router: gateway off, the next prompt starts it';
   const last = status.session;
   if (!last) return `${status.alias}: no turn yet`;
   const model = shortModel(last.model ?? status.routes.find((r) => r.tier === last.tier)?.model);
-  const effort = last.effort ? ` · ${last.effort}` : '';
-  return `${status.alias} ▸ ${model}${effort}`;
+  return [`${status.alias} ▸ ${model}`, last.effort, last.reason].filter(Boolean).join(' · ');
 }
 
 // Markdown for /router:status.
@@ -82,10 +101,32 @@ export function statusReport(status) {
     const effort = last.effort ? ` at ${last.effort}` : '';
     const context = last.tokens ? `, context ${last.tokens} tokens, cache reads ${last.cacheReadTokens}` : '';
     lines.push(`Last turn: ${last.tier} → ${model}${effort}, reason ${last.reason ?? 'unknown'}${context}.`);
+    if (REASONS[last.reason]) lines.push(`Why: ${REASONS[last.reason]}.`);
+    const estimate = describeEstimate(last.estimate);
+    if (estimate) lines.push(`Estimate: ${estimate}.`);
   }
   return lines.join('\n');
 }
 
+// Dollars are list prices: for `plan` models a list-price equivalent, not a charge. `unknown` cache: no response for
+// that cache since the session started or its history broke.
+function describeEstimate(e) {
+  if (!e) return null;
+  const usd = (n) => `$${n.toFixed(2)}`;
+  const parts = [];
+  if (e.upgradeMass !== undefined)
+    parts.push(
+      `upgrade mass ${e.upgradeMass.toFixed(2)} against a bar of ${e.threshold.toFixed(2)}`,
+      `switching tax ${usd(e.taxUsd)} at list prices`,
+    );
+  if (e.downgradeMass !== undefined) parts.push(`downgrade mass ${e.downgradeMass.toFixed(2)}`);
+  if (e.coldUsd !== undefined) parts.push(`cold write ${usd(e.coldUsd)} against the cap of ${usd(e.cap)}`);
+  if (e.streak !== undefined) parts.push(`${e.streak} vote(s) in a row`);
+  if (e.cache?.candidate) parts.push(`cache: candidate ${e.cache.candidate}, current ${e.cache.incumbent}`);
+  else if (typeof e.cache === 'string') parts.push(`cache ${e.cache}`);
+  return parts.join(', ');
+}
+
 // null when the gateway does not answer in time.
 export async function fetchStatus(port, sessionId) {
   const query = sessionId ? `?session=${encodeURIComponent(sessionId)}` : '';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alexeiled/claude-router",
-  "version": "0.6.0",
+  "version": "0.6.1",
   "description": "Claude Code plugin: auto-picks the right model and effort for each turn using Jev routing.",
   "license": "MIT",
   "author": "Alexei Ledenev",