auto-model-router 0.2.31 → 0.3.0

package/.omp-plugin/marketplace.json

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

package/README.md

@@ -3,10 +3,13 @@
 **[Website & benchmarks →](https://drewappling.github.io/auto-model-router/)**
 
 A local model router for [Oh My Pi](https://github.com/oh-my-pi). It presents
-itself as one keyless OpenAI-compatible provider, then picks a concrete
-OpenRouter model **per turn** based on measured price and estimated task
-complexity — including mid-conversation, when a session shifts from mechanical
-tool-loop churn to genuine reasoning work.
+itself as one keyless OpenAI-compatible provider, then picks a concrete model
+**per turn** — from OpenRouter's catalog, and from
+[Ollama Cloud](#ollama-cloud) when that is enabled too — based on measured
+price and estimated task complexity, including mid-conversation, when a
+session shifts from mechanical tool-loop churn to genuine reasoning work.
+With both providers on, every turn ranks the candidates of both together and
+fails over across them.
 
 auto-model-router runs **embedded inside the omp process** (as an omp extension) — no
 separate server, no orphaned process. It binds a free OS-assigned port and
@@ -145,12 +148,17 @@ Harness, tasks and raw per-turn data:
 graph LR
   omp[omp process] -->|OpenAI chat completions| wire[wire/openai]
   wire -->|NormRequest| router[router]
-  catalog[catalog<br/>OpenRouter /models] --> router
+  orcat[OpenRouter /models] --> catalog[catalog<br/>one merged snapshot]
+  olcat[Ollama /api/tags + prices<br/>optional] --> catalog
+  catalog --> router
   cost[cost<br/>forecast + ledger] --> router
   router -->|Decision| guard[escalation guard]
-  guard -->|rendered body| up[upstream/openrouter]
-  up -->|UpstreamChunk| guard
-  guard -->|commit or retry upward| wire
+  guard -->|rendered body| up[upstream/multi<br/>by slug prefix]
+  up --> or[openrouter]
+  up --> ol[ollama<br/>ollama/… slugs]
+  or -->|UpstreamChunk| guard
+  ol -->|UpstreamChunk| guard
+  guard -->|commit, fail over, or retry upward| wire
   guard -->|usage + reported cost| cost
 ```
 
@@ -163,15 +171,15 @@ without touching routing.
 
 | Path | Responsibility |
 | --- | --- |
-| `src/catalog/` | Fetch and normalize OpenRouter `/api/v1/models`: pricing, capability flags, Artificial Analysis quality indices. SQLite-cached with TTL. |
-| `src/cost/` | Cost forecasting per candidate; reconciliation against OpenRouter's authoritative `usage.cost`; the spend ledger; per-model trust; rolling blended rate. |
+| `src/catalog/` | Fetch and normalize OpenRouter `/api/v1/models`: pricing, capability flags, Artificial Analysis quality indices. SQLite-cached with TTL. `ollama-catalog.ts` builds Ollama Cloud models from `/api/tags`, a shipped price table and OpenRouter twins; `composite.ts` merges the two into one snapshot. |
+| `src/cost/` | Cost forecasting per candidate; reconciliation against OpenRouter's authoritative `usage.cost`; the spend ledger; per-model trust; rolling blended rate; `report.ts` usage analytics. |
 | `src/tokens/` | Token estimation with no tokenizer dependency, self-calibrating from observed `prompt_tokens` per tokenizer family. |
 | `src/wire/` | Protocol boundary. `wire/openai/` implements chat completions in and SSE out. |
 | `src/router/` | Feature extraction, complexity classification, candidate filtering and scoring, hysteresis, cache-breakpoint placement, budget guard, probe planning. |
-| `src/upstream/` | OpenRouter transport: streaming dispatch, `session_id` stickiness, error classification, fallback arrays. |
+| `src/upstream/` | Transports: OpenRouter (streaming dispatch, `session_id` stickiness, error classification, fallback arrays) and Ollama Cloud (body rewrite for its compatibility layer, quota/rate-limit breaker); `multi.ts` dispatches by slug prefix. |
 | `src/config/` | Configuration loading, schema validation, and the built-in defaults. |
-| `src/cli/` | `serve`, `stats`, `models`, `explain`, `config` commands. |
-| `omp-extension/` | The omp extensions: `router-embed.ts`, `router-toast.ts`, `router-configure.ts`. |
+| `src/cli/` | `serve`, `stats`, `report`, `models`, `explain`, `config` commands. |
+| `omp-extension/` | The omp extensions: `router-embed.ts`, `router-toast.ts`, `router-configure.ts` (`/router` config, report, status). |
 
 ### Two cost numbers, never conflated
 
@@ -204,7 +212,7 @@ Then add the shipped extensions to omp's `~/.omp/agent/config.yml`
 extensions:
   - auto-model-router/omp-extension/router-embed.ts
   - auto-model-router/omp-extension/router-toast.ts      # optional: chosen-model toasts
-  - auto-model-router/omp-extension/router-configure.ts # optional: /router command
+  - auto-model-router/omp-extension/router-configure.ts # optional: /router config, report, status
 ```
 
 ### From the repo (cross-platform installer)
@@ -227,7 +235,7 @@ The installer adds:
 
 - `router-embed.ts` — **required**; runs the router in-process.
 - `router-toast.ts` — optional; chosen-model toasts.
-- `router-configure.ts` — optional; the `/router` command.
+- `router-configure.ts` — optional; the `/router` command (configure, usage reports, status).
 
 Or add the paths by hand to omp's `~/.omp/agent/config.yml`:
 
@@ -236,7 +244,7 @@ Or add the paths by hand to omp's `~/.omp/agent/config.yml`:
 extensions:
   - /path/to/auto-model-router/omp-extension/router-embed.ts
   - /path/to/auto-model-router/omp-extension/router-toast.ts      # optional: chosen-model toasts
-  - /path/to/auto-model-router/omp-extension/router-configure.ts # optional: /router command
+  - /path/to/auto-model-router/omp-extension/router-configure.ts # optional: /router config, report, status
 ```
 
 Then restart the omp session (extensions load at session start).
@@ -405,7 +413,11 @@ Your OpenRouter guardrails — model and provider allowlists, budget limits,
 Zero-Data-Retention and privacy rules — are therefore the router's outer
 boundary: a model your key cannot reach is never a routing candidate. The
 catalog is refetched in the background every `catalogRefreshMs` (default 5 min),
-so tightening or relaxing a guardrail is picked up without a restart. If a
+so tightening or relaxing a guardrail is picked up without a restart. A refresh
+that keeps fewer than half the previous models is adopted (your guardrails are
+authoritative) but logged at `warn` and reported as `catalog.shrink` on
+`GET /health` until the catalog recovers, because a sharp shrink reroutes every
+turn onto whatever survived. If a
 guardrail narrows the eligible set below a tier's quality floor,
 `adaptiveTierFloors` (on by default) relaxes that tier to the best available
 models rather than leaving it empty — see [Adaptive tier floors](#adaptive-tier-floors)
@@ -465,6 +477,40 @@ virtual profile it picked. Every routed response carries
 
 ---
 
+## Usage reports
+
+The ledger records every dispatch: model decided and served, tier, provider,
+tokens (including cached), reported cost, time to first token, total latency,
+escalation signal, error. Three views aggregate it, all from the same
+`buildUsageReport` in `src/cost/report.ts`:
+
+- `/router report` in omp — a fullscreen hub with the `/models` look: views
+  for overview, providers, models, tiers, by day and status in a sidebar, plus
+  a Window selector (24h / 7d / 30d / 90d) and, when `OMP_HARNESS_ID` is set,
+  a scope toggle between this harness and all harnesses. ↑/↓ move, Enter
+  applies a window or scope, ←/→ also cycle the window, PgUp/PgDn scroll, r
+  reloads, Esc closes. Headless sessions get the same report as text in the
+  transcript. Falls back to reading the ledger directly if the router is
+  unreachable.
+- `auto-model-router report --days 7 [--harness <id>] [--json]` on the terminal.
+- `GET /v1/router/report?days=7&harness=<id>` for dashboards.
+
+What it shows, for the window:
+
+| Block | Columns |
+| --- | --- |
+| totals | spend, dispatches, conversations, $/dispatch, prompt and completion tokens, cache hit rate, model switches, escalations, failovers, errors (aborted separately) |
+| providers | per upstream (`openrouter`, `ollama`): dispatches, spend, share, cache hit, mean TTFT, tokens/s, escalations, errors |
+| models | per served slug (top 12 by spend): the same plus the tier mix it was routed for |
+| tiers | per tier: dispatches, spend, share, cache hit, mean prompt tokens, escalations |
+| by day | UTC calendar days: dispatches, spend, cache hit |
+
+Spend follows the ledger's rule — the provider's reported cost when it gave
+one, else the usage-priced figure the router computed, else the forecast.
+Speed uses only clean streamed rows (TTFT recorded, no error); tokens/s is
+completion tokens over time after first token. Ollama Cloud does not report
+cached tokens, so its cache column reads 0% by construction.
+
 ## Configuring the router
 
 The router's own config lives at `$AUTO_MODEL_ROUTER_HOME/config.yml` (default
@@ -474,12 +520,23 @@ built-in defaults below. There are two ways to edit it:
 ### Via `/router` (in-omp, native UI)
 
 Install the `router-configure` extension, restart omp, then run `/router` in
-the session prompt. It shows a section picker (Server, OpenRouter, Tiers,
-Tasks, Filters, Classifier, Escalation, Hysteresis, Cache, Budget, Ledger,
-Logging, Profiles). Each field prompts through omp's native UI dialogs —
-empty input keeps the current value, `-` clears an optional field. `Save and
-exit` writes the merged config (schema-checked and backed up first). Restart
-the omp session after saving.
+the session prompt. With no arguments it shows a menu (Configure, Report,
+Status); the subcommands go straight there:
+
+| Command | What it does |
+| --- | --- |
+| `/router config` | Section picker over **every** config key: Server, OpenRouter, Ollama Cloud, Benchmarks, Tiers, Tasks, Filters, Classifier, Escalation, Hysteresis, Exploration, Cache, Compaction, Context (agentdox), Budget, Ledger, Logging, Profiles. Only `ollama.prices` and `ollama.twins` (maps) stay YAML-only. |
+| `/router report` | Usage analytics in a fullscreen hub styled like `/models`: pick a view in the sidebar, set the window (24h / 7d / 30d / 90d) and the harness scope there too. `/router report 30d --all` presets them. See [Usage reports](#usage-reports). |
+| `/router status` | The router's `/health`: key sources, catalog size and age, Ollama availability, plan usage and cost bias, agentdox bridge. |
+
+Picking a section lists its fields with their current values (pending edits
+marked), so you see the settings before choosing one to change. Each field
+dialog names the current value in its title, marks it in pickers and uses it
+as the placeholder — empty input keeps it, `-` clears an optional field,
+credentials show as `set`/`unset` and are never echoed. `Save and exit` writes the merged config
+(schema-checked and backed up first). Tier, task, filter, classifier,
+hysteresis, exploration, compaction, cache and budget changes hot-reload;
+restart omp for `server`, `openrouter`, `ollama`, `context` and `ledger`.
 
 ### Via `auto-model-router config` (text wizard / CLI)
 
@@ -541,6 +598,30 @@ what each one does. All values are optional; omit a key to use its default.
 | `catalogTtlMs` | `21600000` (6 h) | How long the model catalog is cached before a forced refetch. |
 | `catalogRefreshMs` | `300000` (5 min) | Background catalog refetch interval; `0` disables it. |
 
+### `ollama` — Ollama Cloud as a second upstream
+
+Off by default. When enabled, Ollama Cloud models join the same catalog as
+OpenRouter's under `ollama/<id>` slugs and are ranked on the same economics:
+a turn picks whichever provider's model is cheapest above the tier's floor,
+and same-tier failover crosses providers (a 402 or 429 from Ollama retries on
+an OpenRouter sibling). See [Ollama Cloud](#ollama-cloud) below.
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `enabled` | `false` | Master switch. |
+| `baseUrl` | `http://127.0.0.1:11434/v1` | A local daemon (proxies `:cloud` models under its sign-in) or `https://ollama.com/v1`. |
+| `apiKey` | unset | Bearer for ollama.com. Resolved from config, then `OLLAMA_API_KEY`, then omp's own auth store (`/login ollama-cloud` in omp) — the same borrowing as the OpenRouter key. The daemon needs none. |
+| `timeoutMs` | `600000` | Per-request timeout. |
+| `catalogTtlMs` | `300000` | Re-list models when the last listing is older than this. |
+| `includeLocal` | `false` | Also expose the daemon's local models (only those named in `prices`). |
+| `prices` | `{}` | USD per million tokens by bare cloud name (`{input, cachedInput?, output}`); overrides or extends the shipped snapshot. |
+| `twins` | `{}` | Bare cloud name → OpenRouter slug, to pin a quality-score twin the name match misses. |
+| `costBias` | `1` | Multiplier on Ollama models' effective cost in ranking; below 1 prefers Ollama. The ledger still records list price. |
+| `biasUntilUsage` | `0.9` | Share of the plan's included monthly credits at which `costBias` switches off and Ollama ranks at list price. Read live from ollama.com's `/api/usage`, which reports usage relative to the plan, so the same value is right on Pro, Max or Team. `1` keeps the bias regardless. |
+| `usagePollMs` | `600000` (10 min) | How often plan usage is re-read. `0` disables it (static bias). Needs the API key; the daemon path without one keeps a static bias. |
+| `quotaCooldownMs` | `900000` | Route around Ollama this long after a 402 (credits exhausted). |
+| `rateLimitCooldownMs` | `60000` | Route around Ollama this long after a 429 (concurrency cap). |
+
 ### `tiers` — per-tier economic envelope
 
 Each tier (`trivial`, `simple`, `moderate`, `hard`) is a `tierConfig`:
@@ -577,6 +658,10 @@ Each task (`coding`, `vision`, `documentation`, `data`, `chat`) is a
 | `minTrustSamples` | `12` | Attempts before trust is enforced. |
 | `trustScopedByHarness` | `false` | `true` = each harness reads only its own trust rows. |
 | `contextHeadroom` | `1.25` | Fraction of context kept free (a model must fit prompt × this). |
+| `latencyWeight` | `0` | How hard to penalise slow models in scoring (soft multiplier on effective cost). `0` disables it. |
+| `latencyMinSamples` | `20` | Streamed samples before latency is judged against a model. |
+| `maxExpectedWaitMs` | unset | Absolute expected-wait ceiling (ms): a hard drop for models *proven* slower (≥ `latencyMinSamples`), regardless of price. The soft penalty is multiplicative and capped, so it cannot demote a slow-but-cheap model — this can. New models keep their cold-start turns; relaxed with trust in tier rescue. Undefined ⇒ off. |
+| `escalationCostWeight` | `0` | Price a model's measured escalation rate at what an escalated retry actually bills (the ledger's $/prompt-token of `attempt > 0` rows), 0–1. The trust divisor reads a 4% escalation rate as a 4% surcharge; the real cost is a whole re-dispatch on the next tier's model. `0` disables the term. |
 
 ### `classifier` — complexity adjudication
 
@@ -591,6 +676,7 @@ Each task (`coding`, `vision`, `documentation`, `data`, `chat`) is a
 | `toolAxis` | `coding` | Quality axis for tool-heavy turns. |
 | `chatAxis` | `intelligence` | Quality axis for chat turns. |
 | `agenticLoopDepth` | `3` | Tool-loop depth at which a turn is treated as agentic. |
+| `mechanicalRetryFactor` | `0.2` | Fraction of the failed-tool and circular-call weights kept on a tool-result continuation; `1` disables the damping. |
 
 ### `escalation` — mid-stream retry upward
 
@@ -604,6 +690,14 @@ Each task (`coding`, `vision`, `documentation`, `data`, `chat`) is a
 | `triggers` | 5 signals | `malformed_tool_args`, `refusal`, `empty_completion`, `repeat_tool_call`, `missing_expected_tool_call`. |
 | `escalateOnLengthStop` | `true` | Escalate on a `length` finish that truncated tool-call args. |
 
+The model that produced the rejected output never serves the retry, at this
+tier or the next. Signals that indict the *provider* rather than the tier —
+`empty_completion`, `refusal`, and an error finish — first try a different
+model in the **same** tier (bounded, like a 5xx failover) and only then step
+up; structural signals (`malformed_tool_args`, `repeat_tool_call`, a truncated
+tool call) escalate a tier directly. A client that hangs up after the finish
+event has already arrived is treated as a completed turn, not an error.
+
 ### `hysteresis` — cache-aware model stickiness
 
 | Key | Default | Meaning |
@@ -611,8 +705,30 @@ Each task (`coding`, `vision`, `documentation`, `data`, `chat`) is a
 | `holdTurns` | `2` | Hold a chosen model this many turns before it can downgrade. |
 | `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. |
 | `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. |
+
+### `compaction` — shrink stale tool output before dispatch
+
+Off by default; see `docs/context-optimization.md`. Every edit shrinks one
+tool-result's content in place behind a re-run breadcrumb, never removes or
+reorders a message, and the plan is persisted per conversation so already
+shrunk results stay shrunk (rewriting them would break the prompt cache).
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `enabled` | `false` | Master switch. |
+| `budgetTokens` | `40000` | Compact when the (already compacted) prompt exceeds this many tokens. |
+| `floorRatio` | `1` | Once compaction fires, compact down to this fraction of the budget so the plan holds for several turns. |
+| `replanGrowthRatio` | `1` | Above 1, only extend an existing plan once the compacted prompt has grown by this factor since the plan was made. Rations plan churn when the budget is unreachable (every turn over budget); fit-to-window is never rationed. |
+| `fitToWindow` | `true` | Also compact when the prompt would overflow the profile's context window. |
+| `protectRecentTurns` | `4` | Never touch the last N user/assistant turns or the volatile tail. |
+| `maxToolResultBytes` | `4096` | Tool results larger than this (outside the protected window) are truncated. |
+| `keepHeadBytes` / `keepTailBytes` | `512` / `512` | Bytes kept around the elision breadcrumb. |
+| `elideSupersededReads` | `true` | Stub an older result when a newer call to the same resource supersedes it. |
+| `collapseDuplicateResults` | `true` | Collapse byte-identical repeated results to a single copy. |
 
 ### `cache` — prompt-cache breakpoints
 
@@ -658,9 +774,62 @@ Each profile is a complete entry (arrays replace wholesale):
 
 | Key | Default | Meaning |
 | --- | --- | --- |
-| `adaptiveTierFloors` | `true` | Derive tier floors from the models actually available (relaxing, never raising, the configured floors). |
+| `adaptiveTierFloors` | `true` | Relax a tier's quality floor to a catalog-derived band when fewer than three available models meet the configured floor (never raising it). A floor that three or more models meet stands as written. |
 | `logLevel` | `info` | `silent`/`error`/`warn`/`info`/`debug`. |
 
+## Ollama Cloud
+
+[Ollama Cloud](https://ollama.com/cloud) hosts open models behind Ollama's own
+OpenAI-compatible endpoint and bills them per token against a plan's monthly
+credits. The router can treat it as a second upstream next to OpenRouter:
+
+```yaml
+ollama:
+  enabled: true
+  # default: the local daemon, which proxies `:cloud` models under whatever
+  # account `ollama signin` used. For ollama.com directly:
+  # baseUrl: https://ollama.com/v1
+  # apiKey: <from https://ollama.com/settings/keys, or OLLAMA_API_KEY, or
+  #          borrowed from omp after `/login ollama-cloud` — no copy needed>
+```
+
+What happens once it is on:
+
+- **One catalog.** Every cloud model Ollama lists becomes `ollama/<id>` (for
+  example `ollama/glm-5.3-flash:cloud` through the daemon, `ollama/glm-5.3-flash`
+  on ollama.com) with the context length and capabilities Ollama publishes
+  (`/api/tags` on the daemon, `/api/show` on ollama.com).
+- **Prices come from a shipped table**, because no Ollama endpoint publishes
+  them: the rates on [ollama.com/pricing](https://ollama.com/pricing) as of
+  2026-09-05 (`src/catalog/ollama-prices.ts`). `ollama.prices` overrides or
+  extends it; a model with no rate from either is left out, on the same rule
+  that drops unpriced OpenRouter models.
+- **Quality scores come from the OpenRouter twin.** Ollama publishes none, so
+  `glm-5.3-flash` inherits `z-ai/glm-5.3-flash`'s indices by name match, which
+  is what lets it serve `simple` and above. `ollama.twins` pins a match the
+  name normaliser cannot make; an unmatched model is unscored and serves only
+  `trivial`.
+- **Same economics, same failover.** Candidates from both providers are ranked
+  together; `costBias` tilts the comparison while a plan's included credits
+  would otherwise go unused. **Credit-aware by default:** the router reads the
+  plan's usage from ollama.com (`/api/usage`, the same figure the dashboard
+  shows, as a share of the plan's included credits) every `usagePollMs`, and
+  once it passes `biasUntilUsage` (90%) Ollama ranks at list price for the rest
+  of the billing month. Because the figure is relative to the plan, nothing
+  about Pro, Max or Team needs configuring; `/health` shows the raw reading
+  and the multiplier in force. A 402 (credits exhausted) or 429 (concurrency cap) from
+  Ollama fails the attempt over to an OpenRouter sibling in the same tier and
+  opens a breaker, so following turns route straight to OpenRouter without
+  paying a doomed dispatch first; `/health` shows `ollama.available` and the
+  cooldown.
+- **Ollama reports no cost per response**, so the ledger records the
+  predicted figure at list price for those rows.
+
+Ollama's compatibility layer differs from OpenRouter's in a few ways the
+router handles for you: no `models[]` fallback cascade, no `tool_choice`,
+`reasoning_effort` instead of the `reasoning` object, and no `cache_control`
+markers (they are stripped before dispatch).
+
 ## Multiple coding harnesses, one router
 
 A single embedded router can serve several omp sessions without them stepping
@@ -782,8 +951,10 @@ come from a small omp extension that polls the router's in-process ledger:
 ```
 
 It raises a TUI toast (`ctx.ui.notify`) like
-`meta/muse-glimmer-30b [trivial] · $0.00001` whenever a new model is chosen.
-Install it by adding the file's absolute path to omp's `extensions:` list.
+`openrouter · meta/muse-glimmer-30b [trivial] · $0.00001` or
+`ollama · glm-5.3-flash [moderate] · $0.00070` whenever a new model is chosen —
+provider first, so a mixed catalog is legible at a glance. Install it by adding
+the file's absolute path to omp's `extensions:` list.
 
 Because the embedded router binds a random port, the toast resolves the router
 base URL on every poll in this order: the embedded router's port file
@@ -860,13 +1031,20 @@ absolute floor admits nothing and the router is trapped in the lowest tier.
 
 With `adaptiveTierFloors: true` (the default), every catalog refresh ranks the
 **available** scored models and splits them into four quantile bands, taking
-each band's lower bound as that tier's adaptive floor. The floor actually
-enforced is `min(configured, adaptive)`:
+each band's lower bound as that tier's adaptive floor. The band applies only
+when the configured floor leaves the tier **thin** — fewer than three available
+models meet it — in which case the floor enforced is `min(configured, adaptive)`:
 
-- a healthy catalog keeps the configured floors verbatim — no behaviour change;
+- a floor that three or more models meet stands exactly as configured — no
+  behaviour change on a healthy catalog;
 - a narrowed catalog falls back to the adaptive floor, so `hard` still gets the
   best quartile of what is available instead of nothing.
 
+The thinness gate matters: a wide catalog carries a long tail of weak scored
+models, so its quantile bands sit *below* the configured floors (measured on a
+347-model key-admitted catalog: coding p50 = 45.8 against `moderate`'s 60), and
+an unconditional `min` would quietly relax every tier.
+
 Relaxation is one-directional by design: an adaptive floor may only **lower** a
 tier floor, never raise one. Two things are deliberately exempt:
 
@@ -931,6 +1109,10 @@ Known gaps:
 
 - The `pi-native` front end is designed for but not implemented; only the
   OpenAI-compatible wire exists today.
+- `escalation.maxHoldMs` is only enforced when a chunk arrives: a stream that
+  emits nothing at all holds the client until the upstream ends. Left as is on
+  purpose — a timer would escalate every turn whose first token lands after
+  8s, which on live traffic is most of glm-5.3-flash's.
 - Blended `cost` figures in `models.yml` are refreshed by re-running
   `auto-model-router config --write`, not automatically.