Merge codex/installable-product-subagents into codex/installable-codex-provider

.agents/notes/implemented/architecture/2026-08-10-product-subagent-providers-in-shared-host.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 .agents/notes/implemented/architecture/2026-08-10-product-subagent-providers-in-shared-host.md
-2026-08-10-product-subagent-providers-in-shared-host.md: 55aa9778ae15031da5eb9cc129c73c103297dac1
-2026-08-10-product-subagent-providers-in-shared-host.zh.md: a43a851daa3231acecba984dc2d950fd03088f7b
+2026-08-10-product-subagent-providers-in-shared-host.md: 196e28c1263c4b6d71eaeb59b9ba8457b36f3ff4
+2026-08-10-product-subagent-providers-in-shared-host.zh.md: b36398be50065dd1520fb97ca15416467c580bf2

.agents/notes/implemented/architecture/2026-08-10-product-subagent-providers-in-shared-host.md

@@ -6,34 +6,34 @@ English | [中文](2026-08-10-product-subagent-providers-in-shared-host.zh.md)
 
 ## Problem
 
-The [Codex and Claude Code provider contracts](../feature/2026-08-04-claude-code-and-codex-subagent-backends.md) are separate, directly installable Profile Bundle packages loaded beside the common subagent tool. Agent Presets are the ordinary owner of one agent's model-visible tools, but a preset cannot safely own either provider: `ctx.subagents` is a process registry, provider names are unique, and host consumers resolve the same registry across sessions. Bundle installation and Preset tool grants are therefore separate deployment and agent-authoring decisions.
+The [Codex and Claude Code provider contracts](../feature/2026-08-04-claude-code-and-codex-subagent-backends.md) were first shipped as independently installable packages that a deployment loaded beside the common subagent tool. Agent Presets later became the ordinary owner of one agent's model-visible tools, but a preset cannot safely own these product providers: `ctx.subagents` is a process registry, provider names are unique within the Host, and host consumers resolve the same registry across sessions. Repeated preset composition would therefore contend for the same configured names. Requiring a person to edit both a Profile and a Preset would also make a generic preset row incomplete by itself.
 
 The placement decision must preserve two independent facts. Loading a provider must not start or authenticate a product, while granting a tool must remain per preset so two sessions can expose different products. A global product switch, a provider instance per agent, or pre-enumerated combination presets would each create a second owner for one of those facts.
 
 ## Decision
 
-Each product Bundle loads its fixed provider exactly once in the shared Host plane. Loading either plugin only registers a dormant backend; the corresponding Codex or Claude process starts on the first actual delegation call. Agent Presets independently contribute ordinary `dsh-tool-subagent` rows for `subagent_codex` and `subagent_claude_code`, so a preset can grant neither tool, either one, or both without changing the provider registry. A tool whose provider Bundle is absent remains unavailable rather than mounting another provider in the Agent plane.
+Product providers remain process-scoped host-plane registrations. The [production-install exclusion decision](../simplification/2026-08-12-production-dsh-excludes-product-subagent-providers.md) supersedes only this note's former base-bundle installation choice: production `dsh-base` neither depends on nor mounts them. A Profile that opts in installs the selected provider Bundle; its patch mounts the default instance, and the Profile may mount additional named instances on the host plane. The [named-instance decision](../feature/2026-08-18-product-subagent-named-instances.md) owns each row's registry identity: both products accept multiple unique `providerName` values while preserving `codex` and `claude-code` as their defaults. Loading either plugin only registers a dormant backend; the corresponding Codex or Claude process starts on the first actual delegation call. Agent Presets independently contribute ordinary `dsh-tool-subagent` rows whose `provider` and `toolName` values expose exactly the configured instances needed by one agent without changing the Host registry.
 
-The [production-closure decision](../simplification/2026-08-12-production-dsh-excludes-product-subagent-providers.md) partially supersedes only this note's former default-inclusion choice: the base bundle excludes both providers, and each provider package owns its directly installable Bundle patch. This note continues to own process-wide Host placement whenever either provider is installed. The provider-contract note continues to own each product protocol, result mapping, cancellation, process-tree lifecycle, and evidence tiers. The [Agent Preset architecture](2026-08-03-per-session-agent-presets.md) continues to own the Host/Agent split, preset authoring, and the rule that edits affect only newly composed sessions.
+Each provider package owns its directly installable Bundle patch and private product runtime. This note continues to own process-wide Host placement whenever either provider is installed. The provider-contract note continues to own each product protocol, result mapping, cancellation, process-tree lifecycle, and evidence tiers. The [Agent Preset architecture](2026-08-03-per-session-agent-presets.md) continues to own the Host/Agent split, preset authoring, and the rule that edits affect only newly composed sessions.
 
-Each Bundle delegates executable selection to its package-owned product runtime: the Codex package runs its declared wrapper, while the Claude Code package lets its Agent SDK select the private native executable. Neither provider consults or falls back to a host product command, while native configuration and authentication remain authoritative. Profile loading creates no product state, probes no version or authentication, and may supply each mounted Provider's deployment configuration, including the product-specific `permissionMode` values owned by the [non-interactive permissions decision](../feature/2026-08-15-product-subagent-noninteractive-permissions.md), without moving those choices into an Agent Preset or model-facing tool. A missing platform payload, authentication failure, and other product failures remain local to the attempted delegation.
+Each Bundle delegates executable selection to its package-owned product runtime: the Codex package runs its declared wrapper, while the Claude Code package lets its pinned Agent SDK select the private native executable. Neither provider consults or falls back to a host product command. Profile loading creates no product state, probes no version or authentication, and may supply each mounted Provider instance's deployment configuration, including the product-specific `permissionMode` values owned by the [non-interactive permissions decision](../feature/2026-08-15-product-subagent-noninteractive-permissions.md), without moving those choices into an Agent Preset or model-facing tool. Missing platform payloads and product failures remain local to the attempted delegation.
 
 ## Verification
 
-Real composition loads no product Bundle, Codex only, Claude Code only, or both, then crosses that availability with Agent Presets that grant neither tool, either one, or both. It proves the Host registry and model-visible tools reflect those independent decisions, no product process starts during composition, and Preset edits affect only later Sessions. The linked provider and background decisions own private-runtime, failure, teardown, tool-schema, and Job evidence.
+The base bundle test proves production `dsh-base` contains neither product provider dependency nor provider row. The Web composition installs both optional Bundles and covers none, Codex-only, Claude-only, and both tool sets, including generation isolation after an authored preset changes. Package-owned Loader compositions prove each Bundle default and additional named instances register without starting a product process. Keyless ACP snapshots pin the Codex two-tool roster and the final four-tool combination, while provider tests separately prove private platform-payload selection without host fallback, configuration isolation, failure, cancellation, and process-tree quiescence.
 
 ## Alternatives considered
 
-**Keep both dormant providers in every base Profile.** This makes every matching Preset row immediately usable, but forces every production installation to carry both provider packages, the Claude Agent SDK, and its large platform CLI payload even when neither integration is wanted.
+**Keep product providers opt-in at the Profile layer.** This preserves a smaller default dependency closure but requires the user to edit both a Profile and a Preset. The production-install exclusion decision accepts that installation trade-off; this note retains the requirement that selected provider instances are mounted on the host plane rather than inside the preset.
 
 **Store global or per-Profile product enable switches.** A process switch competes with the Preset as owner of model-visible tools and cannot express two sessions using different combinations. Availability and authentication are deployment facts, not another persisted product state.
 
-**Mount a provider inside every Agent Preset.** Provider names belong to a process registry, so the second session would collide with the first. Host consumers also need the registry independently of any one agent's lifetime.
+**Mount providers inside every Agent Preset.** Provider names belong to a process registry, so repeated session composition would collide on the same configured names. Host consumers also need the registry independently of any one agent's lifetime.
 
 **Ship four product-combination presets.** Four identities duplicate complete compositions to represent two independent tool rows. Ordinary rows already express the full matrix without adding roster or maintenance state.
 
 ## Consequences
 
-A user installs only the product Bundles a Profile needs and manages model-visible grants through the same Agent Preset authoring path as other plugins. Each new Session receives the intersection of its preset's tool rows and the Host's installed providers. An installed but ungranted product remains dormant and consumes its package and module-loading footprint but no product process, login, model call, or product home; an uninstalled product contributes no provider or product-runtime closure.
+A user installs each selected product provider in a Profile, mounts the required named instances, and exposes their tools through the same Agent Preset authoring path as other plugins. Each new session receives exactly the tools its chosen preset contributes. Profiles that do not select a product provider carry no corresponding package or module-loading footprint; loading selected instances still starts no product process, login, model call, or product home.
 
 The Host registry remains the single provider authority, each Bundle remains the deployment availability authority, and each Preset remains the model-tool authority. This explicit two-gate lifecycle avoids a global enable switch and keeps package removal independent from per-session authoring.

.agents/notes/implemented/architecture/2026-08-10-product-subagent-providers-in-shared-host.zh.md

@@ -6,34 +6,34 @@ Status: implemented
 
 ## 问题
 
-[Codex 与 Claude Code 提供方约定](../feature/2026-08-04-claude-code-and-codex-subagent-backends.md)由两个可直接安装的独立 Profile Bundle 包实现，并在通用 subagent 工具旁加载。Agent Preset 是单个 agent（智能体）的模型可见工具的常规责任方，但 preset 不能安全地拥有任一产品提供方：`ctx.subagents` 是进程级注册表，提供方名称唯一，而宿主消费方会跨会话解析同一个注册表。因此，Bundle 安装与 Preset 工具授权分别属于部署决策和 agent 创作决策。
+[Codex 与 Claude Code 提供方约定](../feature/2026-08-04-claude-code-and-codex-subagent-backends.md)最初以可独立安装的包交付，由部署环境在通用 subagent 工具旁加载。Agent Preset 后来成为单个 agent（智能体）的模型可见工具的常规责任方，但 preset 不能安全地拥有这些产品提供方：`ctx.subagents` 是进程级注册表，提供方名称在 Host 内唯一，而宿主消费方会跨会话解析同一个注册表。因此，重复组装 preset 会争用同一组已配置名称。如果要求用户同时编辑 Profile 和 Preset，也会使通用 preset 配置项本身不完整。
 
 归属决策必须同时保留两个彼此独立的事实：加载提供方不得启动产品，也不得对产品执行身份验证；而工具授权仍须按 preset 决定，这样两个会话才能暴露不同的产品。全局产品开关、按 agent 创建提供方实例或预先枚举的组合 preset，都会为其中一个事实另设第二责任方。
 
 ## 决策
 
-每个产品 Bundle 都会在共享 Host 平面中恰好加载一次各自固定的提供方。加载任一插件只会注册一个休眠后端；对应的 Codex 或 Claude 进程直到第一次实际委派调用时才启动。Agent Preset 分别通过普通的 `dsh-tool-subagent` 行贡献 `subagent_codex` 与 `subagent_claude_code`，因此一个 preset 可以不授权任何工具、只授权其中一个或同时授权两者，而无需更改提供方注册表。若工具对应的提供方 Bundle 未安装，该工具仍不可用，而不会在 Agent 平面中另行挂载提供方。
+产品提供方仍是进程级的 host plane（宿主平面）注册。[生产安装排除决策](../simplification/2026-08-12-production-dsh-excludes-product-subagent-providers.md)只取代本说明原先由 base bundle 安装提供方的选择：生产 `dsh-base` 既不依赖也不挂载它们。选择产品集成的 Profile 会安装目标提供方 Bundle；其 patch 挂载默认实例，而 Profile 可以在 host plane 挂载更多命名实例。[命名实例决策](../feature/2026-08-18-product-subagent-named-instances.md)负责每个配置项的注册身份：两个产品都接受多个唯一的 `providerName`，同时保留 `codex` 与 `claude-code` 作为默认值。加载任一插件只会注册一个休眠后端；对应的 Codex 或 Claude 进程直到第一次实际委派调用时才启动。Agent Preset 通过普通 `dsh-tool-subagent` 配置项的 `provider` 与 `toolName` 准确公开单个 agent 所需的已配置实例，而无需更改 Host 注册表。
 
-[生产依赖闭包决策](../simplification/2026-08-12-production-dsh-excludes-product-subagent-providers.md)只部分取代本说明先前关于默认包含提供方的选择：base 组合包排除两个提供方，每个提供方包都拥有可直接安装的 Bundle patch。本说明继续负责每个已安装提供方的进程级 Host 放置。提供方约定说明继续负责每个产品的协议、结果映射、取消、进程树生命周期与证据层级。[Agent Preset 架构](2026-08-03-per-session-agent-presets.md)继续负责宿主与 agent 的划分、preset 创作，以及改动只影响新组装会话的规则。
+每个提供方包都拥有可直接安装的 Bundle patch 与私有产品运行时。本说明继续负责每个已安装提供方的进程级 Host 放置。提供方约定说明继续负责每个产品的协议、结果映射、取消、进程树生命周期与证据层级。[Agent Preset 架构](2026-08-03-per-session-agent-presets.md)继续负责宿主与 agent 的划分、preset 创作，以及改动只影响新组装会话的规则。
 
-每个 Bundle 都把可执行文件选择交给包自有的产品运行时：Codex 包运行自身声明的 wrapper，Claude Code 包则让 Agent SDK 选择私有原生可执行文件。两个提供方都不会查询或回退宿主产品命令，原生配置与身份验证仍保持权威。加载 Profile 不会创建产品状态、探测版本或测试身份验证；它可以提供每个已挂载 Provider 的部署配置，包括由[非交互权限决策](../feature/2026-08-15-product-subagent-noninteractive-permissions.md)负责的产品专属 `permissionMode` 值，但不会把这些选择移入 Agent Preset 或面向模型的工具。平台载荷缺失、身份验证失败和其他产品故障仍局限于发生问题的那次委派。
+每个 Bundle 都把可执行文件选择交给包自有的产品运行时：Codex 包运行自身声明的 wrapper，Claude Code 包则让锁定的 Agent SDK 选择私有原生可执行文件。两个提供方都不会查询或回退宿主产品命令。加载 Profile 不会创建产品状态、探测版本或测试身份验证；它可以提供每个已挂载 Provider 实例的部署配置，包括由[非交互权限决策](../feature/2026-08-15-product-subagent-noninteractive-permissions.md)负责的产品专属 `permissionMode` 值，但不会把这些选择移入 Agent Preset 或面向模型的工具。平台载荷缺失和产品故障仍局限于发生问题的那次委派。
 
 ## 验证
 
-真实组装会覆盖未安装产品 Bundle、仅安装 Codex、仅安装 Claude Code 或两者都安装四种状态，再与不授权工具、只授权其中一个或同时授权两者的 Agent Preset 交叉。测试证明 Host 注册表与模型可见工具会反映这两个独立决策，组装期间不会启动产品进程，而且 Preset 编辑只影响后续 Session。已链接的提供方与后台执行决策分别拥有私有运行时、失败、清理、工具 schema 及 Job 证据。
+base bundle 测试证明生产 `dsh-base` 既不包含产品提供方依赖，也不包含提供方配置项。Web 组装会安装两个可选 Bundle，并覆盖不暴露任何工具、仅暴露 Codex、仅暴露 Claude 和同时暴露两者这四种工具集合，也覆盖自行创作的 preset 发生改动后的代际隔离。由包负责的 Loader 组装证明每个 Bundle 默认实例与额外命名实例都会完成注册，而不会启动产品进程。无密钥 ACP（Agent Client Protocol）快照固定 Codex 双工具集合与最终四工具组合，提供方测试则另行证明私有平台载荷选择与无宿主回退、配置隔离、失败、取消和进程树完全停稳。
 
 ## 考虑过的替代方案
 
-**在每个 base Profile 中保留两个休眠提供方。** 这样每条匹配的 Preset 行都能立即使用，但即使用户不需要任一集成，每次生产安装仍会携带两个提供方包、Claude Agent SDK 及其大型平台 CLI 载荷。
+**将产品提供方保留为 Profile 层的按需启用项。** 这样可缩小默认依赖闭包，但要求用户同时编辑 Profile 与 Preset。生产安装排除决策接受这项安装取舍；本说明保留的要求是，任何被选中的提供方实例都在 host plane 挂载，而不是放入 preset。
 
 **存储全局或按 Profile 配置的产品启用开关。** 进程级开关会与 Preset 争夺模型可见工具的责任归属，也无法表示两个会话使用不同组合。可用性与身份验证属于部署事实，并非另一份需要持久化的产品状态。
 
-**在每个 Agent Preset 内挂载一个提供方。** 提供方名称属于进程级注册表，因此第二个会话会与第一个冲突。宿主消费方也需要独立于任何单个 agent 的生命周期使用该注册表。
+**在每个 Agent Preset 内挂载提供方。** 提供方名称属于进程级注册表，因此重复组装会话会在同一组已配置名称上发生冲突。宿主消费方也需要独立于任何单个 agent 的生命周期使用该注册表。
 
 **交付四个产品组合 preset。** 四个身份会复制完整组装，只为表示两条独立的工具行。普通行已经能表达完整矩阵，无需新增名单或维护状态。
 
 ## 后果
 
-用户只安装 Profile 所需的产品 Bundle，并通过与其他插件相同的 Agent Preset 创作路径管理模型可见授权。每个新 Session 会获得其 preset 工具行与 Host 已安装提供方的交集。已安装但未授权的产品保持休眠，会产生包和模块加载开销，但不会启动产品进程、登录、调用模型或创建产品主目录；未安装的产品不会进入提供方或产品运行时闭包。
+用户在 Profile 中安装每个被选中的产品提供方，挂载所需命名实例，再通过与其他插件相同的 Agent Preset 创作路径公开这些实例的工具。每个新会话只会获得其所选 preset 所贡献的工具。没有选择产品提供方的 Profile 不承担对应包或模块的加载开销；加载已选择的实例仍不会启动产品进程、登录、调用模型或创建产品主目录。
 
 Host 注册表仍是提供方的唯一权威，每个 Bundle 仍是部署可用性的权威，每个 Preset 仍是模型工具的权威。这个显式的双门生命周期避免全局启用开关，并让包移除与按会话创作保持独立。

.agents/notes/implemented/architecture/2026-08-12-plugin-owned-settings-surface.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 .agents/notes/implemented/architecture/2026-08-12-plugin-owned-settings-surface.md
-2026-08-12-plugin-owned-settings-surface.md: 3137cfe81ef3cb78a940f085c559ab4a7b62cce3
-2026-08-12-plugin-owned-settings-surface.zh.md: 8dd5e5ccebf1cfb80b55a615f6049dd391943bd7
+2026-08-12-plugin-owned-settings-surface.md: 722e6cfbe890418e8305f89790e76976027d7775
+2026-08-12-plugin-owned-settings-surface.zh.md: 93e5227d5f6a629fd32f5a2fe22e9882c7f7c5ac

.agents/notes/implemented/architecture/2026-08-12-plugin-owned-settings-surface.md

@@ -22,7 +22,7 @@ Together the two meant a user-authored plugin was configurable only by hand-edit
 
 **`settings.plugin.item` is keyed on the settings namespace.** The slot moved from `list` to `keyed`, the key being the namespace the card edits, following the `tool.call.toolview` precedent where each tool plugin registers its renderer under the tool name. A card declares `key`, not `id`/`order`. The slot is declared by the Plugins section's `configurable` tab, which owns the card list.
 
-**The tab drives dispatch from the served namespaces.** It reads `settings.describe` once, subscribes to the settings-document invalidation and to connection resets, and dispatches one key per served namespace. What renders is the intersection of two ledgers — namespaces a live Host plugin registered, and cards registered under those keys — computed in the tab's controller from the slot ledger (`ctx.slots.entries`, `ctx.slots.subscribe`) and the wire answer.
+**The tab drives dispatch from the served namespaces.** It derives the current served set from `ctx.settingsScope.describe()` and follows that shared settings mirror, while its own listener follows the card slot ledger. It dispatches one key per served namespace. What renders is the intersection of two ledgers — namespaces a live Host plugin registered, and cards registered under those keys — computed in the tab's controller from the slot ledger (`ctx.slots.entries`, `ctx.slots.subscribe`) and the mirror answer. The later [settings describe mirror decision](2026-08-17-settings-describe-mirror.md) owns the browser-wide read and invalidation lifecycle.
 
 Keying makes absence the signal, and that is what removes the bookkeeping the previous shape needed. A namespace another surface owns (`ui-theme`, `permission`, `llm-*`, `agent-presets`) has no card under its key, so it renders nothing without declaring anything anywhere. A card whose namespace this deployment does not serve is never dispatched, which also fixes the old empty-state defect: the tab counted registered cards, including ones rendering nothing, so a deployment exposing none showed an empty list instead of its empty line.
 
@@ -56,6 +56,6 @@ A plugin distributed outside this repository is configurable from the settings p
 
 Deferred, and larger than this change: the redactor returns a `role('secret')` reachable only through a union, intersection, or transform verbatim (its own `TODO(settings-wire-redaction)`), and `schema.toJSON()` carries a secret's default. That gap predates this change, but serving every registered namespace widens its blast radius from schemas audited in this repository to any third-party schema, so the wire should refuse a namespace it cannot prove it can redact. Also deferred: an assembled-composition test of the headline capability — an overlay-mounted fixture plugin whose Host half registers a namespace and whose `dsh.client` half registers a card, asserted end-to-end. The current coverage proves each half separately; the shipped cards' unchanged output cannot prove the new path.
 
-The wire read the section adds is one `settings.describe` beside the per-scope reads the cards already make. Its invalidation is imprecise in one direction: the wire announces document commits and connection resets, not registrations, so a namespace registered after the section's read joins on the next commit or reconnect.
+The section and its cards add no `settings.describe` reads: both derive from the browser-wide mirror. Its invalidation is imprecise in one direction: the wire announces document commits and connection resets, not registrations, so a namespace registered after the mirror's current answer joins on the next commit or reconnect.
 
 Two frictions remain for an author outside this repository, both recorded in the section's README. The browser half must be a `dsh.client` package built in the client module system's lazy-CJS factory format, and the `clientBundle` preset that emits it lives in `packages/client/tsdown.client.ts` rather than a published package. The bundle-purity gate forbids importing this package's card chrome or staged-form model as values, so such a card reimplements staging and revision fencing. Sharing them would mean either publishing the preset or declaring a child slot inside the card so the section supplies the chrome; neither is built.

.agents/notes/implemented/architecture/2026-08-12-plugin-owned-settings-surface.zh.md

@@ -22,7 +22,7 @@ Status: implemented
 
 **`settings.plugin.item` 以 settings 命名空间为键。** 该 slot 从 `list` 改为 `keyed`，键就是卡片所编辑的命名空间，沿用 `tool.call.toolview` 的先例——每个工具插件把自己的渲染器注册在工具名这个键上。卡片声明 `key`，不再声明 `id`/`order`。该 slot 由「插件」分区的 `configurable` 标签页声明，卡片列表归它所有。
 
-**标签页以被服务的命名空间驱动派发。** 它读取一次 `settings.describe`，订阅 settings 文档失效通知与连接重置，并为每个被服务的命名空间派发一个键。渲染出来的是两份账本的交集——存活 Host 插件注册的命名空间，以及注册在这些键上的卡片——由标签页的 controller 从 slot 账本（`ctx.slots.entries`、`ctx.slots.subscribe`）与协议答复算出。
+**标签页以被服务的命名空间驱动派发。** 它从 `ctx.settingsScope.describe()` 派生当前被服务的集合并跟随该共享 settings 镜像，自身的监听器只跟随卡片 slot 账本；随后为每个被服务的命名空间派发一个键。渲染出来的是两份账本的交集——存活 Host 插件注册的命名空间，以及注册在这些键上的卡片——由标签页的 controller 从 slot 账本（`ctx.slots.entries`、`ctx.slots.subscribe`）与镜像应答算出。后续的 [settings describe 镜像决策](2026-08-17-settings-describe-mirror.md)持有浏览器全局的读取与失效生命周期。
 
 以命名空间为键，让「缺席」本身成为信号，而这正是它消掉旧形态所需簿记的原因。归别的界面所有的命名空间（`ui-theme`、`permission`、`llm-*`、`agent-presets`）在其键上没有卡片，于是什么都不渲染，且无需在任何地方声明任何东西。命名空间未被本部署服务的卡片根本不会被派发，这同时修掉了旧的空态缺陷：标签页数的是已注册卡片，其中包含那些什么都不渲染的，因此一个都不暴露的部署看到的是空列表，而不是它那行空态文案。
 
@@ -56,6 +56,6 @@ Status: implemented
 
 以下延后，且都大于本次改动：脱敏器对只能经由 union、intersection 或 transform 抵达的 `role('secret')` 原样返回（其自身的 `TODO(settings-wire-redaction)`），而 `schema.toJSON()` 会携带 secret 的默认值。该缺口早于本次改动，但服务每一个已注册命名空间，把它的影响面从本仓库内经审计的 schema 扩大到任意第三方 schema，因此协议应当拒绝服务它无法证明可安全脱敏的命名空间。同样延后的还有：对本次头号能力的组装态测试——用 overlay 挂载一个 fixture 插件（Host 半注册命名空间、`dsh.client` 半注册卡片）并在端到端断言。当前覆盖分别证明了两个半侧；已发卡片输出未变这一点，证明不了新路径。
 
-分区新增的协议读取是一次 `settings.describe`，与卡片各自已有的 per-scope 读取并列。它的失效通知在一个方向上不精确：协议通告的是文档提交与连接重置，而非注册行为，因此在分区读取之后才被注册的命名空间，要等下一次提交或重连才会加入。
+分区与其中的卡片都不再新增 `settings.describe` 读取：两者都从浏览器全局的镜像派生。它的失效通知在一个方向上不精确：协议通告的是文档提交与连接重置，而非注册行为，因此在镜像当前应答之后才被注册的命名空间，要等下一次提交或重连才会加入。
 
 对仓库之外的作者仍留有两处摩擦，均记在该分区的 README 里。浏览器半侧必须是按客户端模块系统的 lazy-CJS factory 格式构建的 `dsh.client` 包，而产出它的 `clientBundle` 预设位于 `packages/client/tsdown.client.ts`，并非已发布的包。bundle 纯净度门禁禁止以值的形式导入本包的卡片外观与暂存表单模型，因此这样的卡片要重新实现暂存与 revision 设栅。要共享它们，要么发布该预设，要么在卡片内部声明一层子 slot 让分区提供外观；两者都尚未构建。

.agents/notes/implemented/architecture/2026-08-17-settings-describe-mirror.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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 .agents/notes/implemented/architecture/2026-08-17-settings-describe-mirror.md
+2026-08-17-settings-describe-mirror.md: a3774699ff328a44aed192a16dea0fa19d03c83c
+2026-08-17-settings-describe-mirror.zh.md: c57f5630b4bee0cd77a29a6f5458cb439c7f0585

.agents/notes/implemented/architecture/2026-08-17-settings-describe-mirror.md

@@ -0,0 +1,34 @@
+# Agent Note: Settings describe mirror
+
+Status: implemented
+
+English | [中文](2026-08-17-settings-describe-mirror.zh.md)
+
+## Problem
+
+A cold web boot issued `settings.describe` fifteen times inside ~200ms, and the count grew by two with every client plugin that owned a preference. Two mechanisms stacked: `SettingsScopeBinder.bind()` started a full-document read per bound scope (six scopes in the product composition, plus the plugin-directory tab, the welcome gate, and the models onboarding join), and `onConnected` emits `connection/reset` on the FIRST connection too, so every one of those readers immediately re-read the answer it had fetched milliseconds earlier. Each reader also carried its own invalidation subscriptions and its own `refreshIfLoaded`-style guard, and fifteen independent reads could in principle land on fifteen different document revisions.
+
+## Decision
+
+**One reader, many derivations.** `dsh-client-ui-settings` owns `SettingsDescribeMirror`, the single `settings.describe` reader in the browser: one snapshot store holding the whole answer, refreshed by the owning plugin's two subscriptions (`settings/document-updated`, `connection/reset`). Concurrent `load()` calls fold into the in-flight read plus at most one rerun. The in-flight slot owns a run before its loading publication can synchronously reenter `load()`, then clears inside the run's own try/finally in the same synchronous segment that observes the rerun flag; a `.finally()` on the returned promise would run one microtask later and let a refresh landing in that gap mark a rerun nobody reads.
+
+`bind()` still returns the unchanged `SettingsScope<T>` face, but the controller is now a selector over the mirror: no read path of its own, the same decode rules, and the write queue kept. A committed write folds its answered view back into the mirror (`acceptView`), so sibling scopes see the new revision with no re-read; the fold invalidates any older in-flight answer, and a write before the first held document reruns that read instead of publishing a partial document. A failed latest write triggers one mirror recovery read. Cross-namespace surfaces — the plugin-directory tab, the permission row (its dynamic enum lives in the namespace schema, which scopes deliberately do not carry), the models join, the agent-preset row's writability, and `hasDocument` — consume `ctx.settingsScope.describe()`, the shared read/fold face (`getSnapshot`/`subscribe`/`ensure`/`acceptView`).
+
+This decision updates the browser read and invalidation mechanics recorded by [Host-backed Web preferences](../bug-fix/2026-08-06-host-backed-web-preferences.md) and [plugin-owned settings surface](2026-08-12-plugin-owned-settings-surface.md), while preserving their preference-ownership and namespace-exposure decisions. It also replaces the direct settings-read description in [official DeepSeek first-run credential setup](../feature/2026-07-30-deepseek-onboarding-credential-setup.md); that join now derives its settings half from this mirror.
+
+The cold-boot budget is pinned at two reads by `apps/web/tests/startup-rpc-budget.e2e.ts`: the mirror's eager bind-time read, plus the first-connection reset read, which is kept deliberately — it closes the window where a document commit lands between the eager HTTP read and the SSE subscription and its invalidation is lost. The plan's original target of one read is unreachable without either accepting that lost-invalidation window or delaying the first read until after the SSE stream opens.
+
+## Alternatives considered
+
+- **Single-flight sharing inside `bind()` only** — deduplicates the concurrent bursts but keeps N direct readers, N subscription sets, and the revision skew; readers outside the binder (welcome, models, tab, permission) gain nothing. Rejected as treating the symptom.
+- **Boot-payload embedding** (host inlines the describe answer into the page boot) — saves the first read but adds a second acquisition path with its own staleness rules on top of the mirror it would still need. Deferred; it composes with the mirror if ever wanted.
+- **Per-namespace `settings.describe(ns)`** — shrinks each answer but keeps one read per consumer, so the fan-out and the growth rate stay. Rejected.
+- **One read (no first-reset re-read)** — reachable only by accepting the lost-invalidation window between the eager HTTP read and the SSE subscription, or by delaying the first read until the stream opens; both trade correctness or first-paint freshness for one loopback request. Rejected in favor of the pinned two.
+
+## Consequences
+
+- Startup `settings.describe` went 15 → 2, and a new preference-owning plugin adds zero reads.
+- Every derived surface shows the same document revision at any moment; the per-reader guards (`refreshWelcomeIfLoaded`, `refreshPermissionIfLoaded`, `refreshDocumentIfLoaded`) and their subscriptions are gone.
+- The mirror refreshes on every document commit regardless of namespace, so an external settings edit now costs one background read even while no settings surface is open — the price of surfaces that open already fresh. The per-namespace `ns !== spec.namespace` filters are gone with the per-scope subscriptions.
+- `credentials.describe` (3 startup calls), `agentPreset.list` (2), and `llm.providers` are separate sources and stay direct; the same mirror pattern fits them if they ever need it.
+- A new direct `settings.describe` caller in client code is a budget regression; the e2e's failure message says to grep for callers outside `ui-settings`.

.agents/notes/implemented/architecture/2026-08-17-settings-describe-mirror.zh.md

@@ -0,0 +1,34 @@
+# Agent Note：Settings describe 镜像
+
+Status: implemented
+
+[English](2026-08-17-settings-describe-mirror.md) | 中文
+
+## 问题
+
+一次冷启动的 web boot 在约 200ms 内发出十五次 `settings.describe`，且每新增一个持有偏好设置的客户端插件，该计数再加二。两个机制叠加：`SettingsScopeBinder.bind()` 为每个绑定的 scope 启动一次全量文档读取（产品组合中有六个 scope，外加插件目录 tab、welcome 门与 models onboarding join），而 `onConnected` 在**首次**连接时同样发出 `connection/reset`，于是上述每个读取方都立即重读了几毫秒前刚取到的应答。每个读取方还各自持有失效订阅与各自的 `refreshIfLoaded` 式防护，且十五次独立读取原则上可能落在十五个不同的文档 revision 上。
+
+## 决定
+
+**一个读取方，多个派生面。**`dsh-client-ui-settings` 持有 `SettingsDescribeMirror`——浏览器中唯一的 `settings.describe` 读取方：一个持有完整应答的快照 store，由所属插件的两个订阅（`settings/document-updated`、`connection/reset`）负责刷新。并发的 `load()` 调用折叠进在飞读取加至多一次尾随重读。在飞槽位会在 loading 发布同步重入 `load()` 之前先取得 run 的所有权，随后在 run 自身 try/finally 内、与读取 rerun 标志相同的同步段中清空；若把清理挂在返回 promise 的 `.finally()` 上，它要晚一个微任务执行，落入该间隙的刷新会标记一个无人读取的 rerun。
+
+`bind()` 返回的 `SettingsScope<T>` 面保持不变，但 controller 现在是镜像上的 selector：自身没有读路径，decode 规则不变，写队列保留。提交成功的写入把应答的 view 折回镜像（`acceptView`），兄弟 scope 无需重读即可看到新 revision；这次折叠会废弃更早发出的在飞应答，而首次完整文档尚未建立时到达的写入会让该读取重跑，不会把单个 namespace 发布成残缺文档。失败的最新写入触发一次镜像恢复读取。跨命名空间的表面——插件目录 tab、permission 行（其动态枚举位于命名空间 schema 中，而 scope 有意不携带 schema）、models join、agent-preset 行的可写性、以及 `hasDocument`——消费 `ctx.settingsScope.describe()` 提供的共享读／折叠面（`getSnapshot`／`subscribe`／`ensure`／`acceptView`）。
+
+本决策更新了[通过 Host settings 持久化 Web 用户偏好](../bug-fix/2026-08-06-host-backed-web-preferences.md)和[由插件自己拥有的设置表层](2026-08-12-plugin-owned-settings-surface.md)所记录的浏览器读取与失效机制，同时保留其中关于偏好所有权与命名空间暴露的决策。它也取代了 [DeepSeek 官方首次使用凭据配置](../feature/2026-07-30-deepseek-onboarding-credential-setup.md)中的设置直读描述；该联接的 settings 部分现在从本镜像派生。
+
+冷启动预算由 `apps/web/tests/startup-rpc-budget.e2e.ts` 钉在两次读取：镜像在绑定时的急切读取，加上首连 reset 触发的读取——后者是有意保留的：它关闭了「文档提交落在急切 HTTP 读取与 SSE 订阅之间、其失效通知丢失」的窗口。方案最初的一次读取目标，若不接受该失效丢失窗口、或不把首次读取推迟到 SSE 流建立之后，无法达成。
+
+## 考虑过的备选
+
+- **仅在 `bind()` 内做 single-flight 共享**——能去重并发风暴，但仍保留 N 个直连读取方、N 套订阅以及 revision 偏差；binder 之外的读取方（welcome、models、tab、permission）毫无受益。以治标为由否决。
+- **boot 载荷内嵌**（宿主把 describe 应答内联进页面 boot）——省下首次读取，却在镜像仍然需要的前提下增加第二条带自身陈旧规则的取数路径。推迟；若将来需要，它可与镜像叠加。
+- **按命名空间的 `settings.describe(ns)`**——缩小单次应答，但每个消费者仍各读一次，扇出与增长率原样保留。否决。
+- **一次读取（去掉首连 reset 重读）**——只有接受「急切 HTTP 读取与 SSE 订阅之间的失效丢失窗口」、或把首次读取推迟到流建立之后才可达成；两者都在用正确性或首屏新鲜度换一次环回请求。否决，保留钉住的两次。
+
+## 后果
+
+- 启动期 `settings.describe` 从 15 次降到 2 次，新增持有偏好设置的插件带来零次新增读取。
+- 任一时刻每个派生面看到的都是同一份文档 revision；各读取方的防护（`refreshWelcomeIfLoaded`、`refreshPermissionIfLoaded`、`refreshDocumentIfLoaded`）及其订阅随之消失。
+- 镜像对任何命名空间的文档提交都会刷新，因此在没有任何设置表面打开时，一次外部设置编辑现在也花费一次后台读取——这是「表面打开即新鲜」的代价。随着各 scope 订阅的删除，按命名空间的 `ns !== spec.namespace` 过滤一并消失。
+- `credentials.describe`（启动 3 次）、`agentPreset.list`（2 次）与 `llm.providers` 是另外的数据源，保持直连；若将来需要，同一镜像模式对它们同样适用。
+- 客户端代码中新增直连 `settings.describe` 调用即是预算回归；e2e 的失败信息会提示在 `ui-settings` 之外 grep 调用方。

.agents/notes/implemented/bug-fix/2026-08-06-host-backed-web-preferences.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 .agents/notes/implemented/bug-fix/2026-08-06-host-backed-web-preferences.md
-2026-08-06-host-backed-web-preferences.md: 5d90f2be7c8b4030e9bdc00eed2769491ec009e5
-2026-08-06-host-backed-web-preferences.zh.md: c861c45bff299e06841165a2b36d0781e8f54d99
+2026-08-06-host-backed-web-preferences.md: 2e33d05417bf6c347a57b5c0b6c7281ff1392b5b
+2026-08-06-host-backed-web-preferences.zh.md: 1d3518bb33d334d89408916a5f5210a45b938a01

.agents/notes/implemented/bug-fix/2026-08-06-host-backed-web-preferences.md

@@ -12,9 +12,9 @@ The first theme implementation moved only Appearance to Host settings but awaite
 
 ## Decision
 
-The owning Host halves register three schemas: optional `locale.preference` (`zh` or `en`, where absence delegates to the browser), `ui-theme.preference` (`light`, `dark`, or `system`, default `system`), and `ui-conversation.busyEnter` (`queue` or `steer`, default `queue`). The local settings provider stores explicit choices in `$DSH_HOME/settings.yaml`, which resolves to `~/.dsh/settings.yaml` under the default home. The API proxy explicitly exposes all three namespaces beside the other Web settings; registration alone never crosses that configuration boundary.
+The owning Host halves register three schemas: optional `locale.preference` (`zh` or `en`, where absence delegates to the browser), `ui-theme.preference` (`light`, `dark`, or `system`, default `system`), and `ui-conversation.busyEnter` (`queue` or `steer`, default `queue`). The local settings provider stores explicit choices in `$DSH_HOME/settings.yaml`, which resolves to `~/.dsh/settings.yaml` under the default home. The API proxy serves every registered namespace to a loopback client; field roles still redact secrets.
 
-`dsh-client-ui-settings` provides `ctx.settingsScope.bind(spec)`, which owns one lifecycle per namespace as the browser mirror of the Host-side settings owner seam. It installs `settings/document-updated` and `connection/reset` listeners before starting a background initial read, so no settings transport can block plugin activation and an invalidation cannot fall into a read-before-subscribe gap, and it publishes a snapshot store (status, section value, revision, writability, host/memory mode) the domain service subscribes to. The default decoder validates each incoming section against the namespace's own serialized wire schema, rehydrated through the colocated `ctx.settingsSchema` service, so domains carry no hand-written wire guards. Domain services take the scope as an ordinary constructor collaborator, publish their provisional defaults immediately—browser-derived locale, system theme, and Queue—then adopt an accepted Host section without writing it back; a service constructed without a scope (standalone dictionary or policy fixtures) simply stays process-local.
+`dsh-client-ui-settings` owns one browser-wide settings describe mirror and provides `ctx.settingsScope.bind(spec)` as a per-namespace selector over it. The mirror installs `settings/document-updated` and `connection/reset` listeners before starting its background read, so no settings transport can block plugin activation and an invalidation cannot fall into a read-before-subscribe gap. Each bound scope publishes a snapshot store (status, section value, revision, writability, host/memory mode) the domain service subscribes to, without adding a wire read or listener of its own. The default decoder validates each incoming section against the namespace's own serialized wire schema, rehydrated through the colocated `ctx.settingsSchema` service, so domains carry no hand-written wire guards. Domain services take the scope as an ordinary constructor collaborator, publish their provisional defaults immediately—browser-derived locale, system theme, and Queue—then adopt an accepted Host section without writing it back; a service constructed without a scope (standalone dictionary or policy fixtures) simply stays process-local. The shared read and invalidation lifecycle is specified by the later [settings describe mirror decision](../architecture/2026-08-17-settings-describe-mirror.md).
 
 User changes update the live service synchronously and queue a `settings.mutate` path operation through `scope.set`. The scope serializes gestures, sends the latest known namespace revision as `expectedRevision`, records every successful revision, and lets only the latest write settlement republish live state. A rejected or failed latest write reloads Host state. Disposal rejects new work, skips queued operations, suppresses publication by the in-flight operation, and waits for that operation to settle before the plugin reaches quiescence.
 

.agents/notes/implemented/bug-fix/2026-08-06-host-backed-web-preferences.zh.md

@@ -12,9 +12,9 @@ Web 的 Appearance、Language 和繁忙态 Enter 偏好原本存在浏览器 `lo
 
 ## 决策
 
-各领域所属的 Host half 注册三份 schema：可选的 `locale.preference`（`zh` 或 `en`，缺失时交由浏览器决定）、`ui-theme.preference`（`light`、`dark` 或 `system`，默认为 `system`），以及 `ui-conversation.busyEnter`（`queue` 或 `steer`，默认为 `queue`）。本地 settings 提供方将显式选择存入 `$DSH_HOME/settings.yaml`，在使用默认 home 时，该路径解析为 `~/.dsh/settings.yaml`。API 代理会显式暴露这三个 namespace，与其他 Web settings 并列；仅注册它们，绝不会跨越该配置边界。
+各领域所属的 Host half 注册三份 schema：可选的 `locale.preference`（`zh` 或 `en`，缺失时交由浏览器决定）、`ui-theme.preference`（`light`、`dark` 或 `system`，默认为 `system`），以及 `ui-conversation.busyEnter`（`queue` 或 `steer`，默认为 `queue`）。本地 settings 提供方将显式选择存入 `$DSH_HOME/settings.yaml`，在使用默认 home 时，该路径解析为 `~/.dsh/settings.yaml`。API 代理会向回环客户端服务每一个已注册的 namespace；字段角色仍会脱敏机密值。
 
-`dsh-client-ui-settings` 提供 `ctx.settingsScope.bind(spec)`，为每个 namespace 持有一份生命周期，作为 Host 侧 settings owner seam 的浏览器镜像。它在开始后台初始读取之前安装 `settings/document-updated` 和 `connection/reset` 监听器，因此任何 settings 传输都不会阻塞插件激活，失效通知也不会掉入先读取、后订阅的空档；它还会发布一个供领域服务订阅的快照 store（状态、分节值、revision、可写性、host／内存模式）。默认解码器会对照该 namespace 自身的序列化 wire schema（经同包的 `ctx.settingsSchema` 服务还原）校验每个传入分节，因此各领域无需携带手写的 wire 校验器。领域服务把 scope 当作普通的构造函数协作者接收，立即发布各自的暂定默认值：由浏览器派生的 locale、系统主题和 Queue；随后采纳已获接受的 Host 分节，但不将其写回；不带 scope 构造的服务——独立词典或政策 fixture（测试前置数据）——则仅停留在进程本地。
+`dsh-client-ui-settings` 持有一个浏览器全局的 settings describe 镜像，并提供 `ctx.settingsScope.bind(spec)` 作为该镜像上的逐 namespace selector。镜像在开始后台读取之前安装 `settings/document-updated` 和 `connection/reset` 监听器，因此任何 settings 传输都不会阻塞插件激活，失效通知也不会掉入先读取、后订阅的空档。每个绑定的 scope 会发布一个供领域服务订阅的快照 store（状态、分节值、revision、可写性、host／内存模式），自身不再增加协议读取或监听器。默认解码器会对照该 namespace 自身的序列化 wire schema（经同包的 `ctx.settingsSchema` 服务还原）校验每个传入分节，因此各领域无需携带手写的 wire 校验器。领域服务把 scope 当作普通的构造函数协作者接收，立即发布各自的暂定默认值：由浏览器派生的 locale、系统主题和 Queue；随后采纳已获接受的 Host 分节，但不将其写回；不带 scope 构造的服务——独立词典或政策 fixture（测试前置数据）——则仅停留在进程本地。共享读取与失效生命周期由后续的 [settings describe 镜像决策](../architecture/2026-08-17-settings-describe-mirror.md)规定。
 
 用户变更会同步更新实时服务，并经 `scope.set` 将一项 `settings.mutate` 路径操作排入队列。scope 会串行处理手势，以最新已知 namespace revision 作为 `expectedRevision` 发送，记录每次成功写入的 revision，并且只允许最新写入的结算结果重新发布实时状态。最新写入被拒或失败时，scope 会重新加载 Host 状态。插件释放会拒绝新工作、跳过已排队操作、抑制运行中操作发布状态，并等待该操作结算后才让插件达到完全停稳。
 

.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.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 .agents/notes/implemented/feature/2026-07-24-provider-retry-policies.md
-2026-07-24-provider-retry-policies.md: 1831ce6b96178d11e7c9927ceccbe07ea578cd2c
-2026-07-24-provider-retry-policies.zh.md: 22f18badcb47e4ce086ff2c68c7011612b2eabba
+2026-07-24-provider-retry-policies.md: 96979b219aebece96a1bcc09aa3dd572d2b9222d
+2026-07-24-provider-retry-policies.zh.md: 02fe13e0ddead035ec750c027e889da08e2557ae

.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.md

@@ -12,7 +12,7 @@ Provider policy must follow the request that actually failed, including a route
 
 ## Decision
 
-Each concrete adapter accepts an optional `retryPolicy` inside its provider configuration. The adapter validates and resolves the policy, and `ctx.llm` captures it when that exact provider route registers. When a call enters its final adapter boundary, `ctx.llm` binds the serving registration's immutable policy to that call; the agent loop passes it to closed-step recovery even if the route is disposed or replaced while the request is in flight. `@deepseek-ai/dsh-llm-retry` combines that call-local policy with the failed step's durable provider identity. A call that never reaches a final adapter has no serving policy and delegates. A provider without `retryPolicy` uses the normal defaults.
+Each concrete adapter accepts an optional `retryPolicy` inside its provider configuration, validates and resolves it, and exposes that resolved route policy through `providerRetryPolicy()`. Omission selects the shared core normal default of five retries for every composition, including Web, headless, and custom profiles. The effective policy remains route-owned registration state rather than a retry-executor setting. Layered settings may retain normal-only `maxRetries` or `retryableCodes` after changing `mode` to `always`; the resolver ignores those inactive fields while still rejecting unknown keys, and the registered always policy omits them. When a call enters its final adapter boundary, `ctx.llm` binds the serving registration's immutable policy to that call; the agent loop passes it to closed-step recovery even if the route is disposed or replaced while the request is in flight. `@deepseek-ai/dsh-llm-retry` combines that call-local policy with the failed step's durable provider identity. A call that never reaches a final adapter has no serving policy and delegates.
 
 ```yaml
 providers:
@@ -44,22 +44,28 @@ Each scheduled retry appends a non-surface `llm/retry` event with the failed pro
 
 ## Alternatives considered
 
-**One global `always` switch** — rejected because it cannot isolate the unbounded cost and latency risk to the provider that needs it and can silently apply after runtime rerouting.
+**One retry-executor-level `always` switch** — rejected because it cannot isolate the unbounded cost and latency risk to the provider that needs it and can silently apply after runtime rerouting. Provider route policies remain authoritative, and the effective policy is captured only after routing selects a registration.
 
 **A separate exact-provider list on `dsh-llm-retry`** — rejected because it duplicates provider route names outside their owning adapter configuration and lets provider registration drift from recovery policy.
 
 **A very large finite retry count** — rejected because it eventually violates the requested keep-retrying contract and serializes an arbitrary operational limit as if it were meaningful.
 
+**Adapter-specific omission defaults** — rejected because a shared budget would have to be repeated by every adapter family and every future adapter, making equivalent model routes behave differently depending on their implementation.
+
+**An LLM deployment-level default** — rejected because it introduces another configuration layer only to make Web differ from other compositions. The product default is uniform, while provider settings retain the existing per-route override.
+
+**Stamp five retries into profiles when the Web UI writes them** — rejected because existing profiles, settings written outside that UI, and non-Web compositions would retain the old value.
+
 **Provider-SDK retries** — rejected because hidden attempts multiply agent-level budgets, cannot use the closed-step durability boundary, and may splice or discard streamed output without a reconstructable retry record.
 
 **Put the error into model context** — rejected because a transport or provider diagnostic is operational state, not conversation content. It can expose sensitive provider details and changes the retried request instead of repeating the failed request.
 
 ## Verification
 
-Adapter tests validate nested policies at provider load, prove registration captures configured and default policies, and retain the serving policy across in-flight route replacement. Unit tests select policies from the failed request's serving registration, separate provider and changed-policy histories, exercise always mode beyond the normal budget, pin jitter and delay caps, prove downstream recovery ordering, prove cancellation and disposal drain delegated recovery before reaching quiescence, and prove both abort active backoff waits. Request-level coverage compares the complete messages of failed and retried attempts and rejects both provider error text and discarded partial output. A keyless headless `stream-json` snapshot runs failure, retry, and success through the assembled app, pins the complete `llm/retry` record, and rejects any model-message change between attempts. JSONL and SQLite tests round-trip an always event without `Infinity`; invariant tests bind provider identity to the request header, validate failure and mode-specific timer bounds, and bind retry numbers to provider-policy keys; TUI tests render finite and infinite limits.
+Adapter tests validate nested policies at provider load, prove explicit profile policies reach registration, prove omission resolves to five retries, and retain the serving policy across in-flight route replacement. LLM service tests prove adapter policies are captured and omission uses the shared five-retry behavior. Resolver tests prove always mode ignores retained normal-only fields but returns a pure always policy. Unit tests select policies from the failed request's serving registration, separate provider and changed-policy histories, exercise always mode beyond the normal budget, pin jitter and delay caps, prove downstream recovery ordering, prove cancellation and disposal drain delegated recovery before reaching quiescence, and prove both abort active backoff waits. Request-level coverage compares the complete messages of failed and retried attempts and rejects both provider error text and discarded partial output. A keyless headless `stream-json` snapshot runs failure, retry, and success through the assembled app, pins the complete `llm/retry` record, and rejects any model-message change between attempts. The shipped Web composition snapshot pins omitted DeepSeek and pi-ai policies at five retries, then proves settings can write `{ mode: 'always', maxRetries: 5 }` and obtain a pure always policy. JSONL and SQLite tests round-trip an always event without `Infinity`; invariant tests bind provider identity to the request header, validate failure and mode-specific timer bounds, and bind retry numbers to provider-policy keys; TUI tests render finite and infinite limits.
 
 ## Consequences
 
-Normal mode remains a finite default, while an explicit always policy can spend unbounded requests and time on permanent authentication, quota, invalid-request, protocol, or context failures. Operators must pair always mode with a cancellable caller and provider-specific cost controls. Retry state stays observable and durable without becoming model-visible, and serving-registration capture prevents adapter lifecycle changes from retroactively changing an in-flight request's recovery contract.
+Normal mode remains a finite default, while an explicit always policy can spend unbounded requests and time on permanent authentication, quota, invalid-request, protocol, or context failures. Operators must pair always mode with a cancellable caller and provider-specific cost controls. Any model route using omission defaults may spend up to three more requests and their backoff time than under the former two-retry default, in exchange for recovering from longer transient outages. Retry state stays observable and durable without becoming model-visible, and serving-registration capture prevents adapter lifecycle changes from retroactively changing an in-flight request's recovery contract.
 
 This decision extends the closed-step recovery, single visible adapter attempt, structured failure, and durable status design in [bounded recovery for transient LLM request failures](../architecture/2026-06-21-bounded-llm-request-recovery.md).

.agents/notes/implemented/feature/2026-07-24-provider-retry-policies.zh.md

@@ -12,7 +12,7 @@ Status: implemented
 
 ## 决策
 
-每个具体适配器都在其提供方配置中接受可选的 `retryPolicy`。适配器负责校验并解析策略，`ctx.llm` 则在该特定提供方路由注册时捕获策略。当调用进入最终适配器边界时，`ctx.llm` 会把实际提供服务的注册项所持不可变策略绑定到该调用；即使路由在请求进行期间被 dispose（资源释放）或替换，agent loop（智能体循环）仍会把该策略传给已关闭步骤恢复。`@deepseek-ai/dsh-llm-retry` 会把绑定到该调用的策略与失败步骤的持久化提供方标识结合起来。未到达最终适配器的调用没有实际提供服务的策略，因而会委托后续处理。未配置 `retryPolicy` 的提供方使用 normal 默认值。
+每个具体适配器都在其提供方配置中接受可选的 `retryPolicy`，对它进行校验与解析，并通过 `providerRetryPolicy()` 公开解析后的路由策略。省略配置时，Web、headless 与自定义 profile 等所有组合都使用核心共享的 normal 模式五次重试默认值。有效策略仍然是路由拥有的注册状态，而不是重试执行器设置。分层 settings 在把 `mode` 改为 `always` 后可能保留仅属于 normal 的 `maxRetries` 或 `retryableCodes`；解析器会忽略这些未启用字段，同时仍拒绝未知键，注册后的 always 策略也不包含它们。当调用进入最终适配器边界时，`ctx.llm` 会把实际提供服务的注册项所持不可变策略绑定到该调用；即使路由在请求进行期间被 dispose（资源释放）或替换，agent loop（智能体循环）仍会把该策略传给已关闭步骤恢复。`@deepseek-ai/dsh-llm-retry` 会把绑定到该调用的策略与失败步骤的持久化提供方标识结合起来。未到达最终适配器的调用没有实际提供服务的策略，因而会委托后续处理。
 
 ```yaml
 providers:
@@ -44,22 +44,28 @@ always 模式先请求下游恢复，使上下文溢出压缩（compaction）之
 
 ## 曾考虑的替代方案
 
-**单一全局 `always` 开关**：不予采纳，因为它无法把无界成本与延迟风险限制在确有需要的提供方，还可能在运行时重新路由后悄然生效。
+**重试执行器级的单一 `always` 开关**：不予采纳，因为它无法把无界成本与延迟风险限制在确有需要的提供方，还可能在运行时重新路由后悄然生效。提供方路由策略仍然权威，而且只有在路由选定注册后才捕获有效策略。
 
 **在 `dsh-llm-retry` 上维护单独的指定提供方列表**：不予采纳，因为它会在所属适配器配置之外重复提供方路由名称，并让提供方注册与恢复策略发生偏差。
 
 **设置很大的有限重试次数**：不予采纳，因为它最终仍会违反持续重试的约定，并把任意选取的运维上限序列化成看似有意义的数值。
 
+**按适配器设置不同的省略默认值**：不予采纳，因为共享预算必须在每种适配器族以及未来的每个适配器中重复配置，同等模型路由也会因实现不同而表现不同。
+
+**LLM 部署级默认值**：不予采纳，因为这只为区分 Web 与其他组合增加了一层配置。产品默认值保持统一，提供方 settings 则保留既有的逐路由覆盖能力。
+
+**在 Web UI 写入 profile 时把五次重试写死进去**：不予采纳，因为现有 profile、从该 UI 之外写入的 settings 以及非 Web 组合仍会保留旧值。
+
 **使用提供方 SDK 重试**：不予采纳，因为隐藏尝试会叠加 agent 层预算，无法利用已关闭步骤的持久性边界，还可能在没有可重建重试记录的情况下拼接或丢弃流式输出。
 
 **把错误放入模型上下文**：不予采纳，因为传输或提供方诊断信息属于运维状态，而非对话内容。它可能暴露敏感的提供方细节，并会改变重试请求，无法重复原本失败的请求。
 
 ## 验证
 
-适配器测试会在提供方加载时校验嵌套策略，证明注册流程会捕获已配置策略和默认策略，并证明请求进行期间替换路由后仍会保留实际提供服务的策略。单元测试根据失败请求实际使用的注册项选择策略、分离不同提供方和策略变更后的重试历史、验证 always 模式可越过 normal 预算、固定抖动和延迟上限、证明下游恢复顺序、证明取消与 dispose 会先排空已委托的恢复再达到完全停稳，并证明二者都会停止正在进行的退避等待。请求级覆盖会比较失败尝试与重试尝试的完整消息，并排除提供方错误文本和丢弃的部分输出。一个无密钥 headless `stream-json` 快照会通过组装后的应用执行失败、重试与成功流程，固定完整的 `llm/retry` 记录，并拒绝各次尝试之间出现任何模型消息变化。JSONL 与 SQLite 测试会往返读写不含 `Infinity` 的 always 事件；不变式测试会将提供方标识绑定到请求头、校验失败事实和各模式的计时器边界，并将重试编号绑定到提供方策略键；TUI 测试会渲染有限和无限上限。
+适配器测试会在提供方加载时校验嵌套策略，证明显式 profile 策略抵达注册流程，证明省略配置会解析为五次重试，并证明请求进行期间替换路由后仍会保留实际提供服务的策略。LLM 服务测试会证明适配器策略被捕获，且省略配置使用共享的五次重试行为。解析器测试会证明 always 模式忽略残留的 normal 专属字段，但返回纯 always 策略。单元测试根据失败请求实际使用的注册项选择策略、分离不同提供方和策略变更后的重试历史、验证 always 模式可越过 normal 预算、固定抖动和延迟上限、证明下游恢复顺序、证明取消与 dispose 会先排空已委托的恢复再达到完全停稳，并证明二者都会停止正在进行的退避等待。请求级覆盖会比较失败尝试与重试尝试的完整消息，并排除提供方错误文本和丢弃的部分输出。一个无密钥 headless `stream-json` 快照会通过组装后的应用执行失败、重试与成功流程，固定完整的 `llm/retry` 记录，并拒绝各次尝试之间出现任何模型消息变化。随附的 Web 组合快照会把省略配置的 DeepSeek 与 pi-ai 策略固定为五次重试，再证明 settings 可以写入 `{ mode: 'always', maxRetries: 5 }` 并得到纯 always 策略。JSONL 与 SQLite 测试会往返读写不含 `Infinity` 的 always 事件；不变式测试会将提供方标识绑定到请求头、校验失败事实和各模式的计时器边界，并将重试编号绑定到提供方策略键；TUI 测试会渲染有限和无限上限。
 
 ## 后果
 
-normal 模式仍是有限的默认策略；显式的 always 策略可能在永久性的身份验证、配额、无效请求、协议或上下文错误上耗费无限次请求和无限时间。运维方必须为 always 模式配备可取消的调用方和针对提供方的成本控制。重试状态保持可观察且会持久化，但不会对模型可见；捕获实际提供服务的注册项，也能防止适配器生命周期变化反过来改变进行中请求的恢复约定。
+normal 模式仍是有限的默认策略；显式的 always 策略可能在永久性的身份验证、配额、无效请求、协议或上下文错误上耗费无限次请求和无限时间。运维方必须为 always 模式配备可取消的调用方和针对提供方的成本控制。任何使用省略默认值的模型路由相比原先的两次重试默认值，最多会多花费三次请求及其退避时间，以此换取从更长短暂故障中恢复的能力。重试状态保持可观察且会持久化，但不会对模型可见；捕获实际提供服务的注册项，也能防止适配器生命周期变化反过来改变进行中请求的恢复约定。
 
 本决策扩展了[瞬态 LLM（大语言模型）请求失败的有界恢复](../architecture/2026-06-21-bounded-llm-request-recovery.md)中确定的已关闭步骤恢复、单次可见适配器尝试、结构化失败与持久化状态设计。

.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.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 .agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md
-2026-07-30-deepseek-onboarding-credential-setup.md: 823d10a723af70ec4ff51018b8b86198db0f5c29
-2026-07-30-deepseek-onboarding-credential-setup.zh.md: 7e8d79c23c4b1489bfd818c90558f36509635486
+2026-07-30-deepseek-onboarding-credential-setup.md: 87533e7a55f9b1f05f6a4ba58c3c9888780c158c
+2026-07-30-deepseek-onboarding-credential-setup.zh.md: 575d8232b4837b57d9508ed613530606c05db1f7

.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.md

@@ -10,7 +10,7 @@ The [web configuration plane](../architecture/2026-07-30-web-config-plane.md) ma
 
 ## Decision
 
-**One readiness projection owns both Models and onboarding facts.** `ui-settings-models` keeps a single store that joins `llm.providers({})`, redacted `settings.describe({})`, and batched `credentials.describe({refs})`. The onboarding projection selects the `deepseek-official` configurable-provider entry owned by the `llm-deepseek` namespace and empty settings path, reads the effective `apiKeyEnv`, and evaluates the matching credential descriptor. A live route with the same provider id but no matching configurable-provider declaration is adapter-absent for onboarding. A configured process-environment credential is ready and remains read-only.
+**One readiness projection owns both Models and onboarding facts.** `ui-settings-models` keeps a single store that joins `llm.providers({})`, the redacted namespace views held by the shared settings describe mirror, and batched `credentials.describe({refs})`. The onboarding projection selects the `deepseek-official` configurable-provider entry owned by the `llm-deepseek` namespace and empty settings path, reads the effective `apiKeyEnv`, and evaluates the matching credential descriptor. A live route with the same provider id but no matching configurable-provider declaration is adapter-absent for onboarding. A configured process-environment credential is ready and remains read-only. The later [settings describe mirror decision](../architecture/2026-08-17-settings-describe-mirror.md) owns that settings read and its invalidation ordering.
 
 **The settings shell contributes ordering, not provider policy.** `ui-settings` declares a root-scoped `settings.onboarding` list slot and mounts one ordered step at a time while the current surface is the empty Hero. The active registrant receives `complete()` and a private `openSection(id)` callback; completion transfers ownership to the next entry. `ui-settings-models` registers the DeepSeek step, the preceding welcome notice, and its Models section through `slots.inject()`, so every contribution follows one client Cordis plugin's lifecycle and the dialogs cannot stack. Their common presentation is owned by the [shared-modal onboarding decision](2026-08-13-shared-modal-product-onboarding.md).
 

.agents/notes/implemented/feature/2026-07-30-deepseek-onboarding-credential-setup.zh.md

@@ -10,7 +10,7 @@ Status: implemented
 
 ## 决策
 
-**Models 与首次使用引导共享同一个就绪状态投影。**`ui-settings-models` 维护一个 store，把 `llm.providers({})`、脱敏后的 `settings.describe({})` 和批量调用的 `credentials.describe({refs})` 联接为同一份状态。首次使用投影选取由 `llm-deepseek` namespace 与空 settings path 持有的 `deepseek-official` 可配置提供方条目，读取生效的 `apiKeyEnv`，并检查对应的凭据描述符。同 provider id 但没有匹配可配置提供方声明的存活路由，在首次使用引导中视为适配器缺失。通过进程环境提供的凭据若已配置，则判定为就绪并保持只读。
+**Models 与首次使用引导共享同一个就绪状态投影。**`ui-settings-models` 维护一个 store，把 `llm.providers({})`、共享 settings describe 镜像持有的已脱敏 namespace views 和批量调用的 `credentials.describe({refs})` 联接为同一份状态。首次使用投影选取由 `llm-deepseek` namespace 与空 settings path 持有的 `deepseek-official` 可配置提供方条目，读取生效的 `apiKeyEnv`，并检查对应的凭据描述符。同 provider id 但没有匹配可配置提供方声明的存活路由，在首次使用引导中视为适配器缺失。通过进程环境提供的凭据若已配置，则判定为就绪并保持只读。后续的 [settings describe 镜像决策](../architecture/2026-08-17-settings-describe-mirror.md)持有这次 settings 读取及其失效顺序。
 
 **设置外壳只贡献排序，不持有提供方策略。** `ui-settings` 声明一个根作用域的 `settings.onboarding` list slot，并在当前界面为空白 Hero 时，每次只挂载一个有序步骤。当前注册方会收到 `complete()` 和私有 `openSection(id)` 回调；完成当前步骤后，所有权转交给下一项。`ui-settings-models` 通过 `slots.inject()` 注册 DeepSeek 步骤、排在它之前的欢迎声明及 Models 分区，因此所有贡献都跟随同一个 client Cordis 插件的生命周期，两个弹窗也无法堆叠。它们的共用展示由[共用弹窗引导决策](2026-08-13-shared-modal-product-onboarding.md)持有。
 

.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.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 .agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md
-2026-08-04-claude-code-and-codex-subagent-backends.md: f725c1d9917ce3421ffd992830a551b0c189ff81
-2026-08-04-claude-code-and-codex-subagent-backends.zh.md: d593647a0e9e4cb96a603b2c7dddcf2cf5c555e7
+2026-08-04-claude-code-and-codex-subagent-backends.md: a8f500c7fb934b8634456e1618498909f682f0e2
+2026-08-04-claude-code-and-codex-subagent-backends.zh.md: ca35c38617b1ca38757959735b11618559f6f804

.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.md

@@ -12,12 +12,12 @@ The product integrations must not become second owners for task text, cwd, cance
 
 ## Decision
 
-The harness publishes two sibling one-shot provider packages: `codex` and `claude-code`. This note owns their product protocols, result mapping, and process lifecycle; the [shared-profile-host placement decision](../architecture/2026-08-10-product-subagent-providers-in-shared-host.md) owns process-wide placement, the [production-closure decision](../simplification/2026-08-12-production-dsh-excludes-product-subagent-providers.md) owns their independent optional Bundles and default exclusion, the [product one-shot background decision](2026-08-12-product-subagent-one-shot-background-tasks.md) owns the model-visible scheduling choice, and the [non-interactive permissions decision](2026-08-15-product-subagent-noninteractive-permissions.md) owns each product Provider's Profile-selected mode and diagnostic production. Loading either provider starts no product process, and each tool accepts only a standalone text task; product selection remains deployment configuration.
+The harness publishes two sibling one-shot provider packages whose default registry names are `codex` and `claude-code`. This note owns their product protocols, result mapping, and process lifecycle; the [named-instance decision](2026-08-18-product-subagent-named-instances.md) owns Profile-selected provider identity and static tool binding, the [production-install exclusion decision](../simplification/2026-08-12-production-dsh-excludes-product-subagent-providers.md) owns their independent optional Bundles and host-plane placement, the [product one-shot background decision](2026-08-12-product-subagent-one-shot-background-tasks.md) owns the model-visible scheduling choice, and the [non-interactive permissions decision](2026-08-15-product-subagent-noninteractive-permissions.md) owns each product Provider's Profile-selected mode and diagnostic production. Both packages accept multiple named instances. Loading either provider starts no product process, and each tool accepts only a standalone text task; product and instance selection remain deployment configuration.
 
 Both providers report `inheritsParentContext: false`, advertise no optional start capabilities, and pass the parent Session cwd without copying the parent conversation. Their documented tools use `backgroundMode: 'one-shot'` and `maxDepth: 'provider-managed'`: the consumer keeps foreground collection as the default and may place the same run in the generic Job runtime, while recursion policy stays with the out-of-process product. Every call creates a fresh product process and a non-resumable product conversation. `ctx.subagents` owns named-request resolution and paired lifecycle events; `dsh-tool-subagent` owns model-visible scheduling and foreground-versus-Job adaptation; `ctx.jobs` and `dsh-tool-jobs` own Job ids, state, output, controls, notices, and parent-owner cancellation; each product provider owns native result mapping, while `dsh-subprocess` owns credential scrubbing, process-tree termination, and whole-tree exit observation.
 
 ```text
-fixed tool -> dsh-tool-subagent -> ctx.subagents -> product provider -> product process
+configured tool -> dsh-tool-subagent -> ctx.subagents -> product provider -> product process
   foreground <- final product outcome
   background -> ctx.jobs / dsh-tool-jobs -> Job id / state / notice / controls
   both -> provider disposal -> dsh-subprocess -> whole-tree exit
@@ -34,7 +34,7 @@ fixed tool -> dsh-tool-subagent -> ctx.subagents -> product provider -> product
 
 ## Codex provider
 
-`@deepseek-ai/dsh-subagent-codex` registers the fixed `codex` provider, resolves the `codex` bin declared by its pinned `@openai/codex@0.147.0` package, and starts that wrapper through the current Node executable with `app-server --stdio`. The wrapper selects the private native platform payload; the provider neither resolves nor falls back to a host `codex`. Its public configuration contains an explicit `env` overlay, a positive finite `disposeGraceMs` no greater than the repository's shared `MAX_TIMER_DELAY_MS`, and a three-value native `permissionMode` that defaults to `never`. Installation, login, `CODEX_HOME`, model selection, base URL, and product-session settings remain native Codex or deployment responsibilities; the selected mode owns only the thread approval/reviewer/sandbox fields described by the non-interactive permissions decision.
+`@deepseek-ai/dsh-subagent-codex` registers a Profile-selected provider name that defaults to `codex`, resolves the `codex` bin declared by its pinned `@openai/codex@0.147.0` package, and starts that wrapper through the current Node executable with `app-server --stdio`. The wrapper selects the private native platform payload; the provider neither resolves nor falls back to a host `codex`. Its public configuration contains a non-empty `providerName`, an explicit `env` overlay, a positive finite `disposeGraceMs` no greater than the repository's shared `MAX_TIMER_DELAY_MS`, and a three-value native `permissionMode` that defaults to `never`. Each named instance retains those resolved values for its own runs. Installation, login, `CODEX_HOME`, model selection, base URL, and product-session settings remain native Codex or deployment responsibilities; the selected mode owns only the thread approval/reviewer/sandbox fields described by the non-interactive permissions decision.
 
 Before publication, the provider validates a non-empty text-only task, starts the managed app-server in the parent workspace, completes `initialize` → `initialized`, maps the resolved mode into official `thread/start` fields, and creates an `ephemeral: true` thread. The fixed app-server argv contains no mode or task text. The published run owns exactly one `turn/start`; its thread and turn ids remain private and are never persisted in the parent Session.
 
@@ -48,9 +48,9 @@ Codex 0.147.0 speaks the Responses protocol, while DeepSeek's public OpenAI-comp
 
 ## Claude Code provider
 
-`@deepseek-ai/dsh-subagent-claude-code` registers the fixed `claude-code` provider and invokes `@anthropic-ai/claude-agent-sdk@0.3.220`. The provider omits `pathToClaudeCodeExecutable`, so the SDK selects Claude Code 2.1.220 from the matching OS, CPU, and Linux-libc platform package in its own optional dependency closure. The provider does not resolve or fall back to a host `claude`; an omitted, unsupported, missing, or damaged platform payload fails the first delegation at the SDK startup boundary. The provider uses the official `query()` entrypoint and passes the SDK's native `claude` or `claude.exe` command, arguments, cwd, environment, and forwarded signal from `spawnClaudeCodeProcess` to `dsh-subprocess`; its private `SpawnedProcess` adapter exposes only the stream, event, kill, and exit facts the SDK requires.
+`@deepseek-ai/dsh-subagent-claude-code` registers a Profile-selected provider name that defaults to `claude-code` and invokes `@anthropic-ai/claude-agent-sdk@0.3.220`. The provider omits `pathToClaudeCodeExecutable`, so the SDK selects Claude Code 2.1.220 from the matching OS, CPU, and Linux-libc platform package in its own optional dependency closure. The provider does not resolve or fall back to a host `claude`; an omitted, unsupported, missing, or damaged platform payload fails the first delegation at the SDK startup boundary. The provider uses the official `query()` entrypoint and passes the SDK's native `claude` or `claude.exe` command, arguments, cwd, environment, and forwarded signal from `spawnClaudeCodeProcess` to `dsh-subprocess`; its private `SpawnedProcess` adapter exposes only the stream, event, kill, and exit facts the SDK requires.
 
-The public configuration contains an explicit `env` overlay, a positive finite `disposeGraceMs` no greater than the repository's shared `MAX_TIMER_DELAY_MS`, and a five-value native `permissionMode` that defaults to `dontAsk`. Each run creates its own `AbortController`, sets `persistSession: false`, disables `AskUserQuestion`, and passes the resolved mode to the SDK; only `bypassPermissions` receives the SDK's explicit dangerous confirmation. The provider deliberately omits `settingSources`, so the SDK reads the host's normal user, project, and local Claude settings relative to the parent Session cwd. It neither copies nor filters those settings and does not create or modify login state. Remaining permission prompts are denied, MCP elicitation is declined, and blocking dialogs fail closed instead of waiting for a user interface the provider does not own.
+The public configuration contains a non-empty `providerName`, an explicit `env` overlay, a positive finite `disposeGraceMs` no greater than the repository's shared `MAX_TIMER_DELAY_MS`, and a five-value native `permissionMode` that defaults to `dontAsk`. Each named instance retains those resolved values for its own runs. Each run creates its own `AbortController`, sets `persistSession: false`, disables `AskUserQuestion`, and passes the resolved mode to the SDK; only `bypassPermissions` receives the SDK's explicit dangerous confirmation. The provider deliberately omits `settingSources`, so the SDK reads the host's normal user, project, and local Claude settings relative to the parent Session cwd. It neither copies nor filters those settings and does not create or modify login state. Remaining permission prompts are denied, MCP elicitation is declined, and blocking dialogs fail closed instead of waiting for a user interface the provider does not own.
 
 The provider publishes only after both the SDK `Query` and a live managed CLI handle exist. It consumes the complete SDK stream and completes only when a `result` message has `subtype: "success"`, `is_error: false`, and a nonblank `result`, and the iterator then ends normally. Every SDK error subtype, an error-marked success, a missing result, iterator failure, protocol failure, or process failure becomes `error`. When a permission denial or unattended callback contributes to that failure, the result may additionally carry the bounded, non-assistant diagnostic owned by the non-interactive permissions decision. SDK turn, budget, and structured-output limits are not token-window facts, and the SDK exposes no native refusal terminal, so this provider produces neither `max-tokens` nor `refusal`. Local cancellation wins and becomes `aborted` without permission detail.
 
@@ -60,7 +60,7 @@ The credentialed Claude Code e2e uses the official DeepSeek Claude Code contract
 
 ## Distribution and evidence
 
-Each product owns branch-complete package tests, a required keyless real-product spec, a Loader composition e2e, and a credentialed DeepSeek e2e. The keyless product tier uses the exact official distribution under test, a non-empty fake product key, an isolated temporary workspace and product home, and a loopback fixed-answer model. Missing product requests, wrong authentication, altered task text, a non-exact answer, a skipped real product, or a surviving managed handle fails the required test. The Loader tier boots the README-shaped explicit Profile configuration, verifies both fixed one-shot tools expose optional background scheduling alongside generic Job controls, and starts neither product process. The credentialed tier starts the same production provider and real product with a runtime-only key, requires a unique nonce from the fixed official DeepSeek service, and proves quiescence again; it self-skips only when a local operator supplied no key, while trusted CI preflights the secret.
+Each product owns branch-complete package tests, a required keyless real-product spec, a Loader composition e2e, and a credentialed DeepSeek e2e. The keyless product tier uses the exact official distribution under test, a non-empty fake product key, an isolated temporary workspace and product home, and a loopback fixed-answer model. Missing product requests, wrong authentication, altered task text, a non-exact answer, a skipped real product, or a surviving managed handle fails the required test. The Codex Loader fixture exposes two named Codex instances and tools; the Claude Code Loader fixture exposes the default Codex tool plus two named Claude Code instances and tools. Both fixtures include generic Job controls and start neither product process. The credentialed tier starts the same production provider and real product with a runtime-only key, requires a unique nonce from the fixed official DeepSeek service, and proves quiescence again; it self-skips only when a local operator supplied no key, while trusted CI preflights the secret.
 
 The Codex evidence pins `@openai/codex@0.147.0`, `codex-cli 0.147.0`, and all six optional platform aliases. Its real-product spec observes the package-local wrapper argv, exact Bearer key, original task, byte-exact final answer, thread-level `never` overriding ambient `on-request`, automatic-review startup, unattended command rejection with safe diagnostic and no file side effect, explicit dangerous-bypass writing in suite-owned temporary storage, local cancellation, wrapper/native whole-tree exit, and missing-payload failure without host fallback.
 
@@ -78,7 +78,7 @@ The project owner's distribution authorization is scoped to the official `@anthr
 
 **A shared product-process helper package.** The existing subagent and subprocess seams already own every shared task, result, environment, and process-tree concern. A new helper would duplicate ownership without deleting either private product adapter, so each adapter calls the existing seams directly.
 
-**A model-visible product selector.** Product availability and authentication are deployment facts. Two fixed tools keep each schema and provider binding explicit and avoid adding dynamic selection state to the common service.
+**A model-visible product selector.** Product availability, instance configuration, and authentication are deployment facts. Profile-bound tools keep each schema and provider binding explicit and avoid adding dynamic selection state to the common service.
 
 **Product doubles as required evidence.** Doubles cover exhaustive private protocol branches but do not prove package exports, official distributions, authentication, or real process behavior. Required evidence drives each official product against a loopback model fixture.
 
@@ -88,7 +88,7 @@ The project owner's distribution authorization is scoped to the official `@anthr
 
 ## Consequences
 
-Users delegate through two stable one-shot tools backed by the official product integrations. Explicit Profile installation and host-plane provider placement are owned by the [production-install exclusion decision](../simplification/2026-08-12-production-dsh-excludes-product-subagent-providers.md); per-Preset tool exposure and foreground-default optional Job scheduling are owned by the [product one-shot background decision](2026-08-12-product-subagent-one-shot-background-tasks.md). This note's provider lifecycle keeps native settings and behavior while shared services retain the sole ownership of job settlement and process-tree quiescence.
+Users delegate through Profile-configured one-shot tools backed by the official product integrations. Explicit Profile installation and host-plane provider placement are owned by the [production-install exclusion decision](../simplification/2026-08-12-production-dsh-excludes-product-subagent-providers.md); named instance identity and tool binding are owned by the [named-instance decision](2026-08-18-product-subagent-named-instances.md); per-Preset tool exposure and foreground-default optional Job scheduling are owned by the [product one-shot background decision](2026-08-12-product-subagent-one-shot-background-tasks.md). This note's provider lifecycle keeps native settings and behavior while shared services retain the sole ownership of job settlement and process-tree quiescence.
 
 Every delegation pays for a fresh product process and independent model context. Successful product payload remains final assistant text; a failed product run may separately expose the shared safe diagnostic. Background scheduling additionally exposes generic Job ids, status, completion notices, and collection or cancellation results. Both products use Bundle-pinned platform CLIs plus native account and workspace settings and the selected Provider permission mode. Credentialed e2e runs also spend external API quota and depend on the official DeepSeek endpoint; deterministic protocol, failure, cancellation, and approval coverage remains in the keyless tier. The providers do not resume sessions, stream progress, accept new human interaction, roll back tool or file side effects, or impose a wall-clock timeout.
 

.agents/notes/implemented/feature/2026-08-04-claude-code-and-codex-subagent-backends.zh.md

@@ -12,12 +12,12 @@ Status: implemented
 
 ## 决策
 
-harness 交付两个同级的一次性提供方包：`codex` 与 `claude-code`。本说明负责它们的产品协议、结果映射和进程生命周期；[共享 profile 宿主归属决策](../architecture/2026-08-10-product-subagent-providers-in-shared-host.md)负责进程级放置，[生产依赖闭包决策](../simplification/2026-08-12-production-dsh-excludes-product-subagent-providers.md)负责两个彼此独立的可选 Bundle 及其默认发行排除，[产品一次性后台任务决策](2026-08-12-product-subagent-one-shot-background-tasks.md)负责模型可见的调度选择，[非交互权限决策](2026-08-15-product-subagent-noninteractive-permissions.md)则负责各产品提供方的 Profile 模式选择与诊断生产。加载任一提供方都不会启动产品进程，而且每个工具只接受独立文本任务；产品选择仍属于部署配置。
+harness 交付两个同级的一次性提供方包，其默认注册名称分别为 `codex` 与 `claude-code`。本说明负责它们的产品协议、结果映射和进程生命周期；[命名实例决策](2026-08-18-product-subagent-named-instances.md)负责 Profile 选择的提供方身份与静态工具绑定，[生产安装排除决策](../simplification/2026-08-12-production-dsh-excludes-product-subagent-providers.md)负责各自独立的可选 Bundle 与 host plane（宿主平面）放置，[产品一次性后台任务决策](2026-08-12-product-subagent-one-shot-background-tasks.md)负责模型可见的调度选择，[非交互权限决策](2026-08-15-product-subagent-noninteractive-permissions.md)则负责各产品提供方的 Profile 模式选择与诊断生产。两个包都接受多个命名实例。加载任一提供方都不会启动产品进程，而且每个工具只接受独立文本任务；产品与实例选择仍属于部署配置。
 
 这两个提供方都报告 `inheritsParentContext: false`，不声明任何可选的启动能力，并传递父会话 cwd，但不会复制父级对话。文档所示的工具使用 `backgroundMode: 'one-shot'` 与 `maxDepth: 'provider-managed'`：消费方默认在前台收集结果，也可把同一次运行放入通用 Job 运行时，而递归策略仍由进程外产品负责。每次调用都会创建一个全新的产品进程和一次不可续接的产品对话。`ctx.subagents` 负责具名请求解析与成对生命周期事件；`dsh-tool-subagent` 负责模型可见的调度以及前台与 Job 适配；`ctx.jobs` 和 `dsh-tool-jobs` 负责 Job id、状态、输出、控制、通知与父级 owner 取消；各产品提供方负责原生结果映射，`dsh-subprocess` 则负责凭证清洗、进程树终止以及整棵进程树的退出观测。
 
 ```text
-fixed tool -> dsh-tool-subagent -> ctx.subagents -> product provider -> product process
+configured tool -> dsh-tool-subagent -> ctx.subagents -> product provider -> product process
   foreground <- final product outcome
   background -> ctx.jobs / dsh-tool-jobs -> Job id / state / notice / controls
   both -> provider disposal -> dsh-subprocess -> whole-tree exit
@@ -34,7 +34,7 @@ fixed tool -> dsh-tool-subagent -> ctx.subagents -> product provider -> product
 
 ## Codex 提供方
 
-`@deepseek-ai/dsh-subagent-codex` 注册固定的 `codex` 提供方，解析锁定的 `@openai/codex@0.147.0` 包所声明的 `codex` bin，并使用当前 Node 可执行文件加 `app-server --stdio` 启动该 wrapper。Wrapper 会选择私有原生平台载荷；提供方既不解析也不回退宿主 `codex`。其公开配置包含显式的 `env` 覆盖项、须为正有限值且不得大于仓库共享 `MAX_TIMER_DELAY_MS` 的 `disposeGraceMs`，以及默认使用 `never` 的三值原生 `permissionMode`。安装、登录、`CODEX_HOME`、模型选择、基础 URL 和产品会话设置仍由 Codex 原生机制或部署环境负责；所选模式只拥有非交互权限决策中描述的线程 approval／reviewer／sandbox 字段。
+`@deepseek-ai/dsh-subagent-codex` 注册由 Profile 选择、默认值为 `codex` 的提供方名称，解析锁定的 `@openai/codex@0.147.0` 包所声明的 `codex` bin，并使用当前 Node 可执行文件加 `app-server --stdio` 启动该 wrapper。Wrapper 会选择私有原生平台载荷；提供方既不解析也不回退宿主 `codex`。其公开配置包含非空的 `providerName`、显式的 `env` 覆盖项、须为正有限值且不得大于仓库共享 `MAX_TIMER_DELAY_MS` 的 `disposeGraceMs`，以及默认使用 `never` 的三值原生 `permissionMode`。每个命名实例会为自己的运行保留这些已解析值。安装、登录、`CODEX_HOME`、模型选择、基础 URL 和产品会话设置仍由 Codex 原生机制或部署环境负责；所选模式只拥有非交互权限决策中描述的线程 approval／reviewer／sandbox 字段。
 
 发布前，提供方会验证非空的纯文本任务，在父级工作区中启动受管的 app-server，完成 `initialize` → `initialized` 握手，把已解析模式映射为官方 `thread/start` 字段，并创建一个 `ephemeral: true` 线程。固定 app-server argv 不包含模式或任务文本。已发布的运行只拥有一次 `turn/start`；其线程 ID 与轮次 ID 保持私有，绝不会持久化到父会话。
 
@@ -48,9 +48,9 @@ Codex 0.147.0 使用 Responses 协议，而 DeepSeek 的公开 OpenAI 兼容端
 
 ## Claude Code 提供方
 
-`@deepseek-ai/dsh-subagent-claude-code` 注册固定的 `claude-code` 提供方，并调用 `@anthropic-ai/claude-agent-sdk@0.3.220`。提供方会省略 `pathToClaudeCodeExecutable`，因此 SDK 会从自己的 optional dependency 闭包中，按操作系统、CPU 与 Linux libc 选择携带 Claude Code 2.1.220 的匹配平台包。提供方既不会解析也不会回退宿主 `claude`；省略 optional dependency、不受支持的平台，以及缺失或损坏的平台载荷，都会在第一次委派的 SDK 启动边界失败。提供方使用官方 `query()` 入口点，并把 SDK 的 `spawnClaudeCodeProcess` 给出的原生 `claude` 或 `claude.exe` 命令、参数、cwd、环境和转发的信号交给 `dsh-subprocess`；其私有 `SpawnedProcess` 适配器只公开 SDK 所需的流、事件、终止和退出事实。
+`@deepseek-ai/dsh-subagent-claude-code` 注册由 Profile 选择、默认值为 `claude-code` 的提供方名称，并调用 `@anthropic-ai/claude-agent-sdk@0.3.220`。提供方会省略 `pathToClaudeCodeExecutable`，因此 SDK 会从自己的 optional dependency 闭包中，按操作系统、CPU 与 Linux libc 选择携带 Claude Code 2.1.220 的匹配平台包。提供方既不会解析也不会回退宿主 `claude`；省略 optional dependency、不受支持的平台，以及缺失或损坏的平台载荷，都会在第一次委派的 SDK 启动边界失败。提供方使用官方 `query()` 入口点，并把 SDK 的 `spawnClaudeCodeProcess` 给出的原生 `claude` 或 `claude.exe` 命令、参数、cwd、环境和转发的信号交给 `dsh-subprocess`；其私有 `SpawnedProcess` 适配器只公开 SDK 所需的流、事件、终止和退出事实。
 
-公开配置包含显式的 `env` 覆盖项、须为正有限值且不得大于仓库共享 `MAX_TIMER_DELAY_MS` 的 `disposeGraceMs`，以及默认使用 `dontAsk` 的五值原生 `permissionMode`。每次运行都会创建自己的 `AbortController`，设置 `persistSession: false`、禁用 `AskUserQuestion`，并把已解析模式传给 SDK；只有 `bypassPermissions` 会取得 SDK 的显式危险确认。提供方故意省略 `settingSources`，因此 SDK 会相对于父会话 cwd 读取宿主机常规的用户、项目和本地 Claude 设置。它既不复制也不过滤这些设置，也不会创建或修改登录状态。其余权限提示会被拒绝，MCP elicitation 会被拒绝，阻塞对话会快速失败，而不会等待本提供方不负责的用户界面。
+公开配置包含非空的 `providerName`、显式的 `env` 覆盖项、须为正有限值且不得大于仓库共享 `MAX_TIMER_DELAY_MS` 的 `disposeGraceMs`，以及默认使用 `dontAsk` 的五值原生 `permissionMode`。每个命名实例会为自己的运行保留这些已解析值。每次运行都会创建自己的 `AbortController`，设置 `persistSession: false`、禁用 `AskUserQuestion`，并把已解析模式传给 SDK；只有 `bypassPermissions` 会取得 SDK 的显式危险确认。提供方故意省略 `settingSources`，因此 SDK 会相对于父会话 cwd 读取宿主机常规的用户、项目和本地 Claude 设置。它既不复制也不过滤这些设置，也不会创建或修改登录状态。其余权限提示会被拒绝，MCP elicitation 会被拒绝，阻塞对话会快速失败，而不会等待本提供方不负责的用户界面。
 
 只有在 SDK `Query` 与受管的活动 CLI 句柄都已存在后，提供方才会发布运行。它会消费完整的 SDK 流；只有 `result` 消息具有 `subtype: "success"`、`is_error: false` 和非空白 `result`，且迭代器随后正常结束时，运行才会完成。所有 SDK 错误子类型、标记为错误的成功消息、结果缺失、迭代器失败、协议失败或进程失败都会成为 `error`。当权限拒绝或无人值守回调参与了该失败时，结果还可以携带由非交互权限决策负责的有界、非 assistant 诊断。SDK 的轮次、预算和结构化输出限制不表示 token 窗口耗尽，而且 SDK 没有原生的拒绝终止状态，因此本提供方不会产生 `max-tokens` 或 `refusal`。本地取消会胜出并成为 `aborted`，且不附带权限说明。
 
@@ -60,7 +60,7 @@ Codex 0.147.0 使用 Responses 协议，而 DeepSeek 的公开 OpenAI 兼容端
 
 ## 分发与证据
 
-每个产品都负责覆盖所有分支的包测试、一项必跑的无密钥真实产品测试、一项 Loader 组合 e2e 和一项带密钥 DeepSeek e2e。无密钥产品层级使用被测的确切官方发行版、非空的伪产品密钥、隔离的临时工作区与产品主目录，以及能返回固定答案的回环模型。产品请求缺失、身份验证错误、任务文本被改动、答案不完全一致、真实产品被跳过或受管句柄仍存活，都会使这项必跑测试失败。Loader 层级会启动 README 所示的显式 Profile 配置，在同一个上下文中验证两个固定一次性工具会与通用 Job 控制工具一起公开可选后台调度，而且不会启动任何产品进程。带密钥层级会使用仅在运行时提供的密钥启动同一生产提供方与真实产品，要求从固定的 DeepSeek 官方服务取得唯一随机数，并再次证明完全停稳；仅当本地操作者未提供密钥时才会自行跳过，而受信任的 CI 会预检该 secret。
+每个产品都负责覆盖所有分支的包测试、一项必跑的无密钥真实产品测试、一项 Loader 组合 e2e 和一项带密钥 DeepSeek e2e。无密钥产品层级使用被测的确切官方发行版、非空的伪产品密钥、隔离的临时工作区与产品主目录，以及能返回固定答案的回环模型。产品请求缺失、身份验证错误、任务文本被改动、答案不完全一致、真实产品被跳过或受管句柄仍存活，都会使这项必跑测试失败。Codex Loader fixture 会公开两个命名 Codex 实例与工具；Claude Code Loader fixture 会公开默认 Codex 工具以及两个命名 Claude Code 实例与工具。两个 fixture 都包含通用 Job 控制工具，而且不会启动任何产品进程。带密钥层级会使用仅在运行时提供的密钥启动同一生产提供方与真实产品，要求从固定的 DeepSeek 官方服务取得唯一随机数，并再次证明完全停稳；仅当本地操作者未提供密钥时才会自行跳过，而受信任的 CI 会预检该 secret。
 
 Codex 证据会锁定 `@openai/codex@0.147.0`、`codex-cli 0.147.0` 与六个平台 alias。其真实产品测试会观测包内 wrapper argv、确切的 Bearer 密钥、原始任务、逐字节完全一致的最终回答、线程级 `never` 对环境中 `on-request` 的覆盖、自动评审启动、带安全诊断且不产生文件副作用的无人值守命令拒绝、测试拥有临时存储中的显式危险绕过写入、本地取消、wrapper／原生整棵进程树退出，以及载荷缺失时不回退宿主命令的失败。
 
@@ -78,7 +78,7 @@ Claude Code 证据会锁定 Agent SDK 0.3.220、Claude Code 2.1.220，以及八
 
 **共享产品进程辅助包。** 现有 subagent 与子进程 seam 已负责围绕任务、结果、环境和进程树的全部共享职责。新辅助包无法删除任一私有产品适配器，只会造成责任重复，因此每个适配器都会直接调用现有 seam。
 
-**面向模型的产品选择器。** 产品可用性和身份验证属于部署事实。两个固定工具使各自的 schema 与提供方绑定保持明确，也避免在通用服务中添加动态选择状态。
+**面向模型的产品选择器。** 产品可用性、实例配置和身份验证属于部署事实。由 Profile 绑定的工具使各自的 schema 与提供方绑定保持明确，也避免在通用服务中添加动态选择状态。
 
 **以产品替身作为强制证据。** 替身可以穷尽覆盖私有协议分支，但无法证明包导出、官方发行版、身份验证或真实进程行为。强制证据会驱动每个官方产品连接回环模型 fixture。
 
@@ -88,7 +88,7 @@ Claude Code 证据会锁定 Agent SDK 0.3.220、Claude Code 2.1.220，以及八
 
 ## 后果
 
-用户通过官方产品集成支持的两个稳定一次性工具进行委派。显式 Profile 安装与 host plane 提供方放置由[生产安装排除决策](../simplification/2026-08-12-production-dsh-excludes-product-subagent-providers.md)负责；按 Preset 暴露工具以及默认前台且可选通用 Job 的调度方式由[产品一次性后台任务决策](2026-08-12-product-subagent-one-shot-background-tasks.md)负责。本说明规定的提供方生命周期会保留原生设置与行为，而共享服务继续独占作业结算与进程树完全停稳的责任。
+用户通过由 Profile 配置、并由官方产品集成支持的一次性工具进行委派。显式 Profile 安装与 host plane 提供方放置由[生产安装排除决策](../simplification/2026-08-12-production-dsh-excludes-product-subagent-providers.md)负责；命名实例身份与工具绑定由[命名实例决策](2026-08-18-product-subagent-named-instances.md)负责；按 Preset 暴露工具以及默认前台且可选通用 Job 的调度方式由[产品一次性后台任务决策](2026-08-12-product-subagent-one-shot-background-tasks.md)负责。本说明规定的提供方生命周期会保留原生设置与行为，而共享服务继续独占作业结算与进程树完全停稳的责任。
 
 每次委派都要承担新建产品进程和独立模型上下文的开销。成功的产品载荷仍只有最终 assistant 文本；失败的产品运行可以另行公开共享安全诊断。后台调度还会额外公开通用 Job id、状态、完成通知以及收集或取消结果。两个产品都使用 Bundle 锁定的平台 CLI，并保留原生账户与工作区设置以及所选提供方权限模式。带密钥 e2e 运行还会消耗外部 API 配额，并依赖 DeepSeek 官方端点；对协议、失败、取消与审批的确定性覆盖仍由无密钥层级承担。提供方不会恢复会话、以流式方式传送进度、接受新的人工交互、回滚工具或文件副作用，也不会施加按实际经过时间触发的超时。
 

.agents/notes/implemented/feature/2026-08-12-product-subagent-one-shot-background-tasks.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 .agents/notes/implemented/feature/2026-08-12-product-subagent-one-shot-background-tasks.md
-2026-08-12-product-subagent-one-shot-background-tasks.md: 248bb943f8ee46a7050c373b6b7c3f7dec65d566
-2026-08-12-product-subagent-one-shot-background-tasks.zh.md: d6867a97561e7efbe2b152b6c45991553393b4e7
+2026-08-12-product-subagent-one-shot-background-tasks.md: 5e9522f6fac6eadb874ba2d1d4f45100f962b9e2
+2026-08-12-product-subagent-one-shot-background-tasks.zh.md: 9685701cbe07df226357e9830a875e3928ae039d

.agents/notes/implemented/feature/2026-08-12-product-subagent-one-shot-background-tasks.md

@@ -12,7 +12,9 @@ Exposing background execution must not add a product session, product-specific j
 
 ## Decision
 
-Production `dsh` does not install the optional product providers. A Profile that opts in installs and mounts `dsh-subagent-codex`, `dsh-subagent-claude-code`, or both once on the host plane. The `standard`, `code`, and `cordis` Agent Presets configure the corresponding dormant tool rows with `backgroundMode: one-shot`; removing a row's `disabled` field exposes the existing optional `run_in_background` argument to agents composed from that preset. Omission or `false` waits in the foreground; explicit `true` returns a parent-owned Job id after synchronous Job preflight and registration, without waiting for provider startup or completion.
+Production `dsh` does not install the optional product providers. A Profile that opts in installs the needed `dsh-subagent-codex` or `dsh-subagent-claude-code` packages and mounts the required provider instances on the host plane. The `standard`, `code`, and `cordis` Agent Presets configure the corresponding dormant tool rows with `backgroundMode: one-shot`; removing a row's `disabled` field exposes the existing optional `run_in_background` argument to agents composed from that preset. Omission or `false` waits in the foreground; explicit `true` returns a parent-owned Job id after synchronous Job preflight and registration, without waiting for provider startup or completion.
+
+The [named-instance decision](2026-08-18-product-subagent-named-instances.md) allows multiple rows for either product. Each additional host provider row has its own `providerName`, and each exposed preset tool row binds that exact name through `provider` while keeping a unique `toolName`; the foreground/background scheduling choice does not constrain the number of instances.
 
 The [generic one-shot background adapter](2026-07-08-background-subagent-tasks.md) owns background registration and settlement. It starts the same [`SubagentRun`](2026-06-21-subagent-capability-seam.md), uses a Job-owned cancellation signal across provider startup and execution, waits for `run.result` and `run.dispose()`, maps the terminal result and optional safe diagnostic into the Job, and lets `job_output`, `job_list`, `job_kill`, and the existing completion notice expose that state. The [product provider decision](2026-08-04-claude-code-and-codex-subagent-backends.md) continues to own native protocols, answer selection, local cancellation, and process-tree quiescence; the [non-interactive permissions decision](2026-08-15-product-subagent-noninteractive-permissions.md) owns each product Provider's Profile configuration and diagnostic production.
 
@@ -33,7 +35,7 @@ product tool call
 
 | Fact or resource | Owner | Product-tool responsibility | Observable result |
 | --- | --- | --- | --- |
-| Product provider installation and registration | Explicit Profile | Install the optional provider package and mount it once on the host plane | The provider name is available without adding its package to every production `dsh` install |
+| Product provider installation and registration | Explicit Profile | Install the optional provider package and mount the required named instances on the host plane | The provider names are available without adding the package to every production `dsh` install |
 | Product selection and exposure | Agent Preset | Bind one fixed tool name to one fixed provider | Enabling one row exposes only that product tool |
 | Foreground or background choice | `dsh-tool-subagent` | Resolve `run_in_background` under `one-shot` policy | Omission is foreground; explicit `true` returns a Job id |
 | Job id, state, output, cancellation, and notice | `ctx.jobs` and `dsh-tool-jobs` | Register and present the existing one-shot run | Generic job tools collect or stop the run for the exact parent |
@@ -41,7 +43,7 @@ product tool call
 
 ## Published composition
 
-The production base keeps both optional product providers out of its dependency closure. An opting-in Profile installs and mounts either or both providers once on the host plane. Each full preset keeps both product-tool rows disabled and contributes the generic Job controls to its own agent scope, while the base host owns the shared Job registry. A user copies a preset and removes `disabled` from the matching product rows after the Profile provider is present; no product process starts during composition.
+The production base keeps both optional product providers out of its dependency closure. An opting-in Profile installs the needed packages and mounts the required provider instances on the host plane. Each full preset keeps both product-tool rows disabled and contributes the generic Job controls to its own agent scope, while the base host owns the shared Job registry. A user copies a preset and removes `disabled` from the matching product rows after the Profile providers are present; no product process starts during composition.
 
 A standalone custom composition that enables one-shot background execution must provide the product provider plus the complete generic Job capability: `dsh-jobs-local` as the Job provider and `dsh-tool-jobs` as the model-facing consumer. A Profile based on `dsh-base` already has the Job capability and adds only the optional product provider before enabling the preset tool row. A product tool without the Job runtime can still execute in the foreground, but an explicit background request fails the existing Job preflight instead of publishing an uncollectable id.
 

.agents/notes/implemented/feature/2026-08-12-product-subagent-one-shot-background-tasks.zh.md

@@ -12,7 +12,9 @@ Codex 与 Claude Code 提供方已经能够运行一项自包含任务并返回
 
 ## 决策
 
-生产 `dsh` 不安装可选产品提供方。选择启用产品集成的 Profile 会安装 `dsh-subagent-codex`、`dsh-subagent-claude-code` 或两者，并在 host plane（宿主平面）各挂载一次。`standard`、`code` 与 `cordis` Agent Preset 使用 `backgroundMode: one-shot` 配置相应的休眠工具行；删除某一行的 `disabled` 字段后，现有可选参数 `run_in_background` 会向由该 preset 组装的 agent 公开。省略该参数或传入 `false` 时会在前台等待；显式传入 `true` 时会在同步完成 Job 预检与登记后返回由父级拥有的 Job id，而不会等待提供方启动或完成。
+生产 `dsh` 不安装可选产品提供方。选择启用产品集成的 Profile 会安装所需的 `dsh-subagent-codex` 或 `dsh-subagent-claude-code` 包，并在 host plane（宿主平面）挂载所需的提供方实例。`standard`、`code` 与 `cordis` Agent Preset 使用 `backgroundMode: one-shot` 配置相应的休眠工具行；删除某一行的 `disabled` 字段后，现有可选参数 `run_in_background` 会向由该 preset 组装的 agent 公开。省略该参数或传入 `false` 时会在前台等待；显式传入 `true` 时会在同步完成 Job 预检与登记后返回由父级拥有的 Job id，而不会等待提供方启动或完成。
+
+[命名实例决策](2026-08-18-product-subagent-named-instances.md)允许两个产品分别拥有多个配置项。每个新增宿主提供方配置项都有独立的 `providerName`，每个公开的 preset 工具配置项都通过 `provider` 绑定该名称并保持唯一的 `toolName`；前台或后台调度选择不会限制实例数量。
 
 [通用 one-shot 后台适配器](2026-07-08-background-subagent-tasks.md)负责后台登记与结算。它会启动同一个 [`SubagentRun`](2026-06-21-subagent-capability-seam.md)，让 Job 自有的取消信号覆盖提供方启动与执行，等待 `run.result` 和 `run.dispose()`，把终态结果与可选安全诊断映射进 Job，并由 `job_output`、`job_list`、`job_kill` 与现有完成通知公开该状态。[产品提供方决策](2026-08-04-claude-code-and-codex-subagent-backends.md)继续负责原生协议、答案选择、本地取消与进程树完全停稳；[非交互权限决策](2026-08-15-product-subagent-noninteractive-permissions.md)负责各产品提供方的 Profile 配置与诊断生产。
 
@@ -33,7 +35,7 @@ product tool call
 
 | 事实或资源 | 责任方 | 产品工具职责 | 可观察结果 |
 | --- | --- | --- | --- |
-| 产品提供方安装与登记 | 显式 Profile | 安装可选提供方包，并在 host plane 挂载一次 | 提供方名称可用，但不会让每次生产 `dsh` 安装都包含该包 |
+| 产品提供方安装与登记 | 显式 Profile | 安装可选提供方包，并在 host plane 挂载所需的命名实例 | 提供方名称可用，但不会让每次生产 `dsh` 安装都包含该包 |
 | 产品选择与公开 | Agent Preset | 把一个固定工具名绑定到一个固定提供方 | 启用一行只会公开对应产品工具 |
 | 前台或后台选择 | `dsh-tool-subagent` | 按 `one-shot` 策略解析 `run_in_background` | 省略参数时在前台运行；显式传入 `true` 时返回 Job id |
 | Job id、状态、输出、取消与通知 | `ctx.jobs` 与 `dsh-tool-jobs` | 登记并展示现有 one-shot 运行 | 通用作业工具为准确父级收集或停止运行 |
@@ -41,7 +43,7 @@ product tool call
 
 ## 发布组装
 
-生产 base 不让两个可选产品提供方进入依赖闭包。选择启用产品集成的 Profile 会在 host plane 安装并挂载任一或两个提供方。每个完整 preset 让两个产品工具行保持禁用，并把通用 Job 控制工具贡献到自身 agent 作用域；base host 负责共享 Job 注册表。Profile 提供方存在后，用户复制一个 preset，再从对应产品行删除 `disabled`；组装期间不会启动产品进程。
+生产 base 不让两个可选产品提供方进入依赖闭包。选择启用产品集成的 Profile 会安装所需包，并在 host plane 挂载所需的提供方实例。每个完整 preset 让两个产品工具行保持禁用，并把通用 Job 控制工具贡献到自身 agent 作用域；base host 负责共享 Job 注册表。Profile 提供方实例存在后，用户复制一个 preset，再从对应产品行删除 `disabled`；组装期间不会启动产品进程。
 
 独立自定义组装若启用 one-shot 后台执行，就必须同时提供产品提供方与完整通用 Job 能力：由 `dsh-jobs-local` 充当 Job 提供方，由 `dsh-tool-jobs` 充当面向模型的消费方。基于 `dsh-base` 的 Profile 已具备 Job 能力，只需在启用 preset 工具行前新增可选产品提供方。没有 Job 运行时的产品工具仍可在前台执行，但显式后台请求会在现有 Job 预检中失败，不会发布无法收集的 id。
 

.agents/notes/implemented/feature/2026-08-18-product-subagent-named-instances.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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 .agents/notes/implemented/feature/2026-08-18-product-subagent-named-instances.md
+2026-08-18-product-subagent-named-instances.md: 759d3941ff8404138954c409f0fd4949e357200e
+2026-08-18-product-subagent-named-instances.zh.md: 6faf0e70f639cbc6528e27b800b8e5f99f0d6c86

.agents/notes/implemented/feature/2026-08-18-product-subagent-named-instances.md

@@ -0,0 +1,48 @@
+# Agent Note: Product subagent named instances
+
+Status: implemented
+
+English | [中文](2026-08-18-product-subagent-named-instances.zh.md)
+
+## Problem
+
+A Profile can mount one Cordis plugin package in multiple rows, but the Codex and Claude Code product providers previously registered every row under one fixed product name. A second row therefore failed as a duplicate before its distinct permission mode, environment, or process-release settings could become usable. Deriving an implicit name from those settings would create a second identity rule, while choosing a provider during a tool call would let model input select deployment authority.
+
+The existing subagent registry already owns unique provider names, reversible registration, lifecycle events, and holder-owned published runs. The existing `dsh-tool-subagent` configuration already binds one provider name to one model-visible tool name. Product providers need to expose the missing Profile-owned identity without adding another registry or selection protocol.
+
+## Decision
+
+Each product provider Config owns a non-empty `providerName`; the defaults remain `codex` and `claude-code`. The resolved name is fixed when the plugin row loads and becomes the Provider object's `name`; registration, lookup, lifecycle events, run logs, and HMR removal therefore use the same value. Each mounted row retains its own `permissionMode`, `env`, `disposeGraceMs`, and run resources.
+
+Profiles may mount multiple Codex or Claude Code rows when every row uses a distinct `providerName`. Each `dsh-tool-subagent` row continues to bind its existing `provider` field to that exact name and exposes an independently configured `toolName`. Tool calls carry no provider selector, alias, or permission input. A duplicate provider name fails through the existing `DUPLICATE_PROVIDER` path and leaves the first registration intact.
+
+Removing one provider row blocks new starts and removes only tools bound to that name. Runs already published by the removed instance remain owned by their holders and settle or dispose independently. Sibling instances remain registered and keep their own environment, native permission mode, cancellation controller, product process, and cleanup grace.
+
+### Ownership and lifecycle
+
+| Fact or operation | Owner | Result |
+| --- | --- | --- |
+| Provider instance name | Product Provider Config | One immutable registry name per mounted row, with the existing default when omitted |
+| Name uniqueness and lifecycle events | `ctx.subagents` | Duplicate registration fails; disposal removes only the matching name |
+| Model-visible tool name and binding | `dsh-tool-subagent` Config | One static tool resolves one configured provider name |
+| Permission, environment, and process cleanup | One Provider instance | Concurrent runs and sibling instances do not share deployment configuration or run resources |
+
+## Verification
+
+Both product packages pin their default and custom names, empty-name rejection, duplicate rollback, actual-name diagnostics, two concurrent instances with different permission modes, environments, and cleanup grace, cancellation isolation, and removal of one instance while its published run remains valid. The official product loopback tests run two named instances in one Host against separate model fixtures and prove independent unload and process-tree quiescence. Public Loader compositions mount two rows and two distinct tools for each product without starting either product, while keyless ACP snapshots pin the four-tool combined roster and the absence of a dynamic provider parameter.
+
+## Alternatives considered
+
+**Derive names from the product or permission mode.** An implicit suffix would make identity change when deployment settings change and could still collide across equivalent rows. The Profile supplies the identity explicitly.
+
+**Let a tool call choose the provider.** That would make model input select a permission and environment instance. Separate tool rows keep authorization and exposure static in configuration.
+
+**Create a product-instance catalog or alias registry.** The existing subagent registry already owns names, uniqueness, lookup, events, and disposal. Another directory would duplicate state without a distinct consumer.
+
+**Automatically rename duplicate rows.** Silent suffixing would make tool bindings and lifecycle diagnostics depend on load order. Duplicate names continue to fail loudly.
+
+## Consequences
+
+A Profile can expose several Codex and Claude Code tools backed by separate native permission modes and environments while existing configurations continue to resolve `codex` and `claude-code`. Provider and tool names remain independent configuration facts, so changing one requires updating the binding that refers to it.
+
+The design adds no runtime renaming, model-visible selector, generated tool name, persistent instance directory, shared process pool, or compatibility alias. Correct multi-instance configurations require unique provider names and unique tool names; duplicate tool-name waiting remains a separate limitation.

.agents/notes/implemented/feature/2026-08-18-product-subagent-named-instances.zh.md

@@ -0,0 +1,48 @@
+# Agent Note: 产品 subagent 命名实例
+
+Status: implemented
+
+[English](2026-08-18-product-subagent-named-instances.md) | 中文
+
+## 问题
+
+Profile 可以用多个配置项挂载同一个 Cordis 插件包，但 Codex 与 Claude Code 产品提供方此前会把每个配置项都注册到一个固定产品名称下。因此，第二个配置项会在其独立权限模式、环境或进程释放设置可用前因名称重复而失败。根据这些设置隐式派生名称会建立第二套身份规则，而在工具调用期间选择提供方会让模型输入决定部署权限。
+
+现有 subagent 注册表已经拥有提供方名称唯一性、可逆注册、生命周期事件和由持有方拥有的已发布运行。现有 `dsh-tool-subagent` 配置也已经把一个提供方名称绑定到一个模型可见工具名称。产品提供方只需公开缺失的 Profile 所有身份，无需增加另一套注册表或选择协议。
+
+## 决策
+
+每个产品提供方 Config 都拥有非空的 `providerName`；默认值仍分别为 `codex` 与 `claude-code`。插件配置项加载时会固定解析后的名称，并把它作为 Provider 对象的 `name`；注册、查找、生命周期事件、运行日志和 HMR（热模块替换）移除因此使用同一个值。每个已挂载配置项保留自己的 `permissionMode`、`env`、`disposeGraceMs` 和运行资源。
+
+当每个配置项使用不同的 `providerName` 时，Profile 可以挂载多个 Codex 或 Claude Code 配置项。每个 `dsh-tool-subagent` 配置项继续用已有的 `provider` 字段绑定这个准确名称，并公开独立配置的 `toolName`。工具调用不携带提供方选择器、别名或权限输入。重复提供方名称沿用现有 `DUPLICATE_PROVIDER` 路径失败，而且不会替换第一个注册项。
+
+移除一个提供方配置项会阻止新的启动，并且只移除绑定到该名称的工具。该实例已经发布的运行仍由其持有方拥有，并会独立结算或 dispose（资源释放）。兄弟实例继续保持注册，并保留各自的环境、原生权限模式、取消控制器、产品进程和清理宽限期。
+
+### 所有权与生命周期
+
+| 事实或操作 | 责任方 | 结果 |
+| --- | --- | --- |
+| 提供方实例名称 | 产品提供方 Config | 每个已挂载配置项拥有一个不可变注册名称；省略时使用现有默认值 |
+| 名称唯一性与生命周期事件 | `ctx.subagents` | 重复注册失败；资源释放只移除匹配名称 |
+| 模型可见工具名称与绑定 | `dsh-tool-subagent` Config | 一个静态工具解析一个已配置的提供方名称 |
+| 权限、环境与进程清理 | 一个提供方实例 | 并发运行与兄弟实例不共享部署配置或运行资源 |
+
+## 验证
+
+两个产品包测试都会固定默认与自定义名称、空名称拒绝、重复注册回滚、实际名称诊断、使用不同权限模式、环境与清理宽限期的两个并发实例、取消隔离，以及移除一个实例后其已发布运行仍然有效。官方产品回环测试会在同一个 Host 中针对独立模型 fixture（测试前置数据）运行两个命名实例，并证明独立卸载与进程树完全停稳。公共 Loader 组合会为每个产品挂载两个配置项与两个不同工具，而且不启动任一产品；无密钥 ACP 快照固定最终四工具组合，并证明没有动态提供方参数。
+
+## 考虑过的替代方案
+
+**根据产品或权限模式派生名称。** 隐式后缀会让部署设置变化同时改变身份，而且等价配置项之间仍可能冲突。Profile 会显式提供身份。
+
+**让工具调用选择提供方。** 这会让模型输入选择权限与环境实例。独立工具配置项会让授权与公开范围保持静态配置。
+
+**建立产品实例目录或别名注册表。** 现有 subagent 注册表已经拥有名称、唯一性、查找、事件和资源释放。另一套目录没有独立消费方，只会复制状态。
+
+**自动重命名重复配置项。** 静默添加后缀会让工具绑定与生命周期诊断依赖加载顺序。重复名称继续快速失败。
+
+## 结果
+
+Profile 可以公开多个由不同原生权限模式与环境支持的 Codex 与 Claude Code 工具，而现有配置仍会解析为 `codex` 与 `claude-code`。提供方名称与工具名称继续是彼此独立的配置事实，因此修改其中一项时必须同时更新引用它的绑定。
+
+本设计不增加运行时改名、模型可见选择器、自动生成的工具名称、持久实例目录、共享进程池或兼容别名。正确的多实例配置要求提供方名称与工具名称都保持唯一；重复工具名称的等待问题仍是独立限制。

apps/cli/config/agent-presets/cordis/skills/editing-cordis-compositions/SKILL.md

@@ -156,7 +156,9 @@ Copy these disabled templates from a shipped full preset and remove `disabled` o
     maxDepth: provider-managed
 ```
 
-The two rows are independent. Leaving both disabled preserves the copied preset; enabling one exposes only that installed product tool. The Codex Bundle exclusively uses the wrapper and native platform payload selected by its pinned official package, while the Claude Code Bundle exclusively uses the platform CLI selected by its pinned Agent SDK. Neither provider inspects or falls back to a host product command, and a missing optional payload fails the first delegation. `backgroundMode: one-shot` keeps omitted or `false` calls in the foreground and lets explicit `run_in_background: true` return a generic Job id. Full presets already carry `tool-jobs`, while the base Host carries the job registry; retain both so `job_output`, `job_list`, `job_kill`, cancellation, and completion notices stay available. Neither installing a product Bundle nor composing either preset row starts a product, authenticates an account, selects a model, probes credentials, or manages native product settings.
+For additional named Codex or Claude Code instances, mount a separate host-plane provider row for each instance with a unique `providerName`, then add a separate preset tool row whose `provider` exactly matches that name and whose `toolName` is also unique. Keep the shipped rows for the default `codex` and `claude-code` names; do not reuse one tool row for several providers or derive either name from permission or environment settings.
+
+The two rows are independent. Leaving both disabled preserves the copied preset, enabling one exposes only that product tool, and enabling both exposes both. Production `dsh` does not install either optional provider: before enabling a row, install the matching `@deepseek-ai/dsh-subagent-codex` or `@deepseek-ai/dsh-subagent-claude-code` Bundle in the Profile and restart it. Each Bundle registers its dormant default provider and exclusively uses its pinned package-local platform CLI; additional named instances use extra host-plane rows from the same installed package. A preset cannot provide that host dependency. `backgroundMode: one-shot` keeps omitted or `false` calls in the foreground and lets explicit `run_in_background: true` return a generic Job id. Full presets already carry `tool-jobs`, while the base host carries the job registry; retain both so `job_output`, `job_list`, `job_kill`, cancellation, and completion notices stay available. Installing a Bundle or composing a preset row does not start a product, authenticate an account, select a model, probe credentials, or manage native product settings.
 
 ## What not to move into a preset
 

apps/web/tests/shipped-composition.e2e.ts

@@ -1,6 +1,6 @@
 // Boots the shipped Web composition over the built dist this lane already uses
 // and asserts what that composition produces: the model-visible tool catalog
-// and file-reference guidance plus the sandbox/approval knobs it ships with.
+// and file-reference guidance plus its retry, sandbox, and approval defaults.
 // No browser and no model call — these are composition facts, and the browser
 // scenarios in this lane cover the surface itself.
 import { readFileSync } from 'node:fs'
@@ -10,6 +10,7 @@ import { afterEach, expect, it } from 'vitest'
 import { CallId } from '@deepseek-ai/dsh-llm'
 import { canonicalPath, writableRoots } from '@deepseek-ai/dsh-sandbox'
 import { SessionId } from '@deepseek-ai/dsh-session'
+import { settingsNamespace } from '@deepseek-ai/dsh-settings'
 // Empty type imports carry the tools/sandboxPolicy/approval Context merges.
 import type {} from '@deepseek-ai/dsh-tools'
 import type {} from '@deepseek-ai/dsh-sandbox-policy'
@@ -73,9 +74,66 @@ afterEach(async () => {
   scaffold = undefined
 })
 
-it('assembles the shipped Web catalog, file-reference guidance, and confined access default', async () => {
-  scaffold = await launchWebScaffold()
+it('assembles the shipped Web catalog, file-reference guidance, retry policy, and confined access default', async () => {
+  scaffold = await launchWebScaffold({ deepSeekMissingCredential: true })
   const ctx = scaffold.ctx
+  expect(ctx.llm.providerRetryPolicy('deepseek-official')).toMatchInlineSnapshot(`
+    {
+      "initialDelayMs": 500,
+      "jitterRatio": 0.1,
+      "maxDelayMs": 10000,
+      "maxRetries": 5,
+      "mode": "normal",
+      "retryableCodes": [
+        "EMPTY_RESPONSE",
+        "RATE_LIMIT",
+        "SERVER",
+        "TIMEOUT",
+        "TRANSPORT",
+      ],
+    }
+  `)
+  await ctx.settings.update(settingsNamespace('llm-deepseek'), {
+    retryPolicy: { mode: 'always', maxRetries: 5 },
+  })
+  expect(ctx.llm.providerRetryPolicy('deepseek-official')).toMatchInlineSnapshot(`
+    {
+      "initialDelayMs": 500,
+      "jitterRatio": 0.1,
+      "maxDelayMs": 10000,
+      "mode": "always",
+    }
+  `)
+  await ctx.settings.update(settingsNamespace('llm-pi-ai'), {
+    providers: {
+      openai: {},
+      anthropic: { retryPolicy: { mode: 'always' } },
+    },
+  })
+  expect(ctx.llm.providerRetryPolicy('openai')).toMatchInlineSnapshot(`
+    {
+      "initialDelayMs": 500,
+      "jitterRatio": 0.1,
+      "maxDelayMs": 10000,
+      "maxRetries": 5,
+      "mode": "normal",
+      "retryableCodes": [
+        "EMPTY_RESPONSE",
+        "RATE_LIMIT",
+        "SERVER",
+        "TIMEOUT",
+        "TRANSPORT",
+      ],
+    }
+  `)
+  expect(ctx.llm.providerRetryPolicy('anthropic')).toMatchInlineSnapshot(`
+    {
+      "initialDelayMs": 500,
+      "jitterRatio": 0.1,
+      "maxDelayMs": 10000,
+      "mode": "always",
+    }
+  `)
   // The catalog belongs to an AGENT, not to the process: every model-facing row
   // now lives in a preset mounted under one session's scope, so the global
   // layer holds nothing and a caller must name the agent to see anything. This

apps/web/tests/smoke-real.e2e.ts

@@ -372,7 +372,7 @@ describe('dsh web keyless CLI smoke', () => {
         turn: 1,
         step: 1,
         retry: 1,
-        maxRetries: 2,
+        maxRetries: 5,
         failure: { code: 'TRANSPORT' },
       })
       expect(JSON.stringify(page.events)).toContain('WEB_RETRY_DISCARDED')

apps/web/tests/snapshots/live-interactions/retry.expected.md

@@ -17,7 +17,7 @@
   - img
   - text: Context injection @deepseek-ai/dsh-system-prompt
 - group:
-  - status: Retried model request (1/2) · {{duration}}
+  - status: Retried model request (1/5) · {{duration}}
 - button "Think The user is asking for a one-sentence description of event sourcing. This is a straightforward knowledge question that doesn't require any skill loading or tool calls.":
   - img
   - img

apps/web/tests/startup-rpc-budget.e2e.ts

@@ -0,0 +1,54 @@
+// Cold-boot RPC budget. The describe mirror (packages/client/ui-settings) is
+// the one `settings.describe` reader in the browser, so startup describe
+// traffic stays bounded no matter how many client plugins own a preference.
+// A regression here means a consumer bypassed the mirror — grep for
+// `settings.describe(` outside ui-settings' client sources.
+//
+// Zero model calls: the lane only boots chrome, so no replay fixture mounts.
+import type { Browser, Page } from 'playwright'
+import { chromium } from 'playwright'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { launchWebScaffold, watchConsole, type WebScaffold } from './scaffold.ts'
+import { newEnglishPage } from './support.ts'
+
+/**
+ * Both reads are the mirror's: once eagerly at bind time over HTTP, and once
+ * on the first-connection reset — that second read closes the window where a
+ * document commit lands between the eager read and the SSE subscription and
+ * its invalidation is lost. Every settings consumer derives from these two.
+ */
+const DESCRIBE_BUDGET = 2
+
+let scaffold: WebScaffold
+let browser: Browser
+let page: Page
+
+beforeAll(async () => {
+  scaffold = await launchWebScaffold()
+  browser = await chromium.launch()
+})
+
+afterAll(async () => {
+  await page?.close()
+  await browser?.close()
+  await scaffold?.close()
+})
+
+describe('startup RPC budget', () => {
+  it('keeps cold-boot settings.describe at the mirror count', async () => {
+    page = await newEnglishPage(browser)
+    watchConsole(page)
+    const calls: string[] = []
+    page.on('request', (request) => {
+      const url = new URL(request.url())
+      if (url.pathname.startsWith('/api/')) calls.push(url.pathname.slice('/api/'.length))
+    })
+    await page.goto(scaffold.baseUrl)
+    // Boot settles when the workspace picker is interactive; the trailing wait
+    // absorbs the first-connection reset wave the budget must include.
+    await page.getByRole('textbox', { name: 'Choose workspace' }).waitFor({ timeout: 30_000 })
+    await page.waitForTimeout(3000)
+    const describeCount = calls.filter(method => method === 'settings.describe').length
+    expect(describeCount, `startup /api calls:\n${calls.join('\n')}`).toBe(DESCRIBE_BUDGET)
+  })
+})

apps/web/tsconfig.json

@@ -24,6 +24,7 @@
   "exclude": [
     "tests/scaffold.ts",
     "tests/scaffold-hermetic.e2e.ts",
+    "tests/startup-rpc-budget.e2e.ts",
     "tests/minimal-preset.snapshot.ts",
     "tests/message-feedback-protocol.snapshot.ts",
     "tests/live-interactions.e2e.ts",

docs/config-catalog.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 docs/config-catalog.md
-config-catalog.md: 3a471ea06e911d3d29ebef4ce80353b15a21cb43
-config-catalog.zh.md: f1b53d4a2b3c15abb3176c7af5de9c577f74825f
+config-catalog.md: c379a7a49e4aa670aac3aa203e216b2be8e1955d
+config-catalog.zh.md: e897f5d25a485133d4929061dce0b398edfa8c04

docs/config-catalog.md

@@ -870,7 +870,7 @@ export interface Config {
   models?: DeepSeekCatalogModel[]
   /** Maximum provider idle time while one stream read is outstanding (default five minutes). */
   streamIdleTimeoutMs?: number
-  /** Provider-owned model-request retry policy; omission uses normal defaults. */
+  /** Provider-owned model-request retry policy; omission uses normal mode with five retries. */
   retryPolicy?: RetryPolicyConfig
 }
 
@@ -992,7 +992,7 @@ export interface PiAiProviderProfile {
    * requests instead of being rejected by a request-size cap.
    */
   maxRequestImageBytes?: number
-  /** Provider-owned model-request retry policy; omission uses normal defaults. */
+  /** Provider-owned model-request retry policy; omission uses normal mode with five retries. */
   retryPolicy?: RetryPolicyConfig
 }
 
@@ -2092,6 +2092,8 @@ Requires: `subagents` · `subprocess`
 ```ts config-catalog
 /** Deployment-owned permission, environment, and process-release settings. */
 export interface Config {
+  /** Provider name on `ctx.subagents` (default `claude-code`). */
+  providerName?: string
   /**
    * Explicit environment entries layered over the subprocess seam's
    * credential-scrubbed parent environment.
@@ -2112,7 +2114,7 @@ export interface Config {
 export type ClaudeCodePermissionMode = typeof CLAUDE_CODE_PERMISSION_MODES[number]
 ```
 
-Source: [`packages/subagent/subagent-claude-code/src/index.ts:35`](../packages/subagent/subagent-claude-code/src/index.ts)
+Source: [`packages/subagent/subagent-claude-code/src/index.ts:37`](../packages/subagent/subagent-claude-code/src/index.ts)
 
 <a id="deepseek-aidsh-subagent-codex"></a>
 
@@ -2123,6 +2125,8 @@ Requires: `subagents` · `subprocess`
 ```ts config-catalog
 /** Deployment-owned permission, environment, and process-release settings. */
 export interface Config {
+  /** Provider name on `ctx.subagents` (default `codex`). */
+  providerName?: string
   /**
    * Explicit environment entries layered over the subprocess seam's
    * credential-scrubbed parent environment.
@@ -2141,7 +2145,7 @@ export type CodexPermissionMode =
   | 'dangerously-bypass-approvals-and-sandbox'
 ```
 
-Source: [`packages/subagent/subagent-codex/src/index.ts:33`](../packages/subagent/subagent-codex/src/index.ts)
+Source: [`packages/subagent/subagent-codex/src/index.ts:35`](../packages/subagent/subagent-codex/src/index.ts)
 
 <a id="deepseek-aidsh-subagent-dsh-sdk"></a>
 

docs/config-catalog.zh.md

@@ -872,7 +872,7 @@ export interface Config {
   models?: DeepSeekCatalogModel[]
   /** Maximum provider idle time while one stream read is outstanding (default five minutes). */
   streamIdleTimeoutMs?: number
-  /** Provider-owned model-request retry policy; omission uses normal defaults. */
+  /** Provider-owned model-request retry policy; omission uses normal mode with five retries. */
   retryPolicy?: RetryPolicyConfig
 }
 
@@ -994,7 +994,7 @@ export interface PiAiProviderProfile {
    * requests instead of being rejected by a request-size cap.
    */
   maxRequestImageBytes?: number
-  /** Provider-owned model-request retry policy; omission uses normal defaults. */
+  /** Provider-owned model-request retry policy; omission uses normal mode with five retries. */
   retryPolicy?: RetryPolicyConfig
 }
 
@@ -2094,6 +2094,8 @@ export type PermissionPolicy = 'allow' | 'reject'
 ```ts config-catalog
 /** Deployment-owned permission, environment, and process-release settings. */
 export interface Config {
+  /** Provider name on `ctx.subagents` (default `claude-code`). */
+  providerName?: string
   /**
    * Explicit environment entries layered over the subprocess seam's
    * credential-scrubbed parent environment.
@@ -2114,7 +2116,7 @@ export interface Config {
 export type ClaudeCodePermissionMode = typeof CLAUDE_CODE_PERMISSION_MODES[number]
 ```
 
-来源：[`packages/subagent/subagent-claude-code/src/index.ts:35`](../packages/subagent/subagent-claude-code/src/index.ts)
+来源：[`packages/subagent/subagent-claude-code/src/index.ts:37`](../packages/subagent/subagent-claude-code/src/index.ts)
 
 <a id="deepseek-aidsh-subagent-codex"></a>
 
@@ -2125,6 +2127,8 @@ export type ClaudeCodePermissionMode = typeof CLAUDE_CODE_PERMISSION_MODES[numbe
 ```ts config-catalog
 /** Deployment-owned permission, environment, and process-release settings. */
 export interface Config {
+  /** Provider name on `ctx.subagents` (default `codex`). */
+  providerName?: string
   /**
    * Explicit environment entries layered over the subprocess seam's
    * credential-scrubbed parent environment.
@@ -2143,7 +2147,7 @@ export type CodexPermissionMode =
   | 'dangerously-bypass-approvals-and-sandbox'
 ```
 
-来源：[`packages/subagent/subagent-codex/src/index.ts:33`](../packages/subagent/subagent-codex/src/index.ts)
+来源：[`packages/subagent/subagent-codex/src/index.ts:35`](../packages/subagent/subagent-codex/src/index.ts)
 
 <a id="deepseek-aidsh-subagent-dsh-sdk"></a>
 

docs/subsystems/llm-streaming.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 docs/subsystems/llm-streaming.md
-llm-streaming.md: 7c0e0865f8dcc0e7722bb2205d0129d9e0ca3086
-llm-streaming.zh.md: 5c31909ee79137c6c5eef101235b43a2419b1339
+llm-streaming.md: c1b2ab5f1e0926864f25409c021691d078df9e0f
+llm-streaming.zh.md: 7bf04bf7a4a7de63d20eb67461842ff49f3b189d

docs/subsystems/llm-streaming.md

@@ -240,7 +240,7 @@ Every adapter MUST obey these, and every consumer may rely on them:
 
 ## `ResolvedRetryPolicy`
 
-Provider configuration resolves before route registration into an immutable discriminated union. Normal mode carries `mode: 'normal'`, finite `maxRetries`, `retryableCodes`, and required `initialDelayMs`, `maxDelayMs`, and `jitterRatio`; always mode carries `mode: 'always'` and the same required backoff fields without a finite maximum. `LlmRuntime.providerRetryPolicy(provider)` returns the currently registered value and supplies normal defaults when the adapter omits one; `llmRetryPolicyOf(stream)` returns the value captured from the serving registration after the call selects that registration, so later route disposal or replacement cannot change an in-flight failure's recovery policy. The [generated config catalog](../config-catalog.md) lists the optional input fields.
+Retry configuration resolves before route registration into an immutable discriminated union. Normal mode carries `mode: 'normal'`, finite `maxRetries`, `retryableCodes`, and required `initialDelayMs`, `maxDelayMs`, and `jitterRatio`; always mode carries `mode: 'always'` and the same required backoff fields without a finite maximum. Omitting a provider policy uses the normal default of five retries. Layered settings may retain normal-only `maxRetries` or `retryableCodes` after switching to always mode; the resolver ignores those inactive fields and captures the pure always policy. `LlmRuntime.providerRetryPolicy(provider)` returns the registered value, and `llmRetryPolicyOf(stream)` returns the value captured from the serving registration after the call selects it, so later route disposal or replacement cannot change an in-flight failure's recovery policy. The [generated config catalog](../config-catalog.md) lists the optional input fields.
 
 ## `AppIdentity` — app attribution
 

docs/subsystems/llm-streaming.zh.md

@@ -242,7 +242,7 @@ interface LlmFailure {
 
 ## `ResolvedRetryPolicy`
 
-提供方配置会在路由注册前解析为不可变的可辨识联合。normal mode 携带 `mode: 'normal'`、有限的 `maxRetries`、`retryableCodes`，以及必填的 `initialDelayMs`、`maxDelayMs` 与 `jitterRatio`；always mode 携带 `mode: 'always'` 和相同的必填退避字段，但没有有限上限。`LlmRuntime.providerRetryPolicy(provider)` 返回当前注册的值，并在适配器省略策略时提供 normal 默认值；调用选定该注册后，`llmRetryPolicyOf(stream)` 返回为该调用服务的注册所捕获的值，因此之后释放或替换路由都无法改变进行中失败的恢复策略。可选配置输入字段由[生成的配置目录](../config-catalog.md)列出。
+重试配置会在路由注册前解析为不可变的可辨识联合。normal mode 携带 `mode: 'normal'`、有限的 `maxRetries`、`retryableCodes`，以及必填的 `initialDelayMs`、`maxDelayMs` 与 `jitterRatio`；always mode 携带 `mode: 'always'` 和相同的必填退避字段，但没有有限上限。省略提供方策略时使用重试五次的 normal 默认值。分层 settings 在切换到 always 模式后可能保留仅属于 normal 的 `maxRetries` 或 `retryableCodes`；解析器会忽略这些未启用字段，并捕获纯 always 策略。`LlmRuntime.providerRetryPolicy(provider)` 返回注册值；调用选定实际提供服务的注册后，`llmRetryPolicyOf(stream)` 返回从中捕获的值，因此之后释放或替换路由都无法改变进行中失败的恢复策略。可选配置输入字段由[生成的配置目录](../config-catalog.md)列出。
 
 ## `AppIdentity`：应用归属
 

examples/acp-agent/product-subagent-both.cordis.snapshot.yml

@@ -1,5 +1,5 @@
-# Keyless twin of product-subagent-both.cordis.yml: preserve both product
-# tools while replacing only the external model adapter.
+# Keyless twin of product-subagent-both.cordis.yml: preserve all four named
+# product tools while replacing only the external model adapter.
 - id: base
   name: '@deepseek-ai/cordis-plugin-include'
   config:
@@ -18,25 +18,47 @@
                   models:
                     - id: deepseek-v4-flash
                     - id: deepseek-v4-pro
-          - id: subagent-codex
+          - id: subagent-codex-primary
             name: '@deepseek-ai/dsh-subagent-codex'
             config:
-              permissionMode: approve-for-me
-          - id: subagent-claude-code
+              providerName: codex-primary
+          - id: subagent-codex-secondary
+            name: '@deepseek-ai/dsh-subagent-codex'
+            config:
+              providerName: codex-secondary
+          - id: subagent-claude-primary
+            name: '@deepseek-ai/dsh-subagent-claude-code'
+            config:
+              providerName: claude-primary
+          - id: subagent-claude-secondary
             name: '@deepseek-ai/dsh-subagent-claude-code'
             config:
-              permissionMode: acceptEdits
-          - id: tool-subagent-codex
+              providerName: claude-secondary
+          - id: tool-subagent-codex-primary
+            name: '@deepseek-ai/dsh-tool-subagent'
+            config:
+              provider: codex-primary
+              toolName: subagent_codex_primary
+              backgroundMode: one-shot
+              maxDepth: provider-managed
+          - id: tool-subagent-codex-secondary
+            name: '@deepseek-ai/dsh-tool-subagent'
+            config:
+              provider: codex-secondary
+              toolName: subagent_codex_secondary
+              backgroundMode: one-shot
+              maxDepth: provider-managed
+          - id: tool-subagent-claude-primary
             name: '@deepseek-ai/dsh-tool-subagent'
             config:
-              provider: codex
-              toolName: subagent_codex
+              provider: claude-primary
+              toolName: subagent_claude_primary
               backgroundMode: one-shot
               maxDepth: provider-managed
-          - id: tool-subagent-claude-code
+          - id: tool-subagent-claude-secondary
             name: '@deepseek-ai/dsh-tool-subagent'
             config:
-              provider: claude-code
-              toolName: subagent_claude_code
+              provider: claude-secondary
+              toolName: subagent_claude_secondary
               backgroundMode: one-shot
               maxDepth: provider-managed

examples/acp-agent/product-subagent-both.cordis.yml

@@ -1,31 +1,53 @@
-# Add both native product providers and the same independent one-shot tool rows
-# an Agent Preset may contribute. Loading the composition starts neither
-# product; the scenario pins both model-visible schemas.
+# Add two named Codex providers, two named Claude Code providers, and the
+# independent one-shot tool rows an Agent Preset may contribute. Loading the
+# composition starts neither product; the scenario pins all four schemas.
 - id: base
   name: '@deepseek-ai/cordis-plugin-include'
   config:
     path: ./cordis.yml
     patches:
       - insert:
-          - id: subagent-codex
+          - id: subagent-codex-primary
             name: '@deepseek-ai/dsh-subagent-codex'
             config:
-              permissionMode: approve-for-me
-          - id: subagent-claude-code
+              providerName: codex-primary
+          - id: subagent-codex-secondary
+            name: '@deepseek-ai/dsh-subagent-codex'
+            config:
+              providerName: codex-secondary
+          - id: subagent-claude-primary
+            name: '@deepseek-ai/dsh-subagent-claude-code'
+            config:
+              providerName: claude-primary
+          - id: subagent-claude-secondary
             name: '@deepseek-ai/dsh-subagent-claude-code'
             config:
-              permissionMode: acceptEdits
-          - id: tool-subagent-codex
+              providerName: claude-secondary
+          - id: tool-subagent-codex-primary
+            name: '@deepseek-ai/dsh-tool-subagent'
+            config:
+              provider: codex-primary
+              toolName: subagent_codex_primary
+              backgroundMode: one-shot
+              maxDepth: provider-managed
+          - id: tool-subagent-codex-secondary
+            name: '@deepseek-ai/dsh-tool-subagent'
+            config:
+              provider: codex-secondary
+              toolName: subagent_codex_secondary
+              backgroundMode: one-shot
+              maxDepth: provider-managed
+          - id: tool-subagent-claude-primary
             name: '@deepseek-ai/dsh-tool-subagent'
             config:
-              provider: codex
-              toolName: subagent_codex
+              provider: claude-primary
+              toolName: subagent_claude_primary
               backgroundMode: one-shot
               maxDepth: provider-managed
-          - id: tool-subagent-claude-code
+          - id: tool-subagent-claude-secondary
             name: '@deepseek-ai/dsh-tool-subagent'
             config:
-              provider: claude-code
-              toolName: subagent_claude_code
+              provider: claude-secondary
+              toolName: subagent_claude_secondary
               backgroundMode: one-shot
               maxDepth: provider-managed

examples/acp-agent/product-subagent-codex.cordis.snapshot.yml

@@ -1,5 +1,5 @@
-# Keyless twin of product-subagent-codex.cordis.yml: keep the same product
-# provider/tool composition and replace only the external model adapter.
+# Keyless twin of product-subagent-codex.cordis.yml: keep both named product
+# providers and tools while replacing only the external model adapter.
 - id: base
   name: '@deepseek-ai/cordis-plugin-include'
   config:
@@ -18,14 +18,25 @@
                   models:
                     - id: deepseek-v4-flash
                     - id: deepseek-v4-pro
-          - id: subagent-codex
+          - id: subagent-codex-primary
             name: '@deepseek-ai/dsh-subagent-codex'
             config:
-              permissionMode: approve-for-me
-          - id: tool-subagent-codex
+              providerName: codex-primary
+          - id: subagent-codex-secondary
+            name: '@deepseek-ai/dsh-subagent-codex'
+            config:
+              providerName: codex-secondary
+          - id: tool-subagent-codex-primary
+            name: '@deepseek-ai/dsh-tool-subagent'
+            config:
+              provider: codex-primary
+              toolName: subagent_codex_primary
+              backgroundMode: one-shot
+              maxDepth: provider-managed
+          - id: tool-subagent-codex-secondary
             name: '@deepseek-ai/dsh-tool-subagent'
             config:
-              provider: codex
-              toolName: subagent_codex
+              provider: codex-secondary
+              toolName: subagent_codex_secondary
               backgroundMode: one-shot
               maxDepth: provider-managed

examples/acp-agent/product-subagent-codex.cordis.yml

@@ -1,20 +1,31 @@
-# Add the native Codex product provider and its preset-shaped one-shot tool to
-# the real ACP composition. The model is told not to call it; the scenario pins
-# the assembled request schema without starting Codex.
+# Add two named Codex product providers and their preset-shaped one-shot tools
+# to the real ACP composition. The model is told not to call them; the scenario
+# pins both assembled request schemas without starting Codex.
 - id: base
   name: '@deepseek-ai/cordis-plugin-include'
   config:
     path: ./cordis.yml
     patches:
       - insert:
-          - id: subagent-codex
+          - id: subagent-codex-primary
             name: '@deepseek-ai/dsh-subagent-codex'
             config:
-              permissionMode: approve-for-me
-          - id: tool-subagent-codex
+              providerName: codex-primary
+          - id: subagent-codex-secondary
+            name: '@deepseek-ai/dsh-subagent-codex'
+            config:
+              providerName: codex-secondary
+          - id: tool-subagent-codex-primary
+            name: '@deepseek-ai/dsh-tool-subagent'
+            config:
+              provider: codex-primary
+              toolName: subagent_codex_primary
+              backgroundMode: one-shot
+              maxDepth: provider-managed
+          - id: tool-subagent-codex-secondary
             name: '@deepseek-ai/dsh-tool-subagent'
             config:
-              provider: codex
-              toolName: subagent_codex
+              provider: codex-secondary
+              toolName: subagent_codex_secondary
               backgroundMode: one-shot
               maxDepth: provider-managed

examples/acp-agent/tests/acp.snapshot.ts

@@ -185,7 +185,9 @@ const SCENARIOS: Scenario[] = [
     hasModelTurn: true,
     recorded: false,
     overridden: true,
-    headerClass: 'product-subagent-codex',
+    pinsHeader: true,
+    headerClass: 'product-subagent-result-diagnostic',
+    systemPromptSource: 'product-subagent-codex',
     configPath: PRODUCT_SUBAGENT_RESULT_DIAGNOSTIC_CONFIG,
   },
   {

examples/acp-agent/tests/fixtures/subagent/subagent-claude-code/cordis.yml

@@ -1,5 +1,5 @@
-# Test-only composition of the Claude Code one-shot tool around its Bundle-supplied provider.
-# The owning e2e applies the package's real patch and never invokes a model or product process.
+# Test-only composition of Codex, the Bundle-supplied default Claude provider,
+# and two named Claude instances. It never invokes a model or product process.
 - id: fixture
   name: './fixture.ts'
 
@@ -9,6 +9,27 @@
 - id: subprocess
   name: '@deepseek-ai/dsh-subprocess-local'
 
+- id: subagent-codex
+  name: '@deepseek-ai/dsh-subagent-codex'
+
+- id: subagent-claude-primary
+  name: '@deepseek-ai/dsh-subagent-claude-code'
+  config:
+    providerName: claude-primary
+
+- id: subagent-claude-secondary
+  name: '@deepseek-ai/dsh-subagent-claude-code'
+  config:
+    providerName: claude-secondary
+
+- id: tool-subagent-codex
+  name: '@deepseek-ai/dsh-tool-subagent'
+  config:
+    provider: codex
+    toolName: subagent_codex
+    backgroundMode: one-shot
+    maxDepth: 'provider-managed'
+
 - id: tool-subagent-claude-code
   name: '@deepseek-ai/dsh-tool-subagent'
   config:
@@ -17,6 +38,22 @@
     backgroundMode: one-shot
     maxDepth: 'provider-managed'
 
+- id: tool-subagent-claude-primary
+  name: '@deepseek-ai/dsh-tool-subagent'
+  config:
+    provider: claude-primary
+    toolName: subagent_claude_primary
+    backgroundMode: one-shot
+    maxDepth: 'provider-managed'
+
+- id: tool-subagent-claude-secondary
+  name: '@deepseek-ai/dsh-tool-subagent'
+  config:
+    provider: claude-secondary
+    toolName: subagent_claude_secondary
+    backgroundMode: one-shot
+    maxDepth: 'provider-managed'
+
 - id: agent-spine
   name: '@deepseek-ai/dsh-agent-spine-demo'
   config:

examples/acp-agent/tests/fixtures/subagent/subagent-claude-code/driver.ts

@@ -24,31 +24,56 @@ const ctx = await boot(
 )
 
 try {
-  const provider = ctx.subagents.getProvider('claude-code')
-  if (provider === undefined) throw new Error('claude-code provider was not registered')
-  const tool = ctx.tools.schemas().find(schema => schema.name === 'subagent_claude_code')
-  if (tool === undefined) throw new Error('subagent_claude_code tool was not registered')
-  const properties = tool.parameters.properties
-  if (typeof properties !== 'object' || properties === null || Array.isArray(properties)) {
-    throw new Error('subagent_claude_code has invalid parameter properties')
-  }
-
-  process.stdout.write(`${JSON.stringify({
-    providers: ctx.subagents.list(),
-    provider: {
+  const providerNames = [
+    'codex',
+    'claude-code',
+    'claude-primary',
+    'claude-secondary',
+  ] as const
+  const toolNames = [
+    'subagent_codex',
+    'subagent_claude_code',
+    'subagent_claude_primary',
+    'subagent_claude_secondary',
+  ] as const
+  const providers = providerNames.map((providerName) => {
+    const provider = ctx.subagents.getProvider(providerName)
+    if (provider === undefined) {
+      throw new Error(`${providerName} provider was not registered`)
+    }
+    return {
       name: provider.name,
       capabilities: provider.capabilities,
       inheritsParentContext: provider.inheritsParentContext,
-    },
-    tool: {
+    }
+  })
+  const tools = toolNames.map((toolName) => {
+    const tool = ctx.tools.schemas().find(schema => schema.name === toolName)
+    if (tool === undefined) throw new Error(`${toolName} tool was not registered`)
+    const properties = tool.parameters.properties
+    if (
+      typeof properties !== 'object'
+      || properties === null
+      || Array.isArray(properties)
+    ) {
+      throw new Error(`${toolName} has invalid parameter properties`)
+    }
+    return {
       name: tool.name,
       parameterNames: Object.keys(properties).sort(),
       required: tool.parameters.required,
-    },
-    jobTools: ctx.tools.schemas()
-      .map(schema => schema.name)
-      .filter(name => name === 'job_kill' || name === 'job_list' || name === 'job_output')
-      .sort(),
+    }
+  })
+  const jobTools = ctx.tools.schemas()
+    .map(schema => schema.name)
+    .filter(name => name === 'job_kill' || name === 'job_list' || name === 'job_output')
+    .sort()
+
+  process.stdout.write(`${JSON.stringify({
+    registeredProviders: ctx.subagents.list(),
+    providers,
+    tools,
+    jobTools,
     starts,
   })}\n`)
 } finally {

examples/acp-agent/tests/fixtures/subagent/subagent-codex/cordis.yml

@@ -1,4 +1,4 @@
-# Test-only composition of the Codex one-shot tool around its Bundle-supplied provider.
+# Test-only composition of the Bundle-supplied default and two named Codex instances.
 # The owning e2e applies the package's real patch and never invokes the model or Codex.
 - id: fixture
   name: './fixture.ts'
@@ -9,6 +9,16 @@
 - id: subprocess
   name: '@deepseek-ai/dsh-subprocess-local'
 
+- id: subagent-codex-primary
+  name: '@deepseek-ai/dsh-subagent-codex'
+  config:
+    providerName: codex-primary
+
+- id: subagent-codex-secondary
+  name: '@deepseek-ai/dsh-subagent-codex'
+  config:
+    providerName: codex-secondary
+
 - id: tool-subagent-codex
   name: '@deepseek-ai/dsh-tool-subagent'
   config:
@@ -17,6 +27,22 @@
     backgroundMode: one-shot
     maxDepth: 'provider-managed'
 
+- id: tool-subagent-codex-primary
+  name: '@deepseek-ai/dsh-tool-subagent'
+  config:
+    provider: codex-primary
+    toolName: subagent_codex_primary
+    backgroundMode: one-shot
+    maxDepth: 'provider-managed'
+
+- id: tool-subagent-codex-secondary
+  name: '@deepseek-ai/dsh-tool-subagent'
+  config:
+    provider: codex-secondary
+    toolName: subagent_codex_secondary
+    backgroundMode: one-shot
+    maxDepth: 'provider-managed'
+
 - id: agent-spine
   name: '@deepseek-ai/dsh-agent-spine-demo'
   config:

examples/acp-agent/tests/fixtures/subagent/subagent-codex/driver.ts

@@ -24,14 +24,40 @@ const ctx = await boot(
 )
 
 try {
-  const provider = ctx.subagents.getProvider('codex')
-  if (provider === undefined) throw new Error('Codex provider was not registered')
-  const tool = ctx.tools.schemas().find(schema => schema.name === 'subagent_codex')
-  if (tool === undefined) throw new Error('subagent_codex tool was not registered')
-  const properties = tool.parameters.properties
-  if (typeof properties !== 'object' || properties === null || Array.isArray(properties)) {
-    throw new Error('subagent_codex tool has invalid parameter properties')
-  }
+  const providerNames = ['codex', 'codex-primary', 'codex-secondary'] as const
+  const toolNames = [
+    'subagent_codex',
+    'subagent_codex_primary',
+    'subagent_codex_secondary',
+  ] as const
+  const providers = providerNames.map((providerName) => {
+    const provider = ctx.subagents.getProvider(providerName)
+    if (provider === undefined) {
+      throw new Error(`${providerName} provider was not registered`)
+    }
+    return {
+      name: provider.name,
+      capabilities: provider.capabilities,
+      inheritsParentContext: provider.inheritsParentContext,
+    }
+  })
+  const tools = toolNames.map((toolName) => {
+    const tool = ctx.tools.schemas().find(schema => schema.name === toolName)
+    if (tool === undefined) throw new Error(`${toolName} tool was not registered`)
+    const properties = tool.parameters.properties
+    if (
+      typeof properties !== 'object'
+      || properties === null
+      || Array.isArray(properties)
+    ) {
+      throw new Error(`${toolName} has invalid parameter properties`)
+    }
+    return {
+      name: tool.name,
+      parameterNames: Object.keys(properties).sort(),
+      required: tool.parameters.required,
+    }
+  })
   const jobTools = ctx.tools.schemas()
     .map(schema => schema.name)
     .filter(name => name === 'job_kill' || name === 'job_list' || name === 'job_output')
@@ -39,16 +65,8 @@ try {
 
   process.stdout.write(`${JSON.stringify({
     providers: ctx.subagents.list(),
-    provider: {
-      name: provider.name,
-      capabilities: provider.capabilities,
-      inheritsParentContext: provider.inheritsParentContext,
-    },
-    tool: {
-      name: tool.name,
-      parameterNames: Object.keys(properties).sort(),
-      required: tool.parameters.required,
-    },
+    providerDetails: providers,
+    tools,
     jobTools,
     starts,
   })}\n`)

examples/acp-agent/tests/snapshots/product-subagent-both/tool-schemas.expected.json

@@ -307,7 +307,7 @@
       }
     },
     {
-      "name": "subagent_claude_code",
+      "name": "subagent_claude_primary",
       "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent returns its result, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. This call waits for the result by default. Set `run_in_background: true` to return a job id; collect with `job_output` and stop with `job_kill`.",
       "parameters": {
         "type": "object",
@@ -332,7 +332,57 @@
       }
     },
     {
-      "name": "subagent_codex",
+      "name": "subagent_claude_secondary",
+      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent returns its result, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. This call waits for the result by default. Set `run_in_background: true` to return a job id; collect with `job_output` and stop with `job_kill`.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "description": {
+            "type": "string",
+            "description": "A short (3-5 word) description of the delegated task, for display."
+          },
+          "prompt": {
+            "type": "string",
+            "description": "The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."
+          },
+          "run_in_background": {
+            "type": "boolean",
+            "description": "Whether to run as a background job and return its id. Defaults to false; collect with job_output or stop with job_kill."
+          }
+        },
+        "required": [
+          "description",
+          "prompt"
+        ]
+      }
+    },
+    {
+      "name": "subagent_codex_primary",
+      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent returns its result, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. This call waits for the result by default. Set `run_in_background: true` to return a job id; collect with `job_output` and stop with `job_kill`.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "description": {
+            "type": "string",
+            "description": "A short (3-5 word) description of the delegated task, for display."
+          },
+          "prompt": {
+            "type": "string",
+            "description": "The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."
+          },
+          "run_in_background": {
+            "type": "boolean",
+            "description": "Whether to run as a background job and return its id. Defaults to false; collect with job_output or stop with job_kill."
+          }
+        },
+        "required": [
+          "description",
+          "prompt"
+        ]
+      }
+    },
+    {
+      "name": "subagent_codex_secondary",
       "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent returns its result, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. This call waits for the result by default. Set `run_in_background: true` to return a job id; collect with `job_output` and stop with `job_kill`.",
       "parameters": {
         "type": "object",

examples/acp-agent/tests/snapshots/product-subagent-codex/tool-schemas.expected.json

@@ -307,7 +307,32 @@
       }
     },
     {
-      "name": "subagent_codex",
+      "name": "subagent_codex_primary",
+      "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent returns its result, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. This call waits for the result by default. Set `run_in_background: true` to return a job id; collect with `job_output` and stop with `job_kill`.",
+      "parameters": {
+        "type": "object",
+        "properties": {
+          "description": {
+            "type": "string",
+            "description": "A short (3-5 word) description of the delegated task, for display."
+          },
+          "prompt": {
+            "type": "string",
+            "description": "The complete, self-contained task for the subagent. It does not share this conversation's context, so include everything it needs."
+          },
+          "run_in_background": {
+            "type": "boolean",
+            "description": "Whether to run as a background job and return its id. Defaults to false; collect with job_output or stop with job_kill."
+          }
+        },
+        "required": [
+          "description",
+          "prompt"
+        ]
+      }
+    },
+    {
+      "name": "subagent_codex_secondary",
       "description": "Delegate a self-contained task to a subagent (a separate agent that works in its own context) to offload focused, independent work — research, a scoped implementation, an analysis — so it does not consume this conversation's context. The subagent returns its result, not its intermediate steps. Give it a complete, standalone prompt: it does not see this conversation. This call waits for the result by default. Set `run_in_background: true` to return a job id; collect with `job_output` and stop with `job_kill`.",
       "parameters": {
         "type": "object",

packages/bundle/web-app/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/bundle/web-app/README.md
-README.md: 90d1566b5a7a25f6a827079c4a8ab776e05cc7a3
-README.zh.md: b7156bcab66b53964bb2f0e1c87d9e9a806e3f75
+README.md: 28fb5b3dcfc7fbb912493a6b97495e2ed5a3eece
+README.zh.md: 92157f05497e53c48506666a3a53d638d98a7c9e

packages/bundle/web-app/README.md

@@ -4,6 +4,10 @@ English | [中文](README.zh.md)
 
 The dsh browser-surface bundle. [`cordis.patch.yml`](cordis.patch.yml) rides over [`dsh-base`](../base/README.md): it sets the coding persona, inserts the Web host rows (webserver, API gateway, workspace, projection cache, storage) and the browser plugin roster, the always-on client-plugin reload chain ([`dsh-client-hmr`](../../client/hmr/README.md), idle until a rebuild watcher rewrites client bundles), and mounts this package's `web-runtime` glue plugin (config `{printUrl, surfaceContext, trustedHosts}`). That plugin resolves the built frontend dist through `@deepseek-ai/dsh-web-frontend`'s exports, samples bind-dependent LAN trust once, provides it as `webRuntime` to the browser-trust fence and client roster, mounts the [`frontend-static`](../../host/frontend-static/README.md) fallback owner, registers the harness-source and web-surface prompt sections plus the bash-visible `DSH_WEB_URL` runtime variable when `surfaceContext` is true, and prints the `dsh web:` URL line when `printUrl` is true, after its Loader tree settles so a sibling failure cannot announce a dead app. This bundle also owns the app command line: the ordinary `web-startup` provider ([`src/startup.ts`](src/startup.ts)) injects `ctx.cmdlineArgs` ([`dsh-cmdline`](../../boot/cmdline/README.md)), parses `--host`, `--port`, repeatable `--trusted-host`, and the app's `--help`, then provides `webStartup`. It rejects `--host 0.0.0.0` before publishing that service because the CLI intentionally does not support all-interfaces binding yet. Flag-configured rows inject the service and read it directly from lazy config, so nothing binds a port before argument resolution and `dsh --profile web --help` starts no server. [`dsh-headless`](../headless/README.md) is a sibling surface over the same base and does not mount this bundle.
 
+## Model retry defaults
+
+Web uses the shared bounded normal default of five eligible retries after the initial request. The `deepseek-official` route and settings-added pi-ai routes use that default when they omit `retryPolicy`; explicit provider policies still win. Web adds no retry-specific composition override, so the same omission behavior applies to non-Web profiles.
+
 ## Model Experience
 
 ### Harness-source and Web-surface context

packages/bundle/web-app/README.zh.md

@@ -4,6 +4,10 @@
 
 dsh 浏览器表层组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在 [`dsh-base`](../base/README.md) 之上：设置 coding persona，插入 Web 宿主行（webserver、API 网关、workspace、投影缓存、存储）、浏览器插件名录与始终挂载的客户端插件重载链（[`dsh-client-hmr`](../../client/hmr/README.md)，在重建 watcher 改写客户端 bundle 之前保持空闲），并挂载本包的 `web-runtime` 粘合插件（配置为 `{printUrl, surfaceContext, trustedHosts}`）。该插件通过 `@deepseek-ai/dsh-web-frontend` 的 exports 解析已构建的前端 dist，只采样一次依赖 bind 的 LAN 信任信息并将其作为 `webRuntime` 提供给浏览器信任栅栏和客户端名录，挂载 [`frontend-static`](../../host/frontend-static/README.md) 回退席位所有者，在 `surfaceContext` 为 true 时注册 Harness 源码与 Web 表层提示词段落，以及 bash 可见的 `DSH_WEB_URL` 运行时变量，并在 `printUrl` 为 true 时等自身的 Loader 配置树结算后再打印 `dsh web:` URL 行，避免兄弟行失败时公告一个已失效的应用。本组合包还持有应用命令行：普通 `web-startup` 提供方（[`src/startup.ts`](src/startup.ts)）注入 `ctx.cmdlineArgs`（[`dsh-cmdline`](../../boot/cmdline/README.md)），解析 `--host`、`--port`、可重复的 `--trusted-host` 以及应用自己的 `--help`，再提供 `webStartup`。它会在发布该服务前拒绝 `--host 0.0.0.0`，因为 CLI 目前有意不支持绑定所有网络接口。由 flag 配置的行会注入该服务，并在惰性配置中直接读取它，因此参数解析完成前不会有任何东西绑定端口，`dsh --profile web --help` 也不会启动服务器。[`dsh-headless`](../headless/README.md) 是同一 base 之上的同级表层，不挂载本组合包。
 
+## 模型重试默认值
+
+Web 使用共享的有界 normal 默认值，在首次请求后最多再重试五次符合条件的失败。`deepseek-official` 与由 settings 新增的 pi-ai 路由在省略 `retryPolicy` 时使用该默认值；显式提供方策略仍然优先。Web 不再增加重试专用的组合覆盖，因此非 Web profile 的省略行为与之相同。
+
 ## 模型体验
 
 ### Harness 源码与 Web 表层上下文

packages/client/locale/tests/apply.client.spec.ts

@@ -4,8 +4,7 @@
 import { Context } from '@deepseek-ai/cordis'
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { SlotRegistry } from '@deepseek-ai/dsh-client-runtime/client'
-import { SettingsSchemaService } from '@deepseek-ai/dsh-client-ui-settings/src/client/schema.ts'
-import { SettingsScopeBinder } from '@deepseek-ai/dsh-client-ui-settings/src/client/settings-scope.ts'
+import { apply as settingsApply, inject as settingsInject } from '@deepseek-ai/dsh-client-ui-settings/client'
 import { TestRemote } from '@deepseek-ai/dsh-client-test-runtime'
 import {
   apply, inject, SETTINGS_NS,
@@ -48,7 +47,7 @@ async function bench() {
   ctx.provide('connection', { api: { settings: { describe, mutate } }, isLoopback: true } as never)
   // The settings transport and the forwarded-event port the plugin injects.
   new TestRemote(ctx)
-  await ctx.plugin(SettingsScopeBinder, new SettingsSchemaService(ctx)).await()
+  await ctx.plugin({ inject: [...settingsInject], apply: settingsApply }).await()
   return {
     ctx, slots: ctx.get('slots') as SlotRegistry, describe, mutate,
     setHostPreference: (next: string | undefined) => { preference = next; revision += 1 },
@@ -134,7 +133,10 @@ describe('locale apply', () => {
 
   it('loads and refreshes the explicit Host preference after nonblocking activation', async () => {
     const b = await bench()
+    // The shared mirror read once at bench time; a Host-side change reaches it
+    // through the document invalidation, exactly as production announces one.
     b.setHostPreference('en')
+    b.ctx.remote.$dispatch('settings/document-updated', [LOCALE_SETTINGS_NAMESPACE, 0])
     declareItems(b.slots)
     await b.ctx.plugin({ inject: [...inject], apply }).await()
     const locale = b.ctx.get('locale') as LocaleRuntime
@@ -145,7 +147,7 @@ describe('locale apply', () => {
     b.setHostPreference('en')
     b.ctx.remote.$dispatch('settings/document-updated', [LOCALE_SETTINGS_NAMESPACE, 0])
     await vi.waitFor(() => { expect(locale.getLocale().active).toBe('en') })
-    expect(b.describe).toHaveBeenCalledTimes(3)
+    expect(b.describe).toHaveBeenCalledTimes(4)
   })
 
   it('recovers after an HMR collapse of the declaring entry (stale disposer must not block)', async () => {

packages/client/ui-agent-preset/src/client/index.ts

@@ -46,7 +46,7 @@ export type { AgentPresetOption, AgentPresetSettingsState } from './settings-sto
 export { AGENT_PRESET_SETTINGS_NS, writeDefaultPreset } from './settings-store.ts'
 
 /** Required services (cordis fiber inject). */
-export const inject = ['slots', 'locale', 'connection', 'remote']
+export const inject = ['slots', 'locale', 'connection', 'remote', 'settingsScope']
 
 /**
  * Mount the General-settings row.
@@ -54,7 +54,7 @@ export const inject = ['slots', 'locale', 'connection', 'remote']
  */
 export function apply(ctx: ClientContext): void {
   const { api } = ctx.get('connection') as ConnectionHandle
-  const controller = new AgentPresetSettingsController(api)
+  const controller = new AgentPresetSettingsController(api, ctx.settingsScope.describe())
   // One roster, four surfaces. The chip is registered in a later scope, so it
   // subscribes here rather than being reached from this one.
   const rosterReaders = new Set<() => void>()

packages/client/ui-agent-preset/src/client/settings-store.ts

@@ -9,6 +9,7 @@
 
 import type { IApiClient } from '@deepseek-ai/dsh-api-remotes/client'
 import { createSnapshotStore, type SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SettingsDescribeFace } from '@deepseek-ai/dsh-client-ui-settings/client'
 
 /** The agent-preset settings namespace on the host wire. */
 export const AGENT_PRESET_SETTINGS_NS = 'agent-presets'
@@ -191,7 +192,14 @@ export class AgentPresetSettingsController {
   /** Row snapshot the renderer subscribes to. */
   readonly store: SnapshotStore<AgentPresetSettingsState> = createSnapshotStore(INITIAL)
 
-  constructor(private readonly api: IApiClient) {}
+  /**
+   * @param api - the agent-preset and settings wire faces (roster and default write).
+   * @param describeFace - the shared mirror's describe face (writability source).
+   */
+  constructor(
+    private readonly api: IApiClient,
+    private readonly describeFace: SettingsDescribeFace,
+  ) {}
 
   private set(patch: Partial<AgentPresetSettingsState>): void {
     this.store.set({ ...this.store.getSnapshot(), ...patch })
@@ -212,24 +220,20 @@ export class AgentPresetSettingsController {
       this.set({ status: 'unavailable', options: [], currentValue: '' })
       return
     }
-    try {
-      // The roster says what may be chosen; `settings.describe` says whether
-      // this browser may write the choice down. A non-loopback browser reaches
-      // neither method, so a refused describe leaves the row read-only rather
-      // than offering a control whose write the Host would refuse.
-      const described = await this.api.settings.describe({})
-      this.set({
-        status: 'ready',
-        error: null,
-        writable: described.result.ok && described.result.value.writable,
-        options: presetOptions(presets),
-        // A roster can mark nothing default: settings can name a preset that
-        // was since deleted, and the picker still has to show something.
-        currentValue: presets.find(preset => preset.isDefault)?.id ?? first.id,
-      })
-    } catch (error) {
-      this.set({ status: 'error', error: messageOf(error) })
-    }
+    // The roster says what may be chosen; the shared mirror says whether this
+    // browser may write the choice down. A non-loopback browser's mirror never
+    // answers, so the row stays read-only rather than offering a control
+    // whose write the Host would refuse.
+    await this.describeFace.ensure()
+    this.set({
+      status: 'ready',
+      error: null,
+      writable: this.describeFace.getSnapshot().view?.writable ?? false,
+      options: presetOptions(presets),
+      // A roster can mark nothing default: settings can name a preset that
+      // was since deleted, and the picker still has to show something.
+      currentValue: presets.find(preset => preset.isDefault)?.id ?? first.id,
+    })
   }
 
   /**

packages/client/ui-agent-preset/tests/apply.client.spec.ts

@@ -11,6 +11,7 @@ import { resolveSlotLabel } from '@deepseek-ai/dsh-client-ui-slots'
 import { SlotRegistry } from '@deepseek-ai/dsh-client-runtime/client'
 import { LocaleRuntime } from '@deepseek-ai/dsh-client-locale/client'
 import { TestRemote, usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
+import { apply as settingsApply, inject as settingsInject } from '@deepseek-ai/dsh-client-ui-settings/client'
 import { apply, inject } from '@deepseek-ai/dsh-client-ui-agent-preset/client'
 import { AgentPresetLabel } from '../src/client/AgentPresetLabel.tsx'
 import type { AgentPresetLabelInjected } from '../src/client/AgentPresetLabel.tsx'
@@ -117,6 +118,7 @@ async function bench() {
       },
     },
   } as never)
+  await ctx.plugin({ inject: [...settingsInject], apply: settingsApply }).await()
   return { ctx, slots: ctx.get('slots') as SlotRegistry, calls, moveDefault }
 }
 
@@ -178,7 +180,7 @@ function sessionsDouble(state: {
 
 describe('ui-agent-preset apply', () => {
   it('declares the services it uses', () => {
-    expect(inject).toEqual(['slots', 'locale', 'connection', 'remote'])
+    expect(inject).toEqual(['slots', 'locale', 'connection', 'remote', 'settingsScope'])
   })
 
   it('registers the General row and the settings section', async () => {

packages/client/ui-agent-preset/tests/settings-store.client.spec.ts

@@ -7,9 +7,15 @@
 
 import { describe, expect, it } from 'vitest'
 import type { IApiClient } from '@deepseek-ai/dsh-api-remotes/client'
+import { SettingsDescribeMirror } from '@deepseek-ai/dsh-client-ui-settings/src/client/settings-mirror.ts'
 import {
   AGENT_PRESET_SETTINGS_NS, AgentPresetSettingsController, messageOf,
 } from '../src/client/settings-store.ts'
+
+/** Controller over a real mirror derived from the same fake wire. */
+function derivedController(api: IApiClient) {
+  return new AgentPresetSettingsController(api, new SettingsDescribeMirror(api))
+}
 import { AgentPresetSeatController } from '../src/client/seat-store.ts'
 import type { SeatSessionSummary } from '../src/client/seat-store.ts'
 
@@ -60,7 +66,7 @@ function fakeApi(
 
 describe('the agent-preset settings controller', () => {
   it('disables the control when this browser may not write settings', async () => {
-    const controller = new AgentPresetSettingsController(fakeApi([
+    const controller = derivedController(fakeApi([
       { id: 'standard', trust: 'system', isDefault: true },
     ], { readOnly: true }))
 
@@ -74,7 +80,7 @@ describe('the agent-preset settings controller', () => {
   })
 
   it('derives options and the current default from one roster call', async () => {
-    const controller = new AgentPresetSettingsController(fakeApi([
+    const controller = derivedController(fakeApi([
       { id: 'standard', trust: 'system', isDefault: true },
       { id: 'mine', trust: 'user', isDefault: false },
     ]))
@@ -91,7 +97,7 @@ describe('the agent-preset settings controller', () => {
   })
 
   it('offers no broken preset: the pickers choose the NEXT session\'s composition', async () => {
-    const controller = new AgentPresetSettingsController(fakeApi([
+    const controller = derivedController(fakeApi([
       { id: 'standard', trust: 'system', isDefault: true },
       { id: 'damaged', trust: 'user', isDefault: false, broken: 'the composition is not valid YAML' },
     ] as never))
@@ -105,7 +111,7 @@ describe('the agent-preset settings controller', () => {
   })
 
   it('carries the display metadata a preset published', async () => {
-    const controller = new AgentPresetSettingsController(fakeApi([
+    const controller = derivedController(fakeApi([
       { id: 'standard', trust: 'system', isDefault: true, name: '标准模式', description: '完整的编码 agent。' },
     ] as never))
 
@@ -119,7 +125,7 @@ describe('the agent-preset settings controller', () => {
   })
 
   it('reports an empty roster as unavailable, not as an error', async () => {
-    const controller = new AgentPresetSettingsController(fakeApi([]))
+    const controller = derivedController(fakeApi([]))
 
     await controller.load()
 
@@ -131,7 +137,7 @@ describe('the agent-preset settings controller', () => {
 
   it('writes only the default field, into the agent-presets namespace', async () => {
     const writes: Recorded[] = []
-    const controller = new AgentPresetSettingsController(fakeApi([
+    const controller = derivedController(fakeApi([
       { id: 'standard', trust: 'system', isDefault: true },
       { id: 'minimal', trust: 'system', isDefault: false },
     ], { writes }))
@@ -144,7 +150,7 @@ describe('the agent-preset settings controller', () => {
   })
 
   it('restores the previous value and surfaces the message when the write fails', async () => {
-    const controller = new AgentPresetSettingsController(fakeApi([
+    const controller = derivedController(fakeApi([
       { id: 'standard', trust: 'system', isDefault: true },
       { id: 'minimal', trust: 'system', isDefault: false },
     ], { failWrite: 'read-only settings' }))
@@ -160,7 +166,7 @@ describe('the agent-preset settings controller', () => {
 
   it('ignores a pick that is already the default', async () => {
     const writes: Recorded[] = []
-    const controller = new AgentPresetSettingsController(fakeApi([
+    const controller = derivedController(fakeApi([
       { id: 'standard', trust: 'system', isDefault: true },
     ], { writes }))
     await controller.load()
@@ -171,7 +177,7 @@ describe('the agent-preset settings controller', () => {
   })
 
   it('surfaces a roster failure without claiming the deployment has no presets', async () => {
-    const controller = new AgentPresetSettingsController(fakeApi([], { failList: 'host down' }))
+    const controller = derivedController(fakeApi([], { failList: 'host down' }))
 
     await controller.load()
 
@@ -183,7 +189,7 @@ describe('the agent-preset settings controller', () => {
   it('shows the first preset when the roster marks none default', async () => {
     // Settings can name a preset that was since deleted; the picker still has
     // to show something rather than an empty control.
-    const controller = new AgentPresetSettingsController(fakeApi([
+    const controller = derivedController(fakeApi([
       { id: 'standard', trust: 'system', isDefault: false },
       { id: 'mine', trust: 'user', isDefault: false },
     ]))
@@ -195,7 +201,7 @@ describe('the agent-preset settings controller', () => {
 
   it('ignores a load while one is already in flight', async () => {
     const writes: Recorded[] = []
-    const controller = new AgentPresetSettingsController(fakeApi(
+    const controller = derivedController(fakeApi(
       [{ id: 'standard', trust: 'system', isDefault: true }], { writes }))
 
     await Promise.all([controller.load(), controller.load()])
@@ -211,7 +217,7 @@ describe('the agent-preset settings controller', () => {
   })
 
   it('reports a transport that rejects rather than answering', async () => {
-    const controller = new AgentPresetSettingsController({
+    const controller = derivedController({
       agentPresets: { list: () => Promise.reject(new Error('socket closed')) },
     } as unknown as IApiClient)
 
@@ -221,7 +227,7 @@ describe('the agent-preset settings controller', () => {
   })
 
   it('reports a transport that rejects mid-write and keeps the old default showing', async () => {
-    const controller = new AgentPresetSettingsController(fakeApi([
+    const controller = derivedController(fakeApi([
       { id: 'standard', trust: 'system', isDefault: true },
       { id: 'mine', trust: 'user', isDefault: false },
     ], { failWriteWith: new Error('socket closed') }))
@@ -434,7 +440,7 @@ describe('the new-session chip controller', () => {
     expect(controller.store.getSnapshot().error).toBe('socket closed')
   })
 
-  it('reports a refused describe as a failure rather than a half-read row', async () => {
+  it('degrades to a read-only row while the mirror holds no answer', async () => {
     const api = {
       agentPresets: {
         list: () => Promise.resolve({
@@ -442,16 +448,19 @@ describe('the new-session chip controller', () => {
           result: { ok: true as const, value: { presets: [{ id: 'standard', trust: 'system', isDefault: true }], authorable: true } },
         }),
       },
-      // The roster answered; `settings.describe` is what rejected, and the row
-      // cannot claim a writable default it never confirmed.
+      // The roster answered; the mirror's read is what failed, so the row
+      // shows the current default without offering a write it never confirmed.
       settings: { describe: () => Promise.reject(new Error('socket closed')) },
     } as unknown as IApiClient
-    const controller = new AgentPresetSettingsController(api)
+    const controller = derivedController(api)
 
     await controller.load()
 
-    expect(controller.store.getSnapshot().status).toBe('error')
-    expect(controller.store.getSnapshot().error).toBe('socket closed')
+    expect(controller.store.getSnapshot()).toMatchObject({
+      status: 'ready',
+      writable: false,
+      currentValue: 'standard',
+    })
   })
 
 

packages/client/ui-permission-presets/src/client/index.ts

@@ -33,9 +33,7 @@ import {
 import {
   displayPermissionPreset, FULL_ACCESS_PRESET,
 } from './presentation.ts'
-import {
-  PERMISSION_SETTINGS_NS, PermissionPresetSettingsController, refreshPermissionIfLoaded,
-} from './settings-store.ts'
+import { PermissionPresetSettingsController } from './settings-store.ts'
 
 export type { PermissionRowInjected, PermissionRowProps } from './PermissionRow.tsx'
 export type {
@@ -43,7 +41,7 @@ export type {
 } from './settings-store.ts'
 
 /** Required services (cordis fiber inject). */
-export const inject = ['commandUi', 'sessions', 'slots', 'locale', 'connection', 'remote', 'settingsSchema']
+export const inject = ['commandUi', 'sessions', 'slots', 'locale', 'connection', 'remote', 'settingsScope', 'settingsSchema']
 
 const ACCESS_NS = 'permission.access'
 
@@ -113,7 +111,10 @@ export function apply(ctx: ClientContext): void {
   ctx.effect(() => ctx.locale.register('settings.permission', { zh, en }), 'ui-permission: settings row dictionaries')
 
   const connection = ctx.get('connection') as ConnectionHandle
-  const controller = new PermissionPresetSettingsController(connection.api, ctx.settingsSchema)
+  // The row follows the shared describe mirror, whose owning plugin already
+  // refreshes it on document commits and reconnects.
+  const controller = new PermissionPresetSettingsController(
+    ctx.settingsScope.describe(), connection.api, ctx.settingsSchema)
   const load = (): Promise<void> => controller.load()
   const select = (preset: string): Promise<void> => controller.select(preset)
   const injected = (): PermissionRowInjected => ({
@@ -122,20 +123,7 @@ export function apply(ctx: ClientContext): void {
     select,
   })
 
-  ctx.effect(() => {
-    const refresh = (): void => { refreshPermissionIfLoaded(controller) }
-    const disposers = [
-      ctx.remote.$on('settings/document-updated', (ns) => {
-        if (ns !== PERMISSION_SETTINGS_NS) return
-        refresh()
-      }),
-      ctx.on('connection/reset', () => { refresh() }),
-    ]
-    return () => {
-      controller.dispose()
-      for (const dispose of disposers) dispose()
-    }
-  }, 'ui-permission: settings invalidations')
+  ctx.effect(() => () => { controller.dispose() }, 'ui-permission: settings row directory')
 
   ctx.slots.inject('settings.general.item', () => ctx.slots.register({
     name: 'settings.general.item',

packages/client/ui-permission-presets/src/client/settings-store.ts

@@ -1,7 +1,9 @@
 /**
- * Permission default-settings controller. The host descriptor supplies the
- * current value and the dynamic preset enum; writes target only
- * `defaultPreset` and carry the descriptor revision.
+ * Permission default-settings controller. The permission descriptor comes
+ * from the shared describe mirror (the dynamic preset enum lives in the
+ * namespace schema, which per-namespace scopes do not carry); writes target
+ * only `defaultPreset`, carry the descriptor revision, and fold their answer
+ * back into the mirror.
  */
 
 import type {
@@ -10,7 +12,9 @@ import type {
 import {
   createSnapshotStore, type SnapshotStore,
 } from '@deepseek-ai/dsh-client-runtime/client'
-import type { SchemaNode, SettingsSchemaService } from '@deepseek-ai/dsh-client-ui-settings/client'
+import type {
+  SchemaNode, SettingsDescribeFace, SettingsSchemaService,
+} from '@deepseek-ai/dsh-client-ui-settings/client'
 import { displayPermissionPreset } from './presentation.ts'
 
 /** Permission's settings namespace on the host wire. */
@@ -74,7 +78,7 @@ export function permissionDefaultOf(view: SettingsNamespaceView, schema: Setting
   return { currentValue: value, options }
 }
 
-/** Controller joining Settings reads, writes, and pushed invalidations. */
+/** Controller deriving the row from the shared mirror and writing the default through it. */
 export class PermissionPresetSettingsController {
   /** Row snapshot consumed through a bound selector hook. */
   readonly store: SnapshotStore<PermissionSettingsState> = createSnapshotStore({
@@ -86,57 +90,50 @@ export class PermissionPresetSettingsController {
     revision: 0,
   })
 
-  private generation = 0
-  private view: SettingsNamespaceView | undefined
+  private following: (() => void) | undefined
+  private saving = false
+  private disposed = false
 
-  /** @param api - Settings wire face. */
+  /**
+   * @param describeFace - the shared mirror's read/fold face (descriptor and schema source).
+   * @param api - settings wire face for the `defaultPreset` write.
+   * @param schema - settings-owned schema operations.
+   */
   constructor(
+    private readonly describeFace: SettingsDescribeFace,
     private readonly api: Pick<IApiClient, 'settings'>,
     private readonly schema: SettingsSchemaService,
   ) {}
 
   /**
-   * Refresh the permission descriptor. Latest request wins.
-   * @returns nothing; {@link store} carries success or failure.
+   * Begin following the mirror (idempotent) and reflect its current answer.
+   * @returns settlement once the snapshot reflects the mirror.
    */
   async load(): Promise<void> {
-    const generation = ++this.generation
+    if (this.disposed) return
+    this.following ??= this.describeFace.subscribe(() => { this.derive() })
     this.store.update((state) => {
       state.status = 'loading'
       state.error = null
     })
-    try {
-      const response = await this.api.settings.describe({})
-      if (!response.result.ok) throw new Error(response.result.error.message)
-      if (generation !== this.generation) return
-      const view = response.result.value.namespaces.find(entry => entry.ns === PERMISSION_SETTINGS_NS)
-      if (view === undefined) {
-        this.view = undefined
-        this.store.update((state) => {
-          state.status = 'unavailable'
-          state.writable = false
-          state.currentValue = ''
-          state.options = []
-        })
-        return
-      }
-      this.accept(view, response.result.value.writable)
-    } catch (error) {
-      if (generation !== this.generation) return
-      this.fail(error)
-    }
+    await this.describeFace.ensure()
+    this.derive()
   }
 
   /**
    * Persist one preset as the default for subsequently created sessions.
+   * A selection made while one is already saving is ignored — the row's
+   * control is disabled during the save, so this only drops programmatic
+   * double-submits rather than user intent.
    * @param preset - advertised preset key.
    * @returns nothing; {@link store} carries success or failure.
    */
   async select(preset: string): Promise<void> {
-    const view = this.view
     const state = this.store.getSnapshot()
-    if (view === undefined || !state.writable) return
-    const generation = ++this.generation
+    const view = this.describeFace.getSnapshot().view?.namespaces
+      .find(entry => entry.ns === PERMISSION_SETTINGS_NS)
+    if (view === undefined || !state.writable || this.saving) return
+    this.saving = true
     this.store.update((draft) => {
       draft.status = 'saving'
       draft.error = null
@@ -147,32 +144,70 @@ export class PermissionPresetSettingsController {
         ops: [{ op: 'set', path: ['defaultPreset'], value: preset }],
         expectedRevision: view.revision,
       })
-      if (generation !== this.generation) return
       if (!response.result.ok) throw new Error(response.result.error.message)
-      this.accept(response.result.value, true)
+      this.saving = false
+      if (this.disposed) return
+      // The mirror publish reaches this row's own subscription, so the fold
+      // is also what republishes the accepted value here.
+      this.describeFace.acceptView(response.result.value)
     } catch (error) {
-      if (generation !== this.generation) return
+      this.saving = false
+      if (this.disposed) return
       this.fail(error)
     }
   }
 
-  /** Stop in-flight responses from publishing after plugin disposal. */
+  /** Stop following the mirror; later publishes leave the snapshot alone. */
   dispose(): void {
-    this.generation += 1
-    this.view = undefined
+    this.disposed = true
+    this.following?.()
+    this.following = undefined
   }
 
-  private accept(view: SettingsNamespaceView, writable: boolean): void {
-    const resolved = permissionDefaultOf(view, this.schema)
-    this.view = view
-    this.store.update((state) => {
-      state.status = 'ready'
-      state.error = null
-      state.writable = writable
-      state.currentValue = resolved.currentValue
-      state.options = resolved.options
-      state.revision = view.revision
-    })
+  private derive(): void {
+    if (this.disposed || this.saving) return
+    const mirrored = this.describeFace.getSnapshot()
+    if (mirrored.status === 'unavailable') {
+      // The terminal non-loopback state: settings RPCs are loopback-only, so
+      // the row hides itself exactly like an unserved namespace.
+      this.store.update((state) => {
+        state.status = 'unavailable'
+        state.writable = false
+        state.currentValue = ''
+        state.options = []
+      })
+      return
+    }
+    if (mirrored.view === undefined) {
+      // A held failure with no answer is a failed row; without one the read
+      // is still in flight and the row keeps its loading state.
+      if (mirrored.error !== null) this.fail(new Error(mirrored.error))
+      return
+    }
+    const view = mirrored.view.namespaces.find(entry => entry.ns === PERMISSION_SETTINGS_NS)
+    if (view === undefined) {
+      this.store.update((state) => {
+        state.status = 'unavailable'
+        state.writable = false
+        state.currentValue = ''
+        state.options = []
+      })
+      return
+    }
+    try {
+      const resolved = permissionDefaultOf(view, this.schema)
+      const { writable } = mirrored.view
+      this.store.update((state) => {
+        state.status = 'ready'
+        state.error = null
+        state.writable = writable
+        state.currentValue = resolved.currentValue
+        state.options = resolved.options
+        state.revision = view.revision
+      })
+    } catch (error) {
+      this.fail(error)
+    }
   }
 
   private fail(error: unknown): void {
@@ -182,12 +217,3 @@ export class PermissionPresetSettingsController {
     })
   }
 }
-
-/**
- * Refetch only after the row has opened once.
- * @param controller - permission settings controller.
- */
-export function refreshPermissionIfLoaded(controller: PermissionPresetSettingsController): void {
-  if (controller.store.getSnapshot().status === 'idle') return
-  void controller.load()
-}

packages/client/ui-permission-presets/tests/browser-plugin.client.spec.ts

@@ -13,8 +13,8 @@ import { describe, expect, it } from 'vitest'
 import { SlotRegistry, type SessionId } from '@deepseek-ai/dsh-client-runtime/client'
 import { LocaleRuntime } from '@deepseek-ai/dsh-client-locale/client'
 import { TestRemote } from '@deepseek-ai/dsh-client-test-runtime'
+import { apply as settingsApply, inject as settingsInject } from '@deepseek-ai/dsh-client-ui-settings/client'
 import type { CommandDecoration } from '@deepseek-ai/dsh-client-ui-commands/client'
-import { SettingsSchemaService } from '@deepseek-ai/dsh-client-ui-settings/src/client/schema.ts'
 import type { PermissionSelect } from '@deepseek-ai/dsh-permission-presets/client'
 import {
   PermissionRow, type PermissionRowInjected,
@@ -42,7 +42,6 @@ async function bench() {
   // The plugin injects `remote`; forwarded events reach it through the same
   // `$dispatch` handoff the connection sink makes.
   new TestRemote(ctx)
-  new SettingsSchemaService(ctx)
   ctx.slots.register({
     name: 'root',
     children: {
@@ -60,6 +59,7 @@ async function bench() {
       },
     },
   } as never)
+  await ctx.plugin({ inject: [...settingsInject], apply: settingsApply }).await()
   let decoration: CommandDecoration | undefined
   ctx.provide('commandUi', {
     decorate(c: CommandDecoration) {

packages/client/ui-permission-presets/tests/permission-presets-row.client.spec.tsx

@@ -7,8 +7,17 @@ import type { SettingsNamespaceView } from '@deepseek-ai/dsh-api-remotes/client'
 import { SettingsSchemaService } from '@deepseek-ai/dsh-client-ui-settings/src/client/schema.ts'
 import { PermissionRow, type PermissionRowProps } from '../src/client/PermissionRow.tsx'
 import { en } from '../src/client/locales.ts'
+import { SettingsDescribeMirror } from '@deepseek-ai/dsh-client-ui-settings/src/client/settings-mirror.ts'
 import { PermissionPresetSettingsController } from '../src/client/settings-store.ts'
 
+const schema = new SettingsSchemaService(new Context())
+
+/** Controller over a real mirror derived from the same fake wire. */
+function derivedController(api: { settings: object }) {
+  const wire = api as never
+  return new PermissionPresetSettingsController(new SettingsDescribeMirror(wire), wire, schema)
+}
+
 afterEach(cleanup)
 
 const SCHEMA = {
@@ -22,12 +31,6 @@ const SCHEMA = {
   },
 }
 
-const schema = new SettingsSchemaService(new Context())
-
-function createController(api: ConstructorParameters<typeof PermissionPresetSettingsController>[0]) {
-  return new PermissionPresetSettingsController(api, schema)
-}
-
 function view(defaultPreset: string, revision = 0): SettingsNamespaceView {
   return {
     ns: 'permission',
@@ -66,11 +69,11 @@ function mount(controller: PermissionPresetSettingsController) {
 describe('PermissionRow', () => {
   it('loads the descriptor, opens the menu, and selects a new default', async () => {
     const mutate = vi.fn(() => Promise.resolve(ok(view('workspace-write', 1))))
-    const controller = createController({
+    const controller = derivedController({
       settings: {
         describe: () => Promise.resolve(ok({ writable: true, hasDocument: false, namespaces: [view('read-only')] })),
         mutate,
-      } as never,
+      },
     })
     mount(controller)
     const button = await screen.findByRole('button', { name: 'Read Only' })
@@ -93,11 +96,11 @@ describe('PermissionRow', () => {
 
   it('requires explicit acknowledgement before saving Full access', async () => {
     const mutate = vi.fn(() => Promise.resolve(ok(view('danger-full-access', 1))))
-    const controller = createController({
+    const controller = derivedController({
       settings: {
         describe: () => Promise.resolve(ok({ writable: true, hasDocument: false, namespaces: [view('read-only')] })),
         mutate,
-      } as never,
+      },
     })
     mount(controller)
     fireEvent.click(await screen.findByRole('button', { name: 'Read Only' }))
@@ -117,21 +120,21 @@ describe('PermissionRow', () => {
   })
 
   it('hides an unavailable namespace and disables a read-only provider', async () => {
-    const absent = createController({
+    const absent = derivedController({
       settings: {
         describe: () => Promise.resolve(ok({ writable: true, hasDocument: false, namespaces: [] })),
         mutate: vi.fn(),
-      } as never,
+      },
     })
     const rendered = mount(absent)
     await waitFor(() => { expect(rendered.container.textContent).toBe('') })
     rendered.unmount()
 
-    const readonly = createController({
+    const readonly = derivedController({
       settings: {
         describe: () => Promise.resolve(ok({ writable: false, hasDocument: false, namespaces: [view('read-only')] })),
         mutate: vi.fn(),
-      } as never,
+      },
     })
     mount(readonly)
     expect((await screen.findByRole('button', { name: 'Read Only' })).hasAttribute('disabled')).toBe(true)
@@ -142,7 +145,7 @@ describe('PermissionRow', () => {
       writable: boolean
       namespaces: SettingsNamespaceView[]
     }>>>()
-    const controller = createController({
+    const controller = derivedController({
       settings: {
         describe: () => describe.promise,
         mutate: () => Promise.resolve({
@@ -152,7 +155,7 @@ describe('PermissionRow', () => {
             error: { code: 'settings-conflict', message: 'changed elsewhere', details: {} },
           },
         }),
-      } as never,
+      },
     })
     mount(controller)
     expect((await screen.findByRole('button', { name: 'Loading' })).hasAttribute('disabled')).toBe(true)

packages/client/ui-permission-presets/tests/settings-store.client.spec.ts

@@ -2,8 +2,9 @@ import { Context } from '@deepseek-ai/cordis'
 import { describe, expect, it, vi } from 'vitest'
 import type { SettingsNamespaceView } from '@deepseek-ai/dsh-api-remotes/client'
 import { SettingsSchemaService } from '@deepseek-ai/dsh-client-ui-settings/src/client/schema.ts'
+import { SettingsDescribeMirror } from '@deepseek-ai/dsh-client-ui-settings/src/client/settings-mirror.ts'
 import {
-  PermissionPresetSettingsController, permissionDefaultOf, refreshPermissionIfLoaded,
+  PermissionPresetSettingsController, permissionDefaultOf,
 } from '../src/client/settings-store.ts'
 
 const SCHEMA = {
@@ -22,10 +23,6 @@ function resolveDefault(view: SettingsNamespaceView) {
   return permissionDefaultOf(view, schema)
 }
 
-function createController(api: ConstructorParameters<typeof PermissionPresetSettingsController>[0]) {
-  return new PermissionPresetSettingsController(api, schema)
-}
-
 function view(defaultPreset: string, revision = 0, schema: SettingsNamespaceView['schema'] = SCHEMA): SettingsNamespaceView {
   return {
     ns: 'permission',
@@ -42,6 +39,13 @@ function ok<T>(value: T) {
   return { rpcId: 'test', result: { ok: true as const, value } }
 }
 
+/** The permission controller over a real mirror and one fake wire. */
+function permissionController(api: object) {
+  const wire = { settings: api } as never
+  const mirror = new SettingsDescribeMirror(wire)
+  return { mirror, controller: new PermissionPresetSettingsController(mirror, wire, schema) }
+}
+
 describe('permission settings store', () => {
   it('derives dynamic options and host labels from the descriptor schema', () => {
     expect(resolveDefault(view('read-only'))).toEqual({
@@ -104,9 +108,7 @@ describe('permission settings store', () => {
       namespaces: [view('read-only', 4)],
     })))
     const mutate = vi.fn(() => Promise.resolve(ok(view('workspace-write', 5))))
-    const controller = createController({
-      settings: { describe, mutate } as never,
-    })
+    const { controller } = permissionController({ describe, mutate })
     await controller.load()
     expect(controller.store.getSnapshot()).toMatchObject({
       status: 'ready',
@@ -125,126 +127,140 @@ describe('permission settings store', () => {
       currentValue: 'workspace-write',
       revision: 5,
     })
+    // The write answer folded into the mirror; no re-read followed.
+    expect(describe).toHaveBeenCalledTimes(1)
   })
 
   it('hides the row when the namespace is absent and contains write failures', async () => {
     const describe = vi.fn(() => Promise.resolve(ok({ writable: true, hasDocument: false, namespaces: [] })))
-    const controller = createController({
-      settings: { describe, mutate: vi.fn() } as never,
-    })
+    const { controller } = permissionController({ describe, mutate: vi.fn() })
     await controller.load()
     expect(controller.store.getSnapshot().status).toBe('unavailable')
 
-    const failing = createController({
-      settings: {
-        describe: () => Promise.resolve(ok({ writable: true, hasDocument: false, namespaces: [view('read-only')] })),
-        mutate: () => Promise.resolve({
-          rpcId: 'test',
-          result: {
-            ok: false as const,
-            error: { code: 'settings-conflict', message: 'stale', details: {} },
-          },
-        }),
-      } as never,
-    })
+    const failing = permissionController({
+      describe: () => Promise.resolve(ok({ writable: true, hasDocument: false, namespaces: [view('read-only')] })),
+      mutate: () => Promise.resolve({
+        rpcId: 'test',
+        result: {
+          ok: false as const,
+          error: { code: 'settings-conflict', message: 'stale', details: {} },
+        },
+      }),
+    }).controller
     await failing.load()
     await failing.select('workspace-write')
     expect(failing.store.getSnapshot()).toMatchObject({ status: 'error', error: 'stale' })
   })
 
-  it('contains read failures, no-ops without a writable view, and ignores stale responses', async () => {
-    const first = Promise.withResolvers<ReturnType<typeof ok<{
-      writable: boolean
-      namespaces: SettingsNamespaceView[]
-    }>>>()
-    const describe = vi.fn()
-      .mockImplementationOnce(() => first.promise)
-      .mockResolvedValueOnce(ok({ writable: false, hasDocument: false, namespaces: [view('read-only', 2)] }))
+  it('contains read failures and no-ops without a writable view', async () => {
     const mutate = vi.fn()
-    const controller = createController({
-      settings: { describe, mutate } as never,
-    })
-    const stale = controller.load()
-    await controller.load()
-    first.resolve(ok({ writable: true, hasDocument: false, namespaces: [view('workspace-write', 1)] }))
-    await stale
-    expect(controller.store.getSnapshot()).toMatchObject({
+    const readOnly = permissionController({
+      describe: () => Promise.resolve(ok({
+        writable: false, hasDocument: false, namespaces: [view('read-only', 2)],
+      })),
+      mutate,
+    }).controller
+    await readOnly.load()
+    expect(readOnly.store.getSnapshot()).toMatchObject({
       currentValue: 'read-only',
       writable: false,
       revision: 2,
     })
-    await controller.select('workspace-write')
+    await readOnly.select('workspace-write')
     expect(mutate).not.toHaveBeenCalled()
 
-    const rejected = createController({
-      settings: {
-        describe: () => Promise.resolve({
-          rpcId: 'test',
-          result: { ok: false as const, error: { code: 'internal', message: 'offline', details: {} } },
-        }),
-        mutate,
-      } as never,
-    })
+    const rejected = permissionController({
+      describe: () => Promise.resolve({
+        rpcId: 'test',
+        result: { ok: false as const, error: { code: 'internal', message: 'offline', details: {} } },
+      }),
+      mutate,
+    }).controller
     await rejected.select('workspace-write')
     await rejected.load()
     expect(rejected.store.getSnapshot()).toMatchObject({ status: 'error', error: 'offline' })
+    expect(mutate).not.toHaveBeenCalled()
+
+    const thrown = permissionController({
+      describe: async () => { throw 'disconnected' },
+      mutate,
+    }).controller
+    await thrown.load()
+    expect(thrown.store.getSnapshot()).toMatchObject({ status: 'error', error: 'disconnected' })
 
-    const thrown = createController({
+    const wire = {
       settings: {
-        // Promise consumers must contain unknown rejection values from a
-        // transport implementation, including non-Error legacy clients.
-        // oxlint-disable-next-line typescript/prefer-promise-reject-errors
-        describe: () => Promise.reject('disconnected'),
+        describe: () => Promise.resolve(ok({
+          writable: true, hasDocument: false, namespaces: [view('read-only')],
+        })),
         mutate,
-      } as never,
+      },
+    } as never
+    const mirror = new SettingsDescribeMirror(wire)
+    const malformed = new PermissionPresetSettingsController(mirror, wire, {
+      rehydrate: () => { throw 'schema disconnected' },
+    } as never)
+    await malformed.load()
+    expect(malformed.store.getSnapshot()).toMatchObject({
+      status: 'error', error: 'schema disconnected',
     })
-    await thrown.load()
-    expect(thrown.store.getSnapshot()).toMatchObject({ status: 'error', error: 'disconnected' })
   })
 
-  it('disposal suppresses in-flight reads and writes, and loaded invalidations refetch', async () => {
+  it('hides the row in a remote browser instead of loading forever', async () => {
+    const describeCall = vi.fn()
+    const mutate = vi.fn()
+    const wire = { settings: { describe: describeCall, mutate } } as never
+    const mirror = new SettingsDescribeMirror(wire, 'memory')
+    const controller = new PermissionPresetSettingsController(mirror, wire, schema)
+    await controller.load()
+    expect(controller.store.getSnapshot().status).toBe('unavailable')
+    await controller.select('workspace-write')
+    expect(describeCall).not.toHaveBeenCalled()
+    expect(mutate).not.toHaveBeenCalled()
+  })
+
+  it('follows a mirror refresh without an own read once loaded', async () => {
+    const describe = vi.fn()
+      .mockResolvedValueOnce(ok({ writable: true, hasDocument: false, namespaces: [view('read-only', 1)] }))
+      .mockResolvedValueOnce(ok({ writable: true, hasDocument: false, namespaces: [view('workspace-write', 2)] }))
+    const { mirror, controller } = permissionController({ describe, mutate: vi.fn() })
+    await controller.load()
+    expect(controller.store.getSnapshot()).toMatchObject({ currentValue: 'read-only' })
+
+    await mirror.load()
+
+    expect(controller.store.getSnapshot()).toMatchObject({ currentValue: 'workspace-write', revision: 2 })
+  })
+
+  it('disposal stops deriving and suppresses in-flight writes', async () => {
+    const neverRead = vi.fn()
+    const { controller: neverLoaded } = permissionController({ describe: neverRead, mutate: vi.fn() })
+    neverLoaded.dispose()
+    await neverLoaded.load()
+    expect(neverLoaded.store.getSnapshot().status).toBe('idle')
+    expect(neverRead).not.toHaveBeenCalled()
+
     const read = Promise.withResolvers<ReturnType<typeof ok<{
       writable: boolean
       namespaces: SettingsNamespaceView[]
     }>>>()
-    const describe = vi.fn(() => read.promise)
-    const idle = createController({ settings: { describe, mutate: vi.fn() } as never })
-    refreshPermissionIfLoaded(idle)
-    expect(describe).not.toHaveBeenCalled()
+    const { mirror, controller: idle } = permissionController({ describe: () => read.promise, mutate: vi.fn() })
     const loading = idle.load()
     idle.dispose()
     read.resolve(ok({ writable: true, hasDocument: false, namespaces: [view('read-only')] }))
-    await loading
+    await Promise.all([loading, mirror.load()])
     expect(idle.store.getSnapshot().status).toBe('loading')
 
-    const rejectedRead = Promise.withResolvers<ReturnType<typeof ok<{
-      writable: boolean
-      namespaces: SettingsNamespaceView[]
-    }>>>()
-    const disposedRead = createController({
-      settings: { describe: () => rejectedRead.promise, mutate: vi.fn() } as never,
-    })
-    const reading = disposedRead.load()
-    disposedRead.dispose()
-    rejectedRead.reject(new Error('late read'))
-    await reading
-    expect(disposedRead.store.getSnapshot().status).toBe('loading')
-
     const mutation = Promise.withResolvers<ReturnType<typeof ok<SettingsNamespaceView>>>()
-    const activeDescribe = vi.fn(() => Promise.resolve(ok({
-      writable: true,
-      hasDocument: false,
-      namespaces: [view('read-only')],
-    })))
-    const active = createController({
-      settings: {
-        describe: activeDescribe,
-        mutate: () => mutation.promise,
-      } as never,
+    const { controller: active } = permissionController({
+      describe: () => Promise.resolve(ok({
+        writable: true,
+        hasDocument: false,
+        namespaces: [view('read-only')],
+      })),
+      mutate: () => mutation.promise,
     })
     await active.load()
-    refreshPermissionIfLoaded(active)
-    await vi.waitFor(() => { expect(activeDescribe).toHaveBeenCalledTimes(2) })
     const saving = active.select('workspace-write')
     active.dispose()
     mutation.resolve(ok(view('workspace-write', 1)))
@@ -252,11 +268,9 @@ describe('permission settings store', () => {
     expect(active.store.getSnapshot().status).toBe('saving')
 
     const rejectedMutation = Promise.withResolvers<ReturnType<typeof ok<SettingsNamespaceView>>>()
-    const disposedWrite = createController({
-      settings: {
-        describe: () => Promise.resolve(ok({ writable: true, hasDocument: false, namespaces: [view('read-only')] })),
-        mutate: () => rejectedMutation.promise,
-      } as never,
+    const { controller: disposedWrite } = permissionController({
+      describe: () => Promise.resolve(ok({ writable: true, hasDocument: false, namespaces: [view('read-only')] })),
+      mutate: () => rejectedMutation.promise,
     })
     await disposedWrite.load()
     const writing = disposedWrite.select('workspace-write')

packages/client/ui-settings-general/src/client/index.ts

@@ -24,7 +24,7 @@ import { CloseLabel, HeaderContent, TriggerContent } from './chrome.tsx'
 import { GeneralSection } from './GeneralSection.tsx'
 import { SettingsDocumentAction } from './SettingsDocumentAction.tsx'
 import type { SettingsDocumentActionInjected } from './SettingsDocumentAction.tsx'
-import { refreshDocumentIfLoaded, SettingsDocumentStore } from './settings-document-store.ts'
+import { SettingsDocumentStore } from './settings-document-store.ts'
 import { en, zh, type SettingsKey } from './locales.ts'
 
 export type {
@@ -53,7 +53,7 @@ const NS = 'settings'
  * ui-settings' apply, whose activation order relative to this one is NOT
  * constrained; registrations depend on their slots through `slots.inject()`.
  */
-export const inject = ['slots', 'locale', 'connection']
+export const inject = ['slots', 'locale', 'connection', 'settingsScope']
 
 /**
  * Register the `settings` dictionaries, the chrome content, and the General
@@ -68,8 +68,10 @@ export function apply(ctx: ClientContext): void {
   // locale/change re-registration wiring.
   const t = ctx.locale.bind(NS)
   const connection = ctx.get('connection') as ConnectionHandle
+  // The action follows the shared describe mirror, whose owning plugin
+  // already refreshes it on document commits and reconnects.
   const documentController = connection.isLoopback
-    ? new SettingsDocumentStore(connection.api)
+    ? new SettingsDocumentStore(connection.api, ctx.settingsScope.describe())
     : undefined
   const documentInjected = documentController === undefined
     ? undefined
@@ -77,9 +79,7 @@ export function apply(ctx: ClientContext): void {
       controller: documentController,
       hooks: { snapshot: documentController.store },
     })
-  ctx.effect(() => ctx.on('connection/reset', () => {
-    refreshDocumentIfLoaded(documentController)
-  }), 'ui-settings-general: metadata invalidations')
+  ctx.effect(() => () => { documentController?.dispose() }, 'ui-settings-general: document action directory')
   // The settings shell: this package occupies the sidebar-owned hole and
   // declares the settings slots. Ledger → nav-row projection as an observable
   // source (uSES contract: getSnapshot returns the cached rows until the

packages/client/ui-settings-general/src/client/settings-document-store.ts

@@ -2,6 +2,7 @@
 
 import type { IApiClient } from '@deepseek-ai/dsh-api-remotes/client'
 import { createSnapshotStore, type SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SettingsDescribeFace } from '@deepseek-ai/dsh-client-ui-settings/client'
 
 /** Browser state of the Host-owned settings document. */
 export interface SettingsDocumentState {
@@ -17,51 +18,37 @@ function messageOf(error: unknown): string {
   return error instanceof Error ? error.message : String(error)
 }
 
-/** Loads local-document availability and invokes the pathless Host-owned open operation. */
+/** Derives local-document availability from the shared mirror and invokes the pathless Host-owned open operation. */
 export class SettingsDocumentStore {
   /** uSES-safe state source shared by the registered header action. */
   readonly store: SnapshotStore<SettingsDocumentState> = createSnapshotStore({
     status: 'idle', opening: false, error: null,
   })
 
-  private generation = 0
+  private following: (() => void) | undefined
 
   /**
-   * @param api - loopback settings wire face that reports and opens the provider document.
+   * @param api - loopback settings wire face that opens the provider document.
+   * @param describeFace - the shared mirror's describe face (`hasDocument` source).
    */
-  constructor(private readonly api: Pick<IApiClient, 'settings'>) {}
+  constructor(
+    private readonly api: Pick<IApiClient, 'settings'>,
+    private readonly describeFace: SettingsDescribeFace,
+  ) {}
 
   /**
-   * Load whether the current provider owns a local document.
-   * @returns after the latest metadata response updates the store.
+   * Begin following the mirror (idempotent) and reflect whether the current
+   * provider owns a local document.
+   * @returns settlement once the snapshot reflects the mirror.
    */
   async load(): Promise<void> {
-    const generation = ++this.generation
+    this.following ??= this.describeFace.subscribe(() => { this.derive() })
     this.store.update((state) => {
       state.status = 'loading'
       state.error = null
     })
-    try {
-      const { result } = await this.api.settings.describe({})
-      if (generation !== this.generation) return
-      if (!result.ok) {
-        this.store.update((state) => {
-          state.status = 'unavailable'
-          state.error = result.error.message
-        })
-        return
-      }
-      this.store.update((state) => {
-        state.status = result.value.hasDocument ? 'ready' : 'unavailable'
-        state.error = null
-      })
-    } catch (error) {
-      if (generation !== this.generation) return
-      this.store.update((state) => {
-        state.status = 'unavailable'
-        state.error = messageOf(error)
-      })
-    }
+    await this.describeFace.ensure()
+    this.derive()
   }
 
   /**
@@ -84,13 +71,30 @@ export class SettingsDocumentStore {
       this.store.update((state) => { state.opening = false })
     }
   }
-}
 
-/**
- * Refresh document availability after reconnect only when a surface has already requested it.
- * @param controller - optional loopback document state owner.
- */
-export function refreshDocumentIfLoaded(controller: SettingsDocumentStore | undefined): void {
-  if (controller === undefined || controller.store.getSnapshot().status === 'idle') return
-  void controller.load()
+  /** Stop following the mirror. */
+  dispose(): void {
+    this.following?.()
+    this.following = undefined
+  }
+
+  private derive(): void {
+    const mirrored = this.describeFace.getSnapshot()
+    if (mirrored.view === undefined) {
+      // A held failure with no answer means the document cannot be located;
+      // without one the read is still in flight and loading stands.
+      if (mirrored.error !== null) {
+        this.store.update((state) => {
+          state.status = 'unavailable'
+          state.error = mirrored.error
+        })
+      }
+      return
+    }
+    const { hasDocument } = mirrored.view
+    this.store.update((state) => {
+      state.status = hasDocument ? 'ready' : 'unavailable'
+      state.error = null
+    })
+  }
 }

packages/client/ui-settings-general/tests/apply.client.spec.ts

@@ -4,7 +4,8 @@ import { describe, expect, it, vi } from 'vitest'
 import { resolveSlotLabel } from '@deepseek-ai/dsh-client-ui-slots'
 import { SlotRegistry } from '@deepseek-ai/dsh-client-runtime/client'
 import { LocaleRuntime } from '@deepseek-ai/dsh-client-locale/client'
-import { usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
+import { TestRemote, usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
+import { apply as settingsApply, inject as settingsInject } from '@deepseek-ai/dsh-client-ui-settings/client'
 import { apply, inject } from '@deepseek-ai/dsh-client-ui-settings-general/client'
 import { CloseLabel, HeaderContent, TriggerContent } from '../src/client/chrome.tsx'
 import { GeneralSection } from '../src/client/GeneralSection.tsx'
@@ -48,6 +49,8 @@ async function bench(isLoopback = true) {
     api: { settings: { describe: settingsDescribe, openDocument: settingsOpenDocument } },
     isLoopback,
   } as never)
+  new TestRemote(ctx)
+  await ctx.plugin({ inject: [...settingsInject], apply: settingsApply }).await()
   return { ctx, slots: ctx.get('slots') as SlotRegistry, locale, settingsDescribe, settingsOpenDocument }
 }
 
@@ -75,7 +78,7 @@ function generalEntry(slots: SlotRegistry) {
 
 describe('ui-settings-general apply', () => {
   it('declares the services it uses', () => {
-    expect(inject).toEqual(['slots', 'locale', 'connection'])
+    expect(inject).toEqual(['slots', 'locale', 'connection', 'settingsScope'])
   })
 
   it('fills all five seats for declarations before or after apply', async () => {
@@ -149,16 +152,17 @@ describe('ui-settings-general apply', () => {
     expect(resolveSlotLabel(generalEntry(b.slots)!.options.label)).toBe('通用设置')
   })
 
-  it('refreshes loaded document availability on reconnect without reading it eagerly', async () => {
+  it('reads availability from the shared mirror and follows its reconnect refresh', async () => {
     const b = await bench()
     declare(b.slots)
     await b.ctx.plugin({ inject: [...inject], apply }).await()
     const entry = b.slots.entries('settings.action')[0]!
     const { controller } = (entry.inject as unknown as () => SettingsDocumentActionInjected)()
-    b.ctx.emit('connection/reset')
-    expect(b.settingsDescribe).not.toHaveBeenCalled()
+    // The mirror read once at its own boot; the action's load adds no read.
+    await vi.waitFor(() => { expect(b.settingsDescribe).toHaveBeenCalledOnce() })
     await controller.load()
     expect(b.settingsDescribe).toHaveBeenCalledOnce()
+    expect(controller.store.getSnapshot().status).toBe('ready')
     b.ctx.emit('connection/reset')
     await vi.waitFor(() => { expect(b.settingsDescribe).toHaveBeenCalledTimes(2) })
   })

packages/client/ui-settings-general/tests/components.client.spec.tsx

@@ -7,7 +7,14 @@ import { GeneralSection } from '../src/client/GeneralSection.tsx'
 import { CloseLabel, HeaderContent, TriggerContent } from '../src/client/chrome.tsx'
 import type { TriggerContentProps } from '../src/client/chrome.tsx'
 import { SettingsDocumentAction } from '../src/client/SettingsDocumentAction.tsx'
+import { SettingsDescribeMirror } from '@deepseek-ai/dsh-client-ui-settings/src/client/settings-mirror.ts'
 import { SettingsDocumentStore } from '../src/client/settings-document-store.ts'
+
+/** Store over a real mirror derived from the same fake wire. */
+function derivedDocumentStore(api: object) {
+  const wire = api as never
+  return new SettingsDocumentStore(wire, new SettingsDescribeMirror(wire))
+}
 import { en } from '../src/client/locales.ts'
 
 afterEach(cleanup)
@@ -64,7 +71,7 @@ describe('SettingsDocumentAction', () => {
       rpcId: 'document-open' as never,
       result: { ok: true as const, value: { opened: true as const } },
     }))
-    const controller = new SettingsDocumentStore({
+    const controller = derivedDocumentStore({
       settings: {
         describe: vi.fn(() => Promise.resolve({
           rpcId: 'document-action' as never,
@@ -75,7 +82,7 @@ describe('SettingsDocumentAction', () => {
         })),
         openDocument,
       },
-    } as never)
+    })
     render(<SettingsDocumentAction
       {...kit}
       t={t}
@@ -87,7 +94,7 @@ describe('SettingsDocumentAction', () => {
     await waitFor(() => { expect(openDocument).toHaveBeenCalledWith({}) })
   })
 
-  it('stays absent without a document and retries availability after remount', async () => {
+  it('stays absent without a document and follows a mirror refresh to available', async () => {
     const describe = vi.fn()
       .mockResolvedValueOnce({
         rpcId: 'document-action-absent' as never,
@@ -97,12 +104,9 @@ describe('SettingsDocumentAction', () => {
         rpcId: 'document-action-ready' as never,
         result: { ok: true as const, value: { writable: true, hasDocument: true, namespaces: [] } },
       })
-    const controller = new SettingsDocumentStore({
-      settings: {
-        describe,
-        openDocument: vi.fn(),
-      },
-    } as never)
+    const wire = { settings: { describe, openDocument: vi.fn() } } as never
+    const mirror = new SettingsDescribeMirror(wire)
+    const controller = new SettingsDocumentStore(wire, mirror)
     const first = render(<SettingsDocumentAction
       {...kit}
       t={t}
@@ -118,12 +122,17 @@ describe('SettingsDocumentAction', () => {
       controller={controller}
       useSnapshot={bindSnapshotSelector(controller.store)}
     />)
+    // A remount alone re-reads nothing; availability moves with the mirror's
+    // own refresh (a document commit or reconnect in production).
+    await waitFor(() => { expect(controller.store.getSnapshot().status).toBe('unavailable') })
+    expect(describe).toHaveBeenCalledTimes(1)
+    await mirror.load()
     expect(await screen.findByRole('button', { name: 'Open configuration file' })).toBeTruthy()
     expect(describe).toHaveBeenCalledTimes(2)
   })
 
   it('keeps the action available and reports a native-open failure', async () => {
-    const controller = new SettingsDocumentStore({
+    const controller = derivedDocumentStore({
       settings: {
         describe: vi.fn(() => Promise.resolve({
           rpcId: 'document-action' as never,
@@ -137,7 +146,7 @@ describe('SettingsDocumentAction', () => {
           result: { ok: false as const, error: { code: 'internal' as const, message: 'xdg-open missing', details: {} } },
         })),
       },
-    } as never)
+    })
     render(<SettingsDocumentAction
       {...kit}
       t={t}

packages/client/ui-settings-general/tests/settings-document-store.client.spec.ts

@@ -1,7 +1,14 @@
 import { describe, expect, it, vi } from 'vitest'
 import type { RpcResponse } from '@deepseek-ai/dsh-api-remotes/client'
+import { SettingsDescribeMirror } from '@deepseek-ai/dsh-client-ui-settings/src/client/settings-mirror.ts'
 import { SettingsDocumentStore } from '../src/client/settings-document-store.ts'
 
+/** Store over a real mirror derived from the same fake wire. */
+function derivedDocumentStore(api: object) {
+  const wire = api as never
+  return new SettingsDocumentStore(wire, new SettingsDescribeMirror(wire))
+}
+
 function response(hasDocument = false): RpcResponse<{
   writable: boolean
   hasDocument: boolean
@@ -34,7 +41,7 @@ describe('SettingsDocumentStore', () => {
   it('loads provider metadata and asks the settings domain to open its document', async () => {
     const describe = vi.fn(() => Promise.resolve(response(true)))
     const openDocument = vi.fn(() => Promise.resolve(opened()))
-    const controller = new SettingsDocumentStore({ settings: { describe, openDocument } } as never)
+    const controller = derivedDocumentStore({ settings: { describe, openDocument } })
     await controller.load()
     expect(controller.store.getSnapshot()).toEqual({
       status: 'ready', opening: false, error: null,
@@ -45,23 +52,23 @@ describe('SettingsDocumentStore', () => {
 
   it('marks absent or failed metadata unavailable without opening anything', async () => {
     const openDocument = vi.fn(() => Promise.resolve(opened()))
-    const absent = new SettingsDocumentStore({
+    const absent = derivedDocumentStore({
       settings: { describe: () => Promise.resolve(response()), openDocument },
-    } as never)
+    })
     await absent.load()
     await absent.open()
     expect(absent.store.getSnapshot().status).toBe('unavailable')
     expect(openDocument).not.toHaveBeenCalled()
 
-    const failed = new SettingsDocumentStore({
+    const failed = derivedDocumentStore({
       settings: { describe: () => Promise.reject(new Error('offline')), openDocument },
-    } as never)
+    })
     await failed.load()
     expect(failed.store.getSnapshot()).toMatchObject({ status: 'unavailable', error: 'offline' })
 
-    const rejected = new SettingsDocumentStore({
+    const rejected = derivedDocumentStore({
       settings: { describe: () => Promise.resolve(describeFailed('provider failed')), openDocument },
-    } as never)
+    })
     await rejected.load()
     expect(rejected.store.getSnapshot()).toMatchObject({
       status: 'unavailable', error: 'provider failed',
@@ -71,9 +78,9 @@ describe('SettingsDocumentStore', () => {
   it('collapses concurrent open gestures and recovers after a failure', async () => {
     let resolveOpen!: (response: RpcResponse<{ opened: true }>) => void
     const openDocument = vi.fn(() => new Promise<RpcResponse<{ opened: true }>>((resolve) => { resolveOpen = resolve }))
-    const controller = new SettingsDocumentStore({
+    const controller = derivedDocumentStore({
       settings: { describe: () => Promise.resolve(response(true)), openDocument },
-    } as never)
+    })
     await controller.load()
     const first = controller.open()
     const second = controller.open()
@@ -88,23 +95,15 @@ describe('SettingsDocumentStore', () => {
     })
   })
 
-  it('ignores stale metadata completions and reports non-Error native failures', async () => {
-    let resolveFirst!: (value: ReturnType<typeof response>) => void
-    const first = new Promise<ReturnType<typeof response>>((resolve) => { resolveFirst = resolve })
-    const describe = vi.fn()
-      .mockReturnValueOnce(first)
-      .mockResolvedValueOnce(response(true))
+  it('reports non-Error native failures and recovers availability via a mirror refresh', async () => {
     let rejectOpen!: (reason?: unknown) => void
-    const controller = new SettingsDocumentStore({
+    const controller = derivedDocumentStore({
       settings: {
-        describe,
+        describe: vi.fn(() => Promise.resolve(response(true))),
         openDocument: () => new Promise((_, reject) => { rejectOpen = reject }),
       },
-    } as never)
-    const stale = controller.load()
+    })
     await controller.load()
-    resolveFirst(response())
-    await stale
     expect(controller.store.getSnapshot().status).toBe('ready')
     const opening = controller.open()
     rejectOpen('native unavailable')
@@ -113,20 +112,21 @@ describe('SettingsDocumentStore', () => {
       status: 'ready', opening: false, error: 'native unavailable',
     })
 
-    let rejectFirst!: (error: Error) => void
-    const rejectedFirst = new Promise<ReturnType<typeof response>>((_, reject) => { rejectFirst = reject })
-    const caught = new SettingsDocumentStore({
+    // A first read that failed leaves the action unavailable with the miss
+    // recorded; the mirror's next refresh (a commit or reconnect) recovers it.
+    const wire = {
       settings: {
         describe: vi.fn()
-          .mockReturnValueOnce(rejectedFirst)
+          .mockRejectedValueOnce(new Error('offline'))
           .mockResolvedValueOnce(response(true)),
         openDocument: vi.fn(),
       },
-    } as never)
-    const staleRejection = caught.load()
+    } as never
+    const mirror = new SettingsDescribeMirror(wire)
+    const caught = new SettingsDocumentStore(wire, mirror)
     await caught.load()
-    rejectFirst(new Error('stale offline'))
-    await staleRejection
+    expect(caught.store.getSnapshot()).toMatchObject({ status: 'unavailable', error: 'offline' })
+    await mirror.load()
     expect(caught.store.getSnapshot()).toMatchObject({ status: 'ready', error: null })
   })
 })

packages/client/ui-settings-general/tests/shell.client.spec.ts

@@ -2,6 +2,7 @@
 import { Context } from '@deepseek-ai/cordis'
 import { describe, expect, it, vi } from 'vitest'
 import { SlotRegistry } from '@deepseek-ai/dsh-client-runtime/client'
+import { apply as settingsApply, inject as settingsInject } from '@deepseek-ai/dsh-client-ui-settings/client'
 import { apply, inject } from '../src/client/index.ts'
 import type { SettingsRootInjected } from '../src/client/shell-contract.ts'
 import { SettingsRoot } from '../src/client/SettingsRoot.tsx'
@@ -22,6 +23,7 @@ async function bench() {
     isLoopback: false,
   } as never)
   ctx.provide('remote', { $on: () => () => {} } as never)
+  await ctx.plugin({ inject: [...settingsInject], apply: settingsApply }).await()
   return { ctx, slots: ctx.get('slots') as SlotRegistry }
 }
 
@@ -49,7 +51,7 @@ const CHILD_SPECS = {
 
 describe('ui-settings apply', () => {
   it('declares only the slot registry (a pure composition face, no locale)', () => {
-    expect(inject).toEqual(['slots', 'locale', 'connection'])
+    expect(inject).toEqual(['slots', 'locale', 'connection', 'settingsScope'])
   })
 
   it('registers the shell and declares every child slot, before or after the declaration', async () => {

packages/client/ui-settings-models/src/client/index.ts

@@ -21,7 +21,7 @@ import { DeepSeekOnboardingDialog } from './DeepSeekOnboardingDialog.tsx'
 import type { DeepSeekOnboardingInjected } from './DeepSeekOnboardingDialog.tsx'
 import { WelcomeNotice } from './WelcomeNotice.tsx'
 import type { WelcomeNoticeInjected } from './WelcomeNotice.tsx'
-import { refreshWelcomeIfLoaded, WelcomeNoticeStore } from './welcome-store.ts'
+import { decodeWelcomeSection, WelcomeNoticeStore } from './welcome-store.ts'
 import { ModelsSettingsStore } from './store.ts'
 import { createSettingsSchemaOperations } from './schema-operations.ts'
 import { en, zh, type ModelsKey } from './locales.ts'
@@ -56,7 +56,7 @@ export function refreshIfLoaded(controller: ModelsSettingsStore): void {
  * ui-settings' apply, whose activation order relative to this one is NOT
  * constrained; registration depends on each slot through `slots.inject()`.
  */
-export const inject = ['slots', 'locale', 'connection', 'remote', 'settingsSchema']
+export const inject = ['slots', 'locale', 'connection', 'remote', 'settingsScope', 'settingsSchema']
 
 /**
  * Register the Models section once the `settings.section` declaration is on
@@ -69,7 +69,7 @@ export function apply(ctx: ClientContext): void {
 
   const connection = ctx.get('connection') as ConnectionHandle
   const schema = createSettingsSchemaOperations(ctx.settingsSchema)
-  const controller = new ModelsSettingsStore(connection.api, schema)
+  const controller = new ModelsSettingsStore(connection.api, schema, ctx.settingsScope.describe())
   // Registration-time text (the nav label thunk) and the inject faces share
   // one bound translate; copy freshness rides the locale revision.
   const t = ctx.locale.bind(NS) as ModelsSectionInjected['t']
@@ -87,34 +87,35 @@ export function apply(ctx: ClientContext): void {
     schema,
     t,
   })
-  const welcomeController = new WelcomeNoticeStore(
-    connection.api,
-    connection.isLoopback ? 'host' : 'memory',
-  )
+  // The scope's own memory mode is what keeps a remote browser process-local,
+  // so the store needs no isLoopback branch of its own.
+  const welcomeController = new WelcomeNoticeStore(ctx.settingsScope.bind({
+    namespace: WELCOME_NOTICE_SETTINGS_NAMESPACE,
+    decode: decodeWelcomeSection,
+  }))
   const welcomeInjected = (): WelcomeNoticeInjected => ({
     controller: welcomeController,
     hooks: { welcome: welcomeController.store },
     t,
   })
 
-  // Pushed invalidations converge every open surface without polling: any
-  // settings/credentials/topology change refetches once the page loaded.
+  // Pushed invalidations converge every open surface without polling. The
+  // settingsScope injection makes ui-settings activate first, and remote
+  // dispatch preserves listener order; its listener therefore starts the
+  // mirror refresh before this store joins that refresh. The welcome notice
+  // follows its settings scope, so it needs no subscription here.
   ctx.effect(() => {
     const refreshModels = (): void => { refreshIfLoaded(controller) }
-    const refreshAll = (): void => {
-      refreshModels()
-      refreshWelcomeIfLoaded(welcomeController)
-    }
     const disposers = [
-      ctx.remote.$on('settings/document-updated', (ns) => {
-        refreshModels()
-        if (ns === WELCOME_NOTICE_SETTINGS_NAMESPACE) refreshWelcomeIfLoaded(welcomeController)
-      }),
+      ctx.remote.$on('settings/document-updated', () => { refreshModels() }),
       ctx.remote.$on('credentials/updated', refreshModels),
       ctx.remote.$on('llm/adapters-updated', refreshModels),
-      ctx.on('connection/reset', refreshAll),
+      ctx.on('connection/reset', refreshModels),
     ]
-    return () => { for (const dispose of disposers) dispose() }
+    return () => {
+      welcomeController.dispose()
+      for (const dispose of disposers) dispose()
+    }
   }, 'ui-settings-models: pushed invalidations')
 
   ctx.slots.inject('settings.section', () => ctx.slots.register({

packages/client/ui-settings-models/src/client/store.ts

@@ -1,6 +1,6 @@
 /**
  * Models settings page store: one snapshot joining the configurable-provider
- * directory (`llm.providers`), the settings namespaces (`settings.describe`),
+ * directory (`llm.providers`), the settings namespaces (shared settings mirror),
  * and the referenced credentials (`credentials.describe`). The host stays the
  * single fact source — every mutation writes through the wire and the page
  * re-renders from the next describe, pushed or refetched.
@@ -11,6 +11,7 @@ import type {
 } from '@deepseek-ai/dsh-api-remotes/client'
 import type { SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SettingsDescribeFace } from '@deepseek-ai/dsh-client-ui-settings/client'
 import type { SettingsSchemaOperations } from './schema-operations.ts'
 
 /**
@@ -114,17 +115,21 @@ export class ModelsSettingsStore {
   private generation = 0
 
   /**
-   * @param api - the wire face (settings/credentials/llm domains).
+   * @param api - the wire face (credentials/llm domains, and settings writes).
+   * @param describeFace - the shared mirror's describe face (namespace views and writability).
    */
   constructor(
     private readonly api: Pick<IApiClient, 'settings' | 'credentials' | 'llm'>,
     private readonly schema: SettingsSchemaOperations,
+    private readonly describeFace: SettingsDescribeFace,
   ) {}
 
   /**
-   * Refresh the whole page snapshot: directory and namespaces in parallel,
-   * then one batched credential describe over every referenced ref. A
-   * failure keeps the last good rows and surfaces the error.
+   * Refresh the whole page snapshot: the provider directory and the mirror's
+   * settings answer in parallel, then one batched credential describe over
+   * every referenced ref. Provider failure or absence of an initial settings
+   * answer keeps the last good rows and surfaces an error; a failed settings
+   * refresh reuses the mirror's held view.
    * @returns nothing; the snapshot carries the outcome.
    */
   async load(): Promise<void> {
@@ -132,17 +137,20 @@ export class ModelsSettingsStore {
     this.store.update((s) => { s.status = 'loading'; s.error = null })
     let providers: ConfigurableProviderView[]
     let writable: boolean
-    let views: SettingsNamespaceView[]
+    let views: readonly SettingsNamespaceView[]
     try {
-      const [providersResponse, settingsResponse] = await Promise.all([
+      const [providersResponse] = await Promise.all([
         this.api.llm.providers({}),
-        this.api.settings.describe({}),
+        this.describeFace.ensure(),
       ])
       if (!providersResponse.result.ok) throw new Error(providersResponse.result.error.message)
-      if (!settingsResponse.result.ok) throw new Error(settingsResponse.result.error.message)
+      const mirrored = this.describeFace.getSnapshot()
+      if (mirrored.view === undefined) {
+        throw new Error(mirrored.error ?? 'settings are unavailable in this browser')
+      }
       providers = providersResponse.result.value.providers
-      writable = settingsResponse.result.value.writable
-      views = settingsResponse.result.value.namespaces
+      writable = mirrored.view.writable
+      views = mirrored.view.namespaces
     } catch (error) {
       if (generation !== this.generation) return
       this.store.update((s) => {

packages/client/ui-settings-models/src/client/welcome-store.ts

@@ -1,10 +1,14 @@
-/** Welcome-notice state, durable when the browser may use Host settings. */
+/**
+ * Welcome-notice state derived from the welcome settings scope. The scope is
+ * the transport: a loopback browser follows the durable Host section, while a
+ * remote browser's memory-mode scope never answers and the acknowledgement
+ * stays process-local here.
+ */
 
-import type { IApiClient, SettingsNamespaceView } from '@deepseek-ai/dsh-api-remotes/client'
-import type { SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SettingsScope, SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
 import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
 import {
-  WELCOME_NOTICE_ACK_FIELD, WELCOME_NOTICE_SETTINGS_NAMESPACE, WELCOME_NOTICE_VERSION,
+  WELCOME_NOTICE_ACK_FIELD, WELCOME_NOTICE_VERSION,
 } from '../onboarding-copy.ts'
 
 /** State rendered by the welcome step. */
@@ -14,113 +18,123 @@ export interface WelcomeNoticeState {
   error: string | null
 }
 
-function messageOf(error: unknown): string {
-  return error instanceof Error ? error.message : String(error)
+/** The welcome section as the notice reads it. */
+export type WelcomeSection = Record<string, unknown>
+
+/**
+ * Accept any object section verbatim; a malformed durable value reads as an
+ * empty section, so the notice treats it as unacknowledged instead of leaving
+ * the scope stuck on its previous value.
+ * @param section - the wire section value.
+ * @returns the section object, or an empty one for non-object values.
+ */
+export function decodeWelcomeSection(section: unknown): WelcomeSection {
+  return typeof section === 'object' && section !== null && !Array.isArray(section)
+    ? section as WelcomeSection
+    : {}
 }
 
-function acknowledgementOf(view: SettingsNamespaceView): string | undefined {
-  if (typeof view.value !== 'object' || view.value === null) return undefined
-  const value = (view.value as Record<string, unknown>)[WELCOME_NOTICE_ACK_FIELD]
-  return typeof value === 'string' ? value : undefined
+/* v8 ignore next 3 -- closed-union default only defends future source widening */
+function assertNever(_value: never): never {
+  throw new Error('unexpected welcome settings status')
 }
 
 /** Coordinates durable Host acknowledgement or a process-local remote fallback. */
 export class WelcomeNoticeStore {
   /** uSES-safe state source shared by the registered welcome step. */
-  readonly store: SnapshotStore<WelcomeNoticeState> = createSnapshotStore({
+  readonly store: SnapshotStore<WelcomeNoticeState> = createSnapshotStore<WelcomeNoticeState>({
     status: 'idle', acknowledged: false, error: null,
   })
 
-  private generation = 0
+  private localAcknowledged = false
+  private saving = false
+  private following: (() => void) | undefined
 
   /**
-   * @param api - settings wire face used for durable reads and writes.
-   * @param persistence - remote browsers use memory because settings is loopback-only.
+   * @param scope - the welcome settings namespace scope; its memory mode is
+   * what keeps a remote browser process-local.
    */
-  constructor(
-    private readonly api: Pick<IApiClient, 'settings'>,
-    private readonly persistence: 'host' | 'memory' = 'host',
-  ) {}
+  constructor(private readonly scope: SettingsScope<WelcomeSection>) {}
 
-  /** Load the acknowledgement from Host settings or initialize process-local state. */
-  async load(): Promise<void> {
-    const generation = ++this.generation
-    if (this.persistence === 'memory') {
-      this.store.update((state) => { state.status = 'ready'; state.error = null })
-      return
+  /**
+   * Begin following the bound scope (idempotent) and publish its current answer.
+   * @returns settlement after the current answer is published.
+   */
+  load(): Promise<void> {
+    this.following ??= this.scope.subscribe(() => { this.derive() })
+    this.derive()
+    return Promise.resolve()
+  }
+
+  /**
+   * Persist this copy version, or advance only this process for a remote
+   * browser. Success is judged against the state the write left behind, so a
+   * refused or failed write reports false after its recovery read settles.
+   * @returns true when the selected persistence mode holds the acknowledgement.
+   */
+  async acknowledge(): Promise<boolean> {
+    if (this.scope.getSnapshot().mode === 'memory') {
+      this.localAcknowledged = true
+      this.derive()
+      return true
     }
-    this.store.update((state) => { state.status = 'loading'; state.error = null })
+    this.saving = true
+    this.store.update((state) => { state.status = 'saving'; state.error = null })
     try {
-      const response = await this.api.settings.describe({})
-      if (!response.result.ok) throw new Error(response.result.error.message)
-      const view = response.result.value.namespaces.find(
-        candidate => candidate.ns === WELCOME_NOTICE_SETTINGS_NAMESPACE,
-      )
-      if (view === undefined) throw new Error('welcome acknowledgement settings are unavailable')
-      if (generation !== this.generation) return
-      this.store.update((state) => {
-        state.status = 'ready'
-        state.acknowledged = acknowledgementOf(view) === WELCOME_NOTICE_VERSION
-        state.error = null
-      })
-    } catch (error) {
-      if (generation !== this.generation) return
+      await this.scope.set(WELCOME_NOTICE_ACK_FIELD, WELCOME_NOTICE_VERSION)
+    } finally {
+      this.saving = false
+    }
+    this.derive()
+    const { acknowledged } = this.store.getSnapshot()
+    if (!acknowledged) {
       this.store.update((state) => {
         state.status = 'error'
-        state.acknowledged = false
-        state.error = messageOf(error)
+        state.error = 'the acknowledgement did not persist'
       })
     }
+    return acknowledged
   }
 
-  /**
-   * Persist this copy version, or advance only this process for a remote browser.
-   * @returns true when the selected persistence mode accepted the acknowledgement.
-   */
-  async acknowledge(): Promise<boolean> {
-    const generation = ++this.generation
-    if (this.persistence === 'memory') {
+  /** Stop following the scope. */
+  dispose(): void {
+    this.following?.()
+    this.following = undefined
+  }
+
+  private derive(): void {
+    if (this.saving) return
+    const scope = this.scope.getSnapshot()
+    if (scope.mode === 'memory') {
       this.store.update((state) => {
         state.status = 'ready'
-        state.acknowledged = true
+        state.acknowledged = this.localAcknowledged
         state.error = null
       })
-      return true
+      return
     }
-    this.store.update((state) => { state.status = 'saving'; state.error = null })
-    try {
-      const response = await this.api.settings.mutate({
-        ns: WELCOME_NOTICE_SETTINGS_NAMESPACE,
-        ops: [{ op: 'set', path: [WELCOME_NOTICE_ACK_FIELD], value: WELCOME_NOTICE_VERSION }],
-      })
-      if (!response.result.ok) throw new Error(response.result.error.message)
-      if (generation === this.generation) {
-        this.store.update((state) => {
-          state.status = 'ready'
-          state.acknowledged = true
-          state.error = null
-        })
-      }
-      return true
-    } catch (error) {
-      if (generation === this.generation) {
+    switch (scope.status) {
+      case 'loading':
+        this.store.update((state) => { state.status = 'loading'; state.error = null })
+        return
+      case 'unavailable':
         this.store.update((state) => {
           state.status = 'error'
           state.acknowledged = false
-          state.error = messageOf(error)
+          state.error = 'welcome acknowledgement settings are unavailable'
         })
+        return
+      case 'ready': {
+        const acknowledged = scope.value?.[WELCOME_NOTICE_ACK_FIELD] === WELCOME_NOTICE_VERSION
+        this.store.update((state) => {
+          state.status = 'ready'
+          state.acknowledged = acknowledged
+          state.error = null
+        })
+        return
       }
-      return false
+      /* v8 ignore next -- every current settings scope status is handled above */
+      default: return assertNever(scope.status)
     }
   }
 }
-
-/**
- * Refresh only after welcome state has left idle. A memory-mode load retains
- * acknowledgement so reconnect does not reopen a process-local notice.
- * @param controller - welcome state owner whose current status decides whether to load.
- */
-export function refreshWelcomeIfLoaded(controller: WelcomeNoticeStore): void {
-  if (controller.store.getSnapshot().status === 'idle') return
-  void controller.load()
-}

packages/client/ui-settings-models/tests/apply.client.spec.ts

@@ -5,8 +5,11 @@ import { resolveSlotLabel } from '@deepseek-ai/dsh-client-ui-slots'
 import { SlotRegistry } from '@deepseek-ai/dsh-client-runtime/client'
 import { LocaleRuntime } from '@deepseek-ai/dsh-client-locale/client'
 import { TestRemote, usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
-import { SettingsSchemaService } from '@deepseek-ai/dsh-client-ui-settings/src/client/schema.ts'
+import { apply as settingsApply, inject as settingsInject } from '@deepseek-ai/dsh-client-ui-settings/client'
 import { apply, inject, refreshIfLoaded } from '@deepseek-ai/dsh-client-ui-settings-models/client'
+import {
+  WELCOME_NOTICE_ACK_FIELD, WELCOME_NOTICE_SETTINGS_NAMESPACE, WELCOME_NOTICE_VERSION,
+} from '../src/onboarding-copy.ts'
 import { ModelsSection } from '../src/client/ModelsSection.tsx'
 import { DeepSeekOnboardingDialog } from '../src/client/DeepSeekOnboardingDialog.tsx'
 import { WelcomeNotice } from '../src/client/WelcomeNotice.tsx'
@@ -15,7 +18,7 @@ import { WelcomeNotice } from '../src/client/WelcomeNotice.tsx'
 // the shipped Chinese copy, so they state the browser they assume.
 usePinnedBrowserLanguages('zh-CN')
 
-async function bench(isLoopback = true) {
+async function bench(isLoopback = true, settings?: object, services: object = {}) {
   const ctx = new Context()
   await ctx.plugin(SlotRegistry).await()
   const locale = new LocaleRuntime(ctx)
@@ -23,10 +26,14 @@ async function bench(isLoopback = true) {
   // The plugins inject `remote`; forwarded events reach them through the
   // same `$dispatch` handoff the connection sink makes.
   new TestRemote(ctx)
-  // The apply path only captures the wire face; no call leaves this fake
-  // until a section actually loads.
-  ctx.provide('connection', { api: {}, isLoopback } as never)
-  new SettingsSchemaService(ctx)
+  // Without a settings face the mirror's reads fail and stay contained; the
+  // Models join itself never fetches until a section actually loads. The real
+  // ui-settings apply also provides the settingsSchema service.
+  ctx.provide('connection', {
+    api: settings === undefined ? services : { ...services, settings },
+    isLoopback,
+  } as never)
+  await ctx.plugin({ inject: [...settingsInject], apply: settingsApply }).await()
   return { ctx, slots: ctx.get('slots') as SlotRegistry, locale }
 }
 
@@ -45,7 +52,7 @@ function declare(slots: SlotRegistry): () => void {
 
 describe('ui-settings-models apply', () => {
   it('declares the services it uses', () => {
-    expect(inject).toEqual(['slots', 'locale', 'connection', 'remote', 'settingsSchema'])
+    expect(inject).toEqual(['slots', 'locale', 'connection', 'remote', 'settingsScope', 'settingsSchema'])
   })
 
   it('registers the models nav entry for declarations before or after apply', async () => {
@@ -206,8 +213,31 @@ describe('pushed invalidations', () => {
     expect(load).toHaveBeenCalledTimes(1)
   })
 
-  it('routes only the onboarding namespace invalidation into welcome state', async () => {
-    const b = await bench()
+  it('welcome state follows the shared mirror across document commits', async () => {
+    // The welcome notice derives from its settings scope: a document commit
+    // reaches it through the mirror's one refresh, with no routing here.
+    const acknowledgement = { current: undefined as string | undefined }
+    const settings = {
+      describe: vi.fn(() => Promise.resolve({
+        rpcId: 'apply-welcome' as never,
+        result: {
+          ok: true as const,
+          value: {
+            writable: true,
+            hasDocument: false,
+            namespaces: [{
+              ns: WELCOME_NOTICE_SETTINGS_NAMESPACE,
+              schema: {},
+              value: acknowledgement.current === undefined ? {} : { [WELCOME_NOTICE_ACK_FIELD]: acknowledgement.current },
+              applies: 'live' as const,
+              secrets: [],
+              revision: 0,
+            }],
+          },
+        },
+      })),
+    }
+    const b = await bench(true, settings)
     declare(b.slots)
     await b.ctx.plugin({ inject: [...inject], apply }).await()
     const entry = b.slots.entries('settings.onboarding')
@@ -216,14 +246,59 @@ describe('pushed invalidations', () => {
       entry.inject as unknown as
       () => import('../src/client/WelcomeNotice.tsx').WelcomeNoticeInjected
     )()
-    injected.hooks.welcome.update((state) => { state.status = 'ready' })
-    const load = vi.spyOn(injected.controller, 'load').mockResolvedValue()
+    await injected.controller.load()
+    await vi.waitFor(() => {
+      expect(injected.hooks.welcome.getSnapshot()).toMatchObject({ status: 'ready', acknowledged: false })
+    })
+    acknowledgement.current = WELCOME_NOTICE_VERSION
+    b.ctx.remote.$dispatch('settings/document-updated', ['ui-onboarding', 1])
+    await vi.waitFor(() => {
+      expect(injected.hooks.welcome.getSnapshot()).toMatchObject({ status: 'ready', acknowledged: true })
+    })
+  })
 
-    b.ctx.remote.$dispatch('settings/document-updated', ['llm-deepseek', 1])
-    expect(load).not.toHaveBeenCalled()
-    b.ctx.remote.$dispatch('settings/document-updated', ['ui-onboarding', 2])
-    expect(load).toHaveBeenCalledOnce()
-    b.ctx.emit('connection/reset')
-    expect(load).toHaveBeenCalledTimes(2)
+  it('joins the refreshed mirror view on a settings invalidation', async () => {
+    let revision = 1
+    const describe = vi.fn(() => Promise.resolve({
+      rpcId: `apply-models-${revision}` as never,
+      result: {
+        ok: true as const,
+        value: {
+          writable: true,
+          hasDocument: false,
+          namespaces: [{
+            ns: 'llm-test',
+            schema: {},
+            value: {},
+            applies: 'live' as const,
+            secrets: [],
+            revision,
+          }],
+        },
+      },
+    }))
+    const providers = vi.fn(() => Promise.resolve({
+      rpcId: 'apply-models-providers' as never,
+      result: { ok: true as const, value: { providers: [] } },
+    }))
+    const b = await bench(true, { describe }, { llm: { providers } })
+    declare(b.slots)
+    await b.ctx.plugin({ inject: [...inject], apply }).await()
+    const entry = b.slots.entries('settings.section')
+      .find(candidate => candidate.options.id === 'models')!
+    const injected = (
+      entry.inject as unknown as
+      () => import('../src/client/ModelsSection.tsx').ModelsSectionInjected
+    )()
+    await injected.controller.load()
+    expect(injected.hooks.snapshot.getSnapshot().namespaces.get('llm-test')?.revision).toBe(1)
+
+    revision = 2
+    b.ctx.remote.$dispatch('settings/document-updated', ['llm-test', revision])
+
+    await vi.waitFor(() => {
+      expect(injected.hooks.snapshot.getSnapshot().namespaces.get('llm-test')?.revision).toBe(2)
+    })
+    expect(describe).toHaveBeenCalledTimes(2)
   })
 })

packages/client/ui-settings-models/tests/components.client.spec.tsx

@@ -14,6 +14,7 @@ import {
   DeepSeekModelsEditor, formatCapacity, modelDrafts, parseCapacity, validateDeepSeekModels,
 } from '../src/client/DeepSeekModelsEditor.tsx'
 import { apiKeyFailure } from '../src/client/apiKey.ts'
+import { SettingsDescribeMirror } from '@deepseek-ai/dsh-client-ui-settings/src/client/settings-mirror.ts'
 import { deriveKeyRef, ModelsSettingsStore } from '../src/client/store.ts'
 import type { ProviderRow } from '../src/client/store.ts'
 import { en } from '../src/client/locales.ts'
@@ -186,7 +187,8 @@ type WireFace = ConstructorParameters<typeof ModelsSettingsStore>[0]
 
 async function mountFace(scripted: ReturnType<typeof scriptedFace>) {
   const { face, update, replace, mutate, set, unset } = scripted
-  const controller = new ModelsSettingsStore(face as unknown as WireFace, settingsSchema)
+  const mirror = new SettingsDescribeMirror(face as never)
+  const controller = new ModelsSettingsStore(face as unknown as WireFace, settingsSchema, mirror)
   await controller.load()
   const injected: ModelsSectionProps = {
     controller,
@@ -196,7 +198,7 @@ async function mountFace(scripted: ReturnType<typeof scriptedFace>) {
     t,
   }
   const view = render(<ModelsSection {...injected} />)
-  return { view, face, update, replace, mutate, set, unset, controller }
+  return { view, face, update, replace, mutate, set, unset, controller, mirror }
 }
 
 async function mountSection(overrides: Parameters<typeof scriptedFace>[0] = {}) {
@@ -267,7 +269,7 @@ describe('ModelsSection', () => {
     face.credentials.describe.mockImplementation((payload: { refs: string[] }) => Promise.resolve(ok({
       credentials: Object.fromEntries(payload.refs.map(ref => [ref, { configured: false, writable: true }])),
     })))
-    const controller = new ModelsSettingsStore(face as unknown as WireFace, settingsSchema)
+    const controller = new ModelsSettingsStore(face as unknown as WireFace, settingsSchema, new SettingsDescribeMirror(face as never))
     await controller.load()
     render(<ModelsSection
       controller={controller}
@@ -290,7 +292,7 @@ describe('ModelsSection', () => {
     face.credentials.describe.mockImplementation((payload: { refs: string[] }) => Promise.resolve(ok({
       credentials: Object.fromEntries(payload.refs.map(ref => [ref, { configured: true, writable: true }])),
     })))
-    const controller = new ModelsSettingsStore(face as unknown as WireFace, settingsSchema)
+    const controller = new ModelsSettingsStore(face as unknown as WireFace, settingsSchema, new SettingsDescribeMirror(face as never))
     await controller.load()
     cleanup()
     render(<ModelsSection
@@ -351,7 +353,9 @@ describe('ModelsSection', () => {
     fireEvent.click(screen.getByText(en.apply))
     await waitFor(() => { expect(set).toHaveBeenCalledWith({ ref: 'DEEPSEEK_API_KEY', value: 'sk-live' }) })
     expect(update).not.toHaveBeenCalled()
-    await waitFor(() => { expect(face.settings.describe.mock.calls.length).toBeGreaterThan(1) })
+    // The saved key re-loads the join; the settings answer rides the shared
+    // mirror, so the reload shows as a directory read rather than a describe.
+    await waitFor(() => { expect(face.llm.providers.mock.calls.length).toBeGreaterThan(1) })
     expect((await screen.findByRole('status')).textContent).toBe(
       providerCopy(en.savedProvider, { provider: 'deepseek-official', displayName: 'DeepSeek' }),
     )
@@ -959,7 +963,7 @@ describe('ModelsSection', () => {
     const set = vi.fn()
       .mockResolvedValueOnce(fail('credential store unavailable', 'credential-rejected'))
       .mockResolvedValueOnce(ok({}))
-    const { face, controller } = await mountSection({ mutate, set })
+    const { face, controller, mirror } = await mountSection({ mutate, set })
     fireEvent.click(screen.getByText(en.add))
     await screen.findByLabelText(en.provider)
     fireEvent.change(screen.getByLabelText<HTMLInputElement>(en.keyInput), { target: { value: 'sk-ant' } })
@@ -971,7 +975,12 @@ describe('ModelsSection', () => {
       hasDocument: false,
       namespaces: wireNamespaces().map(namespace => namespace.ns === 'llm-pi-ai' ? afterSettings : namespace),
     }))
-    await act(async () => { await controller.load() })
+    // The refreshed settings answer reaches the page through the mirror's own
+    // refresh (the document commit's invalidation in production).
+    await act(async () => {
+      await mirror.load()
+      await controller.load()
+    })
     expect(controller.store.getSnapshot().namespaces.get('llm-pi-ai')?.revision).toBe(1)
     fireEvent.click(screen.getByText(en.apply))
     await waitFor(() => { expect(set).toHaveBeenCalledTimes(2) })
@@ -1014,7 +1023,7 @@ describe('ModelsSection', () => {
     const unhandled = vi.fn()
     process.on('unhandledRejection', unhandled)
     try {
-      const controller = new ModelsSettingsStore(face as unknown as WireFace, settingsSchema)
+      const controller = new ModelsSettingsStore(face as unknown as WireFace, settingsSchema, new SettingsDescribeMirror(face as never))
       await controller.load()
       render(<ModelsSection
         controller={controller}
@@ -1152,7 +1161,8 @@ describe('ModelsSection', () => {
   it('renders the load failure with a retry control', async () => {
     const face = scriptedFace()
     face.face.llm.providers = vi.fn(() => Promise.resolve(fail('directory down', 'internal'))) as never
-    const controller = new ModelsSettingsStore(face.face as unknown as WireFace, settingsSchema)
+    const controller = new ModelsSettingsStore(
+      face.face as unknown as WireFace, settingsSchema, new SettingsDescribeMirror(face.face as never))
     await controller.load()
     render(<ModelsSection
       controller={controller}
@@ -1173,7 +1183,7 @@ describe('ModelsSection', () => {
       hasDocument: false,
       namespaces: wireNamespaces(),
     })))
-    const controller = new ModelsSettingsStore(face as unknown as WireFace, settingsSchema)
+    const controller = new ModelsSettingsStore(face as unknown as WireFace, settingsSchema, new SettingsDescribeMirror(face as never))
     await controller.load()
     cleanup()
     render(<ModelsSection
@@ -1236,7 +1246,7 @@ describe('ModelsSection', () => {
 
   it('loads on first render of an idle controller', async () => {
     const { face } = scriptedFace()
-    const controller = new ModelsSettingsStore(face as unknown as WireFace, settingsSchema)
+    const controller = new ModelsSettingsStore(face as unknown as WireFace, settingsSchema, new SettingsDescribeMirror(face as never))
     render(<ModelsSection
       controller={controller}
       useSnapshot={bindSnapshotSelector(controller.store)}

packages/client/ui-settings-models/tests/onboarding-dialog.client.spec.tsx

@@ -7,6 +7,7 @@ import type { RpcResponse, SettingsNamespaceView } from '@deepseek-ai/dsh-api-re
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-test-runtime'
 import { DeepSeekOnboardingDialog } from '../src/client/DeepSeekOnboardingDialog.tsx'
 import type { DeepSeekOnboardingDialogProps } from '../src/client/DeepSeekOnboardingDialog.tsx'
+import { SettingsDescribeMirror } from '@deepseek-ai/dsh-client-ui-settings/src/client/settings-mirror.ts'
 import { ModelsSettingsStore } from '../src/client/store.ts'
 import { en } from '../src/client/locales.ts'
 import { settingsSchema } from './settings-schema.client.ts'
@@ -125,7 +126,7 @@ function harness(options: {
       set,
     },
   }
-  const controller = new ModelsSettingsStore(face as never, settingsSchema)
+  const controller = new ModelsSettingsStore(face as never, settingsSchema, new SettingsDescribeMirror(face as never))
   const openSection = vi.fn()
   const complete = vi.fn()
   const unusedHook = (() => { throw new Error('unused standard hook') }) as never

packages/client/ui-settings-models/tests/provider-form.client.spec.tsx

@@ -9,6 +9,7 @@ import { ModelsSection, providerCopy } from '../src/client/ModelsSection.tsx'
 import type { ModelsSectionInjected, ModelsSectionProps } from '../src/client/ModelsSection.tsx'
 import { CustomProviderCard } from '../src/client/CustomProviderCard.tsx'
 import { formatCapacity, parseCapacity } from '../src/client/DeepSeekModelsEditor.tsx'
+import { SettingsDescribeMirror } from '@deepseek-ai/dsh-client-ui-settings/src/client/settings-mirror.ts'
 import { ModelsSettingsStore, deriveKeyRef, protocolChoices } from '../src/client/store.ts'
 import { en } from '../src/client/locales.ts'
 import { settingsSchema } from './settings-schema.client.ts'
@@ -140,7 +141,8 @@ function firstMutate(mutate: ReturnType<typeof vi.fn>): MutateCall {
 
 async function mountSection(options: Parameters<typeof scriptedFace>[0] = {}) {
   const scripted = scriptedFace(options)
-  const controller = new ModelsSettingsStore(scripted.face as unknown as WireFace, settingsSchema)
+  const controller = new ModelsSettingsStore(
+    scripted.face as unknown as WireFace, settingsSchema, new SettingsDescribeMirror(scripted.face as never))
   await controller.load()
   const injected: ModelsSectionProps = {
     controller,
@@ -660,7 +662,8 @@ describe('provider rows', () => {
         active: true,
       }],
     }))) as never
-    const controller = new ModelsSettingsStore(scripted.face as unknown as WireFace, settingsSchema)
+    const controller = new ModelsSettingsStore(
+      scripted.face as unknown as WireFace, settingsSchema, new SettingsDescribeMirror(scripted.face as never))
     await controller.load()
     render(<ModelsSection
       controller={controller}

packages/client/ui-settings-models/tests/store.client.spec.ts

@@ -1,8 +1,9 @@
 /** Page-store join: directory × namespaces × credentials, with last-good rows on failure. */
 import { describe, expect, it } from 'vitest'
 import type { RpcResponse } from '@deepseek-ai/dsh-api-remotes/client'
-import { messageOf, ModelsSettingsStore } from '../src/client/store.ts'
+import { SettingsDescribeMirror } from '@deepseek-ai/dsh-client-ui-settings/src/client/settings-mirror.ts'
 import { settingsSchema } from './settings-schema.client.ts'
+import { messageOf, ModelsSettingsStore } from '../src/client/store.ts'
 
 let nextRpc = 0
 function ok<T>(value: T): RpcResponse<T> {
@@ -67,13 +68,14 @@ function api(overrides: {
       unset: () => Promise.resolve(ok({})),
     },
   }
-  return { face: face as never, seenRefs }
+  const wire = face as never
+  return { face: wire, mirror: new SettingsDescribeMirror(wire), seenRefs }
 }
 
 describe('ModelsSettingsStore', () => {
   it('joins rows with configured, removable, and credential state', async () => {
-    const { face, seenRefs } = api()
-    const store = new ModelsSettingsStore(face, settingsSchema)
+    const { face, mirror, seenRefs } = api()
+    const store = new ModelsSettingsStore(face, settingsSchema, mirror)
     await store.load()
     const state = store.store.getSnapshot()
     expect(state.status).toBe('ready')
@@ -100,8 +102,8 @@ describe('ModelsSettingsStore', () => {
   })
 
   it('degrades the credential badge, not the page, when the credential domain fails', async () => {
-    const { face } = api({ describeCredentials: () => Promise.resolve(fail('no provider')) })
-    const store = new ModelsSettingsStore(face, settingsSchema)
+    const { face, mirror } = api({ describeCredentials: () => Promise.resolve(fail('no provider')) })
+    const store = new ModelsSettingsStore(face, settingsSchema, mirror)
     await store.load()
     const state = store.store.getSnapshot()
     expect(state.status).toBe('ready')
@@ -110,10 +112,10 @@ describe('ModelsSettingsStore', () => {
   })
 
   it('settles a credential transport rejection without leaving the store loading', async () => {
-    const { face } = api({
+    const { face, mirror } = api({
       describeCredentials: () => Promise.reject(new Error('credential transport down')),
     })
-    const store = new ModelsSettingsStore(face, settingsSchema)
+    const store = new ModelsSettingsStore(face, settingsSchema, mirror)
     await expect(store.load()).resolves.toBeUndefined()
     expect(store.store.getSnapshot()).toMatchObject({
       status: 'ready',
@@ -122,22 +124,21 @@ describe('ModelsSettingsStore', () => {
   })
 
   it('stringifies a non-Error credential transport rejection', async () => {
-    const { face } = api({
-      // oxlint-disable-next-line typescript/prefer-promise-reject-errors -- the non-Error rejection is the scenario
-      describeCredentials: () => Promise.reject('credential transport refusal'),
+    const { face, mirror } = api({
+      describeCredentials: async () => { throw 'credential transport refusal' },
     })
-    const store = new ModelsSettingsStore(face, settingsSchema)
+    const store = new ModelsSettingsStore(face, settingsSchema, mirror)
     await expect(store.load()).resolves.toBeUndefined()
     expect(store.store.getSnapshot().credentialError).toBe('credential transport refusal')
   })
 
   it('surfaces a directory failure and keeps the last good rows', async () => {
-    const { face } = api()
-    const store = new ModelsSettingsStore(face, settingsSchema)
+    const { face, mirror } = api()
+    const store = new ModelsSettingsStore(face, settingsSchema, mirror)
     await store.load()
     expect(store.store.getSnapshot().rows).toHaveLength(4)
     const broken = api({ providers: () => Promise.resolve(fail('directory down')) })
-    const failing = new ModelsSettingsStore(broken.face, settingsSchema)
+    const failing = new ModelsSettingsStore(broken.face, settingsSchema, broken.mirror)
     await failing.load()
     expect(failing.store.getSnapshot()).toMatchObject({ status: 'error', error: 'directory down' })
     // The first store's snapshot is untouched by the second's failure.
@@ -148,7 +149,7 @@ describe('ModelsSettingsStore', () => {
     let release: (() => void) | undefined
     const gate = new Promise<void>((resolve) => { release = resolve })
     let call = 0
-    const { face } = api({
+    const { face, mirror } = api({
       providers: async () => {
         call += 1
         if (call === 1) {
@@ -158,7 +159,7 @@ describe('ModelsSettingsStore', () => {
         return ok({ providers: DIRECTORY })
       },
     })
-    const store = new ModelsSettingsStore(face, settingsSchema)
+    const store = new ModelsSettingsStore(face, settingsSchema, mirror)
     const first = store.load()
     const second = store.load()
     release?.()
@@ -169,7 +170,7 @@ describe('ModelsSettingsStore', () => {
 
 describe('edge joins', () => {
   it('treats a non-object profile as having no credential reference', async () => {
-    const { face } = api({
+    const { face, mirror } = api({
       describeSettings: () => Promise.resolve(ok({
         writable: true,
         hasDocument: false,
@@ -188,7 +189,7 @@ describe('edge joins', () => {
         ] as never,
       })),
     })
-    const store = new ModelsSettingsStore(face, settingsSchema)
+    const store = new ModelsSettingsStore(face, settingsSchema, mirror)
     await store.load()
     const state = store.store.getSnapshot()
     expect(state.rows[0]).toMatchObject({ configured: true, removable: false })
@@ -196,7 +197,7 @@ describe('edge joins', () => {
   })
 
   it('skips the credential describe entirely when no row names a reference', async () => {
-    const { face, seenRefs } = api({
+    const { face, mirror, seenRefs } = api({
       describeSettings: () => Promise.resolve(ok({
         writable: true,
         hasDocument: false,
@@ -208,24 +209,56 @@ describe('edge joins', () => {
         ] as never,
       })),
     })
-    const store = new ModelsSettingsStore(face, settingsSchema)
+    const store = new ModelsSettingsStore(face, settingsSchema, mirror)
     await store.load()
     expect(seenRefs).toEqual([])
     expect(store.store.getSnapshot().status).toBe('ready')
   })
 
   it('surfaces a settings describe failure', async () => {
-    const { face } = api({ describeSettings: () => Promise.resolve(fail('settings down')) })
-    const store = new ModelsSettingsStore(face, settingsSchema)
+    const { face, mirror } = api({ describeSettings: () => Promise.resolve(fail('settings down')) })
+    const store = new ModelsSettingsStore(face, settingsSchema, mirror)
     await store.load()
     expect(store.store.getSnapshot()).toMatchObject({ status: 'error', error: 'settings down' })
   })
 
+  it('reports a terminally unavailable settings mirror precisely', async () => {
+    const { face } = api()
+    const store = new ModelsSettingsStore(
+      face,
+      settingsSchema,
+      new SettingsDescribeMirror(face, 'memory'),
+    )
+    await store.load()
+    expect(store.store.getSnapshot()).toMatchObject({
+      status: 'error',
+      error: 'settings are unavailable in this browser',
+    })
+  })
+
+  it('reuses a held settings view after its refresh fails', async () => {
+    let settingsCall = 0
+    const { face, mirror } = api({
+      describeSettings: () => {
+        settingsCall += 1
+        return Promise.resolve(settingsCall === 1
+          ? ok({ writable: true, hasDocument: false, namespaces: NAMESPACES })
+          : fail('settings refresh down'))
+      },
+    })
+    const store = new ModelsSettingsStore(face, settingsSchema, mirror)
+    await store.load()
+    await mirror.load()
+    expect(mirror.getSnapshot().error).toBe('settings refresh down')
+    await store.load()
+    expect(store.store.getSnapshot()).toMatchObject({ status: 'ready', error: null })
+    expect(store.store.getSnapshot().rows).toHaveLength(4)
+  })
+
   it('stringifies a non-Error load failure', async () => {
     // The wire can surface non-Error throwables; the store must stringify them.
-    // oxlint-disable-next-line typescript/prefer-promise-reject-errors -- the non-Error rejection is the scenario
-    const { face } = api({ providers: () => Promise.reject('plain refusal') })
-    const store = new ModelsSettingsStore(face, settingsSchema)
+    const { face, mirror } = api({ providers: async () => { throw 'plain refusal' } })
+    const store = new ModelsSettingsStore(face, settingsSchema, mirror)
     await store.load()
     expect(store.store.getSnapshot()).toMatchObject({ status: 'error', error: 'plain refusal' })
   })
@@ -234,7 +267,7 @@ describe('edge joins', () => {
     let release: (() => void) | undefined
     const gate = new Promise<void>((resolve) => { release = resolve })
     let call = 0
-    const { face } = api({
+    const { face, mirror } = api({
       providers: async () => {
         call += 1
         if (call === 1) {
@@ -244,7 +277,7 @@ describe('edge joins', () => {
         return ok({ providers: DIRECTORY })
       },
     })
-    const store = new ModelsSettingsStore(face, settingsSchema)
+    const store = new ModelsSettingsStore(face, settingsSchema, mirror)
     const first = store.load()
     const second = store.load()
     await second

packages/client/ui-settings-models/tests/welcome-notice.client.spec.tsx

@@ -2,9 +2,17 @@
 import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-test-runtime'
+import { Context } from '@deepseek-ai/cordis'
+import { SettingsSchemaService } from '@deepseek-ai/dsh-client-ui-settings/src/client/schema.ts'
+import { SettingsDescribeMirror } from '@deepseek-ai/dsh-client-ui-settings/src/client/settings-mirror.ts'
+import { SettingsScopeController } from '@deepseek-ai/dsh-client-ui-settings/src/client/settings-scope.ts'
+
+/** Stateless schema service for scope construction in this jsdom fixture. */
+const schemaService = new SettingsSchemaService(new Context())
 import { WelcomeNotice } from '../src/client/WelcomeNotice.tsx'
 import type { WelcomeNoticeProps } from '../src/client/WelcomeNotice.tsx'
-import { WelcomeNoticeStore } from '../src/client/welcome-store.ts'
+import { decodeWelcomeSection, WelcomeNoticeStore } from '../src/client/welcome-store.ts'
+import type { WelcomeSection } from '../src/client/welcome-store.ts'
 import { en, zh } from '../src/client/locales.ts'
 import {
   WELCOME_NOTICE_ACK_FIELD, WELCOME_NOTICE_COPY, WELCOME_NOTICE_SETTINGS_NAMESPACE,
@@ -20,7 +28,24 @@ function response<T>(value: T) {
   return { rpcId: 'welcome-rpc' as never, result: { ok: true as const, value } }
 }
 
-function mount(version?: string, mutateImpl: () => Promise<unknown> = () => Promise.resolve(response({}))) {
+function welcomeView(value: unknown, revision = 0) {
+  return {
+    ns: WELCOME_NOTICE_SETTINGS_NAMESPACE,
+    schema: {},
+    value,
+    base: {},
+    user: {},
+    applies: 'live' as const,
+    secrets: [],
+    revision,
+  }
+}
+
+function mount(
+  version?: string,
+  mutateImpl: () => Promise<unknown> = () =>
+    Promise.resolve(response(welcomeView({ [WELCOME_NOTICE_ACK_FIELD]: WELCOME_NOTICE_VERSION }, 1))),
+) {
   const appRoot = document.createElement('div')
   appRoot.id = 'root'
   document.body.append(appRoot)
@@ -30,21 +55,21 @@ function mount(version?: string, mutateImpl: () => Promise<unknown> = () => Prom
       describe: () => Promise.resolve(response({
         writable: true,
         hasDocument: false,
-        namespaces: [{
-          ns: WELCOME_NOTICE_SETTINGS_NAMESPACE,
-          schema: {},
-          value: version === undefined ? {} : { [WELCOME_NOTICE_ACK_FIELD]: version },
-          base: {},
-          user: {},
-          applies: 'live' as const,
-          secrets: [],
-          revision: 0,
-        }],
+        namespaces: [welcomeView(version === undefined ? {} : { [WELCOME_NOTICE_ACK_FIELD]: version })],
       })),
       mutate,
     },
   }
-  const controller = new WelcomeNoticeStore(api as never)
+  const mirror = new SettingsDescribeMirror(api as never)
+  const scope = new SettingsScopeController<WelcomeSection>(
+    api as never,
+    { namespace: WELCOME_NOTICE_SETTINGS_NAMESPACE, decode: decodeWelcomeSection },
+    mirror,
+    'host',
+    schemaService,
+  )
+  const controller = new WelcomeNoticeStore(scope)
+  void mirror.load()
   const complete = vi.fn()
   const unusedHook = (() => { throw new Error('unused standard hook') }) as never
   const props: WelcomeNoticeProps = {
@@ -57,7 +82,7 @@ function mount(version?: string, mutateImpl: () => Promise<unknown> = () => Prom
     useWelcome: bindSnapshotSelector(controller.store),
     t: key => zh[key],
   }
-  return { ...render(<WelcomeNotice {...props} />), complete, controller, mutate, appRoot }
+  return { ...render(<WelcomeNotice {...props} />), complete, controller, mirror, mutate, appRoot }
 }
 
 describe('WelcomeNotice', () => {
@@ -100,7 +125,10 @@ describe('WelcomeNotice', () => {
 
   it('skips itself when this exact version was already acknowledged', async () => {
     const h = mount(WELCOME_NOTICE_VERSION)
-    await act(async () => { await h.controller.load() })
+    await act(async () => {
+      await h.mirror.load()
+      await h.controller.load()
+    })
     expect(screen.queryByRole('dialog')).toBeNull()
     expect(h.complete).toHaveBeenCalledOnce()
   })

packages/client/ui-settings-models/tests/welcome-store.client.spec.ts

@@ -1,40 +1,58 @@
 import { describe, expect, it, vi } from 'vitest'
 import type { RpcResponse } from '@deepseek-ai/dsh-api-remotes/client'
-import { refreshWelcomeIfLoaded, WelcomeNoticeStore } from '../src/client/welcome-store.ts'
+import { Context } from '@deepseek-ai/cordis'
+import { SettingsSchemaService } from '@deepseek-ai/dsh-client-ui-settings/src/client/schema.ts'
+import { SettingsDescribeMirror } from '@deepseek-ai/dsh-client-ui-settings/src/client/settings-mirror.ts'
+import { SettingsScopeController } from '@deepseek-ai/dsh-client-ui-settings/src/client/settings-scope.ts'
+import { decodeWelcomeSection, WelcomeNoticeStore } from '../src/client/welcome-store.ts'
 import {
   WELCOME_NOTICE_ACK_FIELD, WELCOME_NOTICE_SETTINGS_NAMESPACE, WELCOME_NOTICE_VERSION,
 } from '../src/onboarding-copy.ts'
 
+const schemaService = new SettingsSchemaService(new Context())
+
 let rpc = 0
 function ok<T>(value: T): RpcResponse<T> {
   return { rpcId: `welcome-${rpc++}` as never, result: { ok: true, value } }
 }
 
-function namespace(version?: string) {
+function namespace(value: unknown = {}, revision = 0) {
   return {
     ns: WELCOME_NOTICE_SETTINGS_NAMESPACE,
     schema: {},
-    value: version === undefined ? {} : { [WELCOME_NOTICE_ACK_FIELD]: version },
-    base: {},
-    user: {},
+    value,
     applies: 'live' as const,
     secrets: [],
-    revision: 0,
+    revision,
   }
 }
 
-function deferred<T>() {
-  let resolve!: (value: T) => void
-  let reject!: (reason: unknown) => void
-  const promise = new Promise<T>((res, rej) => { resolve = res; reject = rej })
-  return { promise, resolve, reject }
+function acknowledgedNamespace(version: string, revision = 1) {
+  return namespace({ [WELCOME_NOTICE_ACK_FIELD]: version }, revision)
+}
+
+/** The welcome store over a real mirror-derived scope and a fake wire. */
+function buildWelcome(
+  api: { describe?: ReturnType<typeof vi.fn>; mutate?: ReturnType<typeof vi.fn> },
+  persistence: 'host' | 'memory' = 'host',
+) {
+  const wire = { settings: api } as never
+  const mirror = new SettingsDescribeMirror(wire, persistence)
+  const scope = new SettingsScopeController(
+    wire,
+    { namespace: WELCOME_NOTICE_SETTINGS_NAMESPACE, decode: decodeWelcomeSection },
+    mirror,
+    persistence,
+    schemaService,
+  )
+  return { mirror, controller: new WelcomeNoticeStore(scope) }
 }
 
 describe('WelcomeNoticeStore', () => {
   it('acknowledges in memory without calling loopback-only settings APIs', async () => {
-    const describe = vi.fn()
+    const describeCall = vi.fn()
     const mutate = vi.fn()
-    const controller = new WelcomeNoticeStore({ settings: { describe, mutate } } as never, 'memory')
+    const { controller } = buildWelcome({ describe: describeCall, mutate }, 'memory')
 
     await controller.load()
     expect(controller.store.getSnapshot()).toEqual({ status: 'ready', acknowledged: false, error: null })
@@ -42,7 +60,7 @@ describe('WelcomeNoticeStore', () => {
     expect(controller.store.getSnapshot()).toEqual({ status: 'ready', acknowledged: true, error: null })
     await controller.load()
     expect(controller.store.getSnapshot()).toEqual({ status: 'ready', acknowledged: true, error: null })
-    expect(describe).not.toHaveBeenCalled()
+    expect(describeCall).not.toHaveBeenCalled()
     expect(mutate).not.toHaveBeenCalled()
   })
 
@@ -52,148 +70,101 @@ describe('WelcomeNoticeStore', () => {
       ['older-copy', false],
       [WELCOME_NOTICE_VERSION, true],
     ] as const) {
-      const api = {
-        settings: {
-          describe: vi.fn(() => Promise.resolve(ok({
-            writable: true, hasDocument: false, namespaces: [namespace(version)],
-          }))),
-        },
-      }
-      const controller = new WelcomeNoticeStore(api as never)
+      const describeCall = vi.fn(() => Promise.resolve(ok({
+        writable: true,
+        hasDocument: false,
+        namespaces: [version === undefined ? namespace() : acknowledgedNamespace(version)],
+      })))
+      const { mirror, controller } = buildWelcome({ describe: describeCall })
+      await mirror.load()
       await controller.load()
       expect(controller.store.getSnapshot()).toMatchObject({ status: 'ready', acknowledged })
     }
   })
 
-  it('persists the owner version through one idempotent path mutation', async () => {
-    const mutate = vi.fn(() => Promise.resolve(ok(namespace(WELCOME_NOTICE_VERSION))))
-    const controller = new WelcomeNoticeStore({ settings: { mutate } } as never)
+  it('persists the owner version through one revision-fenced mutation', async () => {
+    const describeCall = vi.fn(() => Promise.resolve(ok({
+      writable: true, hasDocument: false, namespaces: [namespace({}, 3)],
+    })))
+    const mutate = vi.fn(() => Promise.resolve(ok(acknowledgedNamespace(WELCOME_NOTICE_VERSION, 4))))
+    const { mirror, controller } = buildWelcome({ describe: describeCall, mutate })
+    await mirror.load()
+    await controller.load()
     await expect(controller.acknowledge()).resolves.toBe(true)
     expect(mutate).toHaveBeenCalledWith({
       ns: WELCOME_NOTICE_SETTINGS_NAMESPACE,
       ops: [{ op: 'set', path: [WELCOME_NOTICE_ACK_FIELD], value: WELCOME_NOTICE_VERSION }],
+      expectedRevision: 3,
     })
     expect(controller.store.getSnapshot()).toMatchObject({ status: 'ready', acknowledged: true })
+    // The write answer folded into the mirror; no re-read followed.
+    expect(describeCall).toHaveBeenCalledTimes(1)
   })
 
-  it('keeps the notice pending when loading or persistence fails', async () => {
-    const load = new WelcomeNoticeStore({
-      settings: { describe: () => Promise.reject(new Error('offline')) },
-    } as never)
-    await load.load()
-    expect(load.store.getSnapshot()).toEqual({ status: 'error', acknowledged: false, error: 'offline' })
-
-    const save = new WelcomeNoticeStore({
-      settings: { mutate: () => Promise.reject(new Error('disk full')) },
-    } as never)
-    await expect(save.acknowledge()).resolves.toBe(false)
-    expect(save.store.getSnapshot()).toEqual({ status: 'error', acknowledged: false, error: 'disk full' })
+  it('keeps the notice pending while the settings read has not answered', async () => {
+    const describeCall = vi.fn(() => Promise.reject(new Error('offline')))
+    const { mirror, controller } = buildWelcome({ describe: describeCall })
+    await mirror.load()
+    await controller.load()
+    // No answer stands, so the step renders nothing and never acknowledges.
+    expect(controller.store.getSnapshot()).toEqual({ status: 'loading', acknowledged: false, error: null })
+  })
 
-    const nonError = new WelcomeNoticeStore({
-      // Durable/wire failures are unknown; exercise containment of a non-Error rejection.
-      settings: { describe: () => Promise.reject(new Error('offline string')) },
-    } as never)
-    await nonError.load()
-    expect(nonError.store.getSnapshot().error).toBe('offline string')
+  it('reports a failed or refused persistence attempt after its recovery read', async () => {
+    const describeCall = vi.fn(() => Promise.resolve(ok({
+      writable: true, hasDocument: false, namespaces: [namespace()],
+    })))
+    const mutate = vi.fn(() => Promise.reject(new Error('disk full')))
+    const { mirror, controller } = buildWelcome({ describe: describeCall, mutate })
+    await mirror.load()
+    await controller.load()
+    await expect(controller.acknowledge()).resolves.toBe(false)
+    expect(controller.store.getSnapshot()).toMatchObject({
+      status: 'error',
+      acknowledged: false,
+      error: 'the acknowledgement did not persist',
+    })
+    // The failed latest write triggered one mirror recovery read.
+    expect(describeCall).toHaveBeenCalledTimes(2)
   })
 
-  it('reports business failures, missing namespaces, and malformed durable values', async () => {
-    for (const describe of [
-      () => Promise.resolve({
-        rpcId: 'failed' as never,
-        result: { ok: false as const, error: { code: 'internal' as const, message: 'denied', details: {} } },
-      }),
-      () => Promise.resolve(ok({ writable: true, hasDocument: false, namespaces: [] })),
-    ]) {
-      const controller = new WelcomeNoticeStore({ settings: { describe } } as never)
-      await controller.load()
-      expect(controller.store.getSnapshot().status).toBe('error')
-    }
+  it('reports a missing namespace as an error instead of a silent skip', async () => {
+    const describeCall = vi.fn(() => Promise.resolve(ok({
+      writable: true, hasDocument: false, namespaces: [],
+    })))
+    const { mirror, controller } = buildWelcome({ describe: describeCall })
+    await mirror.load()
+    await controller.load()
+    expect(controller.store.getSnapshot()).toMatchObject({
+      status: 'error',
+      error: 'welcome acknowledgement settings are unavailable',
+    })
+  })
 
+  it('reads malformed durable values as unacknowledged', async () => {
     for (const value of [null, 42, { [WELCOME_NOTICE_ACK_FIELD]: 42 }]) {
-      const controller = new WelcomeNoticeStore({
-        settings: { describe: () => Promise.resolve(ok({
-          writable: true,
-          hasDocument: false,
-          namespaces: [{ ...namespace(), value }],
-        })) },
-      } as never)
+      const describeCall = vi.fn(() => Promise.resolve(ok({
+        writable: true, hasDocument: false, namespaces: [namespace(value)],
+      })))
+      const { mirror, controller } = buildWelcome({ describe: describeCall })
+      await mirror.load()
       await controller.load()
       expect(controller.store.getSnapshot()).toMatchObject({ status: 'ready', acknowledged: false })
     }
-
-    const save = new WelcomeNoticeStore({
-      settings: { mutate: () => Promise.resolve({
-        rpcId: 'failed-save' as never,
-        result: {
-          ok: false,
-          error: {
-            code: 'settings-rejected',
-            message: 'denied',
-            details: { ns: WELCOME_NOTICE_SETTINGS_NAMESPACE },
-          },
-        },
-      }) },
-    } as never)
-    await expect(save.acknowledge()).resolves.toBe(false)
-    expect(save.store.getSnapshot().error).toBe('denied')
-  })
-
-  it('lets the latest load win over stale success and failure', async () => {
-    const first = deferred<ReturnType<typeof ok>>()
-    const describe = vi.fn()
-      .mockImplementationOnce(() => first.promise)
-      .mockImplementationOnce(() => Promise.resolve(ok({
-        writable: true, hasDocument: false, namespaces: [namespace()],
-      })))
-    const controller = new WelcomeNoticeStore({ settings: { describe } } as never)
-    const stale = controller.load()
-    await controller.load()
-    first.resolve(ok({
-      writable: true, hasDocument: false, namespaces: [namespace(WELCOME_NOTICE_VERSION)],
-    }))
-    await stale
-    expect(controller.store.getSnapshot().acknowledged).toBe(false)
-
-    const failed = deferred<ReturnType<typeof ok>>()
-    describe
-      .mockImplementationOnce(() => failed.promise)
-      .mockImplementationOnce(() => Promise.resolve(ok({
-        writable: true, hasDocument: false, namespaces: [namespace(WELCOME_NOTICE_VERSION)],
-      })))
-    const staleFailure = controller.load()
-    await controller.load()
-    failed.reject('stale failure')
-    await staleFailure
-    expect(controller.store.getSnapshot()).toMatchObject({ status: 'ready', acknowledged: true, error: null })
   })
 
-  it('contains stale acknowledgement settlements and refreshes only a loaded store', async () => {
-    const write = deferred<ReturnType<typeof ok>>()
-    const describe = vi.fn(() => Promise.resolve(ok({
-      writable: true, hasDocument: false, namespaces: [namespace()],
-    })))
-    const controller = new WelcomeNoticeStore({
-      settings: { mutate: () => write.promise, describe },
-    } as never)
-    refreshWelcomeIfLoaded(controller)
-    expect(describe).not.toHaveBeenCalled()
-    const staleWrite = controller.acknowledge()
+  it('follows a later document change without an own read', async () => {
+    const describeCall = vi.fn()
+      .mockResolvedValueOnce(ok({ writable: true, hasDocument: false, namespaces: [namespace()] }))
+      .mockResolvedValueOnce(ok({
+        writable: true, hasDocument: false,
+        namespaces: [acknowledgedNamespace(WELCOME_NOTICE_VERSION)],
+      }))
+    const { mirror, controller } = buildWelcome({ describe: describeCall })
+    await mirror.load()
     await controller.load()
-    write.resolve(ok(namespace(WELCOME_NOTICE_VERSION)))
-    await expect(staleWrite).resolves.toBe(true)
-    expect(controller.store.getSnapshot().acknowledged).toBe(false)
-    refreshWelcomeIfLoaded(controller)
-    await vi.waitFor(() => { expect(describe).toHaveBeenCalledTimes(2) })
-
-    const failedWrite = deferred<ReturnType<typeof ok>>()
-    const staleFailure = new WelcomeNoticeStore({
-      settings: { mutate: () => failedWrite.promise, describe },
-    } as never)
-    const pending = staleFailure.acknowledge()
-    await staleFailure.load()
-    failedWrite.reject('late failure')
-    await expect(pending).resolves.toBe(false)
-    expect(staleFailure.store.getSnapshot().status).toBe('ready')
+    expect(controller.store.getSnapshot()).toMatchObject({ acknowledged: false })
+    await mirror.load()
+    expect(controller.store.getSnapshot()).toMatchObject({ status: 'ready', acknowledged: true })
   })
 })

packages/client/ui-settings-plugins/src/client/index.ts

@@ -72,26 +72,17 @@ export function apply(ctx: ClientContext): void {
     'ui-settings-plugins: credential invalidations',
   )
 
-  // Which namespaces the Host serves is a registration fact the wire does not
-  // announce, so the directory re-reads on the two signals that can carry a
-  // changed composition: a settings document commit and a reconnect.
+  // Which namespaces the Host serves comes from the shared describe mirror,
+  // whose owning plugin already refreshes it on document commits and
+  // reconnects — the tab only derives.
   const configurable = new ConfigurablePluginsTabController(
-    api, () => ctx.slots.entries('settings.plugin.item'))
+    ctx.settingsScope.describe(), () => ctx.slots.entries('settings.plugin.item'))
   ctx.effect(() => () => { configurable.dispose() }, 'ui-settings-plugins: tab directory')
-  ctx.effect(
-    () => ctx.remote.$on('settings/document-updated', () => { void configurable.load() }),
-    'ui-settings-plugins: served-namespace invalidations',
-  )
-  ctx.effect(
-    () => ctx.on('connection/reset', () => { void configurable.load() }),
-    'ui-settings-plugins: served-namespace reconnect',
-  )
   // A card registered after the first read joins the list without a wire call.
   ctx.effect(
     () => ctx.slots.subscribe('settings.plugin.item', () => { configurable.refresh() }),
     'ui-settings-plugins: card ledger',
   )
-  void configurable.load()
 
   let tabsVersion = -1
   let tabsRevision = -1

packages/client/ui-settings-plugins/src/client/tab-store.ts

@@ -10,7 +10,7 @@
  * trace and does not count toward the empty line.
  */
 
-import type { IApiClient } from '@deepseek-ai/dsh-client-connection/client'
+import type { SettingsDescribeFace } from '@deepseek-ai/dsh-client-ui-settings/client'
 import type { StoredEntry } from '@deepseek-ai/dsh-client-ui-slots'
 import { createSnapshotStore, type SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
 
@@ -42,47 +42,23 @@ export interface ConfigurablePluginsTabFace {
   }
 }
 
-/** Reads the served namespaces and pairs them with the cards that claim them. */
+/** Derives the served namespaces from the shared describe mirror and pairs them with the cards that claim them. */
 export class ConfigurablePluginsTabController {
   private readonly store = createSnapshotStore<ConfigurablePluginsTabState>({ loaded: false, namespaces: [] })
-  /** Last Host answer; kept so a slot mutation republishes without a wire read. */
-  private served: readonly string[] = []
-  private loaded = false
-  private generation = 0
   private disposed = false
+  private readonly unsubscribe: () => void
 
   /**
-   * @param api - settings wire face.
+   * @param describeFace - the shared mirror's describe face; its refreshes
+   * (document commits, reconnects) are what keep the served set current.
    * @param entries - reads the cards currently registered into the section's slot.
    */
   constructor(
-    private readonly api: Pick<IApiClient, 'settings'>,
+    private readonly describeFace: SettingsDescribeFace,
     private readonly entries: () => readonly StoredEntry[],
-  ) {}
-
-  /** Opaque read of {@link disposed}: control flow cannot narrow it across awaits. */
-  private isDisposed(): boolean {
-    return this.disposed
-  }
-
-  /**
-   * Re-read the served namespaces from the Host and republish.
-   * @returns settlement after the read, or immediately once disposed.
-   */
-  async load(): Promise<void> {
-    if (this.isDisposed()) return
-    const generation = ++this.generation
-    let response: Awaited<ReturnType<IApiClient['settings']['describe']>>
-    try {
-      response = await this.api.settings.describe({})
-    } catch (_settingsReadFailure) {
-      // The tab keeps the namespaces it last knew; the next invalidation
-      // or reconnect reads again.
-      return
-    }
-    if (this.isDisposed() || generation !== this.generation || !response.result.ok) return
-    this.served = response.result.value.namespaces.map(view => view.ns)
-    this.loaded = true
+  ) {
+    this.unsubscribe = describeFace.subscribe(() => { this.publish() })
+    void describeFace.ensure()
     this.publish()
   }
 
@@ -92,10 +68,10 @@ export class ConfigurablePluginsTabController {
     this.publish()
   }
 
-  /** Stop publishing; an in-flight read settles without touching the store. */
+  /** Stop publishing and stop following the mirror. */
   dispose(): void {
     this.disposed = true
-    this.generation += 1
+    this.unsubscribe()
   }
 
   /**
@@ -107,17 +83,20 @@ export class ConfigurablePluginsTabController {
   }
 
   private publish(): void {
-    const served = new Set(this.served)
+    if (this.disposed) return
+    const mirrored = this.describeFace.getSnapshot()
+    const loaded = mirrored.view !== undefined
+    const served = new Set(mirrored.view?.namespaces.map(view => view.ns) ?? [])
     const namespaces = this.entries().flatMap(entry =>
       entry.options.key !== undefined && served.has(entry.options.key) ? [entry.options.key] : [])
     const previous = this.store.getSnapshot()
-    // Every settings-document commit re-reads, and most of them change nothing
-    // this section shows. An observable source must keep its snapshot
-    // reference until the fact moves, or each unrelated save re-renders the
-    // whole card list (packages/client/AGENTS.md reactive rule 5).
-    if (previous.loaded === this.loaded
+    // Every settings-document commit refreshes the mirror, and most commits
+    // change nothing this section shows. An observable source must keep its
+    // snapshot reference until the fact moves, or each unrelated save
+    // re-renders the whole card list (packages/client/AGENTS.md reactive rule 5).
+    if (previous.loaded === loaded
       && previous.namespaces.length === namespaces.length
       && previous.namespaces.every((ns, index) => ns === namespaces[index])) return
-    this.store.set({ loaded: this.loaded, namespaces })
+    this.store.set({ loaded, namespaces })
   }
 }

packages/client/ui-settings-plugins/tests/apply.client.spec.ts

@@ -6,8 +6,7 @@ import { resolveSlotLabel } from '@deepseek-ai/dsh-client-ui-slots'
 import { SlotRegistry } from '@deepseek-ai/dsh-client-runtime/client'
 import { LocaleRuntime } from '@deepseek-ai/dsh-client-locale/client'
 import { TestRemote, usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
-import { SettingsSchemaService } from '@deepseek-ai/dsh-client-ui-settings/src/client/schema.ts'
-import { SettingsScopeBinder } from '@deepseek-ai/dsh-client-ui-settings/src/client/settings-scope.ts'
+import { apply as settingsApply, inject as settingsInject } from '@deepseek-ai/dsh-client-ui-settings/client'
 import { apply, inject } from '@deepseek-ai/dsh-client-ui-settings-plugins/client'
 import type {
   ConfigurablePluginsTabFace, PluginsSettingsSectionInjected,
@@ -53,7 +52,7 @@ async function bench(served?: string[]) {
       credentials: { describe: describeCredentials },
     },
   } as never)
-  await ctx.plugin(SettingsScopeBinder, new SettingsSchemaService(ctx)).await()
+  await ctx.plugin({ inject: [...settingsInject], apply: settingsApply }).await()
   return { ctx, slots: ctx.get('slots') as SlotRegistry, describeCredentials, describeSettings }
 }
 

packages/client/ui-settings-plugins/tests/stores.client.spec.ts

@@ -8,6 +8,9 @@ import { stubSettingsScope, type StubSettingsScope } from '@deepseek-ai/dsh-clie
 import { CardForm, numberField, textField } from '../src/client/card-form.ts'
 import { AgentLoopCardController, type AgentLoopSettings } from '../src/client/agent-loop-card-controller.ts'
 import { BashCardController, type BashSettings } from '../src/client/bash-card-controller.ts'
+import {
+  SettingsDescribeMirror, type SettingsMirrorSnapshot,
+} from '@deepseek-ai/dsh-client-ui-settings/src/client/settings-mirror.ts'
 import { ConfigurablePluginsTabController } from '../src/client/tab-store.ts'
 import { WebSearchCardController, type WebSearchSettings } from '../src/client/web-search-card-controller.ts'
 
@@ -555,7 +558,7 @@ describe('ConfigurablePluginsTabController', () => {
         },
       },
     }))
-    return { api: { settings: { describe } } as never, describe }
+    return { mirror: new SettingsDescribeMirror({ settings: { describe } } as never), describe }
   }
 
   /** Slot ledger stand-in: one stored entry per registered card key. */
@@ -565,9 +568,9 @@ describe('ConfigurablePluginsTabController', () => {
 
   it('dispatches the served namespaces a card claims, in card registration order', async () => {
     const settings = settingsApi(['bash', 'ui-theme', 'agent-loop'])
-    const controller = new ConfigurablePluginsTabController(settings.api, () => ledger('agent-loop', 'bash'))
+    const controller = new ConfigurablePluginsTabController(settings.mirror, () => ledger('agent-loop', 'bash'))
 
-    await controller.load()
+    await settings.mirror.ensure()
 
     // ui-theme is served but claimed by no card here — another surface owns
     // it. The order is the cards', not the Host's: plugin activation can
@@ -578,9 +581,9 @@ describe('ConfigurablePluginsTabController', () => {
 
   it('never dispatches a card whose namespace this deployment does not serve', async () => {
     const settings = settingsApi(['bash'])
-    const controller = new ConfigurablePluginsTabController(settings.api, () => ledger('bash', 'web-search-deepseek'))
+    const controller = new ConfigurablePluginsTabController(settings.mirror, () => ledger('bash', 'web-search-deepseek'))
 
-    await controller.load()
+    await settings.mirror.ensure()
 
     expect(controller.inject().hooks.configurablePlugins.getSnapshot().namespaces).toEqual(['bash'])
   })
@@ -588,8 +591,8 @@ describe('ConfigurablePluginsTabController', () => {
   it('takes a card registered after the read without asking the Host again', async () => {
     const settings = settingsApi(['bash'])
     let entries = ledger()
-    const controller = new ConfigurablePluginsTabController(settings.api, () => entries)
-    await controller.load()
+    const controller = new ConfigurablePluginsTabController(settings.mirror, () => entries)
+    await settings.mirror.ensure()
     expect(controller.inject().hooks.configurablePlugins.getSnapshot().namespaces).toEqual([])
 
     entries = ledger('bash')
@@ -599,34 +602,33 @@ describe('ConfigurablePluginsTabController', () => {
     expect(settings.describe).toHaveBeenCalledOnce()
   })
 
-  it('keeps the namespaces it knew when a read fails', async () => {
+  it('keeps the namespaces it knew when a refresh fails', async () => {
     const settings = settingsApi(['bash'])
-    const controller = new ConfigurablePluginsTabController(settings.api, () => ledger('bash'))
-    await controller.load()
+    const controller = new ConfigurablePluginsTabController(settings.mirror, () => ledger('bash'))
+    await settings.mirror.ensure()
     settings.describe.mockRejectedValueOnce(new Error('offline'))
 
-    await controller.load()
+    await settings.mirror.load()
 
     expect(controller.inject().hooks.configurablePlugins.getSnapshot().namespaces).toEqual(['bash'])
   })
 
-  it('publishes nothing once disposed, and never claims it was answered', async () => {
+  it('stops following the mirror once disposed, and never claims it was answered', async () => {
     const settings = settingsApi(['bash'])
-    const controller = new ConfigurablePluginsTabController(settings.api, () => ledger('bash'))
+    const controller = new ConfigurablePluginsTabController(settings.mirror, () => ledger('bash'))
 
     controller.dispose()
-    await controller.load()
+    await settings.mirror.load()
 
     expect(controller.inject().hooks.configurablePlugins.getSnapshot())
       .toEqual({ loaded: false, namespaces: [] })
-    expect(settings.describe).not.toHaveBeenCalled()
   })
 
   it('ignores a slot-ledger change that arrives after disposal', async () => {
     const settings = settingsApi(['bash'])
     let entries = ledger()
-    const controller = new ConfigurablePluginsTabController(settings.api, () => entries)
-    await controller.load()
+    const controller = new ConfigurablePluginsTabController(settings.mirror, () => entries)
+    await settings.mirror.ensure()
 
     controller.dispose()
     entries = ledger('bash')
@@ -635,33 +637,49 @@ describe('ConfigurablePluginsTabController', () => {
     expect(controller.inject().hooks.configurablePlugins.getSnapshot().namespaces).toEqual([])
   })
 
-  it('drops a read a newer one superseded', async () => {
-    // The section re-reads on every settings-document invalidation, so a slow
-    // first answer must not overwrite the newer one that already landed.
-    const settings = settingsApi(['bash'])
-    const controller = new ConfigurablePluginsTabController(settings.api, () => ledger('bash', 'agent-loop'))
-    const slow = Promise.withResolvers<unknown>()
-    settings.describe.mockReturnValueOnce(slow.promise as never)
-    const stale = controller.load()
+  it('ignores a mirror notification already queued when disposal starts', () => {
+    let notify = (): void => {}
+    let snapshot: SettingsMirrorSnapshot = {
+      status: 'ready' as const,
+      view: { writable: true, hasDocument: true, namespaces: [] },
+      error: null,
+    }
+    const describeFace = {
+      getSnapshot: () => snapshot,
+      subscribe: (listener: () => void) => {
+        notify = listener
+        return () => {}
+      },
+      ensure: () => Promise.resolve(),
+      acceptView: vi.fn(),
+    } as never
+    const controller = new ConfigurablePluginsTabController(describeFace, () => ledger('bash'))
+    expect(controller.inject().hooks.configurablePlugins.getSnapshot())
+      .toEqual({ loaded: true, namespaces: [] })
 
-    await controller.load()
-    expect(controller.inject().hooks.configurablePlugins.getSnapshot().namespaces).toEqual(['bash'])
-    slow.resolve({
-      rpcId: 's-0',
-      result: { ok: true, value: { writable: true, hasDocument: true, namespaces: [
-        { ns: 'agent-loop', schema: {}, value: {}, applies: 'live', secrets: [], revision: 0 },
-      ] } },
-    })
-    await stale
+    controller.dispose()
+    snapshot = {
+      status: 'ready',
+      view: {
+        writable: true,
+        hasDocument: true,
+        namespaces: [{
+          ns: 'bash', schema: {}, value: {}, applies: 'live', secrets: [], revision: 1,
+        }],
+      },
+      error: null,
+    }
+    notify()
 
-    expect(controller.inject().hooks.configurablePlugins.getSnapshot().namespaces).toEqual(['bash'])
+    expect(controller.inject().hooks.configurablePlugins.getSnapshot())
+      .toEqual({ loaded: true, namespaces: [] })
   })
 
   it('reports the Host answered even when it serves nothing this tab shows', async () => {
     const settings = settingsApi(['ui-theme'])
-    const controller = new ConfigurablePluginsTabController(settings.api, () => ledger('bash'))
+    const controller = new ConfigurablePluginsTabController(settings.mirror, () => ledger('bash'))
 
-    await controller.load()
+    await settings.mirror.ensure()
 
     expect(controller.inject().hooks.configurablePlugins.getSnapshot())
       .toEqual({ loaded: true, namespaces: [] })

packages/client/ui-settings/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/client/ui-settings/README.md
-README.md: 723e6f7120c256406daedd2085eef055b72263fe
-README.zh.md: 42f6f6e09ee520542ddc74344be5619adf5adf02
+README.md: 990469573309b3a92b5eeb8bc41d89b226dbd0d4
+README.zh.md: a0ce9d5cf6d4633cec9fbf466083c7a11a947e8e

packages/client/ui-settings/README.md

@@ -4,8 +4,7 @@ English | [中文](README.zh.md)
 
 The settings domain's base layer, with no presentation of its own. It provides `ctx.settingsScope`, the Host transport every preference row binds its durable namespace section through; `ctx.settingsSchema`, the synchronous schema-rehydration, validation, and immutable path-editing service used by settings plugins; and the settings slot types registrants fill: `settings.trigger` / `settings.header` / `settings.close` (chrome content), `settings.action` (ordered content-header actions), `settings.section` (one page per feature), `settings.plugins.tab` (feature-owned pages inside the Plugins section), and `settings.onboarding` (ordered feature-owned pages). It depends on no `ui-*` presentation package, so any feature that owns a preference can reach it; the settings SHELL — the `sidebar.settings` occupant, its navigation, and the chrome — lives in ui-settings-general, because a shell dependency on ui-sidebar would close a reference graph cycle through ui-layout and ui-theme. The shell's own contract types live beside the shell for the same reason.
 
-The plugin injects nothing and waits for nothing: schema operations are synchronous, while `ctx.settingsScope.bind(spec)` resolves the wire face through the caller's context at call time. The bound scope's disposer belongs to the calling fiber, and the caller injects `connection` for the transport and `remote` for invalidation. Listeners exist before the first background read starts, so a row's activation never blocks on the settings transport. A bound scope reloads on the forwarded `settings/document-updated` event for its own namespace and on `connection/reset`. Writes carry one field path and the last known namespace revision as `expectedRevision`; a rejected or failed write re-reads unless a newer write already superseded it, and a stale read never publishes over a newer one. The snapshot carries the resolved section, composition `base`, raw `user`, revision, writability, and host/memory mode. A field is overridden when it is present in `user`, even when its value equals `base`; `unset` clears that override. Without a `decode` in the spec, a section that is not a plain object, fails its rehydrated schema, or carries a schema envelope this client cannot rehydrate publishes no value at all, so a row renders its own absent state instead of a half-decoded one.
-
+The plugin injects `connection` and `remote` and owns the one `settings.describe` reader in the browser: a shared mirror holding the whole answer, refreshed on every forwarded `settings/document-updated` event and on `connection/reset` (the first connection included — that read closes the window where a commit lands between the eager read and the SSE subscription). Schema operations are synchronous and live on the `settingsSchema` service. `ctx.settingsScope.bind(spec)` returns a per-namespace scope DERIVED from the mirror on the CALLER's context — the scope's disposer belongs to the calling fiber, binding adds no wire read, a row's activation never blocks on the settings transport, and every derived surface shows the same document revision at any moment. Cross-namespace surfaces (schema introspection, the served-namespace directory, `hasDocument`) read the same mirror through `ctx.settingsScope.describe()`, a read/fold face (`getSnapshot`/`subscribe`/`ensure`, plus `acceptView` folding a write answer in). The scope snapshot carries the resolved section, composition `base`, raw `user`, revision, writability, and host/memory mode; a field is overridden when it is present in `user`, even when its value equals `base`, and `unset` clears that override. Writes stay per-scope: one field path fenced by the namespace revision as `expectedRevision`; a committed write folds its answer back into the mirror with no re-read, a rejected or failed latest write triggers one mirror recovery read, and a superseded one leaves recovery to its successor. Without a `decode` in the spec, a section that is not a plain object, fails its rehydrated schema, or carries a schema envelope this client cannot rehydrate publishes no value at all, so a row renders its own absent state instead of a half-decoded one. The cold-boot read count is pinned by `apps/web/tests/startup-rpc-budget.e2e.ts`; a new direct `settings.describe` caller in client code is a regression against it.
 ## Model Experience
 
 None, as the settings domain base serves browser preference storage and slot declarations; nothing here reaches a model request.

packages/client/ui-settings/README.zh.md

@@ -4,8 +4,7 @@
 
 设置领域的底座，本身不含任何呈现内容。它提供 `ctx.settingsScope`——每个偏好设置行绑定自己那份持久化命名空间分区所用的宿主传输层；`ctx.settingsSchema`——设置插件使用的同步 schema 重建、校验与不可变路径编辑服务；并声明由注册方填充的设置 slot 类型：`settings.trigger`／`settings.header`／`settings.close`（界面框架内容）、`settings.action`（内容标题栏中的有序操作）、`settings.section`（每项功能一页）、`settings.plugins.tab`（“插件”分区内由各功能持有的页面）和 `settings.onboarding`（由各功能持有的有序页面）。它不依赖任何 `ui-*` 呈现包，因此任何持有偏好设置的功能都能够到它；设置**外壳**——`sidebar.settings` 占位方、它的导航与界面框架——位于 ui-settings-general，因为外壳一旦依赖 ui-sidebar，就会经 ui-layout 与 ui-theme 闭合出一条引用图环路。外壳自身的契约类型出于同一原因与外壳放在一起。
 
-该插件不注入任何服务、也不等待任何服务：schema 操作为同步调用，而 `ctx.settingsScope.bind(spec)` 在调用时经调用方的 context 解析线路面。绑定所得 scope 的 disposer 归调用方 fiber 所有，而由调用方注入 `connection` 取得传输层、注入 `remote` 取得失效通知。监听器在首次后台读取启动之前就已存在，因此某一行的激活绝不会阻塞在设置传输层上。已绑定的 scope 会在收到属于自己命名空间的转发 `settings/document-updated` 事件时、以及在 `connection/reset` 时重新读取。写入携带单一字段路径以及最近已知的命名空间 revision 作为 `expectedRevision`；被拒绝或失败的写入会重新读取，除非已有更新的写入取代了它，而陈旧的读取绝不会覆盖更新的发布结果。快照携带解析后的分区、组合 `base`、原始 `user`、revision、可写性以及 host／内存模式。字段只要出现在 `user` 中即视为覆盖，即使其值与 `base` 相等；`unset` 会清除该覆盖。若 spec 未提供 `decode`，则分区不是普通对象、未通过其重建后的 schema 校验、或携带本客户端无法重建的 schema 信封时，一律不发布任何值，于是行渲染自己的缺失状态，而不是一份半解码的值。
-
+该插件注入 `connection` 与 `remote`，并持有浏览器中唯一的 `settings.describe` 读取方：一面持有完整应答的共享镜像，在每次转发的 `settings/document-updated` 事件与 `connection/reset` 时刷新（首次连接也包含在内——这次读取关闭了「提交落在急切读取与 SSE 订阅之间、其失效通知丢失」的窗口）。schema 操作为同步调用，由 `settingsSchema` 服务承载。`ctx.settingsScope.bind(spec)` 在**调用方**的 context 上返回一个由镜像**派生**的按命名空间 scope——scope 的 disposer 归调用方 fiber 所有，绑定不新增任何线路读取，某一行的激活绝不会阻塞在设置传输层上，且任一时刻每个派生面看到的都是同一份文档 revision。跨命名空间的表面（schema 内省、已服务命名空间目录、`hasDocument`）通过 `ctx.settingsScope.describe()` 读同一面镜像，这是一个读取／折叠面（`getSnapshot`／`subscribe`／`ensure`，另有把写应答折入的 `acceptView`）。scope 快照携带解析后的分区、组合 `base`、原始 `user`、revision、可写性以及 host／内存模式；字段只要出现在 `user` 中即视为覆盖，即使其值与 `base` 相等，`unset` 会清除该覆盖。写入仍归各 scope：单一字段路径，以命名空间 revision 作为 `expectedRevision` 围栏；提交成功的写入将应答折回镜像、不再重读，被拒绝或失败的最新写入触发一次镜像恢复读取，被取代的写入则把恢复留给后继者。若 spec 未提供 `decode`，则分区不是普通对象、未通过其重建后的 schema 校验、或携带本客户端无法重建的 schema 信封时，一律不发布任何值，于是行渲染自己的缺失状态，而不是一份半解码的值。冷启动读取次数由 `apps/web/tests/startup-rpc-budget.e2e.ts` 钉住；客户端代码中新增直连 `settings.describe` 调用即是对它的回归。
 ## 模型体验
 
 无。设置领域底座为浏览器提供偏好设置存储与 slot 声明；这里没有任何内容进入模型请求。

packages/client/ui-settings/src/client/index.ts

@@ -1,16 +1,26 @@
 /**
  * Settings domain base plugin, browser half. Provides `ctx.settingsScope`, the
- * settings-namespace Host transport every preference row binds its durable
- * section through, and owns the canonical slot-type contract for the settings
- * surface. It depends on no `ui-*` presentation package, so any feature that
- * owns a preference can reach it: the settings SHELL — the `sidebar.settings`
- * occupant, its navigation, and the chrome — lives in ui-settings-general,
- * because a shell dependency on ui-sidebar would close a reference cycle
- * through ui-layout and ui-theme. Export discipline: packages/client/AGENTS.md.
+ * settings-namespace scope service every preference row binds its durable
+ * section through, and owns the one `settings.describe` reader in the browser:
+ * the describe mirror, whose invalidation subscriptions
+ * (`settings/document-updated`, `connection/reset`) live here so every derived
+ * surface refreshes from a single wire read. It depends on no `ui-*`
+ * presentation package, so any feature that owns a preference can reach it:
+ * the settings SHELL — the `sidebar.settings` occupant, its navigation, and
+ * the chrome — lives in ui-settings-general, because a shell dependency on
+ * ui-sidebar would close a reference cycle through ui-layout and ui-theme.
+ * Export discipline: packages/client/AGENTS.md.
  */
 import type { ClientContext } from '@deepseek-ai/dsh-client-runtime/client'
+import type { ConnectionHandle } from '@deepseek-ai/dsh-api-remotes/client'
+// Type-only pair supplying `$on` and its key face without dragging a build
+// artifact into the Host graph (rationale beside the same pair in
+// settings-scope.ts).
+import type {} from '@deepseek-ai/dsh-api-remotes/types'
+import type {} from '@deepseek-ai/dsh-settings/types'
 import { SettingsSchemaService } from './schema.ts'
 import { SettingsScopeBinder } from './settings-scope.ts'
+import { SettingsDescribeMirror } from './settings-mirror.ts'
 
 export type {
   SettingsGeneralItemOwnerProps, SettingsHeaderOwnerProps, SettingsOnboardingOwnerProps,
@@ -19,15 +29,18 @@ export type {
 export type { SettingsScopeController, SettingsScopeBinder } from './settings-scope.ts'
 export type { SettingsSchemaService } from './schema.ts'
 export type { SchemaNode } from './schema.ts'
+export type { SettingsDescribeFace, SettingsDescribeView, SettingsMirrorSnapshot } from './settings-mirror.ts'
 
 /**
- * Required services: none. The transport is resolved per caller through
- * `this.ctx` at `bind` time, so this plugin waits for nothing.
+ * Required services: the wire handle for the mirror's reads and the forwarded
+ * settings invalidation the mirror refreshes on.
  */
-export const inject = []
+export const inject = ['connection', 'remote']
 
 /**
- * Provide the settings-namespace scope service.
+ * Provide the settings-namespace scope service over one shared describe
+ * mirror, and keep that mirror fresh on the two signals that can move the
+ * settings document: a document commit and a (re)connect.
  *
  * Constructing the service in this plugin's fiber keeps its traced methods
  * bound to each consuming plugin's context.
@@ -35,5 +48,22 @@ export const inject = []
  */
 export function apply(ctx: ClientContext): void {
   const schema = new SettingsSchemaService(ctx)
-  new SettingsScopeBinder(ctx, schema)
+  const connection = ctx.get('connection') as ConnectionHandle
+  const mirror = new SettingsDescribeMirror(
+    connection.api,
+    connection.isLoopback ? 'host' : 'memory',
+  )
+  ctx.effect(() => {
+    const disposers = [
+      (ctx.get('remote') as ClientContext['remote']).$on('settings/document-updated', () => { void mirror.load() }),
+      ctx.on('connection/reset', () => { void mirror.load() }),
+    ]
+    // The first connection also emits connection/reset, so startup normally
+    // costs two reads (budgeted in startup-rpc-budget.e2e.ts). The in-flight
+    // fold does not merge them into one; it guarantees at most one pending
+    // read at a time and that no invalidation arriving mid-read is lost.
+    void mirror.ensure()
+    return () => { for (const dispose of disposers) dispose() }
+  }, 'ui-settings: describe mirror invalidations')
+  new SettingsScopeBinder(ctx, { mirror, schema })
 }

packages/client/ui-settings/src/client/settings-mirror.ts

@@ -0,0 +1,213 @@
+/**
+ * Client mirror of the Host settings document: the one `settings.describe`
+ * reader in the browser. Every settings consumer derives from this store —
+ * per-namespace scopes through `SettingsScopeBinder.bind`, cross-namespace
+ * surfaces through the binder's shared describe face — so startup cost and
+ * freshness are properties of this class, not of how many features own a
+ * preference. The Host stays the fact source: the mirror re-reads on the
+ * invalidations its owning plugin subscribes to and folds write answers in
+ * through {@link SettingsDescribeMirror.acceptView}.
+ */
+
+import type { IApiClient, SettingsNamespaceView } from '@deepseek-ai/dsh-api-remotes/client'
+import { createSnapshotStore, type SnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+
+type SettingsFace = Pick<IApiClient, 'settings'>
+
+/** The full `settings.describe` answer the mirror serves. */
+export interface SettingsDescribeView {
+  /** Every namespace a live Host plugin registered, as the Host reported it. */
+  namespaces: readonly SettingsNamespaceView[]
+  /** Whether the settings provider accepts writes. */
+  writable: boolean
+  /** Whether a native settings document exists for the Host to open. */
+  hasDocument: boolean
+}
+
+/** Mirror state every derived settings surface renders from. */
+export interface SettingsMirrorSnapshot {
+  /**
+   * `unavailable` is the terminal non-loopback state; `ready` persists across
+   * later failed refreshes (the held view keeps serving); `idle` means no
+   * answer is held and no read is running, so `ensure` will start one.
+   */
+  status: 'idle' | 'loading' | 'ready' | 'unavailable'
+  /** The last good answer; undefined until the first success. */
+  view: SettingsDescribeView | undefined
+  /** The latest refresh failure message, cleared by the next success. */
+  error: string | null
+}
+
+/**
+ * The mirror as cross-namespace surfaces consume it: current answer,
+ * subscription, first-use read, and the write-answer fold. `load` stays off
+ * this face — invalidation refreshes belong to the mirror's owning plugin.
+ */
+export interface SettingsDescribeFace {
+  /** @returns the current sync snapshot (stable reference until the next change). */
+  getSnapshot(): SettingsMirrorSnapshot
+  /**
+   * Observe snapshot replacements.
+   * @param listener - invoked after each snapshot change.
+   * @returns the disposer removing this listener.
+   */
+  subscribe(listener: () => void): () => void
+  /**
+   * Resolve once an answer is held (or the mirror is terminally unavailable),
+   * reading only from `idle`.
+   * @returns settlement of the current or newly started read, if any.
+   */
+  ensure(): Promise<void>
+  /**
+   * Fold one write answer's namespace view into the held view without a wire
+   * read, invalidating any older read still in flight.
+   * @param view - the namespace view a settings write answered with.
+   */
+  acceptView(view: SettingsNamespaceView): void
+}
+
+/**
+ * Serializes every Host `settings.describe` read behind one snapshot store.
+ * Concurrent {@link load} calls fold into the in-flight read plus one rerun,
+ * so an invalidation arriving mid-read is never lost and never duplicated.
+ */
+export class SettingsDescribeMirror implements SettingsDescribeFace {
+  private readonly store: SnapshotStore<SettingsMirrorSnapshot>
+  private inFlight: Promise<void> | undefined
+  private rerun = false
+  private generation = 0
+
+  /**
+   * @param api - settings wire face.
+   * @param persistence - remote browsers stay process-local because settings RPCs are loopback-only.
+   */
+  constructor(
+    private readonly api: SettingsFace,
+    private readonly persistence: 'host' | 'memory' = 'host',
+  ) {
+    this.store = createSnapshotStore<SettingsMirrorSnapshot>({
+      status: persistence === 'host' ? 'idle' : 'unavailable',
+      view: undefined,
+      error: null,
+    })
+  }
+
+  /** @returns the current sync snapshot (stable reference until the next change). */
+  getSnapshot(): SettingsMirrorSnapshot {
+    return this.store.getSnapshot()
+  }
+
+  /**
+   * Observe snapshot replacements.
+   * @param listener - invoked after each snapshot change.
+   * @returns the disposer removing this listener.
+   */
+  subscribe(listener: () => void): () => void {
+    return this.store.subscribe(listener)
+  }
+
+  /**
+   * Refresh from the Host. A call during an in-flight read marks one rerun
+   * after it settles instead of racing a second wire read.
+   * @returns settlement after this call's freshness is reflected.
+   */
+  load(): Promise<void> {
+    if (this.persistence === 'memory') return Promise.resolve()
+    if (this.inFlight !== undefined) {
+      this.rerun = true
+      return this.inFlight
+    }
+    // Own the slot before the loading publication can synchronously reenter load().
+    const run = Promise.resolve().then(() => this.run())
+    this.inFlight = run
+    return run
+  }
+
+  /**
+   * Resolve once an answer is held (or the mirror is terminally unavailable),
+   * reading only from `idle`. The cheap idempotent entry for surfaces that
+   * render on first use.
+   * @returns settlement of the current or newly started read, if any.
+   */
+  ensure(): Promise<void> {
+    if (this.persistence === 'memory') return Promise.resolve()
+    if (this.inFlight !== undefined) return this.inFlight
+    if (this.getSnapshot().status === 'idle') return this.load()
+    return Promise.resolve()
+  }
+
+  /**
+   * Fold one write answer's namespace view into the held view without a wire
+   * read, and invalidate any read still in flight. With no held document, the
+   * answer is not published as a partial document; an in-flight read reruns so
+   * it cannot publish a document fetched before the write committed.
+   * @param view - the namespace view a settings write answered with.
+   */
+  acceptView(view: SettingsNamespaceView): void {
+    const before = this.store.getSnapshot()
+    this.generation += 1
+    if (this.inFlight !== undefined) this.rerun = true
+    if (before.view === undefined) return
+    const namespaces = before.view.namespaces.some(row => row.ns === view.ns)
+      ? before.view.namespaces.map(row => row.ns === view.ns ? view : row)
+      : [...before.view.namespaces, view]
+    this.store.set({ ...before, view: { ...before.view, namespaces } })
+  }
+
+  /**
+   * Convenience row lookup on the held view.
+   * @param ns - namespace identity.
+   * @returns the namespace view, or undefined while unanswered or unregistered.
+   */
+  namespace(ns: string): SettingsNamespaceView | undefined {
+    return this.store.getSnapshot().view?.namespaces.find(row => row.ns === ns)
+  }
+
+  private async run(): Promise<void> {
+    // The in-flight slot must clear in the same synchronous segment that
+    // observes `rerun` false (and on abrupt exit): a `.finally()` on the
+    // returned promise runs one microtask later, and a `load()` landing in
+    // that gap would mark a rerun nobody reads, losing the read.
+    try {
+      do {
+        const before = this.store.getSnapshot()
+        if (before.status === 'idle') this.store.set({ ...before, status: 'loading' })
+        // Cleared immediately before the wire read goes out: a load() marked
+        // earlier (including one reentering from the loading publish above)
+        // is covered by this very read, while one landing after needs the
+        // rerun.
+        this.rerun = false
+        const generation = ++this.generation
+        let outcome: { view: SettingsDescribeView } | { failure: string }
+        try {
+          const response = await this.api.settings.describe({})
+          outcome = response.result.ok
+            ? { view: response.result.value }
+            : { failure: response.result.error.message }
+        } catch (error) {
+          outcome = { failure: error instanceof Error ? error.message : String(error) }
+        }
+        // A write answer invalidates a document read before that write committed.
+        if (generation !== this.generation) continue
+        if ('view' in outcome) {
+          this.store.set({ status: 'ready', view: outcome.view, error: null })
+        } else {
+          const held = this.store.getSnapshot()
+          // No answer yet: fall back to idle so `ensure` retries; with one, the
+          // held view keeps serving and only the error field reports the miss.
+          this.store.set({
+            status: held.view === undefined ? 'idle' : 'ready',
+            view: held.view,
+            error: outcome.failure,
+          })
+        }
+      } while (this.shouldRerun())
+    } finally {
+      this.inFlight = undefined
+    }
+  }
+
+  private shouldRerun(): boolean {
+    return this.rerun
+  }
+}

packages/client/ui-settings/src/client/settings-scope.ts

@@ -1,8 +1,11 @@
 /**
  * Host transport for the settings-namespace scope contract. The contract types
  * live in `dsh-client-runtime` (the common dependency of every feature that
- * owns a preference); this file owns the wire behavior and the invalidation
- * subscription, both of which are Settings-surface concerns.
+ * owns a preference); this file owns the per-namespace derivation over the
+ * shared {@link SettingsDescribeMirror} and the serialized write path, both of
+ * which are Settings-surface concerns. Reads never touch the wire here: the
+ * mirror is the one `settings.describe` reader, and every scope is a selector
+ * over its snapshot.
  */
 
 import { Service } from '@deepseek-ai/cordis'
@@ -21,8 +24,8 @@ import {
 // Client half declares `ctx.remote` with no generated import, and the
 // allowlist's `types` subpath is a pure-type source file, so the pair supplies
 // `$on` and its key face without dragging a build artifact in. The runtime
-// `remote` injection belongs to whoever calls `ctx.settingsScope.bind(spec)`: the
-// subscription is registered on the caller's own context.
+// `remote` injection belongs to the providing plugin's apply, which registers
+// the mirror's invalidation subscriptions.
 import type {} from '@deepseek-ai/dsh-api-remotes/client'
 import type {} from '@deepseek-ai/dsh-api-remotes/types'
 // The forwarded event's own declaration: `$on`'s key face is
@@ -31,30 +34,40 @@ import type {} from '@deepseek-ai/dsh-api-remotes/types'
 // cordis `Events` entry (and with it the branded `SettingsNamespace`).
 import type {} from '@deepseek-ai/dsh-settings/types'
 import type { SettingsSchemaService } from './schema.ts'
+import { SettingsDescribeMirror, type SettingsDescribeFace } from './settings-mirror.ts'
+
 type SettingsFace = Pick<IApiClient, 'settings'>
 
 /**
- * Serializes one namespace's Host reads and writes behind a snapshot store.
- * Reads never block plugin activation; writes carry the latest known
- * namespace revision and teardown waits for the operation already crossing
- * the wire.
+ * One namespace's derived view over the shared describe mirror, plus that
+ * namespace's serialized Host writes. Writes carry the latest known namespace
+ * revision, fold their answers back into the mirror, and teardown waits for
+ * the operation already crossing the wire.
  */
 export class SettingsScopeController<T> implements SettingsScope<T> {
   private readonly store: SnapshotStore<SettingsScopeSnapshot<T>>
   private tail: Promise<void> = Promise.resolve()
-  private readGeneration = 0
   private writeGeneration = 0
   private disposed = false
+  private readonly unsubscribe: (() => void) | undefined
+  /**
+   * Revision answered by a superseded write still ahead of the mirror: the
+   * mirror only folds the LATEST settlement in, so a queued successor takes
+   * its fence from here first.
+   */
+  private pendingRevision: number | undefined
 
   /**
-   * @param api - settings wire face.
+   * @param api - settings wire face (writes only; reads ride the mirror).
    * @param spec - namespace identity and optional narrowing decoder.
+   * @param mirror - the shared describe mirror this scope derives from.
    * @param persistence - remote browsers remain process-local because settings RPCs are loopback-only.
    * @param schema - settings-owned schema operations.
    */
   constructor(
     private readonly api: SettingsFace,
     private readonly spec: SettingsScopeSpec<T>,
+    private readonly mirror: SettingsDescribeMirror,
     private readonly persistence: 'host' | 'memory',
     private readonly schema: SettingsSchemaService,
   ) {
@@ -67,6 +80,10 @@ export class SettingsScopeController<T> implements SettingsScope<T> {
       writable: false,
       mode: persistence,
     })
+    if (persistence === 'host') {
+      this.unsubscribe = mirror.subscribe(() => { this.derive() })
+      this.derive()
+    }
   }
 
   /** @returns the current sync snapshot (stable reference until the next change). */
@@ -83,15 +100,6 @@ export class SettingsScopeController<T> implements SettingsScope<T> {
     return this.store.subscribe(listener)
   }
 
-  /**
-   * Queue a Host refresh; a newer read or user write suppresses stale publication.
-   * @returns settlement after the queued read completes or is skipped.
-   */
-  load(): Promise<void> {
-    const generation = ++this.readGeneration
-    return this.enqueue(() => this.read(generation))
-  }
-
   /**
    * Queue one field write; see {@link SettingsScope.set} for the ordering,
    * revision, and recovery contract.
@@ -114,10 +122,9 @@ export class SettingsScopeController<T> implements SettingsScope<T> {
   }
 
   private write(op: SettingsPathOpView): Promise<void> {
-    this.readGeneration += 1
     const generation = ++this.writeGeneration
     return this.enqueue(async () => {
-      const revision = this.getSnapshot().revision
+      const revision = this.pendingRevision ?? this.getSnapshot().revision
       let response: Awaited<ReturnType<SettingsFace['settings']['mutate']>>
       try {
         response = await this.api.settings.mutate({
@@ -126,25 +133,39 @@ export class SettingsScopeController<T> implements SettingsScope<T> {
           ...(revision === undefined ? {} : { expectedRevision: revision }),
         })
       } catch (_settingsWriteFailure) {
-        if (!this.disposed && generation === this.writeGeneration) await this.read(++this.readGeneration)
+        await this.recover(generation)
         return
       }
       if (!response.result.ok) {
-        if (!this.disposed && generation === this.writeGeneration) await this.read(++this.readGeneration)
+        await this.recover(generation)
         return
       }
-      this.accept(response.result.value, generation === this.writeGeneration)
+      if (this.disposed) return
+      if (generation === this.writeGeneration) {
+        this.pendingRevision = undefined
+        this.mirror.acceptView(response.result.value)
+      } else {
+        this.pendingRevision = response.result.value.revision
+      }
     })
   }
 
+  /** Reload Host state for the latest failed write; superseded failures leave recovery to it. */
+  private async recover(generation: number): Promise<void> {
+    if (this.disposed || generation !== this.writeGeneration) return
+    this.pendingRevision = undefined
+    await this.mirror.load()
+  }
+
   /**
-   * Stop queued operations and wait for the current wire call to settle.
+   * Stop queued operations, stop deriving, and wait for the current wire call
+   * to settle.
    * @returns settlement after the controller reaches quiescence.
    */
   async dispose(): Promise<void> {
     this.disposed = true
-    this.readGeneration += 1
     this.writeGeneration += 1
+    this.unsubscribe?.()
     await this.tail
   }
 
@@ -160,36 +181,25 @@ export class SettingsScopeController<T> implements SettingsScope<T> {
     return task
   }
 
-  private async read(generation: number): Promise<void> {
-    let response: Awaited<ReturnType<SettingsFace['settings']['describe']>>
-    try {
-      response = await this.api.settings.describe({})
-    } catch (_settingsReadFailure) {
-      return
-    }
-    if (!response.result.ok || this.disposed) return
-    const { namespaces, writable } = response.result.value
-    const view = namespaces.find(candidate => candidate.ns === this.spec.namespace)
-    const publish = generation === this.readGeneration
+  private derive(): void {
+    if (this.disposed) return
+    const mirrored = this.mirror.getSnapshot()
+    if (mirrored.view === undefined) return
+    const { writable } = mirrored.view
+    const view = mirrored.view.namespaces.find(candidate => candidate.ns === this.spec.namespace)
     if (view === undefined) {
-      if (publish) {
-        this.store.update((draft) => {
-          draft.status = 'unavailable'
-          draft.writable = writable
-        })
-      }
+      this.store.update((draft) => {
+        draft.status = 'unavailable'
+        draft.writable = writable
+      })
       return
     }
-    this.accept(view, publish, writable)
-  }
-
-  private accept(view: SettingsNamespaceView, publish: boolean, writable?: boolean): void {
-    const decoded = publish ? this.decode(view) : undefined
+    const decoded = this.decode(view)
     this.store.update((draft) => {
       draft.revision = view.revision
       draft.base = view.base
       draft.user = view.user
-      if (writable !== undefined) draft.writable = writable
+      draft.writable = writable
       if (decoded === undefined) return
       draft.status = 'ready'
       draft.value = decoded
@@ -227,20 +237,38 @@ declare module '@deepseek-ai/cordis' {
  * (`packages/client/tsdown.client.ts`).
  */
 export class SettingsScopeBinder extends Service {
+  private readonly mirror: SettingsDescribeMirror
+  private readonly schema: SettingsSchemaService
+
   /**
    * @param ctx - the providing plugin's context.
+   * @param config - the shared describe mirror every bound scope derives from,
+   * plus the settings-owned schema operations.
    */
-  constructor(ctx: Context, private readonly schema: SettingsSchemaService) {
+  constructor(ctx: Context, config: { mirror: SettingsDescribeMirror; schema: SettingsSchemaService }) {
     super(ctx, 'settingsScope')
+    this.mirror = config.mirror
+    this.schema = config.schema
+  }
+
+  /**
+   * The shared mirror's read/fold face for cross-namespace surfaces (schema
+   * introspection, the served-namespace directory). Per-namespace consumers
+   * use {@link bind}; both derive from the same snapshot, so they can never
+   * disagree about the document.
+   * @returns the describe face over the shared mirror.
+   */
+  describe(): SettingsDescribeFace {
+    return this.mirror
   }
 
   /**
-   * Bind one namespace scope to settings and connection invalidations on the
-   * CALLER's plugin lifecycle — the service proxy binds `this.ctx` to the
-   * caller at call time, so the scope's disposer belongs to the calling fiber.
-   * Listeners exist before the initial background read starts, so activation
-   * never blocks on the settings transport. The caller injects `connection`
-   * for the transport and `remote` for the forwarded settings invalidation.
+   * Bind one namespace scope on the CALLER's plugin lifecycle — the service
+   * proxy binds `this.ctx` to the caller at call time, so the scope's disposer
+   * belongs to the calling fiber. The scope derives from the shared mirror
+   * (whose invalidation subscriptions live with the providing plugin), so
+   * binding adds no wire read of its own and activation never blocks on the
+   * settings transport.
    * @param spec - domain-owned namespace contract.
    * @returns the bound scope consumed by the domain's services and rows.
    */
@@ -250,21 +278,13 @@ export class SettingsScopeBinder extends Service {
     const controller = new SettingsScopeController<T>(
       connection.api,
       spec,
+      this.mirror,
       connection.isLoopback ? 'host' : 'memory',
       this.schema,
     )
     ctx.effect(() => {
-      const refresh = (namespace?: string): void => {
-        if (namespace !== undefined && namespace !== spec.namespace) return
-        void controller.load()
-      }
-      const disposers = [
-        (ctx.get('remote') as Context['remote']).$on('settings/document-updated', refresh),
-        ctx.on('connection/reset', () => { refresh() }),
-      ]
-      void controller.load()
+      void this.mirror.ensure()
       return async () => {
-        for (const dispose of disposers) dispose()
         await controller.dispose()
       }
     }, `ui-settings: ${spec.namespace} settings scope`)

packages/client/ui-settings/tests/plugin.client.spec.ts

@@ -1,33 +1,60 @@
 /**
  * The settings domain base plugin's own mounting behavior: it stands up
- * `ctx.settingsScope` for every feature that owns a preference row, and the
- * service retires with its fiber.
+ * `ctx.settingsScope` over one shared describe mirror, keeps that mirror
+ * fresh on settings-document and connection-reset invalidations, and retires
+ * both the service and the subscriptions with its fiber.
  */
 import { Context } from '@deepseek-ai/cordis'
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
+import { TestRemote } from '@deepseek-ai/dsh-client-test-runtime'
 import { apply, inject } from '../src/client/index.ts'
 import { SettingsSchemaService } from '../src/client/schema.ts'
 import { SettingsScopeBinder } from '../src/client/settings-scope.ts'
 
-/** Boot the browser half over a bare root context; it injects nothing. */
+/** Boot the browser half over a fake loopback connection and test remote. */
 function bench() {
+  const describeCall = vi.fn().mockResolvedValue({
+    rpcId: 'plugin-bench' as never,
+    result: { ok: true, value: { writable: true, hasDocument: true, namespaces: [] } },
+  })
   const ctx = new Context()
-  return { ctx, fiber: ctx.plugin({ inject: [...inject], apply }) }
+  ctx.provide('connection', {
+    api: { settings: { describe: describeCall } },
+    isLoopback: true,
+  } as never)
+  new TestRemote(ctx)
+  return { ctx, describeCall, fiber: ctx.plugin({ inject: [...inject], apply }) }
 }
 
 describe('settings domain base plugin', () => {
-  it('mounts the scope service under settingsScope', async () => {
-    const { ctx, fiber } = bench()
+  it('mounts the scope service under settingsScope and reads once eagerly', async () => {
+    const { ctx, describeCall, fiber } = bench()
     await fiber.await()
     expect(ctx.get('settingsScope')).toBeInstanceOf(SettingsScopeBinder)
     expect(ctx.get('settingsSchema')).toBeInstanceOf(SettingsSchemaService)
+    await vi.waitFor(() => { expect(describeCall).toHaveBeenCalledTimes(1) })
+  })
+
+  it('refreshes the mirror on document commits and connection resets, once each', async () => {
+    const { ctx, describeCall, fiber } = bench()
+    await fiber.await()
+    await vi.waitFor(() => { expect(describeCall).toHaveBeenCalledTimes(1) })
+    ctx.remote.$dispatch('settings/document-updated', ['ui-test', 0])
+    await vi.waitFor(() => { expect(describeCall).toHaveBeenCalledTimes(2) })
+    ctx.emit('connection/reset')
+    await vi.waitFor(() => { expect(describeCall).toHaveBeenCalledTimes(3) })
   })
 
-  it('fiber disposal retires the service', async () => {
-    const { ctx, fiber } = bench()
+  it('fiber disposal retires the service and its invalidation subscriptions', async () => {
+    const { ctx, describeCall, fiber } = bench()
     await fiber.await()
+    await vi.waitFor(() => { expect(describeCall).toHaveBeenCalledTimes(1) })
     await fiber.dispose()
     expect(ctx.get('settingsScope')).toBeUndefined()
     expect(ctx.get('settingsSchema')).toBeUndefined()
+    ctx.remote.$dispatch('settings/document-updated', ['ui-test', 0])
+    ctx.emit('connection/reset')
+    await Promise.resolve()
+    expect(describeCall).toHaveBeenCalledTimes(1)
   })
 })

packages/client/ui-settings/tests/settings-mirror.client.spec.ts

@@ -0,0 +1,216 @@
+import { describe, expect, it, vi } from 'vitest'
+import type { RpcResponse, SettingsNamespaceView } from '@deepseek-ai/dsh-api-remotes/client'
+import { SettingsDescribeMirror, type SettingsDescribeView } from '../src/client/settings-mirror.ts'
+
+let rpc = 0
+
+function ok<T>(value: T): RpcResponse<T> {
+  return { rpcId: `mirror-${rpc++}` as never, result: { ok: true, value } }
+}
+
+function rejected<T>(message: string): RpcResponse<T> {
+  return {
+    rpcId: `mirror-${rpc++}` as never,
+    result: {
+      ok: false,
+      error: { code: 'settings-rejected', message, details: { ns: 'theme' } },
+    },
+  }
+}
+
+function view(ns: string, revision = 0): SettingsNamespaceView {
+  return { ns, schema: {}, value: { field: ns }, applies: 'live', secrets: [], revision }
+}
+
+function described(namespaces: SettingsNamespaceView[]): RpcResponse<SettingsDescribeView> {
+  return ok({ writable: true, hasDocument: true, namespaces })
+}
+
+function deferred<T>() {
+  let resolve!: (value: T) => void
+  const promise = new Promise<T>((res) => { resolve = res })
+  return { promise, resolve }
+}
+
+describe('SettingsDescribeMirror', () => {
+  it('folds loads before the wire read into it, and mid-flight loads into one rerun', async () => {
+    const gate = deferred<RpcResponse<SettingsDescribeView>>()
+    const describeCall = vi.fn()
+      .mockReturnValueOnce(gate.promise)
+      .mockResolvedValue(described([view('theme', 1)]))
+    const mirror = new SettingsDescribeMirror({ settings: { describe: describeCall } } as never)
+    const first = mirror.load()
+    // Issued before the wire read goes out: covered by that read, no rerun.
+    const early = mirror.load()
+    await Promise.resolve()
+    expect(describeCall).toHaveBeenCalledTimes(1)
+    // Issued while the read is on the wire: exactly one rerun, however many.
+    const mid = mirror.load()
+    const midToo = mirror.load()
+    gate.resolve(described([view('theme', 0)]))
+    await Promise.all([first, early, mid, midToo])
+    expect(describeCall).toHaveBeenCalledTimes(2)
+    expect(mirror.getSnapshot().status).toBe('ready')
+    expect(mirror.namespace('theme')?.revision).toBe(1)
+  })
+
+  it('keeps the last good view when a later refresh fails, recording the failure', async () => {
+    const describeCall = vi.fn()
+      .mockResolvedValueOnce(described([view('theme', 2)]))
+      .mockRejectedValueOnce(new Error('host gone'))
+      .mockResolvedValueOnce(rejected('busy'))
+    const mirror = new SettingsDescribeMirror({ settings: { describe: describeCall } } as never)
+    await mirror.load()
+    expect(mirror.getSnapshot()).toMatchObject({ status: 'ready', error: null })
+    await mirror.load()
+    expect(mirror.getSnapshot()).toMatchObject({ status: 'ready', error: 'host gone' })
+    expect(mirror.namespace('theme')?.revision).toBe(2)
+    await mirror.load()
+    expect(mirror.getSnapshot()).toMatchObject({ status: 'ready', error: 'busy' })
+    expect(mirror.getSnapshot().view?.namespaces).toHaveLength(1)
+  })
+
+  it('returns to idle after a first read that never succeeded, so ensure retries', async () => {
+    const describeCall = vi.fn()
+      .mockRejectedValueOnce(new Error('offline'))
+      .mockResolvedValueOnce(described([view('theme', 1)]))
+    const mirror = new SettingsDescribeMirror({ settings: { describe: describeCall } } as never)
+    await mirror.ensure()
+    expect(mirror.getSnapshot()).toMatchObject({ status: 'idle', view: undefined, error: 'offline' })
+    await mirror.ensure()
+    expect(mirror.getSnapshot()).toMatchObject({ status: 'ready', error: null })
+    expect(describeCall).toHaveBeenCalledTimes(2)
+  })
+
+  it('treats ensure as a no-op once ready', async () => {
+    const describeCall = vi.fn().mockResolvedValue(described([view('theme', 1)]))
+    const mirror = new SettingsDescribeMirror({ settings: { describe: describeCall } } as never)
+    await mirror.ensure()
+    await mirror.ensure()
+    await mirror.ensure()
+    expect(describeCall).toHaveBeenCalledTimes(1)
+  })
+
+  it('memory persistence is terminally unavailable and never touches the wire', async () => {
+    const describeCall = vi.fn()
+    const mirror = new SettingsDescribeMirror({ settings: { describe: describeCall } } as never, 'memory')
+    await mirror.ensure()
+    await mirror.load()
+    expect(mirror.getSnapshot()).toEqual({ status: 'unavailable', view: undefined, error: null })
+    expect(describeCall).not.toHaveBeenCalled()
+  })
+
+  it('acceptView folds one write answer into the held view without a wire read', async () => {
+    const describeCall = vi.fn()
+      .mockResolvedValueOnce(described([view('theme', 1), view('locale', 4)]))
+    const mirror = new SettingsDescribeMirror({ settings: { describe: describeCall } } as never)
+    await mirror.load()
+    const seen: number[] = []
+    mirror.subscribe(() => { seen.push(mirror.namespace('theme')?.revision ?? -1) })
+    mirror.acceptView(view('theme', 9))
+    expect(mirror.namespace('theme')?.revision).toBe(9)
+    expect(mirror.namespace('locale')?.revision).toBe(4)
+    expect(seen).toEqual([9])
+    expect(describeCall).toHaveBeenCalledTimes(1)
+  })
+
+  it('acceptView before any answer is a no-op instead of inventing a document', () => {
+    const describeCall = vi.fn()
+    const mirror = new SettingsDescribeMirror({ settings: { describe: describeCall } } as never)
+    mirror.acceptView(view('theme', 1))
+    expect(mirror.getSnapshot()).toEqual({ status: 'idle', view: undefined, error: null })
+  })
+
+  it('acceptView appends a namespace the held view has not seen yet', async () => {
+    const describeCall = vi.fn().mockResolvedValueOnce(described([view('theme', 1)]))
+    const mirror = new SettingsDescribeMirror({ settings: { describe: describeCall } } as never)
+    await mirror.load()
+    mirror.acceptView(view('fresh-ns', 0))
+    expect(mirror.namespace('fresh-ns')).toBeDefined()
+    expect(mirror.getSnapshot().view?.namespaces).toHaveLength(2)
+  })
+
+  it('never loses a load landing between a run settling and its slot clearing', async () => {
+    // Regression: with the in-flight slot cleared by a promise .finally(),
+    // a load() in the one-microtask gap after the rerun check marked a rerun
+    // nobody read, and that refresh never reached the wire.
+    const describeCall = vi.fn().mockResolvedValue(described([view('theme', 1)]))
+    const mirror = new SettingsDescribeMirror({ settings: { describe: describeCall } } as never)
+    void mirror.load()
+    await vi.waitFor(() => { expect(describeCall).toHaveBeenCalledTimes(1) })
+    void mirror.load()
+    await vi.waitFor(() => { expect(describeCall).toHaveBeenCalledTimes(2) })
+    void mirror.load()
+    await vi.waitFor(() => { expect(describeCall).toHaveBeenCalledTimes(3) })
+  })
+
+  it('starts no second run for a load issued inside the loading publish', async () => {
+    const gate = deferred<RpcResponse<SettingsDescribeView>>()
+    const describeCall = vi.fn().mockReturnValue(gate.promise)
+    const mirror = new SettingsDescribeMirror({ settings: { describe: describeCall } } as never)
+    let reentered = false
+    const unsubscribe = mirror.subscribe(() => {
+      if (reentered) return
+      reentered = true
+      void mirror.load()
+    })
+    const loading = mirror.load()
+    await Promise.resolve()
+    expect(describeCall).toHaveBeenCalledTimes(1)
+    gate.resolve(described([view('theme', 1)]))
+    await loading
+    unsubscribe()
+    // The reentrant load folded into the first run rather than racing it.
+    expect(describeCall).toHaveBeenCalledTimes(1)
+    expect(mirror.getSnapshot().status).toBe('ready')
+  })
+
+  it('lets the first read cover a write folded inside the loading publish', async () => {
+    const describeCall = vi.fn().mockResolvedValue(described([view('theme', 2)]))
+    const mirror = new SettingsDescribeMirror({ settings: { describe: describeCall } } as never)
+    const unsubscribe = mirror.subscribe(() => {
+      unsubscribe()
+      mirror.acceptView(view('theme', 2))
+    })
+
+    await mirror.load()
+
+    expect(describeCall).toHaveBeenCalledTimes(1)
+    expect(mirror.getSnapshot().status).toBe('ready')
+    expect(mirror.namespace('theme')?.revision).toBe(2)
+  })
+
+  it('re-reads after a folded write invalidates an in-flight document', async () => {
+    const slow = deferred<RpcResponse<SettingsDescribeView>>()
+    const describeCall = vi.fn()
+      .mockResolvedValueOnce(described([view('theme', 4), view('locale', 1)]))
+      .mockReturnValueOnce(slow.promise)
+      .mockResolvedValueOnce(described([view('theme', 5), view('locale', 2)]))
+    const mirror = new SettingsDescribeMirror({ settings: { describe: describeCall } } as never)
+    await mirror.load()
+    expect(describeCall).toHaveBeenCalledTimes(1)
+    const stale = mirror.load()
+    await Promise.resolve()
+    mirror.acceptView(view('theme', 5))
+    slow.resolve(described([view('theme', 4), view('locale', 2)]))
+    await stale
+    expect(describeCall).toHaveBeenCalledTimes(3)
+    expect(mirror.namespace('theme')?.revision).toBe(5)
+    expect(mirror.namespace('locale')?.revision).toBe(2)
+  })
+
+  it('re-reads after a pre-answer write invalidates the in-flight document', async () => {
+    const slow = deferred<RpcResponse<SettingsDescribeView>>()
+    const describeCall = vi.fn()
+      .mockReturnValueOnce(slow.promise)
+      .mockResolvedValueOnce(described([view('theme', 2)]))
+    const mirror = new SettingsDescribeMirror({ settings: { describe: describeCall } } as never)
+    const loading = mirror.load()
+    await Promise.resolve()
+    mirror.acceptView(view('theme', 2))
+    slow.resolve(described([view('theme', 1)]))
+    await loading
+    expect(describeCall).toHaveBeenCalledTimes(2)
+    expect(mirror.namespace('theme')?.revision).toBe(2)
+  })
+})

packages/client/ui-settings/tests/settings-scope.client.spec.ts

@@ -1,13 +1,14 @@
 import { Context } from '@deepseek-ai/cordis'
 import z from '@deepseek-ai/schemastery'
 import { describe, expect, it, vi } from 'vitest'
-import type { IApiClient, RpcResponse, SettingsNamespaceView } from '@deepseek-ai/dsh-api-remotes/client'
+import type { RpcResponse, SettingsNamespaceView } from '@deepseek-ai/dsh-api-remotes/client'
 import { TestRemote } from '@deepseek-ai/dsh-client-test-runtime'
-import type { SettingsScope, SettingsScopeSpec } from '@deepseek-ai/dsh-client-runtime/client'
+import type { SettingsScope } from '@deepseek-ai/dsh-client-runtime/client'
 import { SettingsSchemaService } from '../src/client/schema.ts'
-import {
-  SettingsScopeBinder, SettingsScopeController as ProductionSettingsScopeController,
-} from '../src/client/settings-scope.ts'
+import { SettingsScopeController, SettingsScopeBinder } from '../src/client/settings-scope.ts'
+import { SettingsDescribeMirror } from '../src/client/settings-mirror.ts'
+
+const settingsSchema = new SettingsSchemaService(new Context())
 
 interface UiTestSettings {
   preference: 'light' | 'dark' | 'system'
@@ -17,17 +18,6 @@ const ENVELOPE = z.object({
   preference: z.union(['light', 'dark', 'system']).default('system'),
 }).toJSON()
 
-const settingsSchema = new SettingsSchemaService(new Context())
-const SettingsScopeController = class<T> extends ProductionSettingsScopeController<T> {
-  constructor(
-    api: Pick<IApiClient, 'settings'>,
-    spec: SettingsScopeSpec<T>,
-    persistence: 'host' | 'memory' = 'host',
-  ) {
-    super(api, spec, persistence, settingsSchema)
-  }
-}
-
 let rpc = 0
 
 function ok<T>(value: T): RpcResponse<T> {
@@ -66,6 +56,17 @@ function deferred<T>() {
   return { promise, resolve, reject }
 }
 
+/** A host-mode mirror plus a controller derived from it, over one fake wire. */
+function derivedScope(
+  api: { describe?: ReturnType<typeof vi.fn>; mutate?: ReturnType<typeof vi.fn> },
+  spec: { namespace: string; decode?: (section: unknown) => UiTestSettings | undefined } = { namespace: 'ui-test' },
+) {
+  const wire = { settings: api } as never
+  const mirror = new SettingsDescribeMirror(wire)
+  const scope = new SettingsScopeController<UiTestSettings>(wire, spec, mirror, 'host', settingsSchema)
+  return { mirror, scope }
+}
+
 /** Record each distinct published section, starting from the current one. */
 function trackValues(scope: SettingsScope<UiTestSettings>): Array<UiTestSettings | undefined> {
   const seen: Array<UiTestSettings | undefined> = [scope.getSnapshot().value]
@@ -77,16 +78,13 @@ function trackValues(scope: SettingsScope<UiTestSettings>): Array<UiTestSettings
 }
 
 describe('SettingsScopeController', () => {
-  it('starts loading and publishes a schema-valid section with revision and writability', async () => {
+  it('starts loading and derives a schema-valid section with revision and writability', async () => {
     const describeCall = vi.fn().mockResolvedValueOnce(described({ preference: 'dark' }, 3))
-    const scope = new SettingsScopeController<UiTestSettings>(
-      { settings: { describe: describeCall } } as never,
-      { namespace: 'ui-test' },
-    )
+    const { mirror, scope } = derivedScope({ describe: describeCall })
     expect(scope.getSnapshot()).toEqual({
       status: 'loading', value: undefined, revision: undefined, writable: false, mode: 'host',
     })
-    await scope.load()
+    await mirror.load()
     expect(scope.getSnapshot()).toEqual({
       status: 'ready', value: { preference: 'dark' }, revision: 3, writable: true, mode: 'host',
     })
@@ -101,12 +99,9 @@ describe('SettingsScopeController', () => {
       .mockResolvedValueOnce(described(['queue'], 7))
       .mockResolvedValueOnce(rejected())
       .mockRejectedValueOnce(new Error('offline'))
-    const scope = new SettingsScopeController<UiTestSettings>(
-      { settings: { describe: describeCall } } as never,
-      { namespace: 'ui-test' },
-    )
+    const { mirror, scope } = derivedScope({ describe: describeCall })
     const good = trackValues(scope)
-    for (let i = 0; i < 7; i++) await scope.load()
+    for (let i = 0; i < 7; i++) await mirror.load()
     expect(scope.getSnapshot()).toMatchObject({
       status: 'ready', value: { preference: 'dark' }, revision: 7,
     })
@@ -117,45 +112,22 @@ describe('SettingsScopeController', () => {
     const broken = { ...view({ preference: 'dark' }, 2), schema: null }
     const describeCall = vi.fn()
       .mockResolvedValueOnce(ok({ writable: true, hasDocument: true, namespaces: [broken] }))
-    const scope = new SettingsScopeController<UiTestSettings>(
-      { settings: { describe: describeCall } } as never,
-      { namespace: 'ui-test' },
-    )
-    await scope.load()
+    const { mirror, scope } = derivedScope({ describe: describeCall })
+    await mirror.load()
     expect(scope.getSnapshot()).toMatchObject({ status: 'loading', value: undefined, revision: 2 })
   })
 
-  it('suppresses a superseded read of an unexposed namespace', async () => {
-    const describeCall = vi.fn()
-      .mockResolvedValueOnce(ok({ writable: true, hasDocument: true, namespaces: [] }))
-      .mockResolvedValueOnce(described({ preference: 'dark' }, 1))
-    const scope = new SettingsScopeController<UiTestSettings>(
-      { settings: { describe: describeCall } } as never,
-      { namespace: 'ui-test' },
-    )
-    const statuses: string[] = []
-    scope.subscribe(() => { statuses.push(scope.getSnapshot().status) })
-    const stale = scope.load()
-    const fresh = scope.load()
-    await Promise.all([stale, fresh])
-    expect(statuses).not.toContain('unavailable')
-    expect(scope.getSnapshot()).toMatchObject({ status: 'ready', value: { preference: 'dark' } })
-  })
-
   it('reports an unexposed namespace as unavailable and recovers when it reappears', async () => {
     const describeCall = vi.fn()
       .mockResolvedValueOnce(described({ preference: 'light' }, 1))
       .mockResolvedValueOnce(ok({ writable: true, hasDocument: true, namespaces: [] }))
       .mockResolvedValueOnce(described({ preference: 'system' }, 2))
-    const scope = new SettingsScopeController<UiTestSettings>(
-      { settings: { describe: describeCall } } as never,
-      { namespace: 'ui-test' },
-    )
-    await scope.load()
+    const { mirror, scope } = derivedScope({ describe: describeCall })
+    await mirror.load()
     expect(scope.getSnapshot().status).toBe('ready')
-    await scope.load()
+    await mirror.load()
     expect(scope.getSnapshot()).toMatchObject({ status: 'unavailable', value: { preference: 'light' } })
-    await scope.load()
+    await mirror.load()
     expect(scope.getSnapshot()).toMatchObject({ status: 'ready', value: { preference: 'system' }, revision: 2 })
   })
 
@@ -163,18 +135,15 @@ describe('SettingsScopeController', () => {
     const describeCall = vi.fn()
       .mockResolvedValueOnce(described({ preference: 'light' }, 1))
       .mockResolvedValueOnce(described({ preference: 'dark' }, 2))
-    const scope = new SettingsScopeController<UiTestSettings>(
-      { settings: { describe: describeCall } } as never,
-      {
-        namespace: 'ui-test',
-        decode: section => (section as UiTestSettings).preference === 'dark'
-          ? section as UiTestSettings
-          : undefined,
-      },
-    )
-    await scope.load()
+    const { mirror, scope } = derivedScope({ describe: describeCall }, {
+      namespace: 'ui-test',
+      decode: section => (section as UiTestSettings).preference === 'dark'
+        ? section as UiTestSettings
+        : undefined,
+    })
+    await mirror.load()
     expect(scope.getSnapshot()).toMatchObject({ status: 'loading', value: undefined, revision: 1 })
-    await scope.load()
+    await mirror.load()
     expect(scope.getSnapshot()).toMatchObject({ status: 'ready', value: { preference: 'dark' }, revision: 2 })
   })
 
@@ -184,12 +153,9 @@ describe('SettingsScopeController', () => {
     const mutate = vi.fn()
       .mockReturnValueOnce(first.promise)
       .mockResolvedValueOnce(ok(view({ preference: 'light' }, 6)))
-    const scope = new SettingsScopeController<UiTestSettings>(
-      { settings: { describe: describeCall, mutate } } as never,
-      { namespace: 'ui-test' },
-    )
+    const { mirror, scope } = derivedScope({ describe: describeCall, mutate })
     const published = trackValues(scope)
-    await scope.load()
+    await mirror.load()
     const dark = scope.set('preference', 'dark')
     const light = scope.set('preference', 'light')
     await vi.waitFor(() => { expect(mutate).toHaveBeenCalledOnce() })
@@ -209,6 +175,41 @@ describe('SettingsScopeController', () => {
     })
   })
 
+  it('folds the latest write answer into the mirror so a sibling scope sees it', async () => {
+    const describeCall = vi.fn().mockResolvedValueOnce(described({ preference: 'system' }, 4))
+    const mutate = vi.fn().mockResolvedValueOnce(ok(view({ preference: 'dark' }, 5)))
+    const wire = { settings: { describe: describeCall, mutate } } as never
+    const mirror = new SettingsDescribeMirror(wire)
+    const writer = new SettingsScopeController<UiTestSettings>(wire, { namespace: 'ui-test' }, mirror, 'host', settingsSchema)
+    const sibling = new SettingsScopeController<UiTestSettings>(wire, { namespace: 'ui-test' }, mirror, 'host', settingsSchema)
+    await mirror.load()
+    await writer.set('preference', 'dark')
+    expect(describeCall).toHaveBeenCalledTimes(1)
+    expect(sibling.getSnapshot()).toMatchObject({ value: { preference: 'dark' }, revision: 5 })
+  })
+
+  it('re-reads after a revisionless first write lands during the initial read', async () => {
+    const initial = deferred<ReturnType<typeof described>>()
+    const describeCall = vi.fn()
+      .mockReturnValueOnce(initial.promise)
+      .mockResolvedValueOnce(described({ preference: 'dark' }, 2))
+    const mutate = vi.fn().mockResolvedValueOnce(ok(view({ preference: 'dark' }, 2)))
+    const { mirror, scope } = derivedScope({ describe: describeCall, mutate })
+    const loading = mirror.load()
+    await Promise.resolve()
+
+    await scope.set('preference', 'dark')
+    initial.resolve(described({ preference: 'system' }, 1))
+    await loading
+
+    expect(mutate).toHaveBeenCalledWith({
+      ns: 'ui-test',
+      ops: [{ op: 'set', path: ['preference'], value: 'dark' }],
+    })
+    expect(describeCall).toHaveBeenCalledTimes(2)
+    expect(scope.getSnapshot()).toMatchObject({ value: { preference: 'dark' }, revision: 2 })
+  })
+
   it('recovers the latest rejected or thrown write from Host state', async () => {
     const describeCall = vi.fn()
       .mockResolvedValueOnce(described({ preference: 'system' }, 2))
@@ -216,63 +217,74 @@ describe('SettingsScopeController', () => {
     const mutate = vi.fn()
       .mockResolvedValueOnce(rejected())
       .mockRejectedValueOnce(new Error('offline'))
-    const scope = new SettingsScopeController<UiTestSettings>(
-      { settings: { describe: describeCall, mutate } } as never,
-      { namespace: 'ui-test' },
-    )
+    const { mirror, scope } = derivedScope({ describe: describeCall, mutate })
     const published = trackValues(scope)
+    await mirror.load()
     await scope.set('preference', 'dark')
     await scope.set('preference', 'system')
     expect(published.map(section => section?.preference)).toEqual([undefined, 'system', 'light'])
   })
 
   it('does not recover superseded rejected or thrown writes', async () => {
-    const describeCall = vi.fn()
+    const describeCall = vi.fn().mockResolvedValueOnce(described({ preference: 'system' }, 2))
     const mutate = vi.fn()
       .mockResolvedValueOnce(rejected())
       .mockRejectedValueOnce(new Error('offline'))
       .mockResolvedValueOnce(ok(view({ preference: 'light' }, 3)))
-    const scope = new SettingsScopeController<UiTestSettings>(
-      { settings: { describe: describeCall, mutate } } as never,
-      { namespace: 'ui-test' },
-    )
+    const { mirror, scope } = derivedScope({ describe: describeCall, mutate })
     const published = trackValues(scope)
+    await mirror.load()
     await Promise.all([
       scope.set('preference', 'dark'),
       scope.set('preference', 'system'),
       scope.set('preference', 'light'),
     ])
-    expect(describeCall).not.toHaveBeenCalled()
-    expect(published.map(section => section?.preference)).toEqual([undefined, 'light'])
+    expect(describeCall).toHaveBeenCalledTimes(1)
+    expect(published.map(section => section?.preference)).toEqual([undefined, 'system', 'light'])
   })
 
   it('keeps the write queue usable when a subscriber throws', async () => {
     const describeCall = vi.fn()
       .mockResolvedValueOnce(described({ preference: 'dark' }, 1))
       .mockResolvedValueOnce(described({ preference: 'light' }, 2))
-    const scope = new SettingsScopeController<UiTestSettings>(
-      { settings: { describe: describeCall } } as never,
-      { namespace: 'ui-test' },
-    )
+    const { mirror, scope } = derivedScope({ describe: describeCall })
     let thrown = false
     scope.subscribe(() => {
       if (thrown) return
       thrown = true
       throw new Error('subscriber failed')
     })
-    await expect(scope.load()).rejects.toThrow('subscriber failed')
-    await expect(scope.load()).resolves.toBeUndefined()
+    await expect(mirror.load()).rejects.toThrow('subscriber failed')
+    await expect(mirror.load()).resolves.toBeUndefined()
     expect(scope.getSnapshot()).toMatchObject({ value: { preference: 'light' }, revision: 2 })
   })
 
+  it('keeps the write queue usable when a write publication listener throws', async () => {
+    const describeCall = vi.fn().mockResolvedValueOnce(described({ preference: 'system' }, 1))
+    const mutate = vi.fn()
+      .mockResolvedValueOnce(ok(view({ preference: 'dark' }, 2)))
+      .mockResolvedValueOnce(ok(view({ preference: 'light' }, 3)))
+    const { mirror, scope } = derivedScope({ describe: describeCall, mutate })
+    await mirror.load()
+    let shouldThrow = true
+    mirror.subscribe(() => {
+      if (!shouldThrow) return
+      shouldThrow = false
+      throw new Error('write subscriber failed')
+    })
+
+    await expect(scope.set('preference', 'dark')).rejects.toThrow('write subscriber failed')
+    await expect(scope.set('preference', 'light')).resolves.toBeUndefined()
+
+    expect(mutate).toHaveBeenCalledTimes(2)
+    expect(scope.getSnapshot()).toMatchObject({ value: { preference: 'light' }, revision: 3 })
+  })
+
   it('cancels queued and post-dispose writes while draining the in-flight mutation', async () => {
     const first = deferred<RpcResponse<SettingsNamespaceView>>()
     const mutate = vi.fn().mockReturnValue(first.promise)
     const describeCall = vi.fn()
-    const scope = new SettingsScopeController<UiTestSettings>(
-      { settings: { describe: describeCall, mutate } } as never,
-      { namespace: 'ui-test' },
-    )
+    const { scope } = derivedScope({ describe: describeCall, mutate })
     const published = trackValues(scope)
     const dark = scope.set('preference', 'dark')
     await vi.waitFor(() => { expect(mutate).toHaveBeenCalledOnce() })
@@ -284,24 +296,66 @@ describe('SettingsScopeController', () => {
     first.resolve(ok(view({ preference: 'dark' }, 1)))
     await Promise.all([dark, light, stop])
     await scope.set('preference', 'system')
-    await scope.load()
     expect(mutate).toHaveBeenCalledOnce()
     expect(describeCall).not.toHaveBeenCalled()
     expect(published).toEqual([undefined])
   })
 
+  it('stops deriving from the mirror after dispose', async () => {
+    const describeCall = vi.fn()
+      .mockResolvedValueOnce(described({ preference: 'dark' }, 1))
+      .mockResolvedValueOnce(described({ preference: 'light' }, 2))
+    const { mirror, scope } = derivedScope({ describe: describeCall })
+    await mirror.load()
+    expect(scope.getSnapshot()).toMatchObject({ value: { preference: 'dark' } })
+    await scope.dispose()
+    await mirror.load()
+    expect(scope.getSnapshot()).toMatchObject({ value: { preference: 'dark' }, revision: 1 })
+  })
+
+  it('ignores a mirror notification already queued when disposal starts', async () => {
+    let notify = (): void => {}
+    let snapshot = {
+      status: 'ready' as const,
+      view: {
+        writable: true, hasDocument: true,
+        namespaces: [view({ preference: 'dark' }, 1)],
+      },
+      error: null,
+    }
+    const mirror = {
+      getSnapshot: () => snapshot,
+      subscribe: (listener: () => void) => {
+        notify = listener
+        return () => {}
+      },
+    } as never
+    const wire = { settings: {} } as never
+    const scope = new SettingsScopeController<UiTestSettings>(
+      wire, { namespace: 'ui-test' }, mirror, 'host', settingsSchema)
+    expect(scope.getSnapshot()).toMatchObject({ value: { preference: 'dark' }, revision: 1 })
+
+    await scope.dispose()
+    snapshot = {
+      ...snapshot,
+      view: { ...snapshot.view, namespaces: [view({ preference: 'light' }, 2)] },
+    }
+    notify()
+
+    expect(scope.getSnapshot()).toMatchObject({ value: { preference: 'dark' }, revision: 1 })
+  })
+
   it('keeps a remote browser in memory mode without Host calls', async () => {
     const describeCall = vi.fn()
     const mutate = vi.fn()
+    const wire = { settings: { describe: describeCall, mutate } } as never
+    const mirror = new SettingsDescribeMirror(wire, 'memory')
     const scope = new SettingsScopeController<UiTestSettings>(
-      { settings: { describe: describeCall, mutate } } as never,
-      { namespace: 'ui-test' },
-      'memory',
-    )
+      wire, { namespace: 'ui-test' }, mirror, 'memory', settingsSchema)
     expect(scope.getSnapshot()).toEqual({
       status: 'unavailable', value: undefined, revision: undefined, writable: false, mode: 'memory',
     })
-    await scope.load()
+    await mirror.load()
     await scope.set('preference', 'dark')
     await scope.dispose()
     expect(describeCall).not.toHaveBeenCalled()
@@ -316,12 +370,9 @@ describe('SettingsScopeController', () => {
     }
     const describeCall = vi.fn()
       .mockResolvedValueOnce(ok({ writable: true, hasDocument: true, namespaces: [layered] }))
-    const scope = new SettingsScopeController<UiTestSettings>(
-      { settings: { describe: describeCall } } as never,
-      { namespace: 'ui-test' },
-    )
+    const { mirror, scope } = derivedScope({ describe: describeCall })
 
-    await scope.load()
+    await mirror.load()
 
     expect(scope.getSnapshot()).toMatchObject({
       value: { preference: 'dark' },
@@ -334,12 +385,9 @@ describe('SettingsScopeController', () => {
     const inherited: SettingsNamespaceView = { ...view({ preference: 'system' }, 1), base: { preference: 'system' } }
     const describeCall = vi.fn()
       .mockResolvedValueOnce(ok({ writable: true, hasDocument: true, namespaces: [inherited] }))
-    const scope = new SettingsScopeController<UiTestSettings>(
-      { settings: { describe: describeCall } } as never,
-      { namespace: 'ui-test' },
-    )
+    const { mirror, scope } = derivedScope({ describe: describeCall })
 
-    await scope.load()
+    await mirror.load()
 
     expect(scope.getSnapshot().user).toBeUndefined()
   })
@@ -347,11 +395,8 @@ describe('SettingsScopeController', () => {
   it('clears one field through an unset op fenced by the held revision', async () => {
     const mutate = vi.fn().mockResolvedValueOnce(ok(view({ preference: 'system' }, 4)))
     const describeCall = vi.fn().mockResolvedValueOnce(described({ preference: 'dark' }, 3))
-    const scope = new SettingsScopeController<UiTestSettings>(
-      { settings: { describe: describeCall, mutate } } as never,
-      { namespace: 'ui-test' },
-    )
-    await scope.load()
+    const { mirror, scope } = derivedScope({ describe: describeCall, mutate })
+    await mirror.load()
 
     await scope.unset('preference')
 
@@ -368,64 +413,54 @@ describe('SettingsScopeController', () => {
     const describeCall = vi.fn()
       .mockResolvedValueOnce(described({ preference: 'dark' }, 3))
       .mockResolvedValueOnce(described({ preference: 'light' }, 5))
-    const scope = new SettingsScopeController<UiTestSettings>(
-      { settings: { describe: describeCall, mutate } } as never,
-      { namespace: 'ui-test' },
-    )
-    await scope.load()
+    const { mirror, scope } = derivedScope({ describe: describeCall, mutate })
+    await mirror.load()
 
     await scope.unset('preference')
 
     expect(scope.getSnapshot()).toMatchObject({ value: { preference: 'light' }, revision: 5 })
   })
 })
+
 describe('SettingsScopeBinder.bind', () => {
-  it('subscribes before the initial read and converges to the latest queued invalidation', async () => {
-    const initial = deferred<ReturnType<typeof described>>()
-    const describeCall = vi.fn()
-      .mockReturnValueOnce(initial.promise)
-      .mockResolvedValueOnce(described({ preference: 'light' }, 2))
-      .mockResolvedValueOnce(described({ preference: 'system' }, 3))
+  it('shares one mirror read across bound scopes and disposes each with its fiber', async () => {
+    const describeCall = vi.fn().mockResolvedValue(described({ preference: 'dark' }, 1))
+    const wire = { settings: { describe: describeCall } }
+    const mirror = new SettingsDescribeMirror(wire as never)
     const ctx = new Context()
-    ctx.provide('connection', {
-      api: { settings: { describe: describeCall } },
-      isLoopback: true,
-    } as never)
-    let scope!: SettingsScope<UiTestSettings>
+    ctx.provide('connection', { api: wire, isLoopback: true } as never)
+    let theme!: SettingsScope<UiTestSettings>
+    let locale!: SettingsScope<UiTestSettings>
     new TestRemote(ctx)
-    await ctx.plugin(SettingsScopeBinder, new SettingsSchemaService(ctx)).await()
+    await ctx.plugin(SettingsScopeBinder, { mirror, schema: settingsSchema }).await()
+    expect(ctx.settingsScope.describe()).toBe(mirror)
     const fiber = ctx.plugin({
       inject: ['connection', 'remote', 'settingsScope'],
       apply: (plugin: Context) => {
-        scope = plugin.settingsScope.bind<UiTestSettings>({ namespace: 'ui-test' })
+        theme = plugin.settingsScope.bind<UiTestSettings>({ namespace: 'ui-test' })
+        locale = plugin.settingsScope.bind<UiTestSettings>({ namespace: 'ui-test' })
       },
     })
     await fiber.await()
-    await vi.waitFor(() => { expect(describeCall).toHaveBeenCalledOnce() })
-    ctx.remote.$dispatch('settings/document-updated', ['unrelated', 0])
-    ctx.remote.$dispatch('settings/document-updated', ['ui-test', 0])
-    ctx.emit('connection/reset')
-    initial.resolve(described({ preference: 'dark' }, 1))
-    await vi.waitFor(() => { expect(describeCall).toHaveBeenCalledTimes(3) })
     await vi.waitFor(() => {
-      expect(scope.getSnapshot()).toMatchObject({ value: { preference: 'system' }, revision: 3 })
+      expect(theme.getSnapshot()).toMatchObject({ status: 'ready', value: { preference: 'dark' } })
+      expect(locale.getSnapshot()).toMatchObject({ status: 'ready', value: { preference: 'dark' } })
     })
+    expect(describeCall).toHaveBeenCalledTimes(1)
     await fiber.dispose()
-    ctx.remote.$dispatch('settings/document-updated', ['ui-test', 0])
-    await Promise.resolve()
-    expect(describeCall).toHaveBeenCalledTimes(3)
+    await mirror.load()
+    expect(theme.getSnapshot()).toMatchObject({ revision: 1 })
   })
 
   it('binds a remote browser in memory mode without starting a settings read', async () => {
     const describeCall = vi.fn()
+    const wire = { settings: { describe: describeCall } }
+    const mirror = new SettingsDescribeMirror(wire as never, 'memory')
     const ctx = new Context()
-    ctx.provide('connection', {
-      api: { settings: { describe: describeCall } },
-      isLoopback: false,
-    } as never)
+    ctx.provide('connection', { api: wire, isLoopback: false } as never)
     let scope!: SettingsScope<UiTestSettings>
     new TestRemote(ctx)
-    await ctx.plugin(SettingsScopeBinder, new SettingsSchemaService(ctx)).await()
+    await ctx.plugin(SettingsScopeBinder, { mirror, schema: settingsSchema }).await()
     const fiber = ctx.plugin({
       inject: ['connection', 'remote', 'settingsScope'],
       apply: (plugin: Context) => {

packages/client/ui-theme/tests/apply.client.spec.ts

@@ -6,8 +6,7 @@ import { describe, expect, it, vi } from 'vitest'
 import { SlotRegistry } from '@deepseek-ai/dsh-client-runtime/client'
 import { LocaleRuntime } from '@deepseek-ai/dsh-client-locale/client'
 import { TestRemote, usePinnedBrowserLanguages } from '@deepseek-ai/dsh-client-test-runtime'
-import { SettingsSchemaService } from '@deepseek-ai/dsh-client-ui-settings/src/client/schema.ts'
-import { SettingsScopeBinder } from '@deepseek-ai/dsh-client-ui-settings/src/client/settings-scope.ts'
+import { apply as settingsApply, inject as settingsInject } from '@deepseek-ai/dsh-client-ui-settings/client'
 import { apply, inject, SETTINGS_NS } from '@deepseek-ai/dsh-client-ui-theme/client'
 import type { AppearanceRowInjected, ThemeRuntime } from '@deepseek-ai/dsh-client-ui-theme/client'
 import { THEME_SETTINGS_NAMESPACE, ThemeSettingsSchema } from '../src/theme-settings.ts'
@@ -57,7 +56,7 @@ async function bench(isLoopback = true) {
   ctx.provide('connection', { api: { settings: { describe, mutate } }, isLoopback } as never)
   // The settings transport and the forwarded-event port the plugin injects.
   new TestRemote(ctx)
-  await ctx.plugin(SettingsScopeBinder, new SettingsSchemaService(ctx)).await()
+  await ctx.plugin({ inject: [...settingsInject], apply: settingsApply }).await()
   return {
     ctx, slots: ctx.get('slots') as SlotRegistry, locale, describe, mutate,
     setHostPreference: (next: string) => { preference = next },
@@ -128,13 +127,19 @@ describe('ui-theme apply', () => {
 
   it('loads Host settings at boot, refreshes its namespace, and keeps remote browsers process-local', async () => {
     const b = await bench()
+    // The shared mirror read once at bench time; a Host-side change reaches it
+    // through the document invalidation, exactly as production announces one.
     b.setHostPreference('dark')
+    b.ctx.remote.$dispatch('settings/document-updated', [THEME_SETTINGS_NAMESPACE, 0])
     declareItems(b.slots)
     await b.ctx.plugin({ inject: [...inject], apply }).await()
     const theme = b.ctx.get('theme') as ThemeRuntime
     await vi.waitFor(() => { expect(theme.getTheme().preference).toBe('dark') })
+    // The mirror refreshes on every document commit (ns-agnostic); the scope's
+    // derived value only moves when its own namespace changed.
     b.ctx.remote.$dispatch('settings/document-updated', ['unrelated', 0])
-    expect(b.describe).toHaveBeenCalledOnce()
+    await vi.waitFor(() => { expect(b.describe).toHaveBeenCalledTimes(3) })
+    expect(theme.getTheme().preference).toBe('dark')
     b.setHostPreference('light')
     b.ctx.remote.$dispatch('settings/document-updated', [THEME_SETTINGS_NAMESPACE, 0])
     await vi.waitFor(() => { expect(theme.getTheme().preference).toBe('light') })
@@ -152,12 +157,15 @@ describe('ui-theme apply', () => {
     expect(remote.mutate).not.toHaveBeenCalled()
   })
 
-  it('activates before a slow initial settings read and converges when it settles', async () => {
+  it('activates before a slow settings refresh and converges when it settles', async () => {
     const b = await bench()
     b.setHostPreference('dark')
     const describe = b.describe.getMockImplementation()!
     const pending = deferred<Awaited<ReturnType<typeof describe>>>()
     b.describe.mockImplementationOnce(() => pending.promise)
+    // The refresh hangs on the wire; the mirror keeps serving the last good
+    // answer, so activation never blocks on the settings transport.
+    b.ctx.remote.$dispatch('settings/document-updated', [THEME_SETTINGS_NAMESPACE, 0])
     const fiber = b.ctx.plugin({ inject: [...inject], apply })
     await fiber.await()
     const theme = b.ctx.get('theme') as ThemeRuntime
@@ -170,9 +178,10 @@ describe('ui-theme apply', () => {
   it('ignores an invalid preference crossing the settings wire', async () => {
     const b = await bench()
     b.setHostPreference('sepia')
+    b.ctx.remote.$dispatch('settings/document-updated', [THEME_SETTINGS_NAMESPACE, 0])
     await b.ctx.plugin({ inject: [...inject], apply }).await()
     const theme = b.ctx.get('theme') as ThemeRuntime
-    await vi.waitFor(() => { expect(b.describe).toHaveBeenCalledOnce() })
+    await vi.waitFor(() => { expect(b.describe).toHaveBeenCalledTimes(2) })
     expect(theme.getTheme().preference).toBe('system')
   })
 

packages/llm/llm-deepseek/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/llm/llm-deepseek/README.md
-README.md: af89e7ee3bab6ec209349d047f81308eb6e87cef
-README.zh.md: e9ce3206027ffeee9bc49eb7a2ed76ddcbe7bfc8
+README.md: 9bb28e6876b82c521341769123a8b2d0e5d98e09
+README.zh.md: 21c55cfa32bf68e0cac4c0bd72c94c86d955fc00

packages/llm/llm-deepseek/README.md

@@ -20,7 +20,7 @@ The package root exposes the Cordis plugin contract and `DeepSeekAdapter`; wire
     reasoningEffort: high    # optional; off | low | high | max — omitted ⇒ high
     maxTokens: 256000        # optional positive per-request output cap; this is the default
     streamIdleTimeoutMs: 300000 # optional; positive finite Node timer delay; five-minute default
-    retryPolicy:             # optional; omission uses bounded normal defaults
+    retryPolicy:             # optional; omission uses normal mode with five retries
       mode: always           # normal | always
       backoff:
         initialDelayMs: 500
@@ -35,7 +35,7 @@ The package root exposes the Cordis plugin contract and `DeepSeekAdapter`; wire
         contextWindow: 512000
 ```
 
-The plugin registers the single provider route `deepseek-official` together with its resolved `retryPolicy`. A request selects it with `provider: deepseek-official`; its `model` is passed through as the wire `model` string, so changing DeepSeek models does not require lifecycle-time registration. Omitting `models` advertises `deepseek-v4-flash` as `DeepSeek-V4-Flash` and `deepseek-v4-pro` as `DeepSeek-V4-Pro`, each with a 1,000,000-token context window; an explicit list replaces those defaults, while `models: []` advertises none. Catalog entries are exposed through `ctx.llm.listModels('deepseek-official')` for clients such as ACP editors and the Web selector, but remain advisory: unlisted model ids still pass through unchanged. An omitted entry name defaults to its id.
+The plugin registers the single provider route `deepseek-official` together with its resolved `retryPolicy`; omission resolves to normal mode with five retries. A request selects it with `provider: deepseek-official`; its `model` is passed through as the wire `model` string, so changing DeepSeek models does not require lifecycle-time registration. Omitting `models` advertises `deepseek-v4-flash` as `DeepSeek-V4-Flash` and `deepseek-v4-pro` as `DeepSeek-V4-Pro`, each with a 1,000,000-token context window; an explicit list replaces those defaults, while `models: []` advertises none. Catalog entries are exposed through `ctx.llm.listModels('deepseek-official')` for clients such as ACP editors and the Web selector, but remain advisory: unlisted model ids still pass through unchanged. An omitted entry name defaults to its id.
 
 `contextWindow` is optional per configured model and is not exposed through the advisory catalog. `ctx.llm.resolveModelInfo('deepseek-official', model).context` returns an exact model value first, then `defaultContextWindow` for an entry without capacity or an unlisted pass-through id. The adapter default is 1,000,000; pressure-sensitive plugins therefore get deployment-owned capacity without treating the model selector as authoritative. Registering another adapter for `deepseek-official` throws `LlmError('DUPLICATE_ADAPTER')`.
 

packages/llm/llm-deepseek/README.zh.md

@@ -20,7 +20,7 @@ harness LLM（大语言模型）seam 的 DeepSeek chat-completions 适配器：
     reasoningEffort: high    # optional; off | low | high | max — omitted ⇒ high
     maxTokens: 256000        # optional positive per-request output cap; this is the default
     streamIdleTimeoutMs: 300000 # optional; positive finite Node timer delay; five-minute default
-    retryPolicy:             # optional; omission uses bounded normal defaults
+    retryPolicy:             # optional; omission uses normal mode with five retries
       mode: always           # normal | always
       backoff:
         initialDelayMs: 500
@@ -35,7 +35,7 @@ harness LLM（大语言模型）seam 的 DeepSeek chat-completions 适配器：
         contextWindow: 512000
 ```
 
-该插件注册唯一提供方路由 `deepseek-official`，同时注册解析后的 `retryPolicy`。请求使用 `provider: deepseek-official` 选择该路由；其 `model` 会作为协议 `model` 字符串原样传递，因此更改 DeepSeek 模型不需要生命周期时注册。省略 `models` 会公布 `deepseek-v4-flash`（名称为 `DeepSeek-V4-Flash`）和 `deepseek-v4-pro`（名称为 `DeepSeek-V4-Pro`），两者的上下文窗口均为 1,000,000 token；显式列表会替换这些默认值，`models: []` 则不公布任何模型。Catalog 配置项通过 `ctx.llm.listModels('deepseek-official')` 公开给 ACP（Agent Client Protocol）编辑器和 Web 选择器等客户端，但仍只提供建议：未列出模型 id 仍原样传递。省略配置项 name 默认为其 id。
+该插件注册唯一提供方路由 `deepseek-official`，并一同注册解析后的 `retryPolicy`；省略时会解析为 normal 模式并重试五次。请求使用 `provider: deepseek-official` 选择该路由；其 `model` 会作为协议 `model` 字符串原样传递，因此更改 DeepSeek 模型不需要生命周期时注册。省略 `models` 会公布 `deepseek-v4-flash`（名称为 `DeepSeek-V4-Flash`）和 `deepseek-v4-pro`（名称为 `DeepSeek-V4-Pro`），两者的上下文窗口均为 1,000,000 token；显式列表会替换这些默认值，`models: []` 则不公布任何模型。Catalog 配置项通过 `ctx.llm.listModels('deepseek-official')` 公开给 ACP（Agent Client Protocol）编辑器和 Web 选择器等客户端，但仍只提供建议：未列出模型 id 仍原样传递。省略配置项 name 默认为其 id。
 
 `contextWindow` 对每个已配置模型都可选，不会通过建议 catalog 公开。`ctx.llm.resolveModelInfo('deepseek-official', model).context` 先返回精确模型值，再对不含容量的配置项或未列出原样传递 id 返回 `defaultContextWindow`。适配器默认值为 1,000,000；因此，压力敏感插件可以获得由部署决定的容量，不会将模型 selector 视为权威。为 `deepseek-official` 注册另一个适配器会抛出 `LlmError('DUPLICATE_ADAPTER')`。
 

packages/llm/llm-deepseek/src/index.ts

@@ -76,7 +76,7 @@ export interface Config {
   models?: DeepSeekCatalogModel[]
   /** Maximum provider idle time while one stream read is outstanding (default five minutes). */
   streamIdleTimeoutMs?: number
-  /** Provider-owned model-request retry policy; omission uses normal defaults. */
+  /** Provider-owned model-request retry policy; omission uses normal mode with five retries. */
   retryPolicy?: RetryPolicyConfig
 }
 

packages/llm/llm-pi-ai/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/llm/llm-pi-ai/README.md
-README.md: 5dbcb905451f72a700dd09b4052dcb2f88e858c9
-README.zh.md: 217244c7b4d7ecd5aa88427990feb58c96e5acaf
+README.md: f696b6bee50b844bfbc6bab7f9def0e785d450c9
+README.zh.md: cace9d1fdfd85a559674b121b79b3dbb86b4337b

packages/llm/llm-pi-ai/README.md

@@ -8,7 +8,7 @@ The package root exposes the Cordis plugin contract, `PiAiAdapter`, and `support
 
 ## Config
 
-Configure credentials, the model catalog, and deployment-specific transport settings per provider, keyed by the provider route itself. `apiKeyEnv` is a credential *reference* resolved per request, so no secret enters this file. Omitting it leaves the route unauthenticated, which for an installed catalog route means pi-ai's provider-native ambient discovery; a configured reference that resolves to nothing fails the request with `MISSING_CREDENTIAL` instead, because falling through would authenticate with whatever unrelated key the environment happens to hold. One credential serves every model on its route.
+Configure credentials, the model catalog, and deployment-specific transport settings per provider, keyed by the provider route itself. Each profile may set a `retryPolicy`; omission uses normal mode with five retries. `apiKeyEnv` is a credential *reference* resolved per request, so no secret enters this file. Omitting it leaves the route unauthenticated, which for an installed catalog route means pi-ai's provider-native ambient discovery; a configured reference that resolves to nothing fails the request with `MISSING_CREDENTIAL` instead, because falling through would authenticate with whatever unrelated key the environment happens to hold. One credential serves every model on its route.
 
 ```yaml
 - id: llm
@@ -113,7 +113,7 @@ A model that carries reasoning metadata — from the installed catalog or from i
 
 A model **without** that metadata — a hand-declared one whose entry declares no `reasoningEfforts`, and a catalog model pi-ai marks as non-reasoning — exposes no `reasoning` at all. pi-ai reports such a model as supporting the single level `off`, but `off` is translated to *omitting* the reasoning option, which is byte-for-byte the request that naming no effort already produces: selecting it could not disable anything, so a provider whose own default is to think would keep thinking with `off` shown as selected. Reporting the capability as unavailable leaves a surface offering the provider's default and nothing that misrepresents it. The profile `reasoning` value, including `off`, is the deployment default when configured; omitting it preserves the provider default. Per-request `GenerateOptions.reasoningEffort` takes precedence, and a level absent from the exact model capability fails the REQUEST with `UNSUPPORTED_REASONING_EFFORT` before network I/O instead of being clamped. Describing a model never fails that way: the models under one provider disagree about which levels they accept, so `resolveModel` reports a profile level the exact model cannot take as no default at all rather than throwing. A throw there would take the whole provider out of every model catalog built over it — one mis-set profile field hiding even the models that do support the level — so a bad configuration surfaces where it is acted on, not where it is described. pi-ai's common stream options represent `off` by omitting `reasoning`.
 
-Supported profile fields are `apiKeyEnv`, `displayName`, `api`, `baseURL`, `models`, `modelOverrides`, `compat`, `defaultContextWindow`, `defaultMaxTokens`, `defaultInput`, `headers`, `reasoning`, `thinkingBudgets`, `cacheRetention`, `transport`, `timeoutMs`, `websocketConnectTimeoutMs`, `streamIdleTimeoutMs`, `maxRequestImageBytes`, and `retryPolicy`. Each profile's optional retry policy is captured with that provider route; omission uses bounded normal defaults. The stream-idle interval is a positive finite Node timer delay, defaults to five minutes, and covers only an outstanding provider read, not consumer think time. `maxRequestImageBytes` bounds one request's base64-encoded image payload (default 20MiB, a positive integer): every image in history is re-encoded into every request, so when the accumulated payload exceeds the bound, the oldest images are replaced by a fixed text placeholder until the request fits, keeping an image-heavy session serviceable instead of permanently rejected by a gateway request-size cap. The default leaves capacity for system prompts, history, tools, and JSON; deployments behind stricter gateways lower it per route. Harness app attribution wins a conflicting configured header name.
+Supported profile fields are `apiKeyEnv`, `displayName`, `api`, `baseURL`, `models`, `modelOverrides`, `compat`, `defaultContextWindow`, `defaultMaxTokens`, `defaultInput`, `headers`, `reasoning`, `thinkingBudgets`, `cacheRetention`, `transport`, `timeoutMs`, `websocketConnectTimeoutMs`, `streamIdleTimeoutMs`, `maxRequestImageBytes`, and `retryPolicy`. Each resolved profile retry policy is captured with that provider route; omission uses the shared bounded normal default of five retries. The stream-idle interval is a positive finite Node timer delay, defaults to five minutes, and covers only an outstanding provider read, not consumer think time. `maxRequestImageBytes` bounds one request's base64-encoded image payload (default 20MiB, a positive integer): every image in history is re-encoded into every request, so when the accumulated payload exceeds the bound, the oldest images are replaced by a fixed text placeholder until the request fits, keeping an image-heavy session serviceable instead of permanently rejected by a gateway request-size cap. The default leaves capacity for system prompts, history, tools, and JSON; deployments behind stricter gateways lower it per route. Harness app attribution wins a conflicting configured header name.
 
 The adapter forces pi-ai's SDK `maxRetries` to zero so one `stream()` call makes one provider request. The removed profile fields `maxRetries` and `maxRetryDelayMs` fail load instead of silently multiplying or hiding the separately composed agent-level retry budget. Idle expiry aborts the SDK's stable request signal and surfaces `TIMEOUT`; an earlier caller abort remains `ABORTED`.
 
@@ -202,4 +202,4 @@ Recorded response content appends to the next request and does not invalidate it
 - **`GenerateOptions.stop` is unsupported** — pi-ai's common stream options cannot guarantee stop-sequence behavior across providers, so the adapter rejects the field.
 - **In-history `system` messages use pi-ai's common context conversion** — provider-specific placement follows pi-ai rather than a harness-owned wire override.
 - **Provider HTTP status is unavailable** — pi-ai error events do not expose a stable HTTP status across providers; failures expose only stable harness error codes.
-- **Retry policy is provider-owned, not an SDK retry** — each provider profile may configure nested `retryPolicy`, which `dsh-llm-retry` executes at the agent failed-step extension point; pi-ai SDK retries stay disabled so durable agent steps and `llm/retry` events own every visible attempt, and direct `ctx.llm.stream()` calls remain single-attempt.
+- **Retry policy is provider-owned, not an SDK retry** — each provider profile may supply nested `retryPolicy`; omission resolves to normal mode with five retries, and the effective route policy is what `dsh-llm-retry` executes at the agent failed-step extension point. pi-ai SDK retries stay disabled so durable agent steps and `llm/retry` events own every visible attempt, and direct `ctx.llm.stream()` calls remain single-attempt.