@qadanm/opencode-smart-router 0.0.0-stage → 0.6.1

package/docs/ARCHITECTURE.md

@@ -0,0 +1,104 @@
+# Architecture
+
+## Runtime path
+
+```text
+OpenCode prompt admission
+  → session.hook("prompt")
+    → load session model and context tokens
+    → local classifier
+    → hard-requirement eligibility
+    → provider and per-model quota snapshots
+    → expected-cost ranking with cache-loss and hysteresis
+    → session.switchModel(...) when a switch is justified
+  → admission completes
+  → request dispatch
+```
+
+The plugin does not modify the prompt text, attachments, tools, or agent. It never injects a classification prompt and never calls a model to decide routing.
+
+## Modules
+
+| Module | Responsibility |
+|---|---|
+| `src/core/models/seed.ts` | Curated model intelligence, design, tier, privacy, and allowance metadata |
+| `src/core/models/registry.ts` | Merges live OpenCode metadata, approval state, exclusions, and tier overrides |
+| `src/core/classify/classifier.ts` | Deterministic task tier, kind, vision, design, scope, and constraints |
+| `src/core/policy/eligibility.ts` | Hard requirements, privacy, premium policy, context fit, quota blocks |
+| `src/core/quota/ledger.ts` | Bounded local usage ledger, rolling windows, per-model estimates, premium spend |
+| `src/core/quota/commandcode.ts` | Read-only Command Code alpha billing adapter |
+| `src/core/quota/opencode-go.ts` | Read-only Go usage adapter |
+| `src/core/quota/credentials.ts` | Owner-only credential discovery; never logs or persists keys |
+| `src/core/quota/service.ts` | Caching, polling, stale detection, per-provider backoff |
+| `src/core/routing/engine.ts` | Cost estimation, success probability, quota pressure, affinity, decision record |
+| `src/core/failures.ts` | Failure classification and bounded escalation |
+| `src/core/config.ts` | Defaults, validation, global/project precedence, project guardrails |
+| `src/server/shared-core.ts` | One process-wide core: ledger, quota service, persistence, event stream, session ownership, catalog cache |
+| `src/server/controller.ts` | Per-location bridge: hooks, RPC, commands, title queue, session-local state |
+| `src/index.ts` | Plugin definition; creates one bridge per loaded location |
+
+## Prompt timing
+
+The V2 prompt hook runs once during admission, before attachment and skill resolution and before the durable inbox admission. The plugin awaits `ctx.session.switchModel` inside that hook. Integration tests and live desktop tests confirmed that the request-context hook observes the new model for the same prompt.
+
+The router skips switching when:
+
+- routing is paused or disabled;
+- the session is manually overridden or pinned;
+- another routing decision is already in flight for the same session;
+- the session is busy in an active model loop;
+- no eligible route exists.
+
+It never switches in the middle of a response.
+
+## Session state and affinity
+
+Each session tracks the last model, last routed model, context size, cache-read share, step count, failures, retry count, manual override, premium one-shot, and pause state.
+
+The engine prices a model switch as a cache loss. It keeps the current model when the expected savings are below the configured hysteresis. Above 300K context tokens the hysteresis is wider. The router never truncates or rewrites the conversation to make a route cheaper.
+
+## Quota model
+
+Two layers are kept separate:
+
+1. **Provider-reported plan state**: Go percentages, Command Code remaining credits, windows, resets, plan, and billing period.
+2. **Local per-model ledger**: observed step costs and tokens, used where the provider has no per-model breakdown.
+
+Provider values override the ledger for plan-level pressure. Local values supply per-model estimates. Every displayed value carries its source (`provider`, `estimate`, or `unknown`). Polling is read-only and spends no inference allowance.
+
+The ledger keeps 2,000 *raw* usage events for per-request detail, but nothing is discarded when that cap is exceeded. Events older than a 48-hour horizon, or pushed out by the cap, are folded into hourly `UsageBucket` aggregates keyed by provider, model and billing period, retained for 400 days. Aggregation reads both sources, so a heavy week stays fully accounted at a few hundred rows instead of losing its own beginning.
+
+History is also preserved across an upgrade: hydrating a ledger written before aggregates existed folds the overflow into buckets rather than applying the old truncation.
+
+Decisions (120) and sessions (250) remain bounded, and writes are debounced and JSON-sanitized.
+
+Plan definitions live in `src/core/plans/catalog.ts` as data, not as branches in routing or quota code. A plan is a set of credit pools plus the window rule for each pool, so supporting a different user's tier requires no source change, and a provider's plan strings never appear in the routing or policy layers.
+
+## Concurrency
+
+- One shared core is active per server process; each loaded location registers a lightweight bridge.
+- A reload disposes only that location’s bridge. The core persists across reloads, stops its timers after a grace period, and revives on the next setup.
+- Prompt routing is serialized per session. Concurrent submissions for the same session do not double-switch.
+- Different sessions can route concurrently.
+- The ledger is updated in one event loop; persistence is debounced. There is no cross-process writer.
+- Provider probes are single-flight per provider and back off independently.
+
+## Failure handling
+
+- Context overflow → no escalation; recommend compaction or a handoff session.
+- Network, rate limit, provider outage → retry/failover, never premium escalation.
+- Auth → terminal retry decision, cooldown, no model escalation.
+- Tool or command failure → no model escalation.
+- Invalid image → no text-only fallback; require a verified vision route.
+- Capability failure → one bounded escalation opportunity, then stop.
+- Partial generation or side effects → never automatically replayed; the next prompt is routed with the failure history.
+
+## Security
+
+- No API keys or tokens are logged, persisted in router state, or included in RPC output.
+- Command Code keys are read only from owner-only files or the connected integration and sent only to `https://api.commandcode.ai`.
+- Go OAuth tokens are used only for `https://opencode.ai/zen/go/v1/usage`.
+- Training-enabled and free promotional models are blocked by default.
+- Project config files cannot loosen global privacy, extra-credit, or premium policy.
+- The router does not read repository files to classify a prompt; it uses prompt structure and attachments only.
+- Prompt text is not stored by default. Decision records contain signals and reasons, not the prompt.

package/docs/DEBUGGING-GUI.md

@@ -0,0 +1,70 @@
+# Debugging the desktop panel
+
+Written after a session where the panel vanished and four plausible causes were
+investigated before the real one. Read this before touching GUI code.
+
+## Check the server version first
+
+The desktop panel needs **OpenCode Desktop 2.2.x or newer**. A 2.1.x server has no
+GUI plugin API: it will not report `gui` in `/api/plugin`, and it cannot load
+`gui-experimental.cjs` at all.
+
+```bash
+opencode api get /api/info          # must say 2.2.x
+opencode api get /api/plugin        # opcode-smart-router must have features.gui: true
+```
+
+**The common trap:** `opencode` on `PATH` may be an older Homebrew install than
+the app. Running `opencode service restart` then restarts the *old* server, and it
+takes the port the app was using. The app reconnects to it, and the panel stops
+loading with no useful error.
+
+```bash
+which opencode && opencode --version           # CLI on PATH
+ls ~/Library/Application\ Support/ai.opencode.desktop/cli/   # app's bundled CLI
+```
+
+They must both be 2.2.x. If they are not, either `brew upgrade opencode-v2` or
+restart the app itself (`⌘Q`, then relaunch) instead of using the service command.
+The app spawns its own bundled server, which is the one that can load a GUI.
+
+## Then check the id rules
+
+Documented in the GUI guide, and easy to misread:
+
+> A plugin whose id "nests under one with a dot, has one nested under it, or is in
+> the `opencode` namespace" does not load its GUI.
+
+Concretely, this is wrong:
+
+```
+server part  id: "opencode-smart-router"
+tui part     id: "opencode-smart-router.tui"     ◄ nests under the server id
+```
+
+The TUI id must be a sibling, not a child. `test/first-run.test.ts` asserts that no
+two plugin ids nest, because the failure costs the entire panel and produces only
+a generic request failure in the app.
+
+## What the symptoms actually mean
+
+| Symptom | Usual cause |
+|---|---|
+| `Request failed / UnsupportedContentType` | Client and server versions disagree, or the GUI never registered |
+| Tab strip resets to the new-tab page | No GUI entry was loaded for that plugin |
+| `features` has no `gui` | Server too old, or the plugin id nests |
+| Panel renders but RPC fails | Server part failed to load — a plugin with no server part has no GUI |
+| Panel blank, no error | Something in `setup()` threw. A GUI whose setup throws loses the plugin, not just the panel |
+
+## Rules that keep this debuggable
+
+1. **`features.gui: true` is the single fact to check first.** It answers "did the
+   app even find my GUI" before any speculation about bundles, exports or code.
+2. **Never gate a required surface on an optional check.** The panel once rendered
+   as an empty box because it waited for `onboarding()` to settle, and that call
+   did not. Show the normal state; let optional data arrive later.
+3. **A convenience must never be able to break the product.** The auto-open path
+   touches four host APIs inside `setup()`; it is wrapped so a throw cannot remove
+   the plugin.
+4. **Test the version you think you are testing.** `/api/info` reports the server
+   actually running, which is not necessarily the one you started.

package/docs/INSTALL.md

@@ -0,0 +1,151 @@
+# Install, verify, and remove
+
+## Install
+
+One command, from a checkout. Requires Node 20.12+, npm and git. No `jq`.
+
+```bash
+./install              # interactive
+./install --yes        # non-interactive, for CI or an LLM
+./install --dry-run    # print every step, change nothing
+```
+
+It validates the source (typecheck and the full suite), backs up your config,
+builds the bundle, installs it, adds exactly one entry to `plugins`, and confirms
+the bundle loads. Any failure exits non-zero and leaves the machine untouched,
+because every check runs before anything is written.
+
+The install is **versioned and additive**. Each run writes to its own directory:
+
+```text
+~/.config/opencode/plugins/opencode-smart-router/<timestamp>/index.js
+```
+
+and only the config pointer changes. A running OpenCode server keeps the module it
+already loaded; the new version takes effect on the next start. This matters more
+than it sounds: replacing files inside the watched plugin directory invalidates the
+plugin module mid-session and makes the provider's model list go empty, which shows
+up as `Model unavailable: <provider>/<model>` for a model that is perfectly fine.
+
+## Verify
+
+```bash
+./install --dry-run        # reports the current state without changing it
+```
+
+Then restart OpenCode and run `/router-status` in a session. It prints the active
+plan, the allowance windows, and the model the router would pick.
+
+## Disable without uninstalling
+
+Set `"enabled": false` in `~/.config/opencode/smart-router.json` and restart. The
+plugin stays installed and inert; your config, credentials and providers are
+untouched either way.
+
+## Uninstall
+
+```bash
+./scripts/uninstall.sh
+```
+
+Removes the plugin directory and every `plugins` entry under it, then offers the
+exact pre-removal config as a restore point. Restart OpenCode afterwards.
+
+## Update
+
+Run `./install` again. It installs a new versioned directory and repoints the
+config, so old versions can be deleted safely once the new one is confirmed:
+
+```bash
+ls ~/.config/opencode/plugins/opencode-smart-router/
+```
+
+## Rollback
+
+Every install prints the backup it made. Two options:
+
+```bash
+./scripts/uninstall.sh                             # clean removal
+./scripts/uninstall.sh --restore-backup <file>     # restore an exact prior config
+```
+
+## Verify quota and routing
+
+The router exposes an RPC status method:
+
+```bash
+opencode api POST /api/rpc/smart-router/status -d '{"input":{}}'
+```
+
+Use `opencode api` so authentication is handled by OpenCode. The output labels each provider quota source as `provider`, `estimate`, or `unknown`.
+
+For durable usage history, per-model totals and rolling-window forecasts:
+
+```bash
+opencode api POST /api/rpc/smart-router/usage -d '{"input":{}}'
+```
+
+This reports each provider's five-hour, seven-day and monthly consumption with input, output, cache-read and cache-write tokens, the cache share, per-model totals, and a forecast per window. A plan with no five-hour window reports that row as not applicable rather than as 0% used. It makes no inference request.
+
+For a safe dry-run of a routing decision without changing the model:
+
+```bash
+opencode api POST /api/rpc/smart-router/preview \
+  -d '{"input":{"sessionID":"ses_…","text":"Implement a small feature in src/app.ts"}}'
+```
+
+A safe smoke test:
+
+1. Create a new session with a cheap or free model.
+2. Send a narrow CSS change with an explicit file path.
+3. The session should switch to an economy model before the request, and the file should change.
+4. Send an ordinary feature request; it should use a standard model at or above the intelligence floor.
+5. Send a tier-3 request (architecture, sophisticated redesign); with the 0.6.x default
+   `premium.mode: "auto"` it escalates to a plan model (Sonnet 5.5 or GPT-6.1 Sol)
+   automatically — no approval step, paid from the plan-model pool.
+6. Run `/router-why` on the escalated prompt; the reason should name auto escalation
+   and the candidate trace should show the flagship row.
+7. Select a model manually in the desktop picker; the next prompt must not be overridden, and `/router-status` should show `manual`.
+8. Run `/router-auto` to resume.
+
+## Automatic flagship escalation (0.6.0 and later)
+
+The default premium mode is `auto`. How it behaves:
+
+- **Tier-1/2 work never touches the plan-model pool.** Routine tasks stay on the
+  ordinary Design Plan models exactly as before.
+- **Tier-3 work escalates by itself.** Architecture, sophisticated redesigns, and
+  other tier-3 classifications route to Claude Sonnet 5.5 or GPT-6.1 Sol without an
+  approval prompt, while the pool has budget.
+- **The pool is the budget.** Auto escalation is funded from the OpenDesign
+  plan-model pool ($120/month on Pro), read from the plan catalog and tracked in a
+  ledger that survives restarts. When the pool is spent, escalation degrades to an
+  approval gate (`/router-approve`) and the router serves the task with the strongest
+  ordinary model — a routing refusal never fails a serviceable task.
+- **Auto requires a resolvable pool.** If `providers.opendesign.plan` does not
+  resolve to a known plan, auto refuses rather than falling back to the legacy
+  premium budget, so spend is always attributable to a pool.
+
+To change the behavior:
+
+```json
+{
+  "premium": { "mode": "auto", "monthlyBudgetUsd": 120 }
+}
+```
+
+`mode` may be `off` (never premium), `ask` (one-shot approval per request),
+`allowed` (session approval unlocks the legacy premium budget), or `auto`.
+A project-level `.opencode/smart-router.json` can tighten this but not loosen it.
+
+## Configuration
+
+No config file is required. To customize:
+
+```bash
+cp ~/Documents/opencode-smart-router/config.example.json \
+   ~/.config/opencode/smart-router.json
+chmod 600 ~/.config/opencode/smart-router.json
+```
+
+A project may add `.opencode/smart-router.json`. It can tighten privacy and spending policy but cannot loosen global restrictions.

package/docs/LIMITATIONS.md

@@ -0,0 +1,230 @@
+# Limitations and precise blockers
+
+This file records what is proven, what is estimated, and what the installed OpenCode version cannot support.
+
+## 1. Desktop GUI
+
+Installed OpenCode Desktop is **2.1.4**. Its `app.asar` does not contain the experimental GUI plugin loader or the `./gui-experimental` export. The GUI plugin SDK is present in `@opencode/plugin` 2.2.0 and later.
+
+Therefore the deployed interface is:
+
+- native slash commands registered by the server plugin (`/router-status`, `/router-explain`, `/router-report`, `/router-mode`, `/router-approve`, `/router-auto`, `/router-pin`, `/router-exclude`, `/router-pause`, `/router-resume`, `/router-dry-run`, `/router-premium-budget`, `/router-reserve`, `/router-reset-metrics`);
+- a typed RPC surface at `rpc.smart-router.*`, suitable for a future official GUI part.
+
+The router engine does not depend on any panel being open. A side panel was not claimed or faked. On OpenCode 2.2.0 or later, the same RPC surface can back a native settings page or side panel without changing routing core.
+
+## 2. Command Code billing endpoints
+
+Command Code exposes no stable public usage API in its documented Provider API. The plugin reads the same read-only alpha routes the official CLI uses:
+
+```text
+/alpha/whoami?limits=1
+/alpha/billing/credits
+/alpha/billing/subscriptions
+/alpha/usage/summary
+```
+
+These are **undocumented and unstable**. They can change without notice. The adapter:
+
+- uses only `GET`;
+- never discovers or calls mutation endpoints;
+- validates numeric and timestamp shapes;
+- preserves `orgId` when the account belongs to an organization;
+- limits polling to a conservative interval with exponential backoff;
+- keeps the last good snapshot marked `stale` on failure;
+- falls back to a clearly labeled local ledger estimate;
+- never reports missing data as unlimited usage.
+
+The provider API key that OpenCode uses for inference is **not authorized** for these billing routes. The adapter discovers the CLI-compatible key instead. In this installation the working source is:
+
+```text
+~/.config/opencode/commandcode.key
+```
+
+The key is read only from owner-only files, is never logged or persisted by the plugin, and is sent only to `https://api.commandcode.ai`.
+
+Provider-reported values are account-level: remaining included credits, purchased/free extras, five-hour and weekly used/cap/reset, plan, and billing-period spend. There is no per-model provider breakdown. Per-model usage and remaining model allowance are local estimates from observed step costs.
+
+The billing-period usage summary and the remaining-credit balance are **separate accounting pools** and do not reconcile exactly. The adapter treats the remaining-credit balance as authoritative for monthly usage and allowance protection; the summary is kept only as a diagnostic cross-check. The exact reason for the difference is not documented by the provider.
+
+## 3. OpenCode Go usage endpoint
+
+The Go meter endpoint is a read-only, best-effort integration:
+
+```text
+GET https://opencode.ai/zen/go/v1/usage
+```
+
+It is queried with OpenCode's existing OAuth access token from the `opencode` connection. It returns percentages and reset times, not dollar balances. It is not part of the public inference schema and may change. On failure, the router uses the local ledger and labels the source `estimate` or `unknown`.
+
+## 4. Prompt rejection is untyped
+
+The V2 prompt admission hook can mutate a prompt but exposes no typed rejection operation. The router blocks admission by throwing `RouterBlockedError` from the prompt hook. On the installed 2.1.4 server this was verified to reject the prompt with HTTP 500 and no provider request; the session title changes to `BLOCKED` and the reason is recorded in the decision.
+
+This is safe but not polished: the HTTP error is generic, so the title and notification are the user-facing explanation.
+
+### What may and may not block a prompt
+
+Blocking is **opt-in**. `routing.failClosed` defaults to `false`, and the default is the contract, not a tuning knob.
+
+A defect in this plugin degrades to "do not route", never to "do not work". When the router cannot produce a decision because something inside it failed, the prompt is served with the model already selected, which is what would have happened if the plugin were not installed. The reason is recorded in warnings and in the decision record, so the failure is visible without being fatal.
+
+`routing.failClosed: true` is available for an owner who has decided they would rather be stopped than pay for an unrouted request. It applies to plugin faults only. It does **not** govern quota safety: a provider configured for probing but with no reading is always refused, because that is a spending decision about a provider the router cannot see, not a response to its own failure.
+
+Every hook is wrapped in `containHook()` and routing runs against a deadline. A hook cannot throw to the host and cannot hold a prompt indefinitely; if routing has not finished within the budget (10 seconds by default), the prompt proceeds unrouted. The reasoning is in [INCIDENT-2026-11-06-prompt-lockout.md](INCIDENT-2026-11-06-prompt-lockout.md).
+
+## 4a. OpenCode does not contain a plugin hook
+
+Verified against a real OpenCode 2.2.5 process on 2026-11-06:
+
+- a plugin hook that **throws** fails the prompt with HTTP 500;
+- a plugin hook that **never settles** blocks until the caller gives up.
+
+OpenCode has no timeout and no catch of its own at this boundary, so a plugin cannot rely on the host to survive it. Every guarantee therefore has to come from the plugin, which is what `src/server/containment.ts` is for. `scripts/isolated-e2e.sh` asserts both limitations so the reason for that module stays visible.
+
+## 5. Manual CLI selection at session creation
+
+Manual model changes made while the plugin is active are detected through `session.model.selected` and respected. A model passed only at CLI session creation, before the plugin has seen a prompt, is indistinguishable from the session default. The first prompt may therefore be routed normally. Selecting a model in the desktop picker after the session exists is detected.
+
+## 6. Subagents
+
+Child sessions are routed independently. Premium is never propagated from a parent task into a child session; premium mode is capped at balanced for child sessions and one-shot approvals are not inherited. This prevents a premium task from multiplying premium usage through subagent calls. A child can still use a standard model appropriate to its own prompt.
+
+## 7. Billing caps
+
+Client-side quota estimates are not a mathematically guaranteed billing cap. Provider-side enforcement remains authoritative. The router:
+
+- never purchases credits;
+- never enables top-ups;
+- never changes billing settings;
+- blocks automatic routing when provider-reported windows are at the configured reserve;
+- treats a reported zero remaining balance as exhausted even if the provider has not set its `exceeded` flag, so it blocks before knowingly entering purchased credits;
+- blocks when purchased credits would be consumed unless `allowExtraUsage` is explicitly enabled;
+- cannot guarantee that an undocumented provider endpoint or a provider-side fallback will never charge an extra balance.
+
+If Command Code's billing routes fail and the local ledger is incomplete, the router labels the data estimated and fails conservatively rather than assuming capacity.
+
+The purchased-credit guard is unit-tested, including the explicitly-allowed case. It is a client-side policy guarantee, not a provider-side billing lock.
+
+## 8. Cache and context accounting
+
+Prompt caches are provider- and model-specific. A model switch is priced as a cache loss in the router's estimate. The router keeps the current model when the estimated savings are below the hysteresis threshold, and uses a wider threshold above 300K context tokens. It never truncates, summarizes, or deletes conversation history to make a model eligible.
+
+Command Code DeepSeek V4.1 Flash has documented time-of-day pricing: off-peak rates for 17 hours per day and 2x rates from 01:00 to 04:00 and 06:00 to 10:00 UTC, Monday through Friday. The router applies that multiplier to input, output, cache-read, and cache-loss estimates. Models without documented peak metadata use flat catalog rates; their time-of-day pricing is not assumed.
+
+Context-health recommendations are non-destructive: they advise a new session and never compact anything on their own.
+
+Router-driven compaction is governed by `contextManagement.mode`:
+
+- `native` (default) and `conservative` never compact except when the transcript would genuinely exceed the model's verified accepted window. The provider's native handling is preferred; the router steps in only for that case, and announces it.
+- `budget-optimized` preserves the legacy behavior: it compacts early to keep a session on the cheapest qualified route. It exists for small plans and small-window models.
+
+In every mode the window used is the one the provider actually accepts, never a theoretical maximum, and the current model's window is used rather than another provider's variant of the same model. Provider-side prompt caching is never disabled by any mode.
+
+## 8a. OpenDesign plan accounting
+
+OpenDesign Pro exposes two independent credit pools: Design Plan credits ($360/month, $90 per rolling seven days, no five-hour window) and plan model credits ($120/month, no usage windows). They are reported side by side and **never summed**. The advertised $480 total is not a single spendable balance, and Design Plan credit multipliers apply only inside the Design Plan pool.
+
+These figures are **estimated**, not provider-confirmed. An OpenDesign inference key cannot read quota: `GET /v1/usage` and `/v1/me` return 404 and the account-control host rejects an inference key. A control key would enable verified reads; none is configured, and the router never acquires one automatically. Because usage from the OpenDesign app is invisible to the router, the estimate is a lower bound.
+
+`minimax-m3.1-flash`'s Design Plan multiplier is unpublished, so a neutral 1x is applied and the uncertainty is reported rather than hidden. The same applies to the GLM cache-read price.
+
+OpenDesign quota cannot be verified without an account control key. Re-probed on
+2026-10-30 against the live gateway: `/v1/models` returns 200 with the inference
+key, while `/v1/usage`, `/v1/me`, `/v1/credits`, `/v1/billing`, `/v1/account`,
+`/v1/subscription`, `/v1/limits` and `/v1/quota` all return 404. The key is valid
+and authorized for inference; no usage surface exists for it. Quota therefore
+reports `estimated`, derived from this router's own consumption against the
+published plan caps with a configurable safety margin.
+
+That estimate is a lower bound, because usage from the OpenDesign desktop app and
+any other client on the same subscription is invisible to the router. The state
+label is the honest part: `estimated` never becomes `verified` without a control
+key, and `test/opendesign-quota-honesty.test.ts` pins that so it cannot drift.
+
+## 8b. Measured speed
+
+Generation speed is recorded as output tokens per second, which separates a slow provider from a model that reasons for longer. It is compared against the fastest eligible route rather than an absolute figure, is neutral below a configurable sample floor, and raises effective cost without ever making a route ineligible. With few samples it does not change decisions. It is machinery that needs production traffic before it can discriminate.
+
+## 9. Precision of scores
+
+The intelligence floor and design thresholds are planning inputs, not guarantees. Intelligence values come from published model cards where available; design scores are curated and explicitly separate. Models without credible scores are not approved for automatic substantive work. The router does not invent benchmark results.
+
+## 10. What was not done
+
+- No separate dashboard or daemon was installed.
+- No third-party classification service receives prompts, code, or screenshots.
+- No provider billing settings, credentials, or model connections were changed.
+- No project configuration outside the router's optional project override was modified.
+
+## 11. Why a session may stop using your default model
+
+Two independent reasons can move a session off DeepSeek V4.1 Flash, and both are
+correct behavior rather than faults.
+
+**The transcript outgrew the window.** DeepSeek V4.1 Flash has a 328k window, and
+presence in a request requires about 20k of headroom inside 95% of it, so it
+stops being eligible at roughly 291,600 tokens of transcript. Past that point the
+router names the model it dropped, both token counts, and the fact that a new
+session restores it.
+
+**Another model is genuinely cheaper right now.** A session can sit inside a
+model's window and still lose on cost, because credit multipliers and peak
+pricing differ per model. On OpenDesign, Minimax M3.1 Flash carries a neutral
+multiplier while DeepSeek's is 0.5, and DeepSeek doubles during 01:00 to 04:00
+and 06:00 to 10:00 UTC on weekdays. At a 309k transcript on a weekday, MiniMax
+can therefore be about 1.3x cheaper, and the router picks it on merit. In that
+case the context warning is deliberately silent, because nothing was displaced:
+the model never would have won.
+
+Observed live on 2026-10-30, and superseded later the same day. A 309,321-token
+session selected `opendesign/minimax-m3.1-flash` because three conditions held at
+once:
+
+- OpenCode Go was at 90% of a 10% monthly reserve, so it was blocked.
+- Command Code was at 86% of a 15% weekly reserve, so it was blocked.
+- On OpenDesign, DeepSeek was judged against a 328,000 window and needed 329,321.
+
+The first two were correct. The third was not: the 328,000 window was an advisory
+gateway budget that the gateway does not enforce, and DeepSeek would now be
+chosen for that session. The quotas remain real; the context rejection was a
+consequence of the wrong window, which is documented in the section below.
+
+### OpenDesign's context budget is advisory, and was measured
+
+DeepSeek V4.1 Flash shows a 1,048,000-token window in the router. It used to show
+328,000, because the gateway publishes `context_budget: 328000` alongside
+`context_limit: 1048000` and the router treated the budget as the ceiling.
+
+That was wrong. The gateway does not enforce `context_budget`. Measured on
+2026-10-30 with six single requests on `deepseek-v4.1-flash`, `max_tokens: 1`,
+synthetic unique filler, so nothing could be prefix-cached:
+
+| Prompt tokens | Result |
+|---|---|
+| 355,588 | 200 |
+| 753,476 | 200 |
+| 999,593 | 200 |
+| 1,043,337 | 200 |
+| about 1,060,000 | 400 `context_length_exceeded` |
+| about 2.4M | 400 `context_length_exceeded` |
+
+The enforced ceiling is the vendor `context_limit` of 1,048,000, confirmed on both
+sides of the boundary. Total cost of the probes was $0.006.
+
+One control mattered: the first probe reported 355,328 of 355,588 tokens as
+cached, which is implausible for a payload that had never been sent. Repeating it
+with random text produced `cached_tokens: 0`, proving the gateway really did
+tokenize and accept the full input. Without that, a 200 on mostly-cached input
+would have been weak evidence.
+
+The router now uses the vendor limit for a model whose ceiling has been measured,
+and keeps the conservative budget for every other model. That is a per-model
+allowlist rather than a blanket rule, because guessing a larger window than a
+provider accepts fails mid-session with an opaque rejection, which is the failure
+mode this project already hit once.
+
+The router still keeps a 20,000-token margin and a 95% safety fraction, so the
+usable transcript is about 975,600 tokens rather than exactly 1,048,000. That
+margin is not part of the gateway's limit; it is the router refusing to send a
+request that has no room left for the reply.