Merge branch 'stack/agent-profiles-1-seam' into stack/agent-profiles-3-wire

master extracted this layer's inline cold-resume resolver into @deepseek-ai/dsh-api-remotes, whose `setup` was a fixed AgentSetup. A resumed session composes the preset ITS header recorded, so the option becomes a function of that header; the resolver builds the setup before the published re-checks so those stay adjacent to `resume`. Conflicts: docs/cordis-catalog/services.md docs/module-graph.md packages/host/apiproxy/package.json packages/host/apiproxy/src/api-proxy.ts pnpm-lock.yaml
2026-08-08 14:26:38 +08:00
parent 342b5c4830 2afdc68fab
commit c5ca12eabd
649 changed files with 21067 additions and 2810 deletions
--- a/packages/host/apiproxy/README.i18n.yaml
+++ b/packages/host/apiproxy/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/host/apiproxy/README.md
-README.md: 395e0d5085878e230fdf7de49a0ca47745bdc270
-README.zh.md: 2ef34f7d6e7ae031dd5f847dfa13827fe4550839
+README.md: 7ac7bdc6db2e2abbc60d1a8813e229c21ed39fe7
+README.zh.md: d6ece5caed752cf0cc59cc97017549ec2b1e66cb
--- a/packages/host/apiproxy/README.md
+++ b/packages/host/apiproxy/README.md
@@ -2,7 +2,19 @@

 English | [中文](README.zh.md)

-The API gateway every client shape shares: the TS contract (`src/api/`, zero Node dependencies, importable from the browser), the fetch carrier pair (`src/fetch/`: `toFetchHandler` on the host side, `AbstractApiClient` plus platform subclasses on the client side), and the host-side implementation (`src/api-proxy.ts`: `createApiProxy` plus the default-exported `ApiProxyService` gateway plugin — config `{provider, model, workspaceRoot?}`, provides `ctx.apiProxy`). Transport-agnostic by design: this package registers no routes; carriers such as HTTP wrap `ctx.apiProxy` themselves. The shipped core composition lives in [`packages/bundle/base/cordis.patch.yml`](../../bundle/base/cordis.patch.yml).
+The API gateway every client shape shares: the TS contract (`src/api/`, zero Node dependencies, importable from the browser), the fetch carrier pair (`src/fetch/`: `toFetchHandler` on the host side, `AbstractApiClient` plus platform subclasses on the client side), and the host-side implementation (`src/api-proxy.ts`: `createApiProxy` plus the default-exported `ApiProxyService` gateway plugin — config `{provider, model, reasoningEffort?, workspaceRoot?}`, provides `ctx.apiProxy`). Transport-agnostic by design: this package registers no routes; carriers such as HTTP wrap `ctx.apiProxy` themselves. The shipped core composition lives in [`packages/bundle/base/cordis.patch.yml`](../../bundle/base/cordis.patch.yml).
+
+## The default route (`api-gateway` settings section)
+
+`{provider, model, reasoningEffort?}` is also the gateway's user-settings section, registered under `api-gateway`: the composition entry is the `base` layer and `settings.yaml` layers the user's own choice over it. `workspaceRoot` is deliberately outside the section — a launcher fact, not a preference.
+
+A session resolves its route from three tiers, re-read on every access rather than seeded once: a selection made in this process, else the session's own latest logged `request/header`, else this default. Re-reading is what makes both directions hold — a session that has run a turn derives its route from its log forever after, so changing the default never retargets it, while a session still blank (New Session reuses one rather than minting another) starts from a default saved after it was created.
+
+`session.selectModel` records an accepted switch as the new default, which is how the default is chosen in practice: there is no separate gesture. What it stores is the RESOLVED target, so an adapter-materialized default effort is pinned as the user saw it and a later adapter-default change does not silently move stored defaults. The write replaces the section wholesale rather than merging, because switching to a model with no reasoning effort has to clear a stored one; a storage failure is logged without undoing the switch, which already applies to its own session. A deployment with no settings provider keeps the composition entry and a switch stays process-local.
+
+The section's `reasoningEffort` has no counterpart in the plugin config, deliberately: the seam merges the user layer over the composition entry per field, so an absent key cannot override a present one and a composition-set effort would survive every later switch to a model without one. A deployment default for effort belongs on the adapter profile, which resolves per model.
+
+The stored route is not validated against the registry, in either direction. A default naming a route the Models page has since removed still reaches `session.models` as the session's `current` — matching no advertised group, which is precisely what makes a selector prompt for a replacement instead of naming a model the deployment cannot reach. Repairing it silently would also break the deliberate converse: an adapter may serve a model its catalog does not advertise.

 ## Contract layer (`/api`)

@@ -20,7 +32,7 @@ Session titles ride the generic projection pair like every other domain — the

 `session.fork` maps an optional event anchor to the first `turn/end` at or after it, letting a message action include that message's whole turn. An omitted or past-end anchor selects the last completed turn; an in-log anchor whose turn remains open returns `fork-unavailable` rather than clipping backward. The published child inherits the source's seeded history, cwd, latest logged provider/model/reasoning target, and lineage before joining the source Workspace. If Workspace attachment fails, `workspace-attach-failed` carries the already-published child id so clients can reconcile it. The [SessionStore fork decision](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md) owns the boundary rationale.

-Session model routing is a session-domain contract. `session.models` returns the selected provider/model/reasoning target separately from provider-grouped advisory models, exact-route reasoning metadata, and provider-local lookup failures. The current target may be absent from the groups and is never injected as a synthetic row; clients can prompt for a replacement without turning the directory into a routing whitelist. `session.selectModel` validates the optional adapter-owned reasoning effort and replaces the complete target selected for the next prompt-assembly boundary. Catalog membership is not validation: an adapter may resolve an unlisted model, while an unavailable route or unsupported effort returns `model-unavailable`.
+Session model routing is a session-domain contract. `session.models` returns the selected provider/model/reasoning target separately from provider-grouped advisory models, exact-route reasoning metadata, and provider-local lookup failures. The current target may be absent from the groups and is never injected as a synthetic row; clients can prompt for a replacement without turning the directory into a routing whitelist. `session.selectModel` validates the optional adapter-owned reasoning effort and replaces the complete target selected for the next prompt-assembly boundary. Catalog membership is not validation: an adapter may resolve an unlisted model, while an unavailable route or unsupported effort returns `model-unavailable`. `session.models` additionally reports `routable`: whether an adapter currently serves the current target's route, which is deliberately NOT derivable from the groups — a route serving a model it stopped advertising is absent from them yet perfectly usable, while a route whose adapter is gone can serve nothing. `session.prompt` refuses on that same fact with `model-unavailable` rather than spending the pre-step path to fail inside an adapter; a client that disables its composer is an affordance, and this method stays callable regardless.

 Pending queued input is a live control-plane contract, not conversation history. The gateway derives the complete `next-turn` queue from durable `agent/inbox/spliced` mutations and broadcasts authoritative `session/queue` snapshots after each change and on reconnect; pending `next-step` steering stays outside this Web projection. Within `next-step`, user-origin messages carry the `steering` placement while injected context (approval notices, task completion, attached snapshots) carries `context` and is not surfaced until claimed. The message-local `agent/inbox/inserted`, `claimed`, and `discarded` notifications remain available to lifecycle observers but do not build the queue view. `session.updateQueue` addresses one `MessageId`; edit and remove mutate the attached Agent through `Inbox.splice()`. A claim's pure deletion splice wins races before pre-step admission, so a later operation returns `queue-item-not-found`. `session.cancel` aborts only the active turn and preserves pending inbox work; after cancellation reaches quiescence and the closing turn flushes, AgentLoop claims the next waking message in FIFO order, and the browser never resends or promotes it. Queue operations never resume a cold session, and the client never infers retirement from turn or status events.

@@ -32,7 +44,7 @@ A stale continuation discards every partial result, deduplication entry, and cur

 Directory picking delegates to the composed `ctx.directoryPicker` backend ([the directory-picker seam](../directory-picker/README.md)); a method called outside the composed capability's kind fails with `directory-picker-unavailable` (the client needs no advertisement — the composed picker package's own client half renders the matching interaction). Under `native`, `host.pickDirectory` opens one native chooser and returns its selected path (`null` on cancel); this user-paced method does not use the default 30-second unary timeout, while caller/connection aborts still propagate to the native process. Under `browse`, `host.listDirectory` returns one name-sorted directory level with breadcrumb ancestry, a `home` anchor, and host-owned `hidden` flags (absent path = home directory), and `host.createDirectory` creates one validated child segment; the backend's typed failures map 1:1 onto the `directory-unreadable`/`directory-exists`/`directory-create-failed` codes. The browser carrier's prefix-wide trust fence (dsh-client-connection) covers all of these like every other `/api` request.

-`host.openPath` opens a filesystem path with the operating system's default application (`open` on macOS, `Invoke-Item` on Windows, and `xdg-open` on desktop Linux). WSL translates the Linux path through `wslpath -w` and hands the resulting Windows/UNC path to Windows `Invoke-Item` instead of assuming a Linux desktop association. The browser carrier applies the same loopback, same-origin restriction as `host.pickDirectory`.
+`host.openPath` opens a filesystem path with the operating system's default application (`open` on macOS, `Invoke-Item` on Windows, and `xdg-open` on desktop Linux). For `.html`, `.htm`, `.xhtml`, and `.svg`, macOS and desktop Linux prefer a named default browser and fall back to that application handoff when none can be named. WSL translates every Linux path through `wslpath -w` and hands the resulting Windows/UNC path to Windows `Invoke-Item`, including browser-renderable documents, instead of assuming a Linux desktop association. The browser carrier applies the same loopback, same-origin restriction as `host.pickDirectory`.

 The `command.*` and `skill.*` domains expose the host command registry and skill catalog to clients. Every method addresses one session's agent by `sessionId` (a served session always has an Agent; `command.*` resumes cold sessions through the same path as `session.*`, while `skill.list` resolves the project root from the session header without touching the Agent registry). `skill.list` serves the browser's user-selected model-reference path, so it returns only skills that are both model-invocable and user-invocable; this domain has no direct skill-loading RPC. `command.execute` runs a slash-command line host-side with pure admission semantics: the response reports whether the line resolved to a handler plus the minted lifecycle `commandId` when it did (correlating the acknowledgment with the flow node), while the outcome rides the durably logged `command/run`/`command/done` lifecycle pair broadcast on the mux stream. Command handlers may legitimately outlast the 30-second transport health deadline, so `command.execute` carries only caller/connection cancellation; that signal cancels the running handler. `host/commands-changed` is the catalog invalidation frame: clients refetch `command.list` instead of diffing.

--- a/packages/host/apiproxy/README.zh.md
+++ b/packages/host/apiproxy/README.zh.md
@@ -2,7 +2,19 @@

 [English](README.md) | 中文

-所有客户端形态共用的 API 网关：TS 契约（`src/api/`，不依赖 Node，可从浏览器导入）、fetch 载体对（`src/fetch/`：宿主侧的 `toFetchHandler`，以及客户端侧的 `AbstractApiClient` 与平台子类）和宿主侧实现（`src/api-proxy.ts`：`createApiProxy` 加上默认导出的 `ApiProxyService` 网关插件，其配置为 `{provider, model, workspaceRoot?}`，提供 `ctx.apiProxy`）。该包在设计上与传输方式无关，不注册任何路由；HTTP 等载体自行包装 `ctx.apiProxy`。已发布的核心组合位于 [`packages/bundle/base/cordis.patch.yml`](../../bundle/base/cordis.patch.yml)。
+所有客户端形态共用的 API 网关：TS 契约（`src/api/`，不依赖 Node，可从浏览器导入）、fetch 载体对（`src/fetch/`：宿主侧的 `toFetchHandler`，以及客户端侧的 `AbstractApiClient` 与平台子类）和宿主侧实现（`src/api-proxy.ts`：`createApiProxy` 加上默认导出的 `ApiProxyService` 网关插件，其配置为 `{provider, model, reasoningEffort?, workspaceRoot?}`，提供 `ctx.apiProxy`）。该包在设计上与传输方式无关，不注册任何路由；HTTP 等载体自行包装 `ctx.apiProxy`。已发布的核心组合位于 [`packages/bundle/base/cordis.patch.yml`](../../bundle/base/cordis.patch.yml)。
+
+## 默认路由（`api-gateway` 设置段）
+
+`{provider, model, reasoningEffort?}` 同时是网关的用户设置段，注册在 `api-gateway` 之下：组合条目是 `base` 层，`settings.yaml` 把用户自己的选择叠加其上。`workspaceRoot` 刻意不在段内——它是启动器事实，不是偏好。
+
+会话按三级解析自己的路由，且每次读取都重新解析，而不是只在创建时种一次：本进程内的显式选择，其次是该会话自己最新记录的 `request/header`，最后才是这个默认值。重新解析正是让两个方向都成立的原因——已经跑过一轮的会话此后永远从自己的日志推导路由，改默认值不会重定向它；而仍然空白的会话（新建会话会复用一个，而不是再开一个）则会用上它创建之后才保存的默认值。
+
+`session.selectModel` 会把被接受的切换记录为新的默认值，实践中默认值就是这样选定的，没有另一个单独的手势。它存下来的是**解析后**的目标，因此适配器实体化出来的默认推理等级会按用户当时看到的样子钉住，日后适配器改了自己的默认值也不会悄悄移动已存的默认路由。写入是整段替换而非合并，因为切到一个不支持推理的模型必须清掉已存的等级；存储失败只记日志，不会撤销这次切换——它对自己所在的会话已经生效。没有设置提供方的部署保留组合条目，切换只停留在进程内。
+
+设置段里的 `reasoningEffort` 在插件配置中刻意没有对应字段：seam 是按字段把用户层合并到组合条目之上的，缺席的键覆盖不了存在的键，因此组合层设的推理等级会在此后每一次切到不支持推理的模型时继续存活。推理等级的部署级默认值属于适配器 profile，那里是按模型解析的。
+
+存下来的路由不做注册表校验，两个方向都不做。默认值指向一个已在模型页删除的路由时，它照样作为会话的 `current` 送到 `session.models`——匹配不到任何已公布的分组，而这恰恰是让选择器提示重新选择、而不是显示一个部署根本够不着的模型的原因。静默修复它还会破坏刻意保留的反面情形：适配器可以服务一个自己目录未公布的模型。

 ## 契约层（`/api`）

@@ -20,7 +32,7 @@

 `session.fork` 将可选事件锚点映射到该锚点处或其后的首个 `turn/end`，使消息操作可包含该消息所在的完整轮次。锚点省略或超过末尾时，选择最后一个已完成轮次；若锚点已在日志中，而其所在轮次仍开放，则返回 `fork-unavailable`，不会向较早位置裁剪。发布后的子会话会先继承源会话的种子历史、cwd、日志中最新的提供方／模型／推理（reasoning）目标及谱系，再加入源 Workspace。如果附加到 Workspace 失败，`workspace-attach-failed` 会携带已发布的子会话 id，供客户端对账。[SessionStore fork 决策](../../../.agents/notes/implemented/feature/2026-06-30-session-store-fork-api.md)给出边界设计的理由。

-会话模型路由属于会话领域契约。`session.models` 将选中的提供方／模型／推理目标，与按提供方分组的建议性模型、精确路由推理元数据和逐提供方查询失败记录分开返回。当前目标可能不在这些分组中，也绝不会作为合成行注入；客户端可以提示用户选择替代目标，而无需把目录变成路由白名单。`session.selectModel` 校验由适配器持有的可选推理强度，并替换将在下一提示词组装边界使用的完整目标。目录成员关系不构成校验：适配器可以解析未列出的模型，而不可用路由或不受支持的推理强度会返回 `model-unavailable`。
+会话模型路由属于会话领域契约。`session.models` 将选中的提供方／模型／推理目标，与按提供方分组的建议性模型、精确路由推理元数据和逐提供方查询失败记录分开返回。当前目标可能不在这些分组中，也绝不会作为合成行注入；客户端可以提示用户选择替代目标，而无需把目录变成路由白名单。`session.selectModel` 校验由适配器持有的可选推理强度，并替换将在下一提示词组装边界使用的完整目标。目录成员关系不构成校验：适配器可以解析未列出的模型，而不可用路由或不受支持的推理强度会返回 `model-unavailable`。`session.models` 还会报告 `routable`：当前目标的路由是否有适配器在服务。这一点刻意不由分组推导——一条仍在服务、只是不再公布该模型的路由不在分组里，却完全可用；而适配器已经消失的路由什么都服务不了。`session.prompt` 依据同一个事实以 `model-unavailable` 拒绝，而不是把整条 pre-step 路径走完再在适配器内部失败；客户端禁用输入框只是提示性设计，这个方法始终可被调用。

 待处理的 queued 输入属于实时控制平面契约，而非对话历史。网关根据持久 `agent/inbox/spliced` 变更派生完整的 `next-turn` 队列，并在每次变更后及重连时广播权威 `session/queue` 快照；待处理的 `next-step` steering（中途引导）不进入此 Web 投影。在 `next-step` 内，用户来源的消息携带 `steering` placement，而注入上下文（审批通知、任务完成、附加快照）携带 `context`，领取前不对外呈现。面向单条消息的 `agent/inbox/inserted`、`claimed` 与 `discarded` 通知仍供生命周期观察方使用，但不用于构建队列视图。`session.updateQueue` 通过 `MessageId` 寻址单个项；编辑和移除经已挂载 Agent 的 `Inbox.splice()` 修改队列。claim 的纯删除 splice 会在 pre-step 准入前赢得竞态，因此之后的操作返回 `queue-item-not-found`。`session.cancel` 仅中止活动轮次并保留待处理 inbox 工作；取消达到完全停稳且结束中的轮次完成 flush 后，AgentLoop 按 FIFO 顺序认领下一条可唤醒消息，浏览器绝不重发或提升它。队列操作绝不恢复冷会话，客户端也绝不根据轮次或状态事件推断某项已退出队列。

@@ -32,7 +44,7 @@ Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.cr

 目录选择委托给组合的 `ctx.directoryPicker` 后端（[目录选择 seam](../directory-picker/README.md)）；调用组合能力 kind 之外的方法会以 `directory-picker-unavailable` 失败（客户端不需要广播——组合的选择器包自己的 client half 渲染匹配的交互）。在 `native` 下，`host.pickDirectory` 打开一个原生选择器并返回选中路径（取消为 `null`）；该方法需等待用户完成操作，不使用默认的 30 秒一元调用超时，而调用方与连接的中止仍会传播至原生进程。在 `browse` 下，`host.listDirectory` 返回一个按名称排序的目录层级，携带面包屑祖先链、`home` 锚点与宿主判定的 `hidden` 标志（不带路径即家目录），`host.createDirectory` 创建一个经校验的子段；后端的类型化失败 1:1 映射为 `directory-unreadable`／`directory-exists`／`directory-create-failed` 错误码。浏览器载体的前缀级信任栅栏（dsh-client-connection）像覆盖其他所有 `/api` 请求一样覆盖上述全部方法。

-`host.openPath` 会用操作系统的默认应用打开一个文件系统路径（macOS 为 `open`，Windows 为 `Invoke-Item`，桌面 Linux 为 `xdg-open`）。WSL 会通过 `wslpath -w` 转换 Linux 路径，并将所得 Windows/UNC 路径交给 Windows `Invoke-Item`，而非假定存在 Linux 桌面文件关联。浏览器载体对其施加与 `host.pickDirectory` 相同的回环、同源限制。
+`host.openPath` 会用操作系统的默认应用打开一个文件系统路径（macOS 为 `open`，Windows 为 `Invoke-Item`，桌面 Linux 为 `xdg-open`）。对于 `.html`、`.htm`、`.xhtml` 与 `.svg`，macOS 和桌面 Linux 会优先使用能够确定的默认浏览器；无法确定时回退到上述应用交接。WSL 会通过 `wslpath -w` 转换每个 Linux 路径，并将所得 Windows/UNC 路径交给 Windows `Invoke-Item`，浏览器可渲染的文档也不例外，而非假定存在 Linux 桌面文件关联。浏览器载体对其施加与 `host.pickDirectory` 相同的回环、同源限制。

 `command.*` 与 `skill.*` 领域向客户端暴露宿主命令注册表和技能目录。每个方法都通过 `sessionId` 寻址一个会话的 Agent（被服务的会话必有 Agent；`command.*` 经由与 `session.*` 相同的路径恢复冷会话，而 `skill.list` 从会话头解析项目根目录，不触碰 Agent 注册表）。`skill.list` 服务于浏览器中由用户选择的模型引用路径，因此仅返回模型和用户均可调用的 skill；该领域没有直接加载 skill 的 RPC。`command.execute` 在宿主侧运行一条斜杠命令行，语义为纯准入：响应报告该行是否解析到处理器，并在解析到时回带铸造的生命周期 `commandId`（将本次确认与流节点关联）；结局经由持久落账并在 mux 流广播的 `command/run`/`command/done` 生命周期事件对承载。命令处理器运行超过 30 秒的传输健康时限仍属正常，因此 `command.execute` 仅携带调用方／连接取消信号；该信号可取消正在运行的处理器。`host/commands-changed` 是目录失效帧：客户端重新拉取 `command.list` 而不是做差分。

--- a/packages/host/apiproxy/package.json
+++ b/packages/host/apiproxy/package.json
@@ -39,6 +39,7 @@
  "license": "BSD-3-Clause",
  "dependencies": {
    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-api-remotes": "workspace:^",
    "@deepseek-ai/dsh-brand": "workspace:^",
    "@deepseek-ai/dsh-commands": "workspace:^",
    "@deepseek-ai/dsh-credentials": "workspace:^",
@@ -72,6 +73,8 @@
    "@deepseek-ai/dsh-invariants": "workspace:^",
    "@deepseek-ai/dsh-storage": "workspace:^",
    "@deepseek-ai/dsh-storage-domain": "workspace:^",
+    "@deepseek-ai/dsh-type-meta": "workspace:^",
+    "@deepseek-ai/dsh-typert-registry": "workspace:^",
    "cordis": "^4.0.0-rc.7"
  }
 }
--- a/packages/host/apiproxy/src/api-proxy.ts
+++ b/packages/host/apiproxy/src/api-proxy.ts
@@ -8,7 +8,7 @@ import { mkdir, stat } from 'node:fs/promises'
 import { join } from 'node:path'
 import type { Context } from 'cordis'
 import { installAgentLlmTarget } from '@deepseek-ai/dsh-agent'
-import type { Agent, AgentLlmTarget, AgentLlmTargetRef, AgentStatus } from '@deepseek-ai/dsh-agent'
+import type { Agent, AgentLlmTarget, AgentLlmTargetRef, AgentOptions, AgentStatus } from '@deepseek-ai/dsh-agent'
 import { createUserMessage, freezeMessage, ReasoningEffortId } from '@deepseek-ai/dsh-llm'
 import { errorChain } from '@deepseek-ai/dsh-llm'
 import type { MessageSource } from '@deepseek-ai/dsh-llm'
@@ -27,7 +27,8 @@ import {
 import { PresetMountError, UnknownPresetError } from '@deepseek-ai/dsh-agent-presets'
 import type {} from '@deepseek-ai/dsh-tools'
 import type {
-  ApiProxy, CredentialView, GoalRef, HistoryEntry, HostFrame, ModelCatalogFailure, ModelProviderGroup,
+  ApiProxy, ConfigurableProviderView, CredentialView, GoalRef, HistoryEntry, HostFrame,
+  ModelCatalogFailure, ModelProviderGroup,
  ModelReasoning, MuxFrame, QuestionResponsePayload, SessionProjectionsBlock, SessionSearchItem,
  QueuedInboxItem, SessionSummary, SettingsNamespaceView, SubagentAddress, ToolEventView,
  WorkspaceId, WorkspaceView,
@@ -69,11 +70,27 @@ import type {
 } from '@deepseek-ai/dsh-user-interaction'
 import { UserInteractionError } from '@deepseek-ai/dsh-user-interaction'
 import { DirectoryPickerError } from '@deepseek-ai/dsh-host-directory-picker'
+import {
+  ApiRemoteSessionNotFound as SessionNotFound,
+  ApiRemoteSubagentSessionOwnership as SubagentSessionOwnership,
+  apiRemoteSubagentOwnershipError,
+  createApiRemoteAgentResolver,
+  hasApiRemoteSubagentOwner,
+  inspectApiRemoteSession,
+} from '@deepseek-ai/dsh-api-remotes'
 import { openNativePath, openNativeTextFile } from './native-path-opener.ts'

 /** Page size when history is called without maxMessages. */
 const DEFAULT_MAX_MESSAGES = 50

+/**
+ * The settings namespace carrying the user's default route. Named for the
+ * gateway rather than for the package, because this key is what a person reads
+ * and writes in `settings.yaml`; the row id in a composition happens to match
+ * but does not determine it.
+ */
+export const API_GATEWAY_SETTINGS_NAMESPACE = settingsNamespace('api-gateway')
+
 /** Non-model settings namespaces intentionally served to the Web client. */
 const WEB_SETTINGS_NAMESPACES = ['permission'] as const

@@ -330,8 +347,21 @@ function directoryError(error: unknown): RpcError {

 /** Resolved Host routing and project-directory defaults consumed by the API implementation. */
 export interface ApiProxyDefaults {
-  provider: string
-  model: string
+  /**
+   * The route a session starts from when its own log names none. Read on
+   * every access rather than captured, so a default saved during this process
+   * reaches the sessions that have not run a turn yet.
+   */
+  defaultTarget: () => AgentLlmTarget
+  /**
+   * Record a selection as the new default. Either absent, or a closure that
+   * may itself decline — the gateway plugin always passes one, and it no-ops
+   * when the deployment mounts no settings provider or when the write races
+   * service teardown. A switch then stays process-local. A rejection is
+   * reported and swallowed: the switch already applies to its own session,
+   * and undoing it because storage failed would be the worse outcome.
+   */
+  persistDefaultTarget?: (target: AgentLlmTarget) => Promise<void>
  /** Default project directory for new sessions whose create request carries no cwd. */
  cwd: string
  /** Parent directory for name-created workspaces. */
@@ -652,19 +682,6 @@ async function catalogChild(
  }
 }

-/**
- * Thrown by the cold-resume path when the id names no servable session
- * (absent from the store, or a pre-project legacy log without a cwd).
- */
-class SessionNotFound extends Error {}
-
-/** Session identity whose lifecycle belongs to subagent routing, not generic Host resume. */
-class SubagentSessionOwnership extends Error {
-  constructor(readonly sessionId: SessionId) {
-    super(`session "${sessionId}" is a subagent session; use subagent delivery`)
-  }
-}
-
 /**
 * The requested preset differs from the one this session already runs.
 *
@@ -755,11 +772,13 @@ function changedWorkspaceView(workspaceId: string, value: unknown): WorkspaceVie
 * @returns the ApiProxy implementation.
 */
 export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiProxy {
-  const agentOptions = { provider: defaults.provider, model: defaults.model }
+  /** The seed route each create/resume declares; re-read so it never goes stale. */
+  const agentOptions = (): AgentOptions => {
+    const { provider, model } = defaults.defaultTarget()
+    return { provider, model }
+  }
  type WebLlmTargetRef = AgentLlmTargetRef & { current: AgentLlmTarget }
  const targets = new WeakMap<Agent, WebLlmTargetRef>()
-  /** Implicit resume of cold sessions, deduplicating concurrent calls (follows the jsonrpc sessionCreations precedent). */
-  const resumes = new Map<SessionId, Promise<Agent>>()
  /** Client-chosen identity creation/resume, deduplicated across concurrent retries. */
  const sessionCreations = new Map<SessionId, Promise<Agent>>()
  /** Serializes path ownership and explicit title checks with Workspace mutations. */
@@ -770,24 +789,39 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro

  /**
   * Install or return the session-local target that prompt assembly snapshots.
-   * Seed order: latest logged request/header, else the host default routing.
-   * There is no create-time per-session override tier on this wire — if one
-   * returns (a create-options contribution), it must fold in between the two.
+   *
+   * Precedence, resolved on EVERY read rather than seeded once: a selection
+   * made in this process, else the session's own latest logged request/header,
+   * else the live host default. Re-reading is what keeps the two tiers honest
+   * in both directions — a session that has run a turn derives its route from
+   * its log forever after, so changing the default never retargets it; and a
+   * session still blank (New Session reuses one rather than minting another)
+   * starts from a default saved after it was created. There is no create-time
+   * per-session override tier on this wire — if one returns (a create-options
+   * contribution), it must fold in between the selection and the log.
   */
  function targetFor(agent: Agent): WebLlmTargetRef {
    const installed = targets.get(agent)
    if (installed !== undefined) return installed
-    const logged = agent.session.requestHeader()?.config
+    let picked: AgentLlmTarget | undefined
    const target: WebLlmTargetRef = {
-      current: logged === undefined
-        ? { provider: defaults.provider, model: defaults.model }
-        : {
+      get current(): AgentLlmTarget {
+        if (picked !== undefined) return picked
+        // Incrementally folded by the session, so a per-step read costs
+        // O(new events) rather than a rescan.
+        const logged = agent.session.requestHeader()?.config
+        if (logged === undefined) return defaults.defaultTarget()
+        return {
          provider: logged.provider,
          model: logged.model,
          ...logged.reasoningEffort === undefined
            ? {}
            : { reasoningEffort: logged.reasoningEffort },
-        },
+        }
+      },
+      set current(next: AgentLlmTarget) {
+        picked = next
+      },
      assembled: undefined,
    }
    installAgentLlmTarget(agent.ctx, target)
@@ -860,6 +894,24 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
    }
  }

+  const hasSubagentOwner = (
+    session: Pick<Session, 'header'>,
+    agent: Agent | undefined,
+  ): boolean => hasApiRemoteSubagentOwner(ctx, session, agent)
+  const subagentOwnershipError = (sessionId: SessionId): RpcError =>
+    apiRemoteSubagentOwnershipError(sessionId)
+  const inspectServable = (sessionId: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> =>
+    inspectApiRemoteSession(ctx, sessionId)
+  // Cold resume composes the preset the session recorded, for the same reason
+  // `session.create` does: its history was produced under that composition.
+  // Every generic entry point — prompt, models, commands — arrives here, so
+  // leaving it out meant a session opened after a restart ran on host tools
+  // and the deployment persona.
+  const agentFor = createApiRemoteAgentResolver(ctx, {
+    agentOptions,
+    setup: async meta => (await composeAgent(meta.agentPreset)).setup,
+  })
+
  /** Send one transient frame to every connected mux consumer. */
  function broadcast(payload: MuxFrame): void {
    const envelope = frame(payload)
@@ -1041,121 +1093,6 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
    })
  }

-  /**
-   * Generic Host interaction cannot claim a durably classified subagent
-   * (`origin: 'subagent'` in the header) or an Agent runtime-owned by its
-   * live parent.
-   */
-  function hasSubagentOwner(
-    session: Pick<Session, 'header'>,
-    agent: Agent | undefined,
-  ): boolean {
-    if (session.header.origin === 'subagent') return true
-    const parentId = session.header.parentSession
-    if (parentId === undefined || agent === undefined) return false
-    const parent = ctx.agents.get(parentId)
-    return parent !== undefined && ctx.agents.isOwnedBy(agent.id, parent)
-  }
-
-  /** Stable generic-Host error for an identity reserved to subagent routing. */
-  function subagentOwnershipError(sessionId: SessionId): RpcError {
-    return {
-      code: 'agent-busy',
-      message: `session "${sessionId}" is owned by subagent routing`,
-      details: { reason: 'use subagent delivery for this child session' },
-    }
-  }
-
-  /** Inspect one cold served session without repairing, resuming, or publishing it. */
-  async function inspectServable(sessionId: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }> {
-    const persistence = ctx.get('sessionPersistence')
-    if (persistence === undefined) {
-      throw new Error('session persistence is not configured (load a dsh-session-persistence backend)')
-    }
-    const meta = (await persistence.list()).find(m => m.id === sessionId)
-    if (meta === undefined || meta.cwd === undefined) throw new SessionNotFound(`session "${sessionId}" not found`)
-    const inspected = await persistence.inspect(sessionId)
-    if (inspected.meta.cwd === undefined) throw new SessionNotFound(`session "${sessionId}" not found`)
-    return { meta: inspected.meta, events: [...inspected.events] }
-  }
-
-  /**
-   * Resolve one live registered identity through the subagent-ownership
-   * fence: subagent-owned agents answer `agent-busy`, plain agents pass.
-   * Fences the live agent's own session rather than trusting a
-   * "registered ⇒ attached-store" invariant — a registered subagent whose
-   * session is ever absent from the attached store must still not be handed
-   * out through generic Host routing. `undefined` means no live agent.
-   */
-  function fencedLiveAgent(sessionId: SessionId): { agent: Agent } | { error: RpcError } | undefined {
-    const live = ctx.agents.get(sessionId)
-    if (live === undefined) return undefined
-    if (hasSubagentOwner(live.session, live)) return { error: subagentOwnershipError(sessionId) }
-    return { agent: live }
-  }
-
-  async function agentFor(sessionId: SessionId): Promise<{ agent: Agent } | { error: RpcError }> {
-    const fenced = fencedLiveAgent(sessionId)
-    if (fenced !== undefined) return fenced
-    const attached = ctx.sessions.get(sessionId)
-    if (attached !== undefined && hasSubagentOwner(attached, undefined)) {
-      return { error: subagentOwnershipError(sessionId) }
-    }
-    let resume = resumes.get(sessionId)
-    if (resume === undefined) {
-      resume = (async () => {
-        try {
-          const inspected = await inspectServable(sessionId)
-          if (hasSubagentOwner({ header: inspected.meta }, undefined)) {
-            throw new SubagentSessionOwnership(sessionId)
-          }
-          const publishedSession = ctx.sessions.get(sessionId)
-          const publishedAgent = ctx.agents.get(sessionId)
-          if (publishedSession !== undefined && hasSubagentOwner(publishedSession, publishedAgent)) {
-            throw new SubagentSessionOwnership(sessionId)
-          }
-          // Cold resume composes the preset the session recorded, for the
-          // same reason `session.create` does: its history was produced under
-          // that composition. Every generic entry point — prompt, models,
-          // commands — arrives here, so leaving it out meant a session opened
-          // after a restart ran on host tools and the deployment persona.
-          const handle = await ctx.agents.resume({
-            resumeSessionId: sessionId,
-            agentOptions,
-            setup: (await composeAgent(inspected.meta.agentPreset)).setup,
-          })
-          return handle.agent
-        } finally {
-          resumes.delete(sessionId)
-        }
-      })()
-      resumes.set(sessionId, resume)
-    }
-    try {
-      return { agent: await resume }
-    } catch (error: unknown) {
-      if (error instanceof SessionNotFound) {
-        return { error: { code: 'session-not-found', message: error.message, details: { sessionId } } }
-      }
-      if (error instanceof SubagentSessionOwnership) {
-        return { error: subagentOwnershipError(error.sessionId) }
-      }
-      // A concurrent publish can win the identity between the pre-resume
-      // re-check and `ctx.agents.resume` publication; the ID-collision
-      // rejection falls through here. Mirror ensureSession's `.catch` in
-      // full: classify a subagent-owned winner into the stable ownership
-      // error, and hand a clean plain-agent winner straight back.
-      const fenced = fencedLiveAgent(sessionId)
-      if (fenced !== undefined) return fenced
-      const attached = ctx.sessions.get(sessionId)
-      if (attached !== undefined && hasSubagentOwner(attached, undefined)) {
-        return { error: subagentOwnershipError(sessionId) }
-      }
-      // The internal details slot is contractually {}; the reason rides the message.
-      return { error: { code: 'internal', message: `resume failed for session "${sessionId}": ${String(error)}`, details: {} } }
-    }
-  }
-
  type SessionReadState = {
    id: SessionId
    header: SessionHeader
@@ -1248,7 +1185,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
          // longer make.
          return (await ctx.agents.resume({
            resumeSessionId: sessionId,
-            agentOptions,
+            agentOptions: agentOptions(),
            setup: (await composeAgent(inspected.meta.agentPreset)).setup,
          })).agent
        }
@@ -1261,7 +1198,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
        const composition = await composeAgent(presetId)
        return (await ctx.agents.create({
          sessionId,
-          agentOptions,
+          agentOptions: agentOptions(),
          meta: {
            cwd,
            ...composition.agentPreset === undefined ? {} : { agentPreset: composition.agentPreset },
@@ -1424,6 +1361,19 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
    }
  }

+  /**
+   * Whether an adapter currently serves this route, and therefore whether a
+   * session pointed at it can start a turn. Catalog membership cannot answer
+   * it: an adapter may serve a model its own catalog stopped advertising, so
+   * a route missing from the groups is not the same as one nothing serves.
+   * A composition with no llm registry at all cannot judge and says yes —
+   * the dispatch it would have refused fails on its own terms.
+   */
+  function routeServed(provider: string): boolean {
+    const llm = ctx.get('llm')
+    return llm === undefined || llm.listProviders().some(entry => entry.id === provider)
+  }
+
  /** Missing-service report shared by the settings domain (skills-domain stance). */
  function settingsAbsent(): RpcError {
    return { code: 'internal', message: 'settings service is absent: this deployment does not mount a settings provider (e.g. @deepseek-ai/dsh-settings-local) in its composition', details: {} }
@@ -1824,7 +1774,8 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
        if ('error' in found) return err(request, found.error)
        const current = targetFor(found.agent).current
        const { groups, failures } = await buildModelCatalog(ctx)
-        return ok(request, { current: { ...current }, groups, failures })
+        const routable = routeServed(current.provider)
+        return ok(request, { current: { ...current }, routable, groups, failures })
      },

      async selectModel(request) {
@@ -1847,6 +1798,17 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
              : { reasoningEffort: resolved.reasoningEffort },
          }
          targetFor(found.agent).current = selected
+          // A switch is also how this deployment's default is chosen: the next
+          // session created without one of its own starts here. Sessions that
+          // have already logged a route are unaffected — they derive from
+          // their own log (see targetFor).
+          try {
+            await defaults.persistDefaultTarget?.(selected)
+          } catch (error: unknown) {
+            ctx.logger.warn(
+              `api-proxy: the model switch applies to this session but was not saved as the default: ${String(error)}`,
+            )
+          }
          return ok(request, { selected: { ...selected } })
        } catch (error: unknown) {
          return err(request, {
@@ -1958,7 +1920,7 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
                ? {}
                : { agentPreset: forkComposition.agentPreset },
            },
-            agentOptions,
+            agentOptions: agentOptions(),
            setup: forkComposition.setup,
          })
        } catch (error: unknown) {
@@ -1990,6 +1952,20 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
        const found = await agentFor(sessionId)
        if ('error' in found) return err(request, found.error)
        const agent = found.agent
+        // A route no adapter serves cannot start a turn, and letting it try
+        // spends the whole pre-step path to fail inside the adapter with a
+        // message about registration. Refusing here names the model the
+        // session is pointed at while the draft is still in the composer.
+        // This is the enforcement boundary: a client that disables its input
+        // is an affordance, and this method stays callable regardless.
+        const target = targetFor(agent).current
+        if (!routeServed(target.provider)) {
+          return err(request, {
+            code: 'model-unavailable',
+            message: `no adapter serves provider "${target.provider}"; select a model for this session`,
+            details: { provider: target.provider, model: target.model },
+          })
+        }
        // The rpcId rides MessageSource into user/message (merge declaration in api/sessions.ts; provisional correlation).
        const source: MessageSource = { kind: 'user', rpcId: request.rpcId }
        try {
@@ -2343,13 +2319,16 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
    host: {
      describe(request) {
        // TODO(step2): version should read apps/cli's package.json; placeholder for now.
+        const route = defaults.defaultTarget()
        return Promise.resolve(ok(request, {
          version: '0.0.1',
          // Same source as session.create's fallback: the UI's default project
          // must match where an unspecified-cwd session actually lands.
          cwd: defaults.cwd,
-          provider: defaults.provider,
-          model: defaults.model,
+          // Read live for the same reason: this is what the NEXT session will
+          // start from, so a saved default has to be what it reports.
+          provider: route.provider,
+          model: route.model,
          attachedSessions: ctx.agents.list().length,
        }))
      },
@@ -2686,15 +2665,17 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
        const active = new Set(registered.map(provider => provider.id))
        const directory = ctx.llm.listConfigurableProviders()
        const declared = new Set(directory.map(entry => entry.provider))
-        const views = directory.map(entry => ({
+        const views: ConfigurableProviderView[] = directory.map(entry => ({
          provider: entry.provider,
          displayName: entry.displayName,
          settingsNs: entry.settingsNs,
          settingsPath: [...entry.settingsPath],
          active: active.has(entry.provider),
+          ...entry.declared === undefined ? {} : { declared: entry.declared },
        }))
        // Routes registered without a directory declaration still appear —
-        // they exist and serve models — just with no settings address.
+        // they exist and serve models — just with no settings address. No
+        // adapter claimed them, so nothing can say whether they are shipped.
        for (const provider of registered) {
          if (declared.has(provider.id)) continue
          views.push({
@@ -2886,8 +2867,14 @@ export function createApiProxy(ctx: Context, defaults: ApiProxyDefaults): ApiPro
            queue.push(frame({ type: 'host/settings-changed', ns: name }))
            // A provider's own settings carry its model catalog and endpoint,
            // so a change there invalidates the model list even when the route
-            // set is untouched — `llm/adapters-updated` alone misses it.
-            if (modelProviderNamespaces().has(name)) queue.push(frame({ type: 'host/models-changed' }))
+            // set is untouched — `llm/adapters-updated` alone misses it. The
+            // gateway's own section is the other such source: it names the
+            // route every session with no logged one resolves to, so an
+            // externally edited default (another tab, a hand-edited
+            // settings.yaml) has to reach an open selector too.
+            if (modelProviderNamespaces().has(name) || name === String(API_GATEWAY_SETTINGS_NAMESPACE)) {
+              queue.push(frame({ type: 'host/models-changed' }))
+            }
          }),
          ctx.on('credentials/updated', (ref) => {
            queue.push(frame({ type: 'host/credentials-changed', ref: String(ref) }))
--- a/packages/host/apiproxy/src/api/index.ts
+++ b/packages/host/apiproxy/src/api/index.ts
@@ -53,6 +53,7 @@ export type { SettingsApi, SettingsNamespaceView, SettingsPathOpView, SettingsSe
 export type { CredentialsApi, CredentialView } from './credentials.ts'
 export type { ConfigurableProviderView, DiscoveredModelView, LlmApi } from './llm.ts'
 export type { ApprovalResponsePayload } from './approvals.ts'
+
 export type { QuestionResponsePayload } from './questions.ts'

 // ---- Message layer: narrow forms (domain-signature view) ----
@@ -71,6 +72,11 @@ export type {
 // ---- Errors and ids ----
 export { RpcId, transportError } from './rpc.ts'
 export type { RpcError, RpcErrorCode, RpcErrorDetailsMap, RpcResult } from './rpc.ts'
+export {
+  clientRequestSchema,
+  serverRequestSchema,
+  serverResponseSchema,
+} from './rpc.schema.ts'

 // ---- Fixed session-search product bounds ----
 export {
--- a/packages/host/apiproxy/src/api/llm.schema.ts
+++ b/packages/host/apiproxy/src/api/llm.schema.ts
@@ -16,6 +16,7 @@ export const configurableProviderViewSchema = z.object({
  settingsNs: z.string(),
  settingsPath: z.array(z.string()),
  active: z.boolean(),
+  declared: z.boolean().optional(),
 }) satisfies z.ZodType<Wire<ConfigurableProviderView>>

 /** llm.providers request payload. */
--- a/packages/host/apiproxy/src/api/llm.ts
+++ b/packages/host/apiproxy/src/api/llm.ts
@@ -22,6 +22,12 @@ export interface ConfigurableProviderView {
  settingsPath: string[]
  /** Whether the route is currently registered (its models are requestable). */
  active: boolean
+  /**
+   * Whether the owning adapter knows this route only because configuration
+   * declared it. Absent when the adapter draws no such distinction, so a
+   * surface must treat absence as "unknown", not as "shipped".
+   */
+  declared?: boolean
 }

 /** Llm-domain unary methods (the map keys llm.* of RpcMethodMap). */
--- a/packages/host/apiproxy/src/api/sessions.schema.ts
+++ b/packages/host/apiproxy/src/api/sessions.schema.ts
@@ -226,6 +226,7 @@ export const sessionModelsRequestSchema = z.object({
 /** session.models response value. */
 export const sessionModelsValueSchema = z.object({
  current: modelTargetSchema,
+  routable: z.boolean(),
  groups: z.array(modelProviderGroupSchema),
  failures: z.array(modelCatalogFailureSchema),
 }) satisfies z.ZodType<Wire<ResponseValue<'session.models'>>>
--- a/packages/host/apiproxy/src/api/sessions.ts
+++ b/packages/host/apiproxy/src/api/sessions.ts
@@ -117,6 +117,15 @@ export interface ModelCatalogFailure {
 export interface SessionModels {
  /** Target selected for the session's next assembled step. */
  current: ModelTarget
+  /**
+   * Whether an adapter currently serves `current.provider`, and therefore
+   * whether this session can start a turn at all. Deliberately NOT derivable
+   * from `groups`: catalog membership is advisory, so a route serving a model
+   * it stopped advertising is absent from the groups yet perfectly usable,
+   * while a route whose adapter is gone can serve nothing. A surface that
+   * blocks input must read this rather than the groups.
+   */
+  routable: boolean
  /** Successfully loaded provider groups. */
  groups: ModelProviderGroup[]
  /** Provider-local failures; successful groups remain usable. */
--- a/packages/host/apiproxy/src/index.ts
+++ b/packages/host/apiproxy/src/index.ts
@@ -6,20 +6,29 @@
 * (api-proxy.ts: createApiProxy + the ApiProxyService gateway plugin providing
 * `ctx.apiProxy`). Transport-agnostic by design: this package registers no
 * routes — physical carriers wrap `ctx.apiProxy` themselves.
+ *
+ * The gateway also owns the `api-gateway` settings section: the route a
+ * session starts from when its own log names none. The composition entry is
+ * the shipped default and the section layers the user's choice over it, so
+ * switching models in a conversation is what sets the default for the next
+ * one. Sessions that have already logged a route are never retargeted by it.
 */

 import { resolve } from 'node:path'
 import { Context, Service } from 'cordis'
 import z from 'schemastery'
+import type { AgentLlmTarget } from '@deepseek-ai/dsh-agent'
+import { ReasoningEffortId } from '@deepseek-ai/dsh-llm'
+import { installSettingsSection } from '@deepseek-ai/dsh-settings'
 import type { ApiProxy } from './api/index.ts'
-import { createApiProxy } from './api-proxy.ts'
+import { API_GATEWAY_SETTINGS_NAMESPACE, createApiProxy } from './api-proxy.ts'

 export type * from './api/index.ts'
 export { RpcId } from './api/rpc.ts'
 export { toFetchHandler } from './fetch/handler.ts'
 export { AbstractApiClient, InProcessApiClient } from './fetch/client.ts'
 export type { IApiClient } from './fetch/client.ts'
-export { createApiProxy } from './api-proxy.ts'
+export { API_GATEWAY_SETTINGS_NAMESPACE, createApiProxy } from './api-proxy.ts'
 export type { ApiProxyDefaults } from './api-proxy.ts'

 declare module 'cordis' {
@@ -29,9 +38,34 @@ declare module 'cordis' {
  }
 }

-/** Gateway plugin config: host-level agent routing and Workspace creation root. */
+/**
+ * The `api-gateway` settings section: the route a session starts from when its
+ * own log names none. `workspaceRoot` is deliberately not part of it — that is
+ * a launcher fact, not a preference.
+ */
+export interface DefaultRouteSettings {
+  /** Default provider route for created agents. */
+  provider: string
+  /** Default model id. */
+  model: string
+  /** Default reasoning effort; absence preserves the adapter/provider default. */
+  reasoningEffort?: string
+}
+
+/**
+ * Gateway plugin config: host-level agent routing and Workspace creation root.
+ *
+ * `reasoningEffort` is deliberately absent, so the section carries one field
+ * the composition cannot. The seam resolves a section by MERGING the user
+ * layer over the composition entry per field, and an absent key cannot
+ * override a present one — so a composition-set effort would survive every
+ * later switch to a model that has none, and strand it for the next session
+ * to fail on. Effort is a per-model fact anyway: a deployment default belongs
+ * on the adapter profile (`llm-pi-ai`'s `reasoning`, `llm-deepseek`'s own),
+ * which resolves per model rather than per gateway.
+ */
 export interface Config {
-  /** Default provider route for created/resumed agents. */
+  /** Default provider route for created agents. */
  provider: string
  /** Default model id. */
  model: string
@@ -39,6 +73,27 @@ export interface Config {
  workspaceRoot?: string
 }

+/**
+ * Schema of the `api-gateway` section, exported because it IS that section's
+ * contract — the shape anything reading or writing `settings.yaml` addresses.
+ */
+export const DEFAULT_ROUTE_SCHEMA: z<DefaultRouteSettings> = z.object({
+  provider: z.string().required(),
+  model: z.string().required(),
+  reasoningEffort: z.string(),
+})
+
+/** Project the stored/composed section onto the agent-facing target shape. */
+function routeTarget(settings: DefaultRouteSettings): AgentLlmTarget {
+  return {
+    provider: settings.provider,
+    model: settings.model,
+    ...settings.reasoningEffort === undefined
+      ? {}
+      : { reasoningEffort: ReasoningEffortId(settings.reasoningEffort) },
+  }
+}
+
 /**
 * The API gateway service: implements the ApiProxy contract over the composed
 * host context and provides it as `ctx.apiProxy`. The Host cwd is the default
@@ -72,9 +127,30 @@ export class ApiProxyService extends Service implements ApiProxy {
  constructor(ctx: Context, config: Config) {
    super(ctx, 'apiProxy')
    const cwd = process.cwd()
+    // The composition entry is the shipped default; the settings section
+    // layers the user's own choice over it, and a deployment without a
+    // settings provider simply keeps the entry.
+    const entry: DefaultRouteSettings = { provider: config.provider, model: config.model }
+    let route: () => DefaultRouteSettings = () => entry
+    installSettingsSection(ctx, API_GATEWAY_SETTINGS_NAMESPACE, DEFAULT_ROUTE_SCHEMA, entry, {
+      setSource: (current) => {
+        route = current
+      },
+      // Nothing registration-level derives from the default: every consumer
+      // reads it through the thunk at the moment it needs a route.
+      onChange: () => {},
+    })
    const api = createApiProxy(ctx, {
-      provider: config.provider,
-      model: config.model,
+      defaultTarget: () => routeTarget(route()),
+      // Wholesale, never a merge: switching to a model with no reasoning
+      // effort must clear a stored one, and a merged patch would strand it
+      // for the next session to fail on. This clears it because the entry
+      // below the user layer carries no effort to re-inherit — the reason
+      // `Config` deliberately has no such field. The section holds no
+      // secrets, so there is nothing a replace can collaterally drop.
+      persistDefaultTarget: async (target) => {
+        await ctx.get('settings')?.replace(API_GATEWAY_SETTINGS_NAMESPACE, target)
+      },
      cwd,
      workspaceRoot: resolve(config.workspaceRoot ?? cwd),
    })
--- a/packages/host/apiproxy/src/native-path-opener.ts
+++ b/packages/host/apiproxy/src/native-path-opener.ts
@@ -1,6 +1,15 @@
-/** Cross-platform native path and text-document openers used by the local GUI carrier. */
+/**
+ * Cross-platform native path and text-document openers used by the local GUI
+ * carrier.
+ *
+ * The default intent prefers the default browser for documents it renders when
+ * the platform can name one, then falls back to the default application. WSL
+ * translates every path for the Windows desktop instead of assuming a Linux
+ * GUI. The text-editor intent never consults the browser.
+ */

 import { release as osRelease } from 'node:os'
+import { extname } from 'node:path'
 import { runNativeCommand, type NativeCommandRunner } from '@deepseek-ai/dsh-native-command'

 /** Testable command boundary; native implementations never invoke a shell. */
@@ -11,11 +20,63 @@ export interface PathOpenerInternals {
  platform?: NodeJS.Platform
  /** Kernel release override used to distinguish WSL from desktop Linux. */
  osRelease?: string
-  /** WSL environment marker override used with the kernel release. */
-  env?: Readonly<Partial<Record<'WSL_DISTRO_NAME' | 'WSL_INTEROP', string>>>
+  /** Environment used for WSL markers and the desktop Linux browser convention. */
+  env?: NodeJS.ProcessEnv
  run?: PathOpenerRunner
 }

+/** Documents a browser renders, as opposed to ones an editor merely edits. */
+const BROWSER_DOCUMENTS = new Set(['.html', '.htm', '.xhtml', '.svg'])
+
+/**
+ * The macOS bundle registered for `https` — the default browser, as
+ * LaunchServices records it. The nested version dict is stripped first
+ * because it carries its own `LSHandlerRoleAll`.
+ */
+function macBundleForHttps(plist: string): string | undefined {
+  const stripped = plist.replace(/LSHandlerPreferredVersions\s*=\s*\{[^}]*\};/g, '')
+  const block = /\{[^{}]*LSHandlerURLScheme\s*=\s*"?https"?;[^{}]*\}/.exec(stripped)?.[0]
+  if (block === undefined) return undefined
+  return /LSHandlerRoleAll\s*=\s*"?([\w.-]+)"?;/.exec(block)?.[1]
+}
+
+/**
+ * Open one browser-renderable document with the default browser.
+ * @returns true when a browser took it; false when this platform cannot name
+ * one, or naming it failed — the caller then uses the default application.
+ */
+async function openInBrowser(
+  path: string, signal: AbortSignal, platform: NodeJS.Platform,
+  run: PathOpenerRunner, env: NodeJS.ProcessEnv,
+): Promise<boolean> {
+  if (platform === 'darwin') {
+    let bundle: string | undefined
+    try {
+      const { stdout } = await run(
+        'defaults', ['read', 'com.apple.LaunchServices/com.apple.launchservices.secure'], signal)
+      bundle = macBundleForHttps(stdout)
+    } catch {
+      // No LaunchServices record (a fresh account never changed a default):
+      // the content-type handler is then the system's own choice anyway.
+      return false
+    }
+    if (bundle === undefined) return false
+    await run('open', ['-b', bundle, path], signal)
+    return true
+  }
+  if (platform === 'linux') {
+    // $BROWSER is the portable convention; desktop-entry resolution through
+    // xdg-settings needs a launcher this package has no business shipping.
+    const browser = env.BROWSER
+    if (browser === undefined || browser === '') return false
+    await run(browser, [path], signal)
+    return true
+  }
+  // Windows names no browser without reading the UserChoice registry, and its
+  // .html association is the browser in the ordinary case.
+  return false
+}
+
 /** Native path-open intent; macOS distinguishes text editing from file association. */
 type PathOpenIntent = 'default' | 'text-editor'

@@ -63,6 +124,11 @@ async function openNativePathWithIntent(
 ): Promise<void> {
  const platform = internals.platform ?? process.platform
  const run = internals.run ?? runNativeCommand
+  const env = internals.env ?? process.env
+  const wsl = platform === 'linux' && isWsl(internals)
+
+  if (!wsl && intent === 'default' && BROWSER_DOCUMENTS.has(extname(path).toLowerCase())
+    && await openInBrowser(path, signal, platform, run, env)) return

  if (platform === 'darwin') {
    await run('open', intent === 'text-editor' ? ['-t', path] : [path], signal)
@@ -75,7 +141,7 @@ async function openNativePathWithIntent(
  }

  if (platform === 'linux') {
-    if (isWsl(internals)) {
+    if (wsl) {
      await openWslPath(path, signal, run)
      return
    }
@@ -87,10 +153,11 @@ async function openNativePathWithIntent(
 }

 /**
- * Open a filesystem path with the operating system's default application.
+ * Open a filesystem path with the operating system's default application, or
+ * with the default browser when the path names a document a browser renders.
 * @param path - absolute or host-resolvable path (caller owns resolution).
 * @param signal - caller/connection lifetime; abort terminates the native command.
- * @param internals - platform and runner seam for deterministic tests.
+ * @param internals - platform, environment, and runner seam for deterministic tests.
 */
 export function openNativePath(
  path: string,
--- a/packages/host/apiproxy/tests/api-proxy-agent-preset.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-agent-preset.spec.ts
@@ -88,7 +88,11 @@ async function harness(presets?: readonly string[]) {
    },
  }
  ctx.agents.setFactory(factory)
-  const api = createApiProxy(ctx, { provider: 'test', model: 'test-model', cwd, workspaceRoot: cwd })
+  const api = createApiProxy(ctx, {
+    defaultTarget: () => ({ provider: 'test', model: 'test-model' }),
+    cwd,
+    workspaceRoot: cwd,
+  })
  return { api, ctx, cwd }
 }

--- a/packages/host/apiproxy/tests/api-proxy-approval.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-approval.spec.ts
@@ -27,7 +27,7 @@ async function harness(): Promise<{ ctx: Context; api: ApiProxy }> {
  await ctx.plugin(UserInteractionService)
  await ctx.plugin(AgentRegistry)
  await ctx.plugin(ApprovalService)
-  const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+  const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
  return { ctx, api }
 }

@@ -217,7 +217,7 @@ describe('approval pending registry', () => {
    await ctx.plugin(ApprovalService)
    let api!: ApiProxy
    const fiber = ctx.plugin(Object.assign((fiberCtx: Context) => {
-      api = createApiProxy(fiberCtx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+      api = createApiProxy(fiberCtx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
    }, { inject: ['sessions', 'agents', 'userInteraction', 'approval'] }))
    await fiber.await()
    const abort = new AbortController()
--- a/packages/host/apiproxy/tests/api-proxy-blank.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-blank.spec.ts
@@ -35,7 +35,7 @@ async function harness(): Promise<{ ctx: Context; api: ApiProxy; attach: (sessio
  await ctx.plugin(AgentRegistry)
  return {
    ctx,
-    api: createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' }),
+    api: createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }),
    attach: (session) => {
      ctx.agents.register({ id: session.id, session, status: 'idle', ctx } as Agent)
    },
--- a/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-cold.spec.ts
@@ -11,6 +11,8 @@ import { describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import SessionStore from '@deepseek-ai/dsh-session'
 import AgentRegistry from '@deepseek-ai/dsh-agent'
+import { TypeRTLookupFailure } from '@deepseek-ai/dsh-type-meta'
+import TypertRegistry from '@deepseek-ai/dsh-typert-registry'
 import { MessageId } from '@deepseek-ai/dsh-llm'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
@@ -62,7 +64,7 @@ describe('sessions.list cold merge', () => {
        return undefined
      },
    })
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })

    const response = await api.sessions.list(request({}))
    expect(response.result.ok).toBe(true)
@@ -90,7 +92,7 @@ describe('attached updatedAt excludes end-seed', () => {
    await ctx.plugin(SessionStore)
    await ctx.plugin(UserInteractionService)
    await ctx.plugin(AgentRegistry)
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })

    // Old work, resumed just now: the log tail would report the pickup.
    const worked = 1_000_000
@@ -148,7 +150,7 @@ describe('cold history recovery view', () => {
      inspect: (id: SessionId, signal?: AbortSignal) => coordinator.inspect(id, signal),
      locate: () => undefined,
    } as never)
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })

    const history = await api.sessions.history(request({ sessionId, beforeSeq: 2, maxMessages: 10 }))
    if (!history.result.ok) throw new Error('history failed')
@@ -180,6 +182,100 @@ describe('cold history recovery view', () => {
  })
 })

+describe('Remote Agent and Session lookup policy', () => {
+  it('deduplicates a cold resume across Agent and Session parameters', async () => {
+    const ctx = new Context()
+    await ctx.plugin(TypertRegistry)
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(UserInteractionService)
+    const sessionId = sid('session-remote-cold')
+    const meta = header(sessionId, 1000)
+    const inspect = vi.fn(() => Promise.resolve({ meta, events: [] as SessionEvent[] }))
+    ctx.provide('sessionPersistence', {
+      list: () => Promise.resolve([meta]),
+      inspect,
+      locate: () => undefined,
+    } as never)
+    const resumedSession = { id: sessionId, header: meta, events: [] } as unknown as import('@deepseek-ai/dsh-session').Session
+    const resumedAgent = { id: sessionId, session: resumedSession, status: 'idle', ctx } as Agent
+    const release = Promise.withResolvers<undefined>()
+    const resume = vi.spyOn(ctx.agents, 'resume').mockImplementation(async () => {
+      await release.promise
+      return { agent: resumedAgent, dispose: () => Promise.resolve() }
+    })
+    const defaultAgentLookup = ctx.typert.lookups.get('agent')
+    const defaultSessionLookup = ctx.typert.lookups.get('session')
+    createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    await vi.waitFor(() => {
+      expect(ctx.typert.lookups.get('agent')).not.toBe(defaultAgentLookup)
+      expect(ctx.typert.lookups.get('session')).not.toBe(defaultSessionLookup)
+    })
+    const agentLookup = ctx.typert.lookups.get('agent')
+    const sessionLookup = ctx.typert.lookups.get('session')
+    if (agentLookup === undefined || sessionLookup === undefined) throw new Error('core lookup providers were not mounted')
+
+    const resolvedAgent = Promise.resolve(agentLookup.resolve(sessionId))
+    const resolvedSession = Promise.resolve(sessionLookup.resolve(sessionId))
+    await vi.waitFor(() => { expect(resume).toHaveBeenCalledOnce() })
+    release.resolve(undefined)
+
+    await expect(resolvedAgent).resolves.toBe(resumedAgent)
+    await expect(resolvedSession).resolves.toBe(resumedSession)
+    expect(inspect).toHaveBeenCalledOnce()
+  })
+
+  it('preserves the subagent ownership fence for cold and live Remote lookups', async () => {
+    const ctx = new Context()
+    await ctx.plugin(TypertRegistry)
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(UserInteractionService)
+    const coldId = sid('session-remote-cold-child')
+    const coldMeta = header(coldId, 1000, {
+      parentSession: sid('session-parent'),
+      origin: 'subagent',
+    })
+    const inspect = vi.fn(() => Promise.resolve({ meta: coldMeta, events: [] as SessionEvent[] }))
+    ctx.provide('sessionPersistence', {
+      list: () => Promise.resolve([coldMeta]),
+      inspect,
+      locate: () => undefined,
+    } as never)
+    const liveSession = ctx.sessions.create(sid('session-remote-live-child'), {
+      meta: { cwd: '/proj', parentSession: sid('session-parent'), origin: 'subagent' },
+    })
+    const liveAgent = { id: liveSession.id, session: liveSession, status: 'idle', ctx } as Agent
+    ctx.agents.register(liveAgent)
+    const resume = vi.spyOn(ctx.agents, 'resume')
+    const defaultAgentLookup = ctx.typert.lookups.get('agent')
+    const defaultSessionLookup = ctx.typert.lookups.get('session')
+    createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
+    await vi.waitFor(() => {
+      expect(ctx.typert.lookups.get('agent')).not.toBe(defaultAgentLookup)
+      expect(ctx.typert.lookups.get('session')).not.toBe(defaultSessionLookup)
+    })
+    const agentLookup = ctx.typert.lookups.get('agent')
+    const sessionLookup = ctx.typert.lookups.get('session')
+    if (agentLookup === undefined || sessionLookup === undefined) throw new Error('core lookup providers were not mounted')
+    const ownershipFailure = {
+      failure: {
+        code: 'agent-busy',
+        details: { reason: 'use subagent delivery for this child session' },
+      },
+    }
+
+    const coldFailure = Promise.resolve(agentLookup.resolve(coldId))
+    const liveFailure = Promise.resolve(sessionLookup.resolve(liveSession.id))
+    await expect(coldFailure).rejects.toBeInstanceOf(TypeRTLookupFailure)
+    await expect(coldFailure).rejects.toMatchObject(ownershipFailure)
+    await expect(liveFailure).rejects.toBeInstanceOf(TypeRTLookupFailure)
+    await expect(liveFailure).rejects.toMatchObject(ownershipFailure)
+    expect(resume).not.toHaveBeenCalled()
+    expect(inspect).toHaveBeenCalledOnce()
+  })
+})
+
 describe('subagent ownership fence', () => {
  it('reads a cold child without an Agent and rejects generic resume or adoption', async () => {
    const ctx = new Context()
@@ -216,7 +312,7 @@ describe('subagent ownership fence', () => {
      locate: () => undefined,
    } as never)
    const resume = vi.spyOn(ctx.agents, 'resume')
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })

    const history = await api.sessions.history(request({ sessionId }))
    expect(history.result.ok).toBe(true)
@@ -275,7 +371,7 @@ describe('subagent ownership fence', () => {
    // instead of answering `agent-busy`.
    const resume = vi.spyOn(ctx.agents, 'resume')
      .mockRejectedValue(new Error('registry unavailable in this bench'))
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })

    const prompt = await api.sessions.prompt(request({
      sessionId,
@@ -316,7 +412,7 @@ describe('subagent ownership fence', () => {
    })
    const startingChild = { id: startingSession.id, session: startingSession, status: 'idle', ctx } as Agent
    ctx.agents.enter(startingChild, parent)
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })

    const stopped = await api.sessions.cancel(request({ sessionId: originChild.id }))
    expect(stopped.result.ok).toBe(false)
@@ -362,7 +458,7 @@ describe('subagent ownership fence', () => {
    const followup = vi.fn()
    const agent = { id: session.id, session, status: 'idle', ctx, followup } as unknown as Agent
    ctx.agents.register(agent)
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })

    const response = await api.sessions.prompt(request({
      sessionId: agent.id,
@@ -380,7 +476,7 @@ describe('degenerate composition (no persistence, no factory)', () => {
    await ctx.plugin(SessionStore)
    await ctx.plugin(AgentRegistry)
    await ctx.plugin(UserInteractionService)
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })

    const listed = await api.sessions.list(request({}))
    expect(listed.result.ok).toBe(true)
@@ -405,7 +501,7 @@ describe('degenerate composition (no persistence, no factory)', () => {
      list: () => Promise.resolve([]),
      inspect,
    } as never)
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })

    const response = await api.sessions.history(request({ sessionId: sid('session-missing') }))
    expect(response.result.ok).toBe(false)
@@ -431,7 +527,7 @@ describe('sessions.prompt synchronous rejection', () => {
      followup: () => { throw new Error('agent "session-throwing" lifecycle disposed') },
      steer: () => { throw new Error('agent "session-throwing" lifecycle disposed') },
    } as unknown as Agent)
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })

    for (const mode of ['queue', 'steer'] as const) {
      const response = await api.sessions.prompt(request({
@@ -475,7 +571,7 @@ describe('sessions.prompt synchronous rejection', () => {
      ctx.agents.register(child)
      throw new Error('session id already published')
    })
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })

    const models = await api.sessions.models(request({ sessionId }))
    expect(models.result.ok).toBe(false)
--- a/packages/host/apiproxy/tests/api-proxy-commands.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-commands.spec.ts
@@ -25,7 +25,7 @@ import type { RpcRequest, RpcResponse } from '../src/api/rpc.ts'
 import { RpcId } from '../src/api/rpc.ts'
 import { createApiProxy } from '../src/api-proxy.ts'

-const DEFAULTS = { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' }
+const DEFAULTS = { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }

 function request<P>(payload: P): RpcRequest<P> {
  return { rpcId: RpcId(`req-${String(nextRpc++)}`), payload }
--- a/packages/host/apiproxy/tests/api-proxy-config.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-config.spec.ts
@@ -22,9 +22,9 @@ import type { CredentialInfo, CredentialRef, ResolvedCredential } from '@deepsee
 import type { HostFrame } from '../src/api/index.ts'
 import type { RpcRequest, RpcResponse } from '../src/api/rpc.ts'
 import { RpcId } from '../src/api/rpc.ts'
-import { createApiProxy } from '../src/api-proxy.ts'
+import { API_GATEWAY_SETTINGS_NAMESPACE, createApiProxy } from '../src/api-proxy.ts'

-const DEFAULTS = { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' }
+const DEFAULTS = { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }

 let nextRpc = 1
 function request<P>(payload: P): RpcRequest<P> {
@@ -398,6 +398,25 @@ describe('settings domain', () => {
    expect(frames).toEqual([{ type: 'host/settings-changed', ns: 'permission' }])
  })

+  it('invalidates the model catalog when the gateway default route changes', async () => {
+    const ctx = await harness()
+    const route = ctx.settings.register(API_GATEWAY_SETTINGS_NAMESPACE, z.object({
+      provider: z.string().required(),
+      model: z.string().required(),
+    }), { base: { provider: 'deepseek-official', model: 'deepseek-v4-flash' } })
+    const api = createApiProxy(ctx, DEFAULTS)
+    // The gateway's own section names the route every session with no logged
+    // one resolves to, so an externally edited default — another tab, a
+    // hand-edited settings.yaml — has to reach an open selector as well.
+    const frames = await collectHost(api, ['host/settings-changed', 'host/models-changed'], 2, async () => {
+      await route.replace({ provider: 'deepseek-official', model: 'deepseek-reasoner' })
+    })
+    expect(frames).toEqual([
+      { type: 'host/settings-changed', ns: 'api-gateway' },
+      { type: 'host/models-changed' },
+    ])
+  })
+
  it('maps a stale expectedRevision to settings-conflict carrying both revisions', async () => {
    const ctx = await harness()
    ctx.settings.register(NS, AdapterConfig)
--- a/packages/host/apiproxy/tests/api-proxy-default-route.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-default-route.spec.ts
@@ -0,0 +1,108 @@
+/**
+ * The `api-gateway` settings section over a REAL settings provider: the
+ * composition entry as the base layer, the wholesale replace the gateway
+ * persists with, and the fallback when the provider detaches. The other model
+ * specs drive hand-rolled `defaultTarget`/`persistDefaultTarget` closures, so
+ * this is the only place the layering itself is exercised.
+ */
+
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { Settings, installSettingsSection } from '@deepseek-ai/dsh-settings'
+import type { SettingsNamespace } from '@deepseek-ai/dsh-settings'
+import { API_GATEWAY_SETTINGS_NAMESPACE, DEFAULT_ROUTE_SCHEMA } from '../src/index.ts'
+import type { DefaultRouteSettings } from '../src/index.ts'
+
+/** The smallest real provider: one in-memory document, always writable. */
+class MemorySettings extends Settings {
+  doc: Record<string, unknown> = {}
+
+  get writable(): boolean {
+    return true
+  }
+
+  protected load(): Promise<Record<string, unknown>> {
+    return Promise.resolve(structuredClone(this.doc))
+  }
+
+  protected persist(ns: SettingsNamespace, section: Record<string, unknown>): Promise<void> {
+    this.doc = { ...this.doc, [ns]: structuredClone(section) }
+    return Promise.resolve()
+  }
+}
+
+/** Mount the gateway's own section wiring over a live provider. */
+async function boot(entry: DefaultRouteSettings) {
+  const ctx = new Context()
+  const fiber = ctx.plugin(MemorySettings)
+  await fiber.await()
+  let route: () => DefaultRouteSettings = () => entry
+  const consumer = ctx.plugin(function section(child: Context) {
+    installSettingsSection(child, API_GATEWAY_SETTINGS_NAMESPACE, DEFAULT_ROUTE_SCHEMA, entry, {
+      setSource: (current) => { route = current },
+      onChange: () => {},
+    })
+  })
+  await consumer.await()
+  const settings = ctx.get('settings')
+  if (settings === undefined) throw new Error('settings provider did not mount')
+  return { ctx, fiber, consumer, settings, read: () => route() }
+}
+
+describe('the api-gateway default-route section', () => {
+  it('resolves the composition entry until the user layer overrides it', async () => {
+    const bench = await boot({ provider: 'deepseek-official', model: 'deepseek-v4-flash' })
+    expect(bench.read()).toEqual({ provider: 'deepseek-official', model: 'deepseek-v4-flash' })
+
+    await bench.settings.replace(API_GATEWAY_SETTINGS_NAMESPACE, {
+      provider: 'acme-gateway', model: 'acme-large', reasoningEffort: 'high',
+    })
+    expect(bench.read()).toEqual({
+      provider: 'acme-gateway', model: 'acme-large', reasoningEffort: 'high',
+    })
+    await bench.ctx.fiber.dispose()
+  })
+
+  it('clears a stored effort when the next switch has none', async () => {
+    const bench = await boot({ provider: 'deepseek-official', model: 'deepseek-v4-flash' })
+    await bench.settings.replace(API_GATEWAY_SETTINGS_NAMESPACE, {
+      provider: 'acme-gateway', model: 'acme-large', reasoningEffort: 'high',
+    })
+    expect(bench.read().reasoningEffort).toBe('high')
+
+    // The whole reason the gateway persists with `replace` rather than a merge
+    // patch — and the reason `Config` carries no effort for the base layer to
+    // re-inherit here. A stranded effort would fail the next session's first
+    // request against a model that does not support it.
+    await bench.settings.replace(API_GATEWAY_SETTINGS_NAMESPACE, {
+      provider: 'acme-gateway', model: 'acme-plain',
+    })
+    expect(bench.read()).toEqual({ provider: 'acme-gateway', model: 'acme-plain' })
+    await bench.ctx.fiber.dispose()
+  })
+
+  it('layers a hand-written partial section over the entry', async () => {
+    const bench = await boot({ provider: 'deepseek-official', model: 'deepseek-v4-flash' })
+    // Someone editing settings.yaml by hand may name only the model. The
+    // entry supplies the provider, which is what makes this legal — and is
+    // exactly why an effort in the entry could never be cleared, so there
+    // is none to inherit.
+    await bench.settings.replace(API_GATEWAY_SETTINGS_NAMESPACE, { model: 'deepseek-reasoner' })
+    expect(bench.read()).toEqual({ provider: 'deepseek-official', model: 'deepseek-reasoner' })
+    await bench.ctx.fiber.dispose()
+  })
+
+  it('falls back to the composition entry when the provider detaches', async () => {
+    const bench = await boot({ provider: 'deepseek-official', model: 'deepseek-v4-flash' })
+    await bench.settings.replace(API_GATEWAY_SETTINGS_NAMESPACE, {
+      provider: 'acme-gateway', model: 'acme-large',
+    })
+    expect(bench.read().provider).toBe('acme-gateway')
+
+    // A deployment that loses its settings provider keeps serving the route it
+    // was composed with rather than the one it can no longer read.
+    await bench.fiber.dispose()
+    expect(bench.read()).toEqual({ provider: 'deepseek-official', model: 'deepseek-v4-flash' })
+    await bench.ctx.fiber.dispose()
+  })
+})
--- a/packages/host/apiproxy/tests/api-proxy-fork.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-fork.spec.ts
@@ -82,8 +82,7 @@ function liveAgent(
 }

 const api = (ctx: Context) => createApiProxy(ctx, {
-  provider: 'default-provider',
-  model: 'default-model',
+  defaultTarget: () => ({ provider: 'default-provider', model: 'default-model' }),
  cwd: '/tmp',
  workspaceRoot: '/tmp',
 })
--- a/packages/host/apiproxy/tests/api-proxy-models.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-models.spec.ts
@@ -125,7 +125,7 @@ describe('Web session model selection', () => {
      model: 'private-preview',
      reasoningEffort: ReasoningEffortId('max'),
    })
-    const api = createApiProxy(ctx, { provider: 'deepseek-official', model: 'deepseek-chat', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'deepseek-official', model: 'deepseek-chat' }), cwd: '/tmp', workspaceRoot: '/tmp' })

    const catalog = expectValue(await api.sessions.models(request({ sessionId })))
    expect(catalog.current).toEqual({
@@ -160,7 +160,7 @@ describe('Web session model selection', () => {

  it('accepts an advisory-unlisted model, rejects an unavailable provider, and switches only after the next assembly', async () => {
    const { ctx, agent, sessionId } = await harness()
-    const api = createApiProxy(ctx, { provider: 'deepseek-official', model: 'deepseek-chat', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'deepseek-official', model: 'deepseek-chat' }), cwd: '/tmp', workspaceRoot: '/tmp' })
    const seed: LlmCallConfig = { provider: 'seed', model: 'seed', temperature: 0.2 }
    const signal = new AbortController().signal

@@ -225,4 +225,132 @@ describe('Web session model selection', () => {
      .toEqual({ provider: 'deepseek-official', model: 'private-preview', reasoningEffort: 'max' })
    await ctx.fiber.dispose()
  })
+
+  it('reads the host default live for a session whose log names no route', async () => {
+    const { ctx, sessionId } = await harness()
+    let stored = { provider: 'deepseek-official', model: 'deepseek-chat' }
+    const api = createApiProxy(ctx, {
+      defaultTarget: () => stored,
+      cwd: '/tmp',
+      workspaceRoot: '/tmp',
+    })
+
+    expect(expectValue(await api.sessions.models(request({ sessionId }))).current)
+      .toEqual({ provider: 'deepseek-official', model: 'deepseek-chat' })
+    // The default moving after the session exists still reaches it: New
+    // Session reuses a blank session rather than minting another, so a seed
+    // captured at creation would show the superseded model there.
+    stored = { provider: 'deepseek-official', model: 'deepseek-reasoner' }
+    expect(expectValue(await api.sessions.models(request({ sessionId }))).current)
+      .toEqual({ provider: 'deepseek-official', model: 'deepseek-reasoner' })
+    expect(expectValue(await api.host.describe(request({}))))
+      .toMatchObject({ provider: 'deepseek-official', model: 'deepseek-reasoner' })
+    await ctx.fiber.dispose()
+  })
+
+  it('keeps a session that logged a route on it when the host default moves', async () => {
+    const { ctx, sessionId } = await harness({
+      provider: 'deepseek-official',
+      model: 'deepseek-chat',
+    })
+    let stored = { provider: 'deepseek-official', model: 'deepseek-chat' }
+    const api = createApiProxy(ctx, {
+      defaultTarget: () => stored,
+      cwd: '/tmp',
+      workspaceRoot: '/tmp',
+    })
+
+    stored = { provider: 'duplicate', model: 'same' }
+    expect(expectValue(await api.sessions.models(request({ sessionId }))).current)
+      .toEqual({ provider: 'deepseek-official', model: 'deepseek-chat' })
+    await ctx.fiber.dispose()
+  })
+
+  it('saves an accepted selection as the default and survives a storage failure', async () => {
+    const { ctx, sessionId } = await harness()
+    const saved: unknown[] = []
+    let reject = false
+    const api = createApiProxy(ctx, {
+      defaultTarget: () => ({ provider: 'deepseek-official', model: 'deepseek-chat' }),
+      persistDefaultTarget: (target) => {
+        saved.push(target)
+        return reject ? Promise.reject(new Error('read-only document')) : Promise.resolve()
+      },
+      cwd: '/tmp',
+      workspaceRoot: '/tmp',
+    })
+
+    expectValue(await api.sessions.selectModel(request({
+      sessionId, provider: 'deepseek-official', model: 'deepseek-reasoner', reasoningEffort: 'max',
+    })))
+    expect(saved).toEqual([
+      { provider: 'deepseek-official', model: 'deepseek-reasoner', reasoningEffort: 'max' },
+    ])
+
+    // A refused selection never becomes anyone's default.
+    await api.sessions.selectModel(request({ sessionId, provider: 'missing', model: 'model' }))
+    expect(saved).toHaveLength(1)
+
+    // Storage failing is not the selection failing: the switch already applies
+    // to this session, so the call still succeeds.
+    reject = true
+    const stillAccepted = expectValue(await api.sessions.selectModel(request({
+      sessionId, provider: 'deepseek-official', model: 'deepseek-chat',
+    })))
+    expect(stillAccepted.selected).toEqual({ provider: 'deepseek-official', model: 'deepseek-chat', reasoningEffort: 'high' })
+    expect(expectValue(await api.sessions.models(request({ sessionId }))).current)
+      .toEqual({ provider: 'deepseek-official', model: 'deepseek-chat', reasoningEffort: 'high' })
+    await ctx.fiber.dispose()
+  })
+
+  it('refuses a prompt no adapter can route, and reports it on the directory', async () => {
+    const { ctx, sessionId } = await harness()
+    const api = createApiProxy(ctx, {
+      defaultTarget: () => ({ provider: 'deleted-gateway', model: 'deleted-model' }),
+      cwd: '/tmp',
+      workspaceRoot: '/tmp',
+    })
+
+    // The client disabling its input is an affordance; this method stays
+    // callable, so the refusal has to live here.
+    const refused = await api.sessions.prompt(request({
+      sessionId, mode: 'queue' as const, content: [{ type: 'text' as const, text: 'hi' }],
+    }))
+    expect(refused.result).toMatchObject({
+      ok: false,
+      error: { code: 'model-unavailable', details: { provider: 'deleted-gateway', model: 'deleted-model' } },
+    })
+    expect(expectValue(await api.sessions.models(request({ sessionId }))).routable).toBe(false)
+
+    // An advisory-unlisted model on a live route is NOT this: the route
+    // serves it, so the prompt goes through and nothing blocks.
+    expectValue(await api.sessions.selectModel(request({
+      sessionId, provider: 'deepseek-official', model: 'unlisted-but-served',
+    })))
+    const catalog = expectValue(await api.sessions.models(request({ sessionId })))
+    expect(catalog.routable).toBe(true)
+    expect(catalog.groups.flatMap(group => group.models.map(model => model.id)))
+      .not.toContain('unlisted-but-served')
+    await ctx.fiber.dispose()
+  })
+
+  it('serves a session and its catalog when the stored default names a route that is gone', async () => {
+    const { ctx, sessionId } = await harness()
+    const api = createApiProxy(ctx, {
+      // What a Models-page removal leaves behind: the settings document still
+      // names the route the user last picked, and nothing serves it.
+      defaultTarget: () => ({ provider: 'deleted-gateway', model: 'deleted-model' }),
+      cwd: '/tmp',
+      workspaceRoot: '/tmp',
+    })
+
+    const catalog = expectValue(await api.sessions.models(request({ sessionId })))
+    // Passed through rather than repaired: matching no group is precisely what
+    // makes the composer seat prompt for a selection instead of naming a model
+    // the deployment cannot reach.
+    expect(catalog.current).toEqual({ provider: 'deleted-gateway', model: 'deleted-model' })
+    expect(catalog.groups.flatMap(group => group.models.map(model => `${group.id}/${model.id}`)))
+      .not.toContain('deleted-gateway/deleted-model')
+    await ctx.fiber.dispose()
+  })
 })
--- a/packages/host/apiproxy/tests/api-proxy-projections.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-projections.spec.ts
@@ -68,7 +68,7 @@ function seedMessages(session: Session, count: number): void {
  }
 }

-const api = (ctx: Context) => createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+const api = (ctx: Context) => createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })

 describe('session.history projections block', () => {
  it('serves the unit value on the tail page with asOfSeq = last event seq', async () => {
--- a/packages/host/apiproxy/tests/api-proxy-question.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-question.spec.ts
@@ -13,7 +13,7 @@ async function harness(): Promise<{ ctx: Context; api: ApiProxy }> {
  await ctx.plugin(UserInteractionService)
  return {
    ctx,
-    api: createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' }),
+    api: createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }),
  }
 }

--- a/packages/host/apiproxy/tests/api-proxy-rename.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-rename.spec.ts
@@ -68,7 +68,7 @@ function liveAgent(ctx: Context, id: string, turns: number): Session {
  return session
 }

-const api = (ctx: Context) => createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+const api = (ctx: Context) => createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })

 describe('sessions.rename', () => {
  it('accepts through the composed title service: normalized user-source event, echoed seq', async () => {
--- a/packages/host/apiproxy/tests/api-proxy-search.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-search.spec.ts
@@ -27,7 +27,7 @@ vi.mock('node:fs/promises', async (importOriginal) => {
 })

 const sid = (value: string): SessionId => value as SessionId
-const defaults = { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' }
+const defaults = { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' }

 function request(query: string): RpcRequest<{ query: string }> {
  return { rpcId: RpcId(`search-${query}`), payload: { query } }
--- a/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-subagents.spec.ts
@@ -88,7 +88,7 @@ function bench(options: {
  ctx.provide('sessionProjections', { snapshot, restore, onChanged: () => () => {} })
  ctx.provide('userInteraction', { registerProvider: () => () => {} })
  const api = createApiProxy(ctx, {
-    provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp',
+    defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp',
  })
  return { api, getAgent, listChildren, inspect, snapshot, restore, followup, parent }
 }
--- a/packages/host/apiproxy/tests/api-proxy-view.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-view.spec.ts
@@ -105,7 +105,7 @@ async function collect(iterable: AsyncIterable<RpcRequest<MuxFrame>>, count: num
 describe('mux live view computation', () => {
  it('attaches the three standard card views, omits view without a presenter, soft-falls on throw', async () => {
    const { ctx } = await harness()
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
    const abort = new AbortController()
    const stream = api.events.mux({ rpcId: RpcId('t-mux'), payload: {} }, abort.signal)
    const collected = collect(stream, 9, abort)
@@ -170,7 +170,7 @@ describe('mux live view computation', () => {

  it('serves history entries with call/result views, backscan pairing, and soft-falls', async () => {
    const { ctx } = await harness()
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
    const session = ctx.sessions.create()
    // history resolves the agent first; a live structural stub is enough (only
    // .session is read on this path).
@@ -238,7 +238,7 @@ describe('mux live view computation', () => {

  it('counts only append-origin messages toward maxMessages and keeps compaction provenance whole', async () => {
    const { ctx } = await harness()
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
    const session = ctx.sessions.create()
    ctx.agents.register({ id: session.id, session, status: 'idle', ctx } as Agent)
    session.append('turn/start', { turn: 1 })
@@ -287,7 +287,7 @@ describe('mux live view computation', () => {

  it('drops a disposed session from the live open-call table (result after dispose gets no view)', async () => {
    const { ctx } = await harness()
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
    const abort = new AbortController()
    const stream = api.events.mux({ rpcId: RpcId('t-mux3'), payload: {} }, abort.signal)

@@ -308,7 +308,7 @@ describe('mux live view computation', () => {

  it('pairs a result after turn/end via the in-memory backscan fallback', async () => {
    const { ctx } = await harness()
-    const api = createApiProxy(ctx, { provider: 'p', model: 'm', cwd: '/tmp', workspaceRoot: '/tmp' })
+    const api = createApiProxy(ctx, { defaultTarget: () => ({ provider: 'p', model: 'm' }), cwd: '/tmp', workspaceRoot: '/tmp' })
    const abort = new AbortController()
    const stream = api.events.mux({ rpcId: RpcId('t-mux2'), payload: {} }, abort.signal)
    const collected = collect(stream, 4, abort)
--- a/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-workspace.spec.ts
@@ -100,8 +100,7 @@ async function harness(
  // object per harness mirrors the seam's stability contract.
  ctx.provide('directoryPicker', { capability: () => picker } as never)
  const api = createApiProxy(ctx, {
-    provider: 'test',
-    model: 'test-model',
+    defaultTarget: () => ({ provider: 'test', model: 'test-model' }),
    cwd: workspaceRoot,
    workspaceRoot,
    ...extras.openPath === undefined ? {} : { openPath: extras.openPath },
--- a/packages/host/apiproxy/tests/client-handler.spec.ts
+++ b/packages/host/apiproxy/tests/client-handler.spec.ts
@@ -45,6 +45,7 @@ function scriptedApi(overrides: {
      }),
      models: r => ok(r, {
        current: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+        routable: true,
        groups: [],
        failures: [],
      }),
--- a/packages/host/apiproxy/tests/fetch-carrier.spec.ts
+++ b/packages/host/apiproxy/tests/fetch-carrier.spec.ts
@@ -64,6 +64,7 @@ function fakeApi(overrides: Partial<{ muxFrames: MuxFrame[]; hostFrames: HostFra
            ok: true,
            value: {
              current: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+              routable: true,
              groups: [],
              failures: [],
            },
--- a/packages/host/apiproxy/tests/native-path-opener.spec.ts
+++ b/packages/host/apiproxy/tests/native-path-opener.spec.ts
@@ -167,3 +167,123 @@ describe('native path opener', () => {
    })
  })
 })
+
+describe('browser-renderable documents', () => {
+  const LS_PLIST = `{
+    LSHandlers = (
+        {
+            LSHandlerPreferredVersions =             {
+                LSHandlerRoleAll = "-";
+            };
+            LSHandlerRoleAll = "com.google.chrome";
+            LSHandlerURLScheme = https;
+        }
+    );
+}`
+
+  it('opens a page with the default browser rather than the .html handler on darwin', async () => {
+    const calls: { command: string; args: readonly string[] }[] = []
+    const run = async (command: string, args: readonly string[]) => {
+      calls.push({ command, args })
+      return { stdout: command === 'defaults' ? LS_PLIST : '', stderr: '' }
+    }
+    await openNativePath('/w/page.html', new AbortController().signal, { platform: 'darwin', run })
+    // A developer who bound .html to an editor still gets a rendered page.
+    expect(calls.map(c => [c.command, ...c.args])).toEqual([
+      ['defaults', 'read', 'com.apple.LaunchServices/com.apple.launchservices.secure'],
+      ['open', '-b', 'com.google.chrome', '/w/page.html'],
+    ])
+  })
+
+  it('leaves every other document to the default application', async () => {
+    const calls: string[][] = []
+    const run = async (command: string, args: readonly string[]) => {
+      calls.push([command, ...args])
+      return { stdout: '', stderr: '' }
+    }
+    await openNativePath('/w/report.md', new AbortController().signal, { platform: 'darwin', run })
+    // No LaunchServices read at all: markdown is not a browser document.
+    expect(calls).toEqual([['open', '/w/report.md']])
+  })
+
+  it('falls back to the default application when no browser can be named', async () => {
+    // LaunchServices has no https record (a fresh account), so the system's
+    // own content-type choice is the best answer available.
+    const calls: string[][] = []
+    const run = async (command: string, args: readonly string[]) => {
+      calls.push([command, ...args])
+      if (command === 'defaults') throw new Error('domain not found')
+      return { stdout: '', stderr: '' }
+    }
+    await openNativePath('/w/page.html', new AbortController().signal, { platform: 'darwin', run })
+    expect(calls).toEqual([
+      ['defaults', 'read', 'com.apple.LaunchServices/com.apple.launchservices.secure'],
+      ['open', '/w/page.html'],
+    ])
+
+    // A record without an https handler is the same answer.
+    const bare: string[][] = []
+    await openNativePath('/w/page.html', new AbortController().signal, {
+      platform: 'darwin',
+      run: async (command, args) => {
+        bare.push([command, ...args])
+        return { stdout: '{ LSHandlers = ( ); }', stderr: '' }
+      },
+    })
+    expect(bare[1]).toEqual(['open', '/w/page.html'])
+  })
+
+  it('honors $BROWSER on linux and leaves windows to its association', async () => {
+    const linux: string[][] = []
+    await openNativePath('/w/page.html', new AbortController().signal, {
+      platform: 'linux',
+      osRelease: '6.8.0-generic',
+      env: { BROWSER: 'firefox' },
+      run: async (command, args) => { linux.push([command, ...args]); return { stdout: '', stderr: '' } },
+    })
+    expect(linux).toEqual([['firefox', '/w/page.html']])
+
+    // Unset $BROWSER: xdg-open's association is the fallback.
+    const bare: string[][] = []
+    await openNativePath('/w/page.html', new AbortController().signal, {
+      platform: 'linux',
+      osRelease: '6.8.0-generic',
+      env: {},
+      run: async (command, args) => { bare.push([command, ...args]); return { stdout: '', stderr: '' } },
+    })
+    expect(bare).toEqual([['xdg-open', '/w/page.html']])
+
+    // Windows names no browser without the UserChoice registry.
+    const win: string[][] = []
+    await openNativePath('C:\\w\\page.html', new AbortController().signal, {
+      platform: 'win32',
+      run: async (command, args) => { win.push([command, ...args]); return { stdout: '', stderr: '' } },
+    })
+    expect(win[0]?.[0]).toBe('powershell.exe')
+  })
+
+  it('hands browser-renderable WSL paths to the Windows desktop', async () => {
+    const calls: string[][] = []
+    await openNativePath('/home/test/page.html', new AbortController().signal, {
+      platform: 'linux',
+      osRelease: '5.15.153.1-microsoft-standard-WSL2',
+      env: { BROWSER: 'firefox' },
+      run: async (command, args) => {
+        calls.push([command, ...args])
+        return {
+          stdout: command === 'wslpath' ? 'C:\\workspace\\page.html\n' : '',
+          stderr: '',
+        }
+      },
+    })
+    expect(calls).toEqual([
+      ['wslpath', '-w', '/home/test/page.html'],
+      [
+        'powershell.exe',
+        '-NoProfile',
+        '-Command',
+        "Invoke-Item -LiteralPath 'C:\\workspace\\page.html'",
+      ],
+    ])
+  })
+})
--- a/packages/host/apiproxy/tests/rpc-schemas.spec.ts
+++ b/packages/host/apiproxy/tests/rpc-schemas.spec.ts
@@ -197,6 +197,7 @@ describe('sessions domain schemas', () => {
    expect(sessionModelsRequestSchema.parse({ sessionId: 's1' }).sessionId).toBe('s1')
    expect(sessionModelsValueSchema.parse({
      current: { provider: 'deepseek-official', model: 'deepseek-v4-flash', reasoningEffort: 'max' },
+      routable: true,
      groups: [{
        id: 'deepseek-official',
        name: 'DeepSeek',
@@ -274,8 +275,10 @@ describe('sessions domain schemas', () => {
 describe('host domain schemas', () => {
  it('validates describe request/value', () => {
    expect(hostDescribeRequestSchema.parse({})).toEqual({})
-    const value = hostDescribeValueSchema.parse({ version: '1', cwd: '/x', provider: 'p', model: 'm', attachedSessions: 2 })
-    expect(value.attachedSessions).toBe(2)
+    const value = hostDescribeValueSchema.parse({
+      version: '1', cwd: '/x', provider: 'p', model: 'm', attachedSessions: 2,
+    })
+    expect(value).toMatchObject({ provider: 'p', model: 'm', attachedSessions: 2 })
    expect(hostDescribeValueSchema.parse({ version: '1', cwd: '/x', attachedSessions: 0 }).provider).toBeUndefined()
  })

--- a/packages/host/apiproxy/tsconfig.json
+++ b/packages/host/apiproxy/tsconfig.json
@@ -23,6 +23,9 @@
    {
      "path": "../../../vendor/schemastery"
    },
+    {
+      "path": "../../api/remotes/tsconfig.host.json"
+    },
    {
      "path": "../../util/brand"
    },
--- a/packages/host/directory-picker-native/tsdown.config.ts
+++ b/packages/host/directory-picker-native/tsdown.config.ts
@@ -3,18 +3,21 @@ import { clientBundle } from '../../client/tsdown.client.ts'
 // The Win32 dialog worker builds as its own CJS entry (mirroring
 // dsh-workflow-workerthread's worker): path-loaded by the driver, inlining
 // the dialog logic while koffi stays an external native require.
-export default [
-  ...clientBundle('@deepseek-ai/dsh-host-directory-picker-native', ['lib/types/index.js', 'lib/types/invariant.js']),
+export default clientBundle(
+  '@deepseek-ai/dsh-host-directory-picker-native',
+  ['lib/types/index.js', 'lib/types/invariant.js'],
  {
-    // The artifact is lib/worker.cjs (the ./worker export the workspace
-    // constraint keys on), bundled from the descriptive source entry.
-    entry: { worker: 'lib/types/win32-dialog-worker.js' },
-    outDir: 'lib',
-    format: ['cjs'] as ['cjs'],
-    platform: 'node' as const,
-    target: 'es2024',
-    fixedExtension: false,
-    dts: false,
-    clean: false,
+    companions: [{
+      // The artifact is lib/worker.cjs (the ./worker export the workspace
+      // constraint keys on), bundled from the descriptive source entry.
+      entry: { worker: 'lib/types/win32-dialog-worker.js' },
+      outDir: 'lib',
+      format: ['cjs'],
+      platform: 'node',
+      target: 'es2024',
+      fixedExtension: false,
+      dts: false,
+      clean: false,
+    }],
  },
-]
+)
--- a/packages/host/frontend-static/README.i18n.yaml
+++ b/packages/host/frontend-static/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/host/frontend-static/README.md
-README.md: c3a831abb1060b59e1802d38d5407a29d24e3bb3
-README.zh.md: d4dc71763280a3c88c73de50f63f2615570c7182
+README.md: 82ba5a2cd0937e2c24505648aa1e3daec6bf2ece
+README.zh.md: 1130aa7cc241ee5245fceaba0ef66fcf95871e67
--- a/packages/host/frontend-static/README.md
+++ b/packages/host/frontend-static/README.md
@@ -16,4 +16,4 @@ None; this package neither assembles nor sends a provider request.

 ## Known Limitations and Deferred Work

- **The starter MIME table is minimal** — extensions beyond the vite-emitted set fall back to `application/octet-stream`; extend the table when an asset class actually ships.
+- **The starter MIME table is minimal** — it covers the Vite-emitted asset set plus the shipped PWA manifest; other extensions fall back to `application/octet-stream` until an asset class actually ships.
--- a/packages/host/frontend-static/README.zh.md
+++ b/packages/host/frontend-static/README.zh.md
@@ -16,4 +16,4 @@ Web 壳的 SPA dist 服务器：一个函数插件（配置为 `{distIndex}`）

 ## 已知限制与延期工作

- **初始 MIME 表很精简**：vite 输出集合以外的扩展名会回退到 `application/octet-stream`；实际发布新的资产类别时再扩展该表。
+- **初始 MIME 表很精简**：它覆盖 Vite 输出的资产集合及实际交付的 PWA manifest；其他扩展名在相应资产类别实际发布前都会回退到 `application/octet-stream`。
--- a/packages/host/frontend-static/src/index.ts
+++ b/packages/host/frontend-static/src/index.ts
@@ -41,6 +41,7 @@ const MIME: Record<string, string> = {
  '.svg': 'image/svg+xml',
  '.json': 'application/json',
  '.map': 'application/json',
+  '.webmanifest': 'application/manifest+json',
 }

 /**
--- a/packages/host/frontend-static/tests/frontend-static.spec.ts
+++ b/packages/host/frontend-static/tests/frontend-static.spec.ts
@@ -36,6 +36,7 @@ async function loadComposition(): Promise<Context> {
  await writeFile(distIndex, '<head></head><body>shell</body>')
  await writeFile(join(dist, 'app.js'), 'export {}')
  await writeFile(join(dist, 'blob.bin'), 'BLOB')
+  await writeFile(join(dist, 'manifest.webmanifest'), '{}')
  const configPath = join(root, 'cordis.yml')
  await writeFile(configPath, [
    "- name: '@deepseek-ai/dsh-host-webserver'",
@@ -92,8 +93,13 @@ describe('real Loader composition', () => {
    const server = loaded.httpServer
    const port = server.port

-    // Real asset with its MIME type; a live rebuild is served on the next read.
+    // Real assets with their MIME types; a live rebuild is served on the next read.
    expect(await request(port, '/app.js')).toMatchObject({ status: 200, type: 'text/javascript; charset=utf-8', body: 'export {}' })
+    expect(await request(port, '/manifest.webmanifest')).toMatchObject({
+      status: 200,
+      type: 'application/manifest+json',
+      body: '{}',
+    })
    await writeFile(join(root!, 'dist', 'app.js'), 'export const rebuilt = true')
    expect(await request(port, '/app.js')).toMatchObject({ status: 200, body: 'export const rebuilt = true' })