dsh-model-switch 0.0.0-stage → 0.4.18

package/CHANGELOG.md

@@ -0,0 +1,184 @@
+## v0.4.18
+
+Declare official DSH `0.2.0-rc.2` compatible in `package.json#dsh.compatibility.dshReleases`.
+
+Evidence, in the order this repository's compatibility policy requires:
+
+- **Public API review:** the 0.2.x Host renamed the pending-question withdrawal verb (`PendingQuestion.cancel()` → `dismiss()`), fires `session.selectModel`'s deployment-default write without awaiting it, and reports a refused `ModelDirectory.select` as a returned `{ ok: false }` value instead of throwing. Each difference broke v0.4.16, and each is fixed in v0.4.17.
+- **Tests and build:** `pnpm run check` green — `tsc` + `tsdown`, the full vitest suite, and the pack gate against a real tarball.
+- **Lab plane:** profile composition `exit 0` with no skipped bundle, Host boot on port 3082 with the plugin's capability RPC answering, and the npm-installed build booting on port 3085 with its client bundle served.
+- **Live desktop verification on 0.2.0-rc.2:** all three Plan Review actions exercised against a real session — Discuss withdraws the takeover and returns the composer; Reject delivers typed feedback verbatim as the answer's `custom` text; Confirm commits a different execution model, approves the plan, and restores the Main default to its pre-switch value.
+
+## v0.4.17
+
+First release published to the npm registry, so `dsh plugin --profile <name> add dsh-model-switch` installs prebuilt code without a git build authorization. Publishing builds `lib/` through `prepublishOnly`, and `pnpm run check` now runs its pack gate on Windows as well.
+
+- Plan Review **Discuss in chat** now withdraws the takeover through the verb the running Host publishes (`PendingQuestion.dismiss()` on 0.2.x, `cancel()` on 0.1.x) instead of calling `cancel()` unconditionally, which threw on a Host that renamed it; a Host exposing neither is named explicitly.
+- Plan Review **Reject** sends text from the card's feedback field as the answer's `custom` text, so a rejection reaches the model with what to change instead of a bare option label.
+- Compensate the deployment default through the namespace revision actually observed: wait for the Host's unawaited `session.selectModel` default write, fence on the observed revision, retry once against a concurrent edit, and never fail the answer. The previous `captured + 1` fence assumed an awaiting Host and could either refuse the restore (leaving the Plan unanswerable) or silently leave the Main default switched.
+- Treat a refused official `ModelDirectory.select` result as an uncommitted model change instead of reporting success.
+- Keep Confirm and Reject closed after a settled review while Discuss and a reload affordance stay reachable, and surface the wire code of a failed action.
+- Fix a line-ending fragile mobile width-budget assertion.
+- Make the pack gate portable: resolve npm's own CLI when a shell-less spawn cannot launch the Windows `.cmd` shim, compare archive members across line endings, and link the extracted package with a junction on Windows.
+
+## v0.4.16
+
+- Bundle shared Provider UI helpers from the published v0.2.14 release.
+- Apply the official menu backdrop material and preserve picker focus through model selection, pane changes, and search dismissal.
+- Keep search autofocus and return focus to the trigger when Escape closes the summary.
+- Verify official DSH 0.1.7-rc.2 with open-ended Host dependency ranges.
+
+## v0.4.15
+
+Accept DSH releases from 0.1.7-alpha.2 onward through open-ended peer and development ranges. Rebuild and verify against official 0.1.7-rc.1 without changing model routing behavior.
+
+## v0.4.14
+
+Target official DSH `0.1.7-alpha.2`, pin Provider UI `0.2.12`, and move Main, Subagent, search, image, and compaction controls to published ConfigForms. On non-loopback browsers the official forms are memory-only: Settings shows an explicit unavailable state and the picker refuses selections that would otherwise persist a deployment-wide default without a safe restoration path.
+
+## v0.4.13
+
+Replacement Subagent runtime exposes public `resolveMaxDepth` so Host 0.1.6-alpha.2 Standard remount keeps Model Switch routing. Compile target stays `0.1.5-rc.1`.
+
+## v0.4.12
+
+Optional Default Subagent route (Official inherit when off) and Switch compaction as a Send protection B-row.
+
+## v0.4.11
+
+Rank live catalogRoutes. Compact-on-switch uses previous-provider usage when present.
+
+# Changelog
+
+## [0.4.10] - 2026-09-13
+
+- Include completion notices in the send-time budget; verify concurrent sessions, retained-input retry, live progress, and durable notice replay through the real agent loop.
+- On send, when the assembled target model or context-tier id differs from the last request, check the pending request against the target window and compact once with the previous model if needed. Picker-only changes do no work. Default on; Settings → Model Switch can turn it off without disabling DSH automatic compaction.
+- DSH Host packages are no longer version-locked. `@deepseek-ai/dsh-*` peers are `*` and optional; unknown Hosts warn once and still mount. Cordis stays `>=4.0.2 <5.0.0`. Compile-target `devDependencies` remain `0.1.5-rc.1`.
+- Keep Fast / Context / Thinking / Effort switches on the current Agent after a turn; disable unpublished sibling rows instead of ignoring clicks.
+- Composer picker Cursor mark comes from `dsh-llm-providers-ui` 0.2.6.
+
+## [0.4.9] - 2026-09-09
+
+- Reserve the selected execution runtime as soon as a prompt is submitted, before the first token or native binding.
+- Native Antigravity keeps its models and effort; DSH keeps LLM-provider choices and disables Agent providers until cancel or a durable native binding.
+
+## [0.4.8] - 2026-09-07
+
+- Development dependency now points at the final `dsh-llm-providers-ui` 0.1.10 release URL with pinned integrity; Alpha.4 fixtures updated coherently (roots + provider identity + fresh self-root tarball).
+
+## [0.4.7] - 2026-09-06
+
+- Unify provider-owned independent Web search metadata and execution for DeepSeek, Codex and Grok through the existing adapter registry and authenticated capability RPC.
+- Reuse official DeepSeek search settings/credentials and preserve the deployment’s complete Web config, including fetchProvider. Global search routing remains an explicit opt-in with no silent fallback.
+- Recover capability polling after transient failures and Host revision resets; skip unchanged heartbeats without hiding unload warnings or enabling stale saves.
+- Preserve Antigravity session routing and released v0.4.6 runtime compatibility; correct picker test fixtures without weakening approval safety assertions.
+- Coordinate with Codex 0.3.14, Grok 0.3.11 and Provider Directory 0.1.9; install and validate immutable packages in lab before production promotion.
+
+## [0.4.6] - 2026-09-03
+
+### Changed
+
+- DSH compatibility declarations cover the verified Alpha.4 and rc.1 runtimes.
+- Unknown runtimes warn once and use the normal best-effort mount path; only reproduced failures may be blocklisted.
+
+
+## 0.4.2
+
+- Settings → LLM Providers: drag cards to reorder; chat picker follows `llm-providers.order` via dsh-llm-providers-ui.
+
+
+## 0.4.3
+
+- Keep a Host-accepted composer selection visible while its durable Session projection catches up, then return authority to newer projected selections.
+
+## 0.4.1 - 2026-08-29
+
+- Support DSH 0.1.2-alpha.1 through the public Cordis, Settings, Remote, Session, and Model Directory services after the monolithic client runtime removal.
+- Carry fixed Subagent reasoning effort on alpha.1.
+- Let the composer model trigger use the full available seat width on mobile instead of clipping long model labels.
+- Keep Composer and Plan model switches session-local with a revision-fenced Main-default restore where the Host couples session selection to deployment defaults.
+- Publish bilingual product documentation and screenshots, including the provider-catalog rules for custom Picker families.
+
+## 0.3.11 - 2026-08-27
+
+- Lock the real composer UI path for independent Context 1M and Fast On selection: when the provider catalog publishes a combined `*-1m-fast` row, the picker preserves both dimensions and submits that exact model id.
+- Document through regression evidence that providers must publish the combined row; separate `*-1m` and `*-fast` rows cannot represent both dimensions simultaneously.
+
+## 0.3.10 - 2026-08-27
+
+- Keep mobile picker triggers, headings, model names, catalog descriptions, and values readable by rendering and wrapping instead of truncating.
+- Resolve optional mobile interaction operations only through Cordis's typed public non-strict service lookup.
+- Consolidate each picker snapshot and its operations into one render view backed by the official directory status/routability contract, retaining selected routes absent from the advisory catalog.
+- Isolate popup activation, positioning, and dismissal in a deep internal module.
+- Keep composer and Plan Review picker crashes mounted as localized, retryable diagnostics.
+- Preserve Plan Review's one-row mobile footer while shrinking controls and wrapping action labels inside their buttons at narrow widths.
+
+## 0.3.9 - 2026-08-27
+
+- Preserve the 320px preferred picker width whenever the mobile viewport allows it, shifting away from the trigger instead of squeezing to 240px.
+- Hide horizontal list overflow while retaining vertical scrolling, removing the mobile horizontal scrollbar.
+
+## 0.3.8 - 2026-08-27
+
+- Keep a mobile pointer's open/close intent idempotent through the 750ms tap-fallback window so a detail-zero programmatic click cannot reopen a picker that the user just closed.
+
+## 0.3.7 - 2026-08-27
+
+- Make click the sole owner of picker toggle state so one mobile touch cannot open on pointerdown and immediately close on its synthetic click.
+
+## 0.3.6 - 2026-08-27
+
+- Restore non-strict lookup for the optional mobile interaction service; Cordis may reject direct undeclared-property access, which previously crashed the custom seat on render.
+
+## 0.3.5 - 2026-08-27
+
+- Declare the merged picker's Sessions and model-directory services in the client plugin's top-level injection contract so production completes the custom seat registration.
+
+## 0.3.4 - 2026-08-27
+
+- Contain composer-seat render/effect errors inside the merged picker so a crash cannot silently abdicate to the official picker; show a retryable diagnostic instead.
+- Treat the Sessions face as optional while the public model-directory service gate is active.
+
+## 0.3.3 - 2026-08-27
+
+- Restore merged picker ownership of the composer model seat by matching the official service gate and using an unambiguous winning priority.
+- Treat optional mobile interaction-surface failures as a graceful degradation instead of crashing and abdicating the custom seat to the official picker.
+
+## 0.3.2 - 2026-08-27
+
+- Match Model Switch route cards to the shared LLM Providers chrome: radius, fill, border, spacing, icon treatment, title weight, summary size, chevron, and expanded body.
+
+## 0.3.1 - 2026-08-27
+
+- Keep the Model Switch settings nav glyph after the official Settings shell redraws its SVG.
+- Restore a visible platform-gray fill for collapsed route cards; every route remains collapsed on mount.
+
+## 0.3.0 - 2026-08-27
+
+- Absorb the composer model picker and Plan Review execution picker into this package.
+- Plan Review uses the official warn-strip card, a short capsule trigger, and a two-level Model/Effort/Context/Fast/Thinking menu.
+- One `dsh plugin add dsh-model-switch` now covers routing Settings and composer/Plan selection. Remove a standalone `dsh-composer-picker` install to avoid a second model seat.
+- Picker trigger shows the family name plus distinct effort / Fast / context bits; duplicate context windows collapse to one menu row.
+- Known limitations: Settings nav icon still patches official nav DOM (no public icon field, same pattern as usage-monitor).
+
+## 0.2.0 - 2026-08-26
+
+- Keep official `web_search` ownership and add a thin `model-switch` Web Search provider with Codex model routing.
+- Add stable `generate_image` routing through optional Codex and Grok adapters, with provider-specific schemas regenerated after Image route changes.
+- Add Search and Image settings cards while keeping Vision/read_image excluded.
+- Preserve existing provider-specific image tools and `web_fetch` as rollback paths.
+
+
+## 0.1.1 - 2026-08-26
+
+- Ship compiled Host/Client `lib/` in the git tag so `github:…#v0.1.1` installs can boot.
+
+## 0.1.0 - 2026-08-26
+
+- Add Main default and follow-main/fixed Subagent model routing for DSH 0.1.1-rc.2.
+- Resolve follow-main from the active parent request header before stale session options.
+- Preserve inherited provider/model when rc.2 cannot carry reasoning effort.
+- Leave Search, Vision, image reading, ordinary chat attachments, and image generation on their existing official/provider paths.
+- Add localized Model Switch settings and clean plugin lifecycle integration.
+- Keep ordinary chat attachments on the official DSH path.

package/IMPLEMENTATION_PLAN.md

@@ -0,0 +1,40 @@
+# Model Switch implementation plan
+
+## Milestone 1 — package and pure routing core
+
+1. Establish the publishable package, strict TypeScript declaration build, ESM bundle, and fail-closed Cordis entry.
+2. Preserve the released Main/Subagent deep modules. Add two confirmed v0.2 seams: a `ModelSwitchSearchProvider` implementing the official `WebSearchProvider` interface over a provider adapter registry, and a stable `generate_image` tool over an Image adapter registry. Keep Vision outside runtime delivery.
+3. Gate an actual tarball: load every export target from extraction; reject source, tests, scripts, source maps, patch/diff payloads, Core paths/fork contracts, and local dependency protocols.
+4. Prove emitted artifacts reproduce from different checkout paths.
+
+**Completion:** `pnpm run check` and `git diff --check` pass. No DSH runtime, UI, preset, or lab changes occur.
+
+## Milestone 2 — released runtime seams
+
+Register each feasible Settings/runtime capability only through released public Cordis/DSH interfaces, and expose every unavailable route as explicit capability data rather than simulated behavior. Contract-test against clean alpha.1 infrastructure rather than a hand-built context alone.
+
+**Implemented foundation on alpha.1:** Model Switch owns its Settings namespace; Main reads/saves through the official Agent Default Model service; registration, committed updates, Main delegation, and disposal are covered by a real Cordis + Settings composition test.
+
+**Implemented coordinated replacement:** the package bundle patch disables the released Loader row with id `subagent` and inserts the uniquely identified plugin-owned `dsh-model-switch/subagent-runtime`; removing the bundle restores the official profile composition. The replacement selects provider/model/effort before delegating to the official alpha.1 one-shot and continuable descriptor creation, and fails closed for partial routes, ambiguous or unexpected rows, and unsupported effort transport. Do not replace the launcher-pinned AgentPresets row: a nested AgentPresets instance loads a second dsh-scope identity and breaks session.create. Official presets consume the replacement `subagents` service after the Subagent Loader row is replaced. Search must use the released Web provider seam rather than registering a duplicate tool; Image may register only the unique `generate_image` name.
+
+Known seam constraints from alpha.1 inspection:
+
+- Web session creation has no atomic create-time model override; use the existing public Main Settings namespace rather than post-create selection. The Host couples `session.selectModel` to a deployment-default write, so the owned composer/Plan picker restores the captured Main default through `settings.mutate` at the immediately following revision; conflicts are left untouched so concurrent Settings edits win.
+- Tool registration has disposal but no atomic replacement; stage complete generations and roll back on registration failure.
+- A later child model switch cannot rewrite its durable continuable descriptor; creation snapshots remain authoritative.
+- Search routing owns only provider id `model-switch`; the deployment profile pins `web.searchProvider: model-switch` while preserving its existing `fetchProvider`. The official `web_search` and `web_fetch` tools are untouched.
+- `generate_image` is unique, so existing provider-specific image tools remain enabled and require no owner suppression.
+- Codex and Grok register Search and Image adapters. The DeepSeek bridge reuses the official public search implementation and existing settings/credential service. Optional Cordis injection preserves standalone provider behavior and disposal; only Host-projected search metadata reaches the UI.
+- Vision remains outside runtime delivery and must not register or shadow `read_image`.
+
+## Milestone 3 — settings surface
+
+Contribute the Model Switch settings section through declared client slots (alpha.1 has no generic standalone page registry). Use one lifecycle controller/store, three derived prop shares, plain presentation data/callbacks, optimistic revisions, independent row saves, capability filtering, and zh/en dictionaries.
+
+## Milestone 4 — provider adapters and composition
+
+Keep the launcher-pinned `agent-presets` row and official web tools. Add clean optional adapter releases to Codex and Grok without Vision or hard runtime dependency cycles. Explicitly configure Lab `web.searchProvider` to `model-switch` while preserving the complete existing Web config, including `fetchProvider`. The bundle does not modify the Web row; restore the prior deployment search pin before removing Model Switch. Model Switch ships no preset copies.
+
+## Milestone 5 — pack/profile/lab acceptance
+
+Run the full composition matrix from packed artifacts under `DSH_HOME=~/.dsh-lab` on port 3082. Validate boot, HTTP, profile composition, and artifact hashes; leave browser-only visual checks to the human because the managed browser must not open DSH itself.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 NOirBRight
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/PRODUCT.md

@@ -0,0 +1,33 @@
+# Model Switch — frozen product scope
+
+**Model Switch** is a coordinated plugin-only DSH product for explicit model routing. Product, package, bundle, and settings-page identity remain **Model Switch** / `dsh-model-switch`. It may replace independently packaged DSH modules through name-matched public disable-and-insert patches and may extend self-maintained provider plugins, but never edits DSH Core, official package files, or production during acceptance.
+
+## Routes
+
+- **Default Main:** provider, model, and optional effort. It uses the public Settings namespace and is copied only into newly created sessions; existing sessions are never migrated or selected through the session picker.
+- **Default Subagent:** one optional fixed provider/model/effort, injected only when a child spawn names no provider, model, or effort. When the setting is off, stored `follow-main` is read as unset and Model Switch injects nothing; Official inherit (parent live request, then creation snapshot) and the official Allowlist remain DSH's. The default is not an Allowlist and need not be a member of one. Local spawn, fork, continuable, and workflow children use this policy unless the spawn already supplies provider, model, or effort. Remote Codex/Claude children are outside unified routing.
+- **Search Router:** does not register or replace `web_search`. Model Switch registers one public `WebSearchProvider` with id `model-switch`; the existing official `web_search` continues through `ctx.web`, whose configured search provider must be `model-switch`. The thin provider selects the configured backend adapter and model at execution time and returns the official `WebSearchResult` unchanged. v0.2.0 supports Codex Search only. `web_fetch` and its configured provider remain unchanged.
+- **Vision:** excluded. Model Switch exposes no Vision setting, does not shadow `read_image`, and does not preprocess chat attachments.
+- **Image Router:** owns a new, uniquely named stable `generate_image` tool. It selects the configured Codex or Grok adapter/model at execution time, rejects backend-incompatible fields, and returns normalized image metadata. Existing provider-specific image tools remain available as rollback paths.
+- **Composer Picker:** replaces the composer model seat with a suffix-grouped Model / Effort / Context / Fast / Thinking picker and submits through the official Model Directory. Variant changes preserve an effort only when the target catalog row supports it, otherwise they use the target default or omit effort. Picker changes are session-local. A submitted prompt reserves the selected runtime immediately (composer submitting, pending first turn, or running). Native Antigravity keeps its models and effort; DSH keeps LLM-provider choices and disables Agent providers. After a successful native binding, other groups stay disabled. Cancel without a binding releases the reservation; existing DSH history still cannot convert onto an External Agent. On a Host version that also persists session selection as the deployment default, the plugin restores the pre-switch Main default through the public Settings RPC with a revision fence; a concurrent Settings-page edit wins.
+- **Plan Review:** intercepts the official `plan-review` composer takeover with a header execution-model picker and right-aligned Discuss in chat / Reject / Confirm actions. Confirm commits the selected model before answering; a refused commit leaves the review pending and retryable, while a deployment default this plugin could not restore is announced after the answer instead of holding the human's decision back. Reject carries optional human feedback as the answer's own `custom` text, which plan mode reports to the model. Discuss in chat withdraws the takeover through the Host's own verb — `dismiss()` where the Host publishes it, `cancel()` on the older generation — and names the Host when neither seam exists, so a settled review is never a dead end. The same runtime reservation applies.
+
+Model choices are capability-driven. Invalid, unavailable, or unsupported selections remain visible to configuration surfaces and fail loudly at use; routing never silently falls back.
+
+## Preset modes
+
+Official `agent-presets` stay in the process. A nested `ctx.plugin(AgentPresets)` from this package would load a second `@deepseek-ai/dsh-scope` identity, so `session.create` fails with an unscoped-context refusal. Preset delegation tools already resolve the replacement `subagents` service after the Subagent Loader row is replaced. Model Switch ships no preset roots and leaves the official presets unchanged.
+
+## Settings and lifecycle
+
+The settings surface aggregates public Settings namespaces, reads and mutates with optimistic revisions, and saves rows independently. Changing a Main or fixed Subagent model applies only the target catalog row's default effort, so an effort never leaks across providers or models. The Subagent card is a RouteCard with an instant on/off for the Default Subagent route; turning it off keeps the last provider/model on disk. Switch compaction is a B-row in the Send protection group (发送保护), default on, written immediately. Every registration, watcher, and dynamic tool generation has clean disposal. All visible copy lives in zh/en locale dictionaries.
+
+## Exclusions
+
+Send-time context protection (check, and compact with the previous model when a sent message would exceed the target window) is in scope. Model Switch does not own global compaction policy, titles, fetch routing, fallback, load balancing, provider credentials, CLI/API, configuration history, or DSH Core edits. Coordinated changes are limited to Model Switch and self-maintained provider plugins. Installing this package replaces a standalone `dsh-composer-picker` install; keep only one composer model seat.
+
+Official `settings.section` has no icon field. The Settings nav glyph is a label-matched DOM swap, the same published pattern as usage-monitor, until an official icon seam exists. The Plan Review takeover uses priority -5, and the composer model seat uses priority -10.
+
+## Delivery architecture
+
+The package foundation and pure deep modules remain the policy/test surface. Runtime delivery disables the independent Subagent Loader row with its official name and inserts a uniquely identified replacement. Official AgentPresets stay mounted so they share the process `dsh-scope` identity. Search uses the released `ctx.web.registerSearchProvider()` seam so official tool ownership is preserved. Image uses a unique tool name and provider-owned authenticated adapters. Self-maintained Codex/Grok plugins register optional adapters through the public Model Switch service when present; standalone provider behavior is unchanged. Vision remains disabled. Replacement modules preserve the official public interfaces and fail closed when compatibility or capability validation fails.

package/README.md

@@ -1,3 +1,198 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# Model Switch
+
+English | [中文](README.zh.md)
+
+Choose one explicit route for Main, Subagents, Web Search, image generation, the active conversation, and Plan execution in DeepSeek Harness. Model Switch uses public DSH services and provider-owned adapters; it does not patch DSH Core or manage provider credentials.
+
+<p align="center"><img src="docs/screenshots/composer-picker.png" alt="Composer Picker with Model, Effort, Context, and Fast controls" width="314"></p>
+
+The picker retains keyboard focus when changing panes or closing search, without overriding search autofocus. Escape from the summary closes the picker and returns focus to its trigger.
+
+## Routes
+
+| Route | Behavior |
+| --- | --- |
+| Main model | Default provider, model, and optional effort for newly created sessions. Existing sessions are not migrated. |
+| Subagent | Follow the active parent route, or use a fixed provider/model/effort. Workflow overrides remain authoritative. |
+| Composer Picker | Changes only the active session and submits the exact catalog model id. Main defaults are preserved. |
+| Plan Review | Chooses the execution model before the Plan approval response is sent. |
+| Web Search | Keeps official `web_search`; after deployment opt-in, routes through the selected, dynamically declared provider search adapter. |
+| Image generation | Provides one stable `generate_image` tool routed through a selected Codex or Grok adapter. |
+
+Invalid, unavailable, or unsupported routes fail explicitly. Model Switch never silently falls back to another provider or model. Composer icons identify the execution runtime: DSH-owned LLM routes use the theme-adaptive DSH whale; providers declaring the Agent role use their own mark. Sidebar quota icons remain provider-specific.
+
+Idle blank sessions may pick an External Agent. Submission, pending-first-turn, and running state reserve the selected execution runtime even before a token or native binding exists: native Antigravity keeps its model/effort choices; DSH keeps LLM-provider choices but disables Agent providers. After the first accepted user message, Composer and Plan Review keep Agent-role rows visible but disabled unless the session is already native-bound. After the active session successfully opens a native Antigravity session, the pickers read its plugin-owned binding and disable other providers while keeping available Antigravity model and effort controls. The DSH global picker lock remains authoritative. Binding reads refresh on mount, input-phase, request-activity or catalog changes, and before selection; failed reads show a localized alert and preserve a known native lock. These reads do not start the native runtime or gate conversation history. Antigravity owns the separate execution-time guard; Model Switch does not create custom Core history events.
+
+The existing 3082 lab replay probe is `node scripts/check-lab-runtime-lock.mjs [native|runtime-absent|plugin-absent]`. It checks the dedicated QA conversation under the already-established condition; it does not disable plugins, select a model, or send a turn. `node scripts/check-lab-native-execution.mjs` verifies the saved guard rejection, restored native continuation, DeepSeek-parent/Antigravity-child completion, and restoration of temporary subagent preferences through public history streams.
+
+## Configure Main and Subagents
+
+Open **Settings → Model Switch**. Main changes affect new sessions only. Subagents may follow Main or use a fixed provider, model, and effort.
+Official DSH `0.1.7-alpha.2` makes ConfigForms memory-only in non-loopback browsers. This page shows an unavailable message there; open Settings on the Host loopback URL instead. The composer picker refuses model changes in that mode because the published `session.selectModel` also persists the deployment default, which cannot be safely restored without a writable Main ConfigForm. Remote editing and session-only selection require an upstream authenticated ConfigForm seam and a session-only selection API; this plugin does not bypass the official policy.
+
+Changing the Main or fixed Subagent provider/model replaces the previous model's effort with the target model's default. Models without reasoning support receive no effort.
+
+![Model Switch settings with a fixed Subagent route](docs/screenshots/settings-subagent.png)
+
+Follow Main resolves the active parent request first, then the configured Main default. A fixed route is injected before the official Subagent descriptor is created. DSH 0.1.2-alpha.4 carries provider, model, and fixed reasoning effort in that descriptor.
+
+## How custom models appear in the Picker
+
+Model Switch does not turn an arbitrary string in its own settings into a model. A provider plugin must publish the model to the official DSH model catalog first:
+
+```text
+Provider configuration
+→ provider publishes model rows to the DSH catalog
+→ the active session Model Directory exposes provider/model metadata
+→ Model Switch groups those catalog rows
+→ the Picker submits the original provider id and model id
+```
+
+The catalog supplies the provider name, model id/name, reasoning efforts, and default effort. A saved route that is no longer present remains visible as unavailable in Settings; the Picker does not pretend it is routable.
+
+### Variant id grammar
+
+Model Switch groups catalog rows by provider and by the model id after peeling these suffixes:
+
+| Catalog model id | Picker variant |
+| --- | --- |
+| `acme-v1` | Standard row |
+| `acme-v1-fast` | Fast |
+| `acme-v1-128k` | Context 128K |
+| `acme-v1-1m` | Context 1M |
+| `acme-v1-1m-fast` | Context 1M + Fast |
+
+Rules:
+
+- `-fast` creates the Fast axis.
+- `-<n>k` and `-<n>m` create Context tiers; suffixes may be combined with `-fast` in either order.
+- `reasoning.efforts` creates the Effort choices; `reasoning.defaultEffort` selects the initial value.
+- Switching Fast, Context, or Thinking variants keeps the current effort only when the target catalog row supports it; otherwise the target row's default effort (or no effort) is used.
+- Reasoning metadata marks a catalog row as Thinking-capable.
+- Unrecognized ids remain independent model families; Model Switch never drops them.
+
+To support a combined selection, the provider must publish the combined row. Publishing only `acme-v1-fast` and `acme-v1-1m` cannot represent Fast + 1M; publish `acme-v1-1m-fast` as well. The Picker never synthesizes a model id that the provider did not publish.
+
+## Plan Review
+
+Plan Review owns an execution-model draft separate from Main. **Confirm** first commits that model to the active session, then answers the pending Plan review. A refused commit leaves the review pending and retryable; a Session switch the Host accepted but whose deployment default could not be restored is announced after the answer instead of withholding it. **Reject** and **Discuss in chat** do not execute the Plan.
+
+**Reject** sends the option the asker offered, and any text typed in the card's feedback field as the answer's own `custom` text — plan mode reports that text back to the model as the reason to keep planning, so a rejection can carry what to change. **Discuss in chat** withdraws the takeover so the composer returns and the human speaks in their own words; it uses the Host's `dismiss()` where published and the older generation's `cancel()` otherwise, and names the Host when neither exists. Answering a settled review closes Confirm and Reject, while Discuss and the reload affordance stay reachable so the card always has a way back. Failures keep their wire code (`session/writer-held: …`) visible instead of a bare localized sentence.
+
+![Plan Review with an execution-model picker](docs/screenshots/plan-review.png)
+
+## Send-time context protection
+
+When a sent message will use a different model or context-tier id than the last request, Model Switch checks the full pending request against the target window before that request is sent. Choosing a model in the picker does not compact. If the target is over budget, history is compacted once with the previous model through a private compaction engine; DSH's own automatic compaction settings are not changed. Progress appears as plugin notices in the transcript. The budget includes the completion notice and pending model-change notice; an oversized summary blocks the request. Failure keeps the user message in the session and does not send the target request or emit a switch-success notice. Turn the behavior off with **Settings → Model Switch → Check and compact context on send** (on by default). Native External Agent runtimes are not treated as DSH-compactable history.
+
+## What Model Switch does not change
+
+- `web_fetch` and its configured provider
+- Vision routing, `read_image`, and ordinary chat attachments
+- Provider login, credentials, or provider settings cards
+- Official Agent Presets
+- Existing provider-specific image tools
+- Existing sessions when the Main default changes
+- Global compaction policy, titles, or DSH Core
+
+## Installation
+
+Model Switch ships prebuilt code, so an install needs no build authorization. Install it from the npm registry:
+
+```sh
+dsh plugin --profile web add --force dsh-model-switch
+```
+
+A packed tarball installs the same build without a registry:
+
+```sh
+dsh plugin --profile web add --force ./dsh-model-switch-0.4.17.tgz
+```
+
+Then install only the provider adapters you use. This release was checked against official DeepSeek Harness `0.1.7-rc.2` and verified on `0.2.0-rc.2`:
+
+```sh
+dsh plugin --profile web add --force \
+  https://github.com/NOirBRight/dsh-llm-providers-ui/releases/latest/download/dsh-llm-providers-ui-0.2.14.tgz
+dsh plugin --profile web add --force \
+  https://github.com/NOirBRight/dsh-llm-codex/releases/latest/download/dsh-llm-codex-0.3.23.tgz
+dsh plugin --profile web add --force \
+  https://github.com/NOirBRight/dsh-llm-grok/releases/latest/download/dsh-llm-grok-0.3.19.tgz
+```
+
+### Search routing (0.4.7)
+
+Providers declare independent search adapters and model metadata on the existing Host `ModelSwitchAdapterRegistry`. The browser receives only id/name/model metadata over authenticated Connection RPC, not adapters or credentials. Registration/unload updates subscribers; in-place catalog changes are picked up by the bounded 20-second heartbeat. `ProviderDirectory` remains the client role/usage owner, not a second Host execution registry. Published 0.2.8 `sortCatalogGroups` only ranks hardcoded LLM routes; Model Switch ranks live `catalogRoutes` itself so Agent catalog ids follow saved card order when the Owner publishes them. Native `catalogId` / `unknown` account styling still need a newer Owner than published 0.2.8.
+
+DeepSeek uses the official public `DeepSeekSearchProvider`, the existing `web-search-deepseek` settings and credential service. Codex uses its existing ChatGPT credentials; Grok uses its existing subscription token and provider-owned Responses search. Native conversational networking alone does not create a search option. Missing credentials, invalid settings, unsupported models and unavailable adapters fail explicitly, without fallback.
+
+**Registering an adapter does not select the global Web route.** Installation leaves the deployment's existing Web configuration untouched. To opt in, set the existing Web entry's `searchProvider` to `model-switch` while retaining **every other existing config field**, especially `fetchProvider`. DSH id-targeted patches replace the entire config rather than deep-merging it: copy the complete effective config from `dsh --profile web --dump-config`, then change only searchProvider in the deployment/user patch. Do not copy an assumed `fetchProvider: http` over a custom pin.
+
+After opting in, configure the requested search provider/model in Model Switch Settings. No complete supported route means `WEB_PROVIDER_CONFIGURED_UNAVAILABLE` through the official selector; there is no automatic DeepSeek fallback. Without the global pin, the dropdown does not control `web_search`. An unpinned Web service can become ambiguous when multiple search providers are usable. Before uninstalling Model Switch, restore the deployment's prior search pin; otherwise the official selector correctly reports a missing configured provider. The official `web_search` and `web_fetch` tools are never replaced.
+
+Release-aligned search regression: `DSH_RELEASE_ANCHOR=/path/to/official/install/package.json pnpm exec vitest run --config tests/vitest.release.config.ts`. See [search audit and acceptance](docs/search-provider-audit.md) for exact baselines, dependencies and live status.
+
+If `dsh-composer-picker` is installed, remove it from the profile before enabling Model Switch. Model Switch already owns the Composer Picker and Plan Review seat; two owners produce duplicate or competing UI.
+
+Production profiles must use a released registry version or GitHub tag rather than workspace-local dependencies. Restart the selected DSH profile after installation or route changes.
+
+## Compatibility
+
+DSH Host peers and development dependencies accept `>=0.1.7-alpha.2`, including rc.1 and later releases. The development lockfile resolves to rc.2. Cordis accepts `>=4.0.4 <5.0.0`.
+
+Verified releases: `0.1.7-alpha.2`, `0.1.7-rc.1`, `0.1.7-rc.2`, `0.2.0-rc.2`. The 0.2.0 claim covers the Host's renamed question verbs, its unawaited `session.selectModel` default write, and its returned `ModelDirectory.select` refusal, each verified in the lab and on a live desktop session.
+
+The verified releases in `package.json#dsh.compatibility.dshReleases` are evidence, not an allowlist. Review public API changes and test new Host releases before adding a verification claim.
+
+## Development
+
+Requires Node 22.19+ and pnpm.
+
+```sh
+pnpm install
+pnpm run check
+```
+
+`check` builds Host and Client artifacts, runs unit and Cordis/Settings composition tests, validates the extracted package, and verifies reproducible bundles. Product scope is defined in [PRODUCT.md](PRODUCT.md); implementation constraints live in [IMPLEMENTATION_PLAN.md](IMPLEMENTATION_PLAN.md).
+
+## Release installation (Latest)
+
+Explicit model routing for Main, Subagent, Composer, Plan Review, and capability tools, checked on official DeepSeek Harness `0.1.7-rc.2` and `0.2.0-rc.2`. The release artifact contains built Host/Client files, not sibling source or local paths.
+
+Latest installation (the asset filename must match the current latest release):
+
+~~~sh
+dsh plugin --profile web add --force \
+  https://github.com/NOirBRight/dsh-llm-providers-ui/releases/latest/download/dsh-llm-providers-ui-0.2.14.tgz
+dsh plugin --profile web add --force \
+  https://github.com/NOirBRight/dsh-model-switch/releases/latest/download/dsh-model-switch-0.4.16.tgz
+~~~
+
+Fixed-version installation:
+
+~~~sh
+dsh plugin --profile web add --force \
+  https://github.com/NOirBRight/dsh-llm-providers-ui/releases/download/v0.2.14/dsh-llm-providers-ui-0.2.14.tgz
+dsh plugin --profile web add --force \
+  https://github.com/NOirBRight/dsh-model-switch/releases/download/v0.4.16/dsh-model-switch-0.4.16.tgz
+~~~
+
+Update, uninstall, and verify:
+
+~~~sh
+# Update to the latest Release
+dsh plugin --profile web add --force \
+  https://github.com/NOirBRight/dsh-llm-providers-ui/releases/latest/download/dsh-llm-providers-ui-0.2.14.tgz
+dsh plugin --profile web add --force \
+  https://github.com/NOirBRight/dsh-model-switch/releases/latest/download/dsh-model-switch-0.4.16.tgz
+# Verify the loaded version
+dsh plugin --profile web list
+# Uninstall only this plugin
+dsh plugin --profile web remove dsh-model-switch
+~~~
+
+Configuration: use the plugin section in Settings for Web UI plugins, or the profile dsh.profile.bundles entry for Host-only plugins. Start with this README's minimal YAML/JSON example and provide credentials/backend addresses explicitly.
+
+Rollback: reinstall the immutable v0.4.15 archive and restore the recorded profile; no Host downgrade is required. Inspect journalctl --user -u dsh-web.service; never link a checkout into production.
+
+Release and integrity: [v0.4.16](https://github.com/NOirBRight/dsh-model-switch/releases/tag/v0.4.16) · [SHA256](https://github.com/NOirBRight/dsh-model-switch/releases/download/v0.4.16/dsh-model-switch-0.4.16.tgz.sha256).