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

package/docs/OPENDESIGN-INTEGRATION.md

@@ -0,0 +1,635 @@
+# OpenDesign Go provider integration
+
+OpenDesign Go is a third subscription provider alongside OpenCode Go Plus and
+Command Code GOAT. This document records what the integration does, where its
+numbers come from, and what it cannot promise.
+
+It extends the existing Option C router. It is not a second router, and it does
+not change the behavior of the two existing providers.
+
+---
+
+## 1. What was implemented
+
+| Area | Change |
+|---|---|
+| Provider adapter | `src/core/providers/opendesign.ts` : base URL handling, protocol selection, read-only model discovery, error and size normalization |
+| Model catalog | `src/core/providers/opendesign-models.ts` : the 39 models the gateway serves, with credit multipliers and curated quality scores |
+| Credit semantics | `src/core/providers/opendesign-credits.ts` : published multipliers, promotion handling, credit conversion |
+| Quota integration | `src/core/quota/opendesign.ts` : verified / estimated / unknown / exhausted states |
+| Credential discovery | `src/core/quota/credentials.ts` : inference key and explicitly supplied control key, kept separate |
+| Routing | `src/core/routing/engine.ts` : credit multiplier in the cost ranking, cooldown exclusion, reliability weighting |
+| Policy | `src/core/policy/eligibility.ts` : subscription-only guard and unknown-quota policy |
+| Quota coordinator | `src/core/quota/service.ts` : OpenDesign probes run through the same single-flight service as the other two providers |
+| Model registry | `src/core/models/seed.ts`, `src/core/models/registry.ts`: OpenDesign seeds, gateway metadata merged over them |
+| Shared core | `src/server/shared-core.ts` : one single-flight discovery per process, merged into the one model catalog |
+| Commands | `/router-opendesign` added; `/router-status`, `/router-report`, `/router-explain` updated |
+
+The provider is **optional and disabled by default**. A user with no OpenDesign
+credentials sees no behavior change at all.
+
+---
+
+## 2. Source revisions examined
+
+Recorded 2026-10-28.
+
+| Source | Revision | Used for |
+|---|---|---|
+| `nexu-io/open-design` | `c6bb5a8b8190` | Billing preflight, model probing, error taxonomy |
+| `nexu-io/open-design` PR #8339 | merge `eb27acd32250`, merged 2026-09-24 | Advisory preflight vs gateway funding vs wallet display |
+| `nexu-io/open-design` #8674 | open | No API-key-readable quota endpoint |
+| `nexu-io/open-design` #8870 | open | Control-key lifecycle and revocation gaps |
+| `nexu-io/open-design` #8687 | open | Anthropic-messages drops reasoning for DeepSeek V4.1 Flash |
+| `KouzakiUmi/dsh-opendesign-corouter` | `afb390a6bd66` | Gateway shape, protocol endpoints, empty-turn behavior |
+| `KouzakiUmi/dsh-subusage` | `d6d997ddce7a` | Control-plane paths, window classification, credential handling |
+| `open-design.ai/help/cloud-api/`, `/help/billing/`, `/model-credits/` | retrieved 2026-10-28 | Plan shape, credit multipliers, window rules |
+
+---
+
+## 3. What the gateway actually reports
+
+`GET {base}/v1/models` with the inference key returns the account's entitled
+models with authoritative metadata. Captured 2026-10-28.
+
+| Model | Usable input | Output | Image input | Credits |
+|---|---|---|---|---|
+| DeepSeek V4.1 Flash | 1,048,000 (measured) | 128,000 | yes | 0.5× |
+| Claude Haiku 5.5 | 228,000 | 128,000 | yes | 2× |
+| GLM-5.3 Flash | 232,000 | 32,000 | yes | 1× |
+| GLM-5.3 Flash-X | 232,000 | 32,000 | yes | 2× |
+| GPT-6 Luna | 400,000 | 128,000 | yes | 4× |
+| MiMo V2.6 Flash | 232,000 | 32,000 | yes | 1× |
+| MiMo V2.6 Pro | 232,000 | 32,000 | yes | 1× |
+| MiniMax M3.1 Flash | unknown | unknown | yes | not published |
+| DeepSeek V4 Flash | 232,000 | 32,000 | no | 1× |
+| DeepSeek V4 Flash Vision Exp | 232,000 | 32,000 | yes | 1× |
+| DeepSeek V4 Pro | 328,000 | 128,000 | no | 1× |
+| Hunyuan H4 Preview | 232,000 | 32,000 | no | 1× |
+| Kimi K2.7 Code | 262,000 | 32,000 | yes | 1× |
+
+Three findings that change how the router treats OpenDesign:
+
+1. **`context_budget` is advisory, not an enforced ceiling.** This was corrected
+   on 2026-10-30 by direct measurement. The gateway advertises a
+   `context_budget` of 228k to 400k against a vendor `context_limit` of up to
+   1.05M, but it does not enforce the budget. On `deepseek-v4.1-flash` the
+   gateway accepted 1,043,337 input tokens with HTTP 200 and rejected only above
+   the 1,048,000 vendor limit with `context_length_exceeded`. Six probes, $0.006
+   total; see `docs/AUDIT-deepseek-context-2026-10-30.md`.
+
+   The router therefore uses `context_budget` only for models whose real ceiling
+   has not been measured. For a measured model it uses the vendor limit. Assuming
+   the smaller number is not free: it discarded roughly 716,000 usable tokens on
+   DeepSeek and compacted sessions at 304,000 that the gateway would have served
+   past a million.
+2. **Image support is verified from the gateway**, not inferred from a model
+   card. `hy4-preview`, `deepseek-v4-flash` and `deepseek-v4-pro` are text only
+   on this gateway.
+3. **MiniMax M3.1 Flash reports no context or output budget.** The router uses
+   the vendor limit of 1,000,000 and flags the multiplier as unverified. An
+   earlier version used a hand-written 232k guess here, which shrank the window
+   four-fold and blocked a live session.
+
+A fourth finding, observed live on 2026-10-28: the gateway resolves a **billing
+scope** before answering, even a read-only `/v1/models` request. During this
+work it returned `503 workspace_billing_scope_unavailable` with an upstream
+`context deadline exceeded` against `amr-api.open-design.ai/api/internal/billing/scope/…`,
+then succeeded on retry. Two consequences:
+
+- Every OpenDesign request, including model discovery, depends on a billing
+  service that can time out. Transient 503s are expected and must be retried
+  with backoff, which the router's quota backoff and failure classification
+  already handle.
+- This is a plausible upstream contributor to dropped streams: the billing
+  scope resolution sits in front of the response stream.
+
+Models without a curated quality score are seeded unapproved. Approve them
+explicitly in `models.approved` if you want them routed.
+
+---
+
+## 4. How quota is obtained
+
+OpenDesign publishes no quota API for an inference key. Verified empirically on
+2026-10-28:
+
+| Path | Result |
+|---|---|
+| `GET amr-link.open-design.ai/v1/usage` | 404 |
+| `GET amr-link.open-design.ai/v1/me` | 404 |
+| `GET amr-api.open-design.ai/api/v1/workspaces/current` with the inference key | 401 `unauthenticated` |
+| `GET amr-api.open-design.ai/api/v1/billing/summary` with the inference key | 401 `unauthenticated` |
+| `GET amr-api.open-design.ai/api/v1/wallet/balance` with the inference key | 401 `unauthenticated` |
+
+Issues #8674 and #8870, which ask for exactly this, are both still open.
+
+The integration therefore has three states:
+
+- **`verified`**: a control key was supplied explicitly. The router reads
+  `workspaces/current`, `workspaces/{id}/billing/coding-plan-usage` and
+  `billing/summary`, and reports provider numbers. This is the only state in
+  which the wallet balance is reported.
+- **`estimated`**: only the inference key is available. The router models its
+  own credit consumption against the published plan caps, applies a
+  configurable safety margin (default 20%), and reports it as a lower bound.
+- **`unavailable`**: nothing could be established. OpenDesign is then not
+  routed to.
+
+`stale` marks verified or estimated data older than twice the probe interval.
+`exhausted` marks a confirmed or modelled window that has been used up.
+
+The router never obtains a control key, never asks for a browser session, and
+never scrapes cookies. A control key is used only when you point
+`providers.opendesign.controlKeyPath` at a file you created yourself.
+
+---
+
+## 5. Billing accuracy and limits
+
+The Go plan shape is:
+
+- $10 per month
+- Design Plan monthly maximum **$120**
+- 7-day window maximum **$30**
+- 5-hour window maximum **$10**
+- Plan-model credits **$0**
+
+The 5-hour and 7-day values are nested limits inside the monthly maximum. They
+are never added together.
+
+What is exact, estimated, and unknown:
+
+- **Exact.** Window limits and reset times when a control key is configured;
+  the plan tier; which models the gateway serves; each model's usable context,
+  output budget and image support.
+- **Estimated.** Credit consumption. The router converts token counts into a
+  dollar value of model usage using the curated vendor list price, then applies
+  the published Design Plan multiplier. OpenDesign does not publish per-token
+  prices for plan models, so the underlying price is a proxy, not a quote.
+- **Unknown.** Usage from outside OpenCode. The OpenDesign desktop app and any
+  other client share the same allowance, and the router cannot see them. The
+  estimated state is therefore a lower bound, which is why a margin is applied.
+- **Unknown.** The multiplier for MiniMax M3.1 Flash. It is not published, so
+  the neutral 1× rate is used and flagged.
+
+The DeepSeek V4.1 Flash off-peak promotion of 2026-10-20 to 2026-10-27 is
+recorded but never applied: it has expired, and OpenDesign states that
+app-only offers do not automatically apply through APIs.
+
+---
+
+## 6. Spending policy
+
+Default configuration:
+
+- `subscriptionOnly: true`
+- `allowExtraUsage: false`
+
+With those set, the router will not send a request to OpenDesign when the
+subscription allowance is exhausted, even though the gateway could fund the
+request from purchased balance. It also refuses a request whose projected cost
+does not fit inside what is left of the applicable window.
+
+**This is a client-side guard, and it is not a guarantee.** OpenDesign's
+gateway chooses the funding source per request. The upstream client removed
+client-side wallet-zero blocking for exactly this reason, recording that the
+gateway decides. The router cannot prevent a server-side charge; it can only
+avoid sending a request it can already see does not fit.
+
+You must confirm in the OpenDesign account console that automatic recharge is
+disabled. The router cannot check that on your behalf.
+
+---
+
+## 7. Credential setup
+
+The inference key is the only credential the provider needs.
+
+```bash
+# 1. Create a key in the OpenDesign Cloud console, API keys page.
+# 2. Store it with owner-only permissions.
+umask 077
+printf '%s' 'sk-amr-your-key' > ~/.config/opencode/opendesign.key
+chmod 600 ~/.config/opencode/opendesign.key
+```
+
+The router discovers it from, in order: `$OPENDESIGN_API_KEY`, an explicit
+`providers.opendesign.credentialPath`, `~/.config/opencode/opendesign.key`,
+`opendesign.env`, `opendesign.json`, and finally the OpenCode provider
+settings. Credential files must not be group- or world-readable.
+
+Then point OpenCode at the gateway in `opencode.json`:
+
+```json
+{
+  "providers": {
+    "opendesign": {
+      "name": "OpenDesign Go",
+      "package": "@opencode/ai/providers/openai-compatible",
+      "options": {
+        "baseURL": "https://amr-link.open-design.ai/v1",
+        "apiKey": "{env:OPENDESIGN_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+And enable it for the router in `~/.config/opencode/smart-router.json`:
+
+```json
+{
+  "providers": {
+    "opendesign": {
+      "enabled": true,
+      "subscriptionOnly": true,
+      "allowExtraUsage": false,
+      "monthlyCreditsUsd": 120,
+      "fiveHourCapUsd": 10,
+      "weeklyCapUsd": 30
+    }
+  }
+}
+```
+
+The gateway base URL already contains `/v1`. The router never appends it twice.
+
+**Protocol.** Use chat-completions, which is what the OpenAI-compatible
+package speaks. Do not configure the Anthropic-messages protocol for DeepSeek
+V4.1 Flash: upstream issue #8687 reports that it drops reasoning and stalls
+agents that rely on tool calls. The router warns when it sees this combination.
+
+Verify with `/router-opendesign`, which lists the entitled models the gateway
+actually returned and makes no inference request.
+
+### Getting closer to exact numbers without a control key
+
+Re-probed against the live gateway on 2026-11-04, with a valid inference key:
+
+| Request | Result |
+|---|---|
+| `GET /v1/models` | 200 |
+| `GET /v1/usage`, `/v1/me`, `/v1/credits`, `/v1/billing`, `/v1/account`, `/v1/subscription`, `/v1/limits`, `/v1/quota`, `/v1/workspaces` | 404 |
+| `GET https://amr-api.open-design.ai/api/v1/workspaces/current` (inference key) | 401 |
+| any `chat/completions` response | no credit or quota headers; `usage` carries tokens only |
+
+So the inference key still cannot see account usage, and the router still will not
+scrape a browser session. If you can read your own account page, you can give the
+router the number instead of letting it guess:
+
+```json
+{
+  "providers": {
+    "opendesign": {
+      "baseline": {
+        "at": "2026-11-04T12:00:00Z",
+        "designPlanUsedUsd": 37.8,
+        "weeklyResetsAt": "2026-11-05T03:00:00Z"
+      }
+    }
+  }
+}
+```
+
+The router adds every OpenDesign request it routes after `at` to that figure, and
+labels the result as starting from your reading rather than from zero.
+
+Two rules keep this honest:
+
+- **The baseline expires when its window resets, not when it gets old.** These
+  are different. A seven-day window that resets in 23 hours means the reading
+  describes the window ending then; afterwards it describes a window that no
+  longer exists, and seeding it into the new one would attribute old usage to
+  fresh credit. Supply `weeklyResetsAt` (and `monthlyResetsAt`) from the account
+  page. Without them the router falls back to an age-based assumption and says
+  so in the panel.
+- **Read the percentage off the window it belongs to.** On Pro, the account page
+  shows Design Plan credits as a share of the seven-day allowance ($90), not the
+  monthly one ($360). 42% of the week is $37.80, which is 10.5% of the month.
+  Entering `151.20` because "42% of 360" would overstate usage fourfold.
+
+### What the vendor documentation settles
+
+Read from <https://open-design.ai/model-credits/> and
+<https://open-design.ai/help/billing/> on 2026-11-04. These are public pages, so
+every claim below is verifiable and should be re-checked when terms change.
+
+**The seven-day window is fixed, not rolling.** "For new subscriptions, the 7-day
+window starts when the subscription begins and resets every 7 days… subscribe on
+Wednesday at 10:00 AM, it resets the following Wednesday at 10:00 AM." The catalog
+called this `rolling-7-day`, which would slide continuously and understate
+available headroom for most of the week. Now `fixed-7-day`.
+
+**The pools spill.** "Design Plan models use Design Plan credits first, then any
+remaining plan model credits." The catalog already modelled the draw order
+correctly; its prose did not (it claimed the pools are "never added together",
+which reads as "never interact"). Go has no plan model pool, so a spent window
+there really does mean waiting.
+
+**Only Design Plan credits have windows.** Plan model credits have neither a
+five-hour nor a seven-day window and reset per billing cycle. Unused subscription
+credits do not roll over.
+
+**Per-plan ceilings, corrected:**
+
+| Plan | Monthly max | Plan models | Design Plan | 7-day | 5-hour |
+|---|---|---|---|---|---|
+| Go | $120 | $0 | $120 | $30 | $10 |
+| Plus | $180 | $20 | $160 | **$40** | — |
+| Pro | $480 | $120 | $360 | $90 | — |
+| Max | $900 | $300 | $600 | $150 | — |
+
+Plus had **no** weekly ceiling in the catalog, which made it look able to spend
+its entire $160 in one week — a 4x understatement of the real limit.
+
+**Multipliers are confirmed, not inferred.** The published table matches ours
+exactly: DeepSeek V4.1 Flash 0.5×, the majority 1×, Claude Haiku 5.5 and
+GLM-5.3 Flash-X 2×, GPT-6 Luna 4×. Also documented: MiniMax M3.1 Flash is 1×,
+and the October off-peak 0.25× promotion expired on 2026-10-27 and applies to
+the app only, never to API usage.
+
+**Still no usage endpoint.** Upstream issue `nexu-io/open-design#8674` asks for
+exactly the endpoint this router needs — per-window `used_percent` and
+`resets_at` for API key holders — and remains open. The account host rejects an
+inference key with 401 and bot-blocks non-browser requests. So the estimate plus
+the user-supplied baseline remain the only path, and this is a vendor gap rather
+than something to work around.
+
+### Where the prices come from, and why they drifted
+
+The model catalog stores the **published API price** per million tokens. The
+Design Plan multiplier is a separate factor applied on top, so the credit cost of
+a request is `published price x multiplier`. Conflating the two is the mistake the
+catalog made for thirteen of its thirty-three models.
+
+Checked against CoRouter's public model pages on 2026-11-04. That page is
+machine-readable: every model panel carries `data-model-panel` with the exact API
+model ID, so the mapping is read rather than inferred from display names.
+
+What was wrong:
+
+| Model | Was | Published | Effect |
+|---|---|---|---|
+| `deepseek-v4.1-flash` | 0.15 | **0.30** | **charged a quarter of real cost** |
+| `deepseek-v4-pro` | 0.66 | 1.32 | half |
+| `deepseek-v4-flash` | 0.66 | 0.44 | 1.5x too high |
+| `glm-5.3-flash` | 0.15 | 0.075 | 2x too high |
+| `hy4-preview` | 0.14 | 0.834 | 6x too low |
+| `kimi-k2.7-code` | 3.00 | 0.95 | 3x too high |
+| plus 7 more | | | |
+
+The model in daily use was the worst case, and it looked like a double-applied
+multiplier: 0.15 is 0.30 x 0.5. But there was no single rule, which is why this
+was fixed model by model rather than by scaling.
+
+Two consequences worth stating:
+
+- **Routing changed.** With real prices, GLM-5.3 Flash ($0.075, intelligence
+  41.8) beats DeepSeek V4.1 Flash ($0.30, 39.5) for ordinary work. Several tests
+  had recorded the old winner; they were updated, and the reasoning is in the
+  diff rather than silently rebaselined.
+- **`test/opendesign-pricing.test.ts` now pins every published price.** A failure
+  there means either the provider changed its rates (update both) or somebody
+  hand-edited the catalog.
+
+The plan caps were checked at the same time and were already correct: Pro is
+$360 Design Plan plus $120 plan models, which is the $480 total the pricing page
+advertises, and Design Plan credits are consumed before plan model credits.
+
+### Two estimator defects, and why the tests missed them
+
+Both shipped with green tests. Recording them because the pattern matters more
+than the bugs.
+
+**The reported cost was thrown away.** Every completed step carries the cost the
+host actually charged, and the ledger already stores it (`usage[].usd`).
+`localTotals` ignored it and recomputed price from the static table, then applied
+the Design Plan multiplier — re-deriving an approximation of a number that was
+sitting right there. It also drifted in a specific case: a step funded from plan
+model credits after the Design Plan allowance is spent is charged at the plain
+rate, while the table still applied the Design Plan multiplier.
+
+Now: a non-zero reported cost is used, with the multiplier applied only when the
+step is funded from the Design Plan pool. A reported cost of **zero means "not
+reported", not "free"**, so it falls back to the table.
+
+**The fixed window never took effect.** The catalog was corrected to
+`fixed-7-day` and a test asserted it — but the test checked the catalog, not the
+estimator, and `localTotals` still bucketed by `now - 7 days`. The declaration
+and the behavior disagreed, with every test passing.
+
+Now `weeklyWindowStart()` anchors the window to the known reset time from a
+pasted reading, so the window is the subscription's, not a sliding seven days.
+The monthly bucket is untouched: it follows the billing cycle.
+
+The lesson is in `test/opendesign-window-and-cost.test.ts`: assert on computed
+figures, never on declarations. A test that checks a constant is a test that the
+constant was typed, not that anything uses it.
+
+### Calibration, and reading OpenCode's own history
+
+Two sources of truth now replace most of the guessing.
+
+**Calibration reads the charges it already handled.** Every completed step carries
+the provider's real charge, so the router can compare its own arithmetic with the
+truth on each request. The safety margin becomes measured rather than assumed: a
+fresh install has no evidence and keeps the wide default; after a handful of
+agreeing requests the margin narrows to the error actually observed. It never
+narrows below a floor, and a systematic disagreement keeps the wide margin and
+raises a warning — that is a catalog problem, not something to absorb.
+
+**OpenCode's own database has the history the ledger lacks.** Everything routed
+before the router existed is recorded per message, with its own model, tokens,
+cost and timestamp. That is strictly better than the session-level bootstrap this
+replaced:
+
+| | Session summary | Message history |
+|---|---|---|
+| Timestamp | the session's last update | each request's own |
+| Model | whatever is selected now | the one that served it |
+| Re-read | never | yes, idempotently |
+
+The per-message timestamp is what matters for a fixed seven-day window: a session
+summary smears a week of work onto one instant, so every request in it lands in
+whichever window that instant fell into.
+
+Read with `readOnly: true`, always. The module must be incapable of damaging a
+user's history, and making a write impossible is cheaper than remembering not to.
+`node:sqlite` is experimental and may be absent; every failure returns a reason
+and the router routes without it.
+
+Together these remove the recurring paste. What remains impossible to see is
+usage from *other* clients on the same account, which is why the paste survives
+as a one-time seed.
+
+### Reading the account: paste any console page
+
+There is no API for usage — upstream `nexu-io/open-design#8674` asks for one and
+remains open, the account host answers 401 to an inference key, and the gateway
+serves no usage route. So the console is the only source, and asking a person to
+translate it is where the errors come from.
+
+The panel therefore accepts **either** page and works out which it was given:
+
+| Page | What it contributes | Writes? |
+|---|---|---|
+| **Plan & balance** | The percentage of the seven-day allowance, its reset time, the tier and the wallet | yes — seeds the baseline |
+| **Usage** | Per-model tokens and charged credits for a date range | no — it is evidence about the catalog |
+| **Billing** | Same shape as Usage when it lists charges | no |
+
+Pasting a *usage* page is the more valuable of the two, because it verifies the
+arithmetic instead of assuming it. For one model, `charged credits / published
+price` is the multiplier the account actually applied: a 0.5x model charged
+$0.15 for $0.30 of usage is confirmation, and a 1x model charged twice what the
+price implies is a catalog bug — which is exactly how ten wrong prices were found
+on 2026-11-04.
+
+Reconciliation is deliberately advisory. One window of one account is not
+evidence about every customer, so a disagreement is shown with the size of the
+gap for a human to act on; it never silently adjusts prices.
+
+The parser is tolerant of what a clipboard actually produces: cells copied one
+per line, or a whole row on one line, with navigation text included. Two details
+worth knowing, both found by these tests:
+
+- A trailing `5.5` is part of a model name (`Claude Haiku 5.5`), not a
+  measurement. An inline row must carry a dollar amount or a real token count.
+- A second dollar figure while a row is open is the `Total` line starting a new
+  row. Without that, the total overwrites the last model's charge and every
+  comparison after it is wrong in a way that looks like a catalog error.
+
+### The control key is not obtainable through the product
+
+Checked on 2026-11-04 against the account's API keys page. It offers exactly one
+kind of key, `sk-amr-…`, described as connecting tools "to model services", and
+every listed key carries the same prefix. There is no control-key type, no
+account-scope option and no separate privilege to grant.
+
+So the `controlKeyPath` support below is real but unreachable for an ordinary
+customer: it exists for a credential this product does not issue. Do not present
+it as the fix for estimated numbers, and do not tell users to go and find one.
+The evidence says the account-control endpoints come from a different surface
+than the one customers can authenticate against.
+
+A control key is optional and only changes quota reporting from estimated to
+verified. Supply it only if you accept that it is a privileged credential:
+
+```json
+{ "providers": { "opendesign": { "controlKeyPath": "~/.config/opencode/opendesign-control.key" } } }
+```
+
+---
+
+## 8. Reliability handling (also fixes MiniMax stream drops)
+
+The router previously recorded `provider_outage` counts but never attributed
+them to a model, and a stream that died after the response started was
+classified `unknown`, which does not count against a model. A model that
+repeatedly dropped streams therefore kept its perfect reliability record and
+kept being selected.
+
+Three changes fix this:
+
+1. **Classification.** Mid-stream faults are recognized even when the HTTP
+   status is 200. This covers OpenCode's `provider.internal`
+   ("Streaming response failed: [500] EngineCore encountered an issue") and
+   `provider.invalid-output` ("OpenAI Chat stream ended without
+   finish_reason") signatures. User interrupts are classified `interrupted`
+   and never count against a model.
+2. **Attribution.** `session.execution.failed` and `session.idle` outcomes are
+   recorded against the model the host is actually serving, falling back to
+   the host's session record when the router has none.
+3. **Cooldown and demotion.** A provider fault puts the model into a cooldown
+   that lengthens with each repeat, and reliability now weights the success
+   estimate more strongly. A model that keeps dropping streams is avoided even
+   after the cooldown expires.
+
+Verified against a simulated mid-stream fault: the fault is classified
+`provider_outage`, attributed to the model, and the session moves elsewhere on
+the next prompt.
+
+---
+
+## 9. Lifecycle guarantees
+
+OpenDesign adds no second core, no extra polling loop, and no duplicate
+registration:
+
+- One shared core per server process, one event stream, one quota coordinator.
+- Model discovery is single-flight with a five-minute TTL and runs only when
+  the provider is enabled.
+- Quota probes go through the same per-provider backoff, single-flight and
+  retry-after handling as the other two providers.
+- The estimated quota path makes **no network request at all**.
+- A failed discovery keeps the last good catalog instead of dropping every
+  OpenDesign route.
+- An unknown OpenDesign state never disables an unrelated provider.
+- Teardown and revival follow the existing shared-core lifecycle.
+
+Verified with three concurrent project bridges: one core, one event stream,
+correct bridge counts, zero duplicate registrations.
+
+---
+
+## 10. Test and canary evidence
+
+`npx vitest run` reports **330 tests passing**. `tsc --noEmit` is clean.
+
+Three pre-existing test failures were fixed on the way. The suite read the
+developer's real `~/.config/opencode/smart-router.json` and merged it over the
+settings each test intended to use, so the result depended on the machine the
+tests ran on. The suite is now hermetic.
+
+The isolated three-provider canary ran against a local mock that mirrors the
+live gateway's response shape byte for byte, with a disposable HOME, config,
+data and cache:
+
+- Three providers registered and approved.
+- A session routed to OpenDesign, one to GOAT, one to Go Plus.
+- Credit multiplier 0.5× visible in the decision record.
+- Cache affinity: a large-context session stayed on its provider.
+- A simulated mid-stream fault was classified, attributed, and the session
+  moved off the model.
+- A verified exhausted five-hour window with a $50 wallet present moved the
+  session off OpenDesign.
+- Informational commands made zero inference requests.
+- One core, one event stream, correct bridge counts.
+
+Evidence and the 30-minute soak result are recorded in
+`docs/evidence/opendesign-2026-10-28/`.
+
+---
+
+## 11. Rollback
+
+The provider is inert unless `providers.opendesign.enabled` is true. To remove
+it entirely:
+
+```bash
+jq '.providers.opendesign = {"enabled": false}' \
+  ~/.config/opencode/smart-router.json > /tmp/sr.json && \
+  mv /tmp/sr.json ~/.config/opencode/smart-router.json
+```
+
+Then remove the `opendesign` block from `providers` in `opencode.json` and
+reload. The plugin directory can be restored from the pre-deployment backup, or
+reverted to the previous release artifact:
+
+```bash
+shasum -a 256 dist-release/index.js
+# 8c71c46c5f7616f950c6a3fcf5c42be2198407848cf9ffac15d01504496f8920
+```
+
+Emergency rollback scripts from the previous release remain valid.
+
+---
+
+## 12. What still needs your decision
+
+- Whether to enable the provider, and whether to supply a control key.
+- Whether to approve the unapproved OpenDesign models
+  (`deepseek-v4-pro`, `deepseek-v4-flash`, `deepseek-v4-flash-vision-exp`,
+  `glm-5.3-flashx`, `hy4-preview`, `kimi-k2.7-code`).
+- Confirming automatic recharge is disabled in the OpenDesign console.
+- Authorising any real-provider test. None was run.