Merge remote-tracking branch 'origin/master' into xjt/generated-docs-zh-translation-apply

# Conflicts:
#	.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.i18n.yaml
#	.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md
#	docs/architecture.i18n.yaml
#	docs/architecture.zh.md
#	docs/user/guide/providers.i18n.yaml
#	docs/user/guide/providers.zh.md
#	docs/user/guide/quickstart.i18n.yaml
#	docs/user/guide/quickstart.zh.md
#	packages/boot/app-boot/README.i18n.yaml
#	packages/boot/app-boot/README.zh.md
#	packages/bundle/headless/README.i18n.yaml
#	packages/bundle/headless/README.zh.md

.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.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-07-15-llm-model-catalog-and-acp-selection.md
-2026-07-15-llm-model-catalog-and-acp-selection.md: 9edc723b0dfafeaf395eb9325373835138ddbc41
-2026-07-15-llm-model-catalog-and-acp-selection.zh.md: aefd0af3e4de8fac4f5819e0ee279d3343aec6be
+2026-07-15-llm-model-catalog-and-acp-selection.md: 41174209d2c44bedb5dd0615c5f877ecebd43639
+2026-07-15-llm-model-catalog-and-acp-selection.zh.md: 43442487649f7a552d66bd66b64e0e5072f5e00b

.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.md

@@ -34,9 +34,9 @@ The ACP automation transport is not a catalog consumer. Its deployment config su
 
 ### Prompt/request consistency and durability
 
-`installAgentLlmTarget` (in `dsh-agent`) installs scoped `system-prompt/assemble` and `agent/request` listeners for a front-door-owned target. Prompt assembly snapshots the selected pair once per step, overwrites the assembled `provider` and `model` variables after downstream prompt listeners, and the request listener applies that same snapshot after downstream request listeners. A selection during asynchronous assembly therefore starts on the next step rather than splitting prompt text from routing. Other call-config fields remain untouched.
+`installModelSelection` (in `dsh-agent`) installs scoped `system-prompt/assemble` and `agent/request` listeners for a front-door-owned selection. Prompt assembly snapshots the selected pair once per step, overwrites the assembled `provider` and `model` variables after downstream prompt listeners, and the request listener applies that same snapshot after downstream request listeners. A selection during asynchronous assembly therefore starts on the next step rather than splitting prompt text from routing. Other call-config fields remain untouched.
 
-The request header remains the durable source of truth. When a selected target is actually used, the existing full `request/header` snapshot records it, and a front door initializes its selection from the folded last request header before falling back to creation options. A selection that is never used by a request is intentionally in-memory only because it never became model-visible state.
+The request header remains the durable source of truth. When a selection is actually used, the existing full `request/header` snapshot records it, and a front door initializes its selection from the folded last request header before falling back to creation options. A selection that is never used by a request is intentionally in-memory only because it never became model-visible state.
 
 ## Alternatives considered
 

.agents/notes/implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.zh.md

@@ -34,9 +34,9 @@ ACP 自动化传输层不是目录消费方。它通过部署配置为新创建
 
 ### 提示词／请求一致性与持久化
 
-`installAgentLlmTarget`（位于 `dsh-agent`）为前门拥有的目标安装 agent 作用域的 `system-prompt/assemble` 与 `agent/request` 监听器。提示词组装在每个步骤对所选组合做一次快照，在下游提示词监听器之后覆写组装出的 `provider` 与 `model` 变量；请求监听器在下游请求监听器之后应用同一快照。因此，发生在异步组装期间的选择会从下一个步骤生效，而不会让提示词文本与路由分裂。其他调用配置字段保持不变。
+`installModelSelection`（位于 `dsh-agent`）为前门拥有的选择安装 agent 作用域的 `system-prompt/assemble` 与 `agent/request` 监听器。提示词组装在每个步骤对所选组合做一次快照，在下游提示词监听器之后覆写组装出的 `provider` 与 `model` 变量；请求监听器在下游请求监听器之后应用同一快照。因此，发生在异步组装期间的选择会从下一个步骤生效，而不会让提示词文本与路由分裂。其他调用配置字段保持不变。
 
-请求头仍是持久化的真源。当所选目标真正被使用时，现有的完整 `request/header` 快照会记录它；前门先从折叠后的最后一个请求头初始化其选择，然后才回退到创建选项。从未被请求使用的选择有意只保留在内存中，因为它从未成为模型可见状态。
+请求头仍是持久化的真源。当某个选择真正被使用时，现有的完整 `request/header` 快照会记录它；前门先从折叠后的最后一个请求头初始化其选择，然后才回退到创建选项。从未被请求使用的选择有意只保留在内存中，因为它从未成为模型可见状态。
 
 ## 考虑过的替代方案
 

.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.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-07-19-gui-layering-and-rpc-protocol.md
-2026-07-19-gui-layering-and-rpc-protocol.md: 8e020e4fe9b60100671c0cf0e98e28532d850f94
-2026-07-19-gui-layering-and-rpc-protocol.zh.md: 5c7ee5a407216807e84bd2e62f604dc9c24b6ec9
+2026-07-19-gui-layering-and-rpc-protocol.md: ceb8e5db593aef14d6db259f6293381fe83defe2
+2026-07-19-gui-layering-and-rpc-protocol.zh.md: bc0b6a9e883a1ce7d2990f8dc7284035649ac215

.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md

@@ -31,7 +31,7 @@ Directories layer as follows:
     - **Fetch-arrival plugin packages** (`ui-layout`, `ui-sidebar`, `ui-conversation`, `ui-trajectory`): dual-entry — the root index is the node half (an empty `apply`, existing so the host Loader governs lifecycle and the web plugin registry discovers the package.json `dshClient` declaration); the implementation lives under `src/client/`, shipped as the `./client` subpath (a tsdown closure-factory bundle). Cross-plugin consumption of `/client` is type-only; value cooperation goes through cordis services.
 - `apps/` holds the externally exported application shapes, assembled from Client / Host mixtures.
     - `apps/web` (`dsh-frontend`) is the vite application: a thin `main.ts` over the shell surface exported by `dsh-client-web`.
-    - `apps/cli` (`@deepseek-ai/dsh`) dispatches shapes: `dsh web` = startHost + webserver + the built `dsh-frontend` dist; `dsh run` = headless in-process calls, zero HTTP.
+    - `apps/cli` (`@deepseek-ai/dsh`) dispatches shapes: `dsh web` = Host + webserver + the built `dsh-frontend` dist; `dsh run` = [a direct core Agent/Session front door](2026-08-09-headless-direct-core-front-door.md), with zero Host, HTTP, or browser layer.
     - A future Electron shape reuses the same web client packages over an IPC fetch carrier.
 
 ```
@@ -79,7 +79,7 @@ Packages under `packages/host/*` and `packages/client/*` **must carry the direct
 2. **Write an assembly module under `apps/`**: `startHost()` + a client subclass + the shape's private signal/print/exit semantics; a mixture never becomes a package — assembly is written in the app.
 3. **Import `dsh-host-webserver` only if you need HTTP carriage**, otherwise zero ports.
 
-The two existing shapes are the template: `apps/cli/src/web.ts` (startHost + dist location + startWebServer + signal shutdown) and `headless.ts` (startHost + InProcessApiClient isomorphic direct calls, zero HTTP zero ports). ACP-class protocol bridges do not follow this checklist: they expose core to the external ecosystem, mount via `ctx.plugin(front-door plugin)` directly, and wear no fetch.
+The two existing shapes preserve the boundary: the Web shape mounts Host, carrier, and browser composition, while `dsh run` mounts a direct core runner with zero Host, HTTP, or ports. ACP-class protocol bridges do not follow the client-carrier checklist: they expose core to the external ecosystem, mount via `ctx.plugin(front-door plugin)` directly, and wear no fetch.
 
 ## Message protocol
 
@@ -215,7 +215,7 @@ All four quadrant full forms pass through `onEnvelope`; the base implementation
 
 | Subclass | Package | doFetch | Purpose |
 |---|---|---|---|
-| `InProcessApiClient` | apiproxy itself | the injected `{ fetch }` handler | **The isomorphic point**: `new InProcessApiClient(toFetchHandler(api))` never touches the network yet runs the real wire serialization/zod/SSE framing — `dsh run` headless is the protocol's second real consumer |
+| `InProcessApiClient` | apiproxy itself | the injected `{ fetch }` handler | **The isomorphic point**: `new InProcessApiClient(toFetchHandler(api))` never touches the network yet runs the real wire serialization/zod/SSE framing; carrier tests and callers can exercise the protocol without opening a port, while product `dsh run` drives core directly |
 | `WebApiClient` | dsh-client-connection | `globalThis.fetch` uplink + one same-origin WebSocket downlink per logical stream | the browser shape; physical boundary in the [WebSocket downlink carrier](2026-08-04-websocket-downlink-carrier.md) |
 | `FixtureApiClient` | dsh-client-connection | unused (protocol-layer override) | serverless UI development (`?fixture`): overrides the `callUnary`/`openMux`/`openHost`/`respond` virtuals and is itself the fake server (frame rpcIds minted by it, semantics self-consistent) |
 | (future) IPC bridge subclass | apps/electron | IPC serialization round trip | swaps only doFetch; contract and base class unchanged |
@@ -242,7 +242,7 @@ Every client shape consumes one contract: adding a unary method is a five-step m
 |---|---|
 | Packaging by "product shape" (a web family, an electron family) | What shapes share is host/client capability, not the shape itself; capability-provider layering means a new shape needs zero new packages |
 | A package per mixture (e.g. a standalone headless package) | A mixture has exactly one consumer (its own app); packaging it is ownerless abstraction, while assembly in the app is readable and disposable |
-| Consuming clients connecting to ctx directly (skipping the apiproxy layer) | A second command plane bypasses the contract, losing wire validation/observability/multi-client consistency; ctx keeps exactly two formal uses — front doors and headless event subscription |
+| Consuming clients connecting to ctx directly (skipping the apiproxy layer) | Client shapes require wire validation, observability, and multi-client consistency. Direct headless is a local front door with no client boundary and uses the public Agent/Session seams rather than a client command plane |
 | webserver depending on runtime (saving the handler injection) | Structural-typing injection keeps webserver reusable by sidecars/tests with zero workspace deps; a package dependency would drag assembly knowledge into the carrier layer |
 | Package names without the group prefix (continuing dsh-<tail>) | `dsh-runtime`/`dsh-web-ui` lose their belonging in the flat npm namespace; the cost is one explicit paths entry per package |
 | Reusing the in-repo JSON-RPC 2.0 (dsh-jsonrpc) | Numeric error codes degrade to a single fallback code, contracts get aligned by hand in two copies, and naming drifts without a convention |

.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md

@@ -29,7 +29,7 @@ Status: implemented
     - **fetch 到达插件包**（`ui-layout`、`ui-sidebar`、`ui-conversation`、`ui-trajectory`）：双入口——根入口是 node 半边（空 `apply`，其存在是为了让 host Loader 管辖生命周期、让 web 插件注册表发现 package.json 的 `dshClient` 声明）；实现住在 `src/client/` 下，经 `./client` 子路径发布（tsdown 闭包工厂 bundle）。跨插件消费 `/client` 只限类型；值层面的协作走 cordis 服务。
 - `apps/` 作为对外导出的应用形态入口，可以由 Client / Host 混合组装。
     - `apps/web`（`dsh-frontend`）是 vite 应用：`dsh-client-web` 导出的壳表面之上的一层薄 `main.ts`。
-    - `apps/cli`（`@deepseek-ai/dsh`）做形态分发：`dsh web` = startHost + webserver + 构建出的 `dsh-frontend` dist；`dsh run` = headless 进程内直调，零 HTTP。
+    - `apps/cli`（`@deepseek-ai/dsh`）做形态分发：`dsh web` = Host + webserver + 构建出的 `dsh-frontend` dist；`dsh run` = [直接使用核心 Agent／Session 的前门](2026-08-09-headless-direct-core-front-door.md)，不含 Host、HTTP 或浏览器层。
     - 将来的 Electron 形态经由 IPC fetch 载体复用同一套 web client 包。
 
 ```
@@ -77,7 +77,7 @@ TypeScript 以 solution 根引用的**两个聚合 program** 检查（`tsconfig.
 2. **在 `apps/` 下写拼装模块**：`startHost()` + 客户端子类 + 该形态私有的信号/打印/退出语义；混合体不建包，拼装写在 app 里。
 3. **需要 HTTP 承载才 import `dsh-host-webserver`**，否则零端口。
 
-现有两形态即模板：`apps/cli/src/web.ts`（startHost + dist 定位 + startWebServer + 信号停机）与 `headless.ts`（startHost + InProcessApiClient 同构直调，零 HTTP 零端口）。ACP 类协议桥不走本清单：它把 core 暴露给外部生态，直接 `ctx.plugin(前门插件)` 挂载、不套 fetch。
+现有两种形态保持这一边界：Web 形态挂载 Host、载体与浏览器组合，而 `dsh run` 挂载直接使用核心服务的 runner，不包含 Host、HTTP 或端口。ACP 类协议桥不遵循 client 载体清单：它把 core 暴露给外部生态，直接通过 `ctx.plugin(前门插件)` 挂载，不套 fetch。
 
 ## 消息协议
 
@@ -213,7 +213,7 @@ export type ResponseValue<K> =
 
 | 子类 | 所在包 | doFetch | 用途 |
 |---|---|---|---|
-| `InProcessApiClient` | apiproxy 本包 | 注入的 `{ fetch }` handler | **同构点**：`new InProcessApiClient(toFetchHandler(api))` 全程不过网络但真跑 wire 序列化/zod/SSE 帧——`dsh run` headless 即协议第二真实消费者 |
+| `InProcessApiClient` | apiproxy 本包 | 注入的 `{ fetch }` handler | **同构点**：`new InProcessApiClient(toFetchHandler(api))` 全程不过网络但真跑 wire 序列化/zod/SSE 帧；载体测试与调用方可以在不打开端口的情况下运行这套协议，而产品 `dsh run` 直接驱动 core |
 | `WebApiClient` | dsh-client-connection | `globalThis.fetch` 上行 + 每逻辑流一条同源 WebSocket 下行 | 浏览器形态；物理边界见 [WebSocket 下行载体](2026-08-04-websocket-downlink-carrier.md) |
 | `FixtureApiClient` | dsh-client-connection | 不用（协议层覆写） | 无 server 的 UI 开发（`?fixture`）：覆写 `callUnary`/`openMux`/`openHost`/`respond` 虚方法，自己就是假 server（帧 rpcId 由它 mint，语义自洽） |
 | （将来）IPC 桥子类 | apps/electron | IPC 序列化往返 | 仅换 doFetch，约定/基类零改 |
@@ -240,7 +240,7 @@ export type ResponseValue<K> =
 |---|---|
 | 按「产品形态」分包（web 一族、electron 一族） | 形态间共享的是 host/client 两侧能力而非形态本身；能力支持方分层让新形态零新包 |
 | 混合体建包（如 headless 独立包） | 混合体只有一个消费者（它自己的 app），建包是无主抽象；拼装写在 app 里可读可弃 |
-| 消费型 client 直连 ctx（省 apiproxy 一层） | 第二命令面绕开约定，wire 校验/观测/多端一致性全失；ctx 只留给前门与 headless 事件订阅两个正式用途 |
+| 消费型 client 直连 ctx（省 apiproxy 一层） | client 形态需要 wire 校验、观测与多 client 一致性。直接 headless 是没有 client 边界的本地前门，使用公开的 Agent／Session seam，而不是 client 命令面 |
 | webserver 依赖 runtime（省 handler 注入） | 结构 typing 注入让 webserver 可被 sidecar/测试复用且零 workspace 依赖；包依赖会把装配知识拖进承载层 |
 | 包名不带组前缀（沿用 dsh-<尾段>） | `dsh-runtime`/`dsh-web-ui` 在扁平 npm 命名空间里失去归属信息；代价只是每包一条显式 paths |
 | 复用仓内 JSON-RPC 2.0（dsh-jsonrpc） | 数字错误码退化成单码兜底、约定双份人肉对齐、命名无 convention 自然漂移 |

.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.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-07-24-web-config-tree-boot-and-transport-layering.md
-2026-07-24-web-config-tree-boot-and-transport-layering.md: 88f94b1f58ae7a3451c7772f4a9ff7d6564254c0
-2026-07-24-web-config-tree-boot-and-transport-layering.zh.md: 5f03dfbb8e5eaeeb52076584721e70ea66a292df
+2026-07-24-web-config-tree-boot-and-transport-layering.md: 496499a691dbca012e5e953cbb6eb1d0bf25b635
+2026-07-24-web-config-tree-boot-and-transport-layering.zh.md: 4a83db6f797ad2a0b048ef996d10dbc5ea0a33dd

.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.md

@@ -16,23 +16,23 @@ English | [中文](2026-07-24-web-config-tree-boot-and-transport-layering.zh.md)
 
 **Boot glue is a class pair.** `AppCLIEntry` (apps/cli) and `AppWebEntry` (the shell kernel) hold only what must exist independently of cordis: argv facts, the composed patch set, the parsed boot manifest, the module system instance, loading-page handles — everything else lives in plugins. `AppCLIEntry.run()` is three stages: layered env (ambient > cwd `.env` > `$DSH_HOME/.env`, closing the defect above) → patch composition → Loader include boot plus the activation audit. `AppWebEntry.run()` mirrors it browser-side: parse `window.__DSH_BOOT__` into a `BootManifest` (two views: npm-package rows for the module table, cordis-plugin rows for entry composition; malformed wire throws), build the module system, render the loading page, prefetch the `immediately` tier in parallel with Context/Loader setup, **await the prefetch before creating entries** (materialization is `tree.import`'s synchronous require, unprotected by fiber inject waiting; cross-package require edges such as i18n → runtime/client need every immediately-tier factory registered first — an empirically found 10–25% boot race otherwise), adopt the modules entry, create the graph rows, settle, sweep.
 
-**Config sources have one declaration place each.** yml static values are engineering defaults; the profile json (`./.dsh-tmp-profile/config.json`, read-only, never created, cwd-anchored until the `$DSH_HOME` migration) is user config mapped through a static `PROFILE_MAPPINGS` table onto target rows (`provider`/`model` → the `api-gateway` row, `persistenceRoot` → the jsonl row); CLI flags map onto the `webserver` row with a field set disjoint from the json's; env values enter through yml `!!js` expressions, never through the mapping table. Patches replace a row's config wholesale, so the entry class re-reads the yml row's static values (bypass parse) and merges overrides on top. An unmapped json key fails loud. The resolved frontend `distIndex` rides the same patch channel — an assembly fact, not user config.
+**Config sources have one declaration place each.** Bundle yml values are engineering defaults, Settings sections are writable user preferences, CLI flags address their owning launcher rows, and env values enter through yml `!!js` expressions. Patches replace a row's config wholesale. The resolved frontend `distIndex` uses that patch channel as an assembly fact. The transport-independent provider/model default belongs to `ctx.agentDefaultModel`; the [direct headless front door](2026-08-09-headless-direct-core-front-door.md) and the Web gateway consume the same state.
 
-**The transport splits five ways.** `dsh-host-apiproxy` upgraded to the gateway plugin (`api-gateway` row): default-exports `ApiProxyService`, config `{provider, model}`, provides `ctx.apiProxy`, transport-agnostic and registers no routes — `createApiProxy` moved here from the retired runtime package. `dsh-host-webserver` shrank to a plain route-registration plugin: `HttpServerService` provides `ctx.httpServer` (`register(route) → disposer` with duplicate-pattern throw, `tapIndex` transforms applied in registration order, `port`), listens on activation, per-request failures answer 400 and log without exiting, and knows no harness concepts. The connection node half owns the binding: it injects both services and registers `toFetchHandler(ctx.apiProxy)` under the `/api` prefix — future IPC carriers swap connection's transport while the gateway stays untouched. The modules node half (`ClientModuleHostService`, providing `ctx.clientModuleHost`) owns the graph: incremental per-package scanning (no full-rescan code path — `internal/plugin` marks the fiber's entry name dirty, a flush reconciles each name against live entries, package metadata including negative verdicts is cached forever, re-hashing is reachable only through `rebuilt(id)`), the bundle route, the index tap, and `onRebuilt`/`onGraphChanged` notification. The hmr node half owns dev reload: `fs.watchFile` stat-polling driven by `onGraphChanged` membership, and the `/plugins/events` SSE route.
+**The transport splits five ways.** `dsh-host-apiproxy` is the gateway plugin (`api-gateway` row): it default-exports `ApiProxyService`, configures only `{workspaceRoot?}`, consumes the base layer's front-door-neutral `ctx.agentDefaultModel`, provides `ctx.apiProxy`, remains transport-agnostic, and registers no routes. `dsh-host-webserver` is a plain route-registration plugin: `HttpServerService` provides `ctx.httpServer` (`register(route) → disposer` with duplicate-pattern throw, `tapIndex` transforms applied in registration order, `port`), listens on activation, answers per-request failures with 400 and logging, and knows no harness concepts. The connection node half owns the `/api` binding from `ctx.apiProxy` through `toFetchHandler`. The modules node half (`ClientModuleHostService`, providing `ctx.clientModuleHost`) owns incremental package scanning, the bundle route, the index tap, and `onRebuilt`/`onGraphChanged` notification. The hmr node half owns dev reload through `fs.watchFile` membership and the `/plugins/events` SSE route.
 
 **Package export discipline.** The modules package exposes exactly `.` (node half) and `./client` (the complete browser half: `ClientModuleSystem`, `parseBootManifest`, the adoption plugin face) — no bespoke subpaths; wire types re-export through the root for host-side consumers. The adoption handshake: the kernel writes the constructed instance to `window.__DSH_MODULES__` before cordis exists; the `./client` apply reads the slot (missing = loud throw) and provides `ctx.modules`.
 
 ## Consequences
 
 - Recomposing a web deployment is a yml/patch edit; the retired pieces (`mountWebPlugins`, `CLIENT_PACKAGES`, `createHostWebPluginRegistry`, `startWebServer`, the webserver's graph/SSE/api knowledge) are deleted.
-- Headless boots the same composition through the same entry (landed in the stacked follow-up): port 0 is its only surface difference, the model face gains `ask_user_question`/workspace context/model titles per the unification ruling, and `bootHost`/`startHost` retired with the `dsh-host-runtime` package. The profile write path, the `$DSH_HOME` profile relocation, and IPC carriers remain recorded deferrals.
+- [Headless is a direct core front door](2026-08-09-headless-direct-core-front-door.md): its shipped profile contains the shared base Agent capabilities and omits Host, HTTP, Web, and browser layers. The transport split in this note is the browser surface's contract.
 - A TypeScript pitfall worth remembering: a `declare module 'cordis'` augmentation in a file with **no cordis import** is demoted to a standalone module declaration and silently shatters the program-wide `Context` merge (`ctx.on`/`ctx.effect` vanish across the program). Anchor with `import type {} from 'cordis'`.
 
 ## Alternatives considered
 
 | Rejected | One-line reason |
 |---|---|
-| Dedicated `dsh-host-profile` receiver package | The profile json is consumed at patch time; the only runtime consumer of `{provider, model}` is the gateway itself — its config is the receiver |
+| Dedicated `dsh-host-profile` receiver package | User model state belongs to the Settings-backed `ctx.agentDefaultModel`; an extra Host receiver would duplicate ownership and exclude direct front doors |
 | Runtime `assembly` shim plugin providing an `apiHandler` service | Existed only because `createApiProxy` lived in runtime; moving it into apiproxy made the gateway self-hosting, and `toFetchHandler` is a pure function the binding side calls |
 | Full-rescan + incremental scan coexisting | Two implementations, two semantics; the single per-package path covers the activation pass too |
 | A bespoke `./impl` export on the modules package | Non-uniform export surface; the standard `./client` carries the whole browser half |

.agents/notes/implemented/architecture/2026-07-24-web-config-tree-boot-and-transport-layering.zh.md

@@ -16,23 +16,23 @@ Status: implemented
 
 **boot 胶水由两个类组成。** `AppCLIEntry`（apps/cli）与 `AppWebEntry`（壳内核）只持有那些必须独立于 cordis、提前存在的东西：argv 事实、合成的 patch 集、解析出的 boot manifest（元数据清单）、模块系统实例、loading 页句柄——其余一律进插件。`AppCLIEntry.run()` 三段：分层 env（ambient > cwd `.env` > `$DSH_HOME/.env`，顺手关掉上述缺陷）→ patch 合成 → Loader include boot 加 activation audit。`AppWebEntry.run()` 在浏览器侧镜像它：把 `window.__DSH_BOOT__` 解析成 `BootManifest`（双视角：npm 包行给模块表、cordis 插件行给 entry 组合；畸形 wire 大声抛）、建模块系统、渲染 loading 页、immediately 层预取与 Context/Loader 准备并行、**create entry 之前等预取齐**（物化是 `tree.import` 的同步 require，不受 fiber inject 等待保护；i18n → runtime/client 这类跨包 require 边要求 immediately 层工厂全部注册完——否则有实测 10–25% 的 boot 竞态）、收编 modules entry、逐一创建图行、settle、sweep。
 
-**每个配置源有唯一声明位置。** yml 静态值是工程默认；profile json（`./.dsh-tmp-profile/config.json`，只读、绝不创建、暂锚 cwd 直至 `$DSH_HOME` 迁移）是用户配置，经静态 `PROFILE_MAPPINGS` 表映射到目标行（`provider`/`model` → `api-gateway` 行，`persistenceRoot` → jsonl 行）；CLI（命令行界面）flags 映射到 `webserver` 行、字段集与 json 不相交；env 值经 yml `!!js` 表达式进入，绝不进映射表。patch 整体替换行 config，故 entry 类旁路 parse 重读 yml 行静态值再叠加覆盖。未映射的 json 键 fail loud。解析出的前端 `distIndex` 走同一 patch 通道——装配事实，不是用户配置。
+**每个配置源有唯一声明位置。** 组合包 yml 值是工程默认，Settings 分节是可写的用户偏好，CLI（命令行界面）flags 面向其归属的启动器配置行，env 值则通过 yml `!!js` 表达式进入。patch 会整体替换一行的 config。解析后的前端 `distIndex` 通过同一条 patch 通道作为组装事实传递。与传输无关的提供方／模型默认值归 `ctx.agentDefaultModel` 所有；[直接 headless 前门](2026-08-09-headless-direct-core-front-door.md)与 Web 网关消费同一份状态。
 
-**传输五分。** `dsh-host-apiproxy` 升格网关插件（`api-gateway` 行）：默认导出 `ApiProxyService`，config `{provider, model}`，provide `ctx.apiProxy`，传输无关、不注册路由——`createApiProxy` 从已退役的运行时包迁入。`dsh-host-webserver` 缩成朴素路由注册插件：`HttpServerService` provide `ctx.httpServer`（`register(route) → disposer`、重复 pattern 即抛、`tapIndex` 按注册序应用、`port`），激活即 listen，单请求失败答 400 并记日志，不退出进程，不认识任何 harness 概念。connection node 半拥有绑定：inject 两个服务，把 `toFetchHandler(ctx.apiProxy)` 注册在 `/api` 前缀下——将来 IPC 载体只换 connection 的传输，网关零改动。modules node 半（`ClientModuleHostService`，provide `ctx.clientModuleHost`）拥有图：单包增量扫描（无全量重扫路径——`internal/plugin` 把 fiber 的 entry 名标脏，flush 逐名对账 live entries，包括否定结论在内的包元数据会永久缓存，重哈希唯一入口 `rebuilt(id)`）、bundle 路由、index tap、`onRebuilt`/`onGraphChanged` 通知。HMR node 半拥有开发期重载：`fs.watchFile` stat 轮询、watch 集合跟随 `onGraphChanged`、`/plugins/events` SSE 路由。
+**传输五分。** `dsh-host-apiproxy` 是网关插件（`api-gateway` 行）：默认导出 `ApiProxyService`，只配置 `{workspaceRoot?}`，消费 base 层不偏向特定前门的 `ctx.agentDefaultModel`，provide `ctx.apiProxy`，保持传输无关且不注册路由。`dsh-host-webserver` 是朴素的路由注册插件：`HttpServerService` provide `ctx.httpServer`（`register(route) → disposer`、重复 pattern 即抛、`tapIndex` 按注册序应用、`port`），激活即 listen，单请求失败时答 400 并记日志，且不认识任何 harness 概念。connection node 半拥有从 `ctx.apiProxy` 经 `toFetchHandler` 绑定到 `/api` 的逻辑。modules node 半（`ClientModuleHostService`，provide `ctx.clientModuleHost`）拥有单包增量扫描、bundle 路由、index tap 与 `onRebuilt`/`onGraphChanged` 通知。HMR node 半通过 `fs.watchFile` membership 与 `/plugins/events` SSE 路由拥有开发期重载。
 
 **包出口纪律。** modules 包只暴露 `.`（node 半）与 `./client`（完整浏览器半：`ClientModuleSystem`、`parseBootManifest`、收编插件面）——不设专用子路径；wire 类型经根出口 re-export 给 host 侧消费方。收编握手：内核在 cordis 之前把建好的实例写入 `window.__DSH_MODULES__`；`./client` 的 apply 读取该槽位（缺少时显式抛错）并 provide `ctx.modules`。
 
 ## 后果
 
 - 重组一个 web 部署 = 改 yml/patch；退役件（`mountWebPlugins`、`CLIENT_PACKAGES`、`createHostWebPluginRegistry`、`startWebServer`、webserver 的图/SSE/api 知识）全部删除。
-- headless 已在 stacked 后续轮迁入同一组合同一入口：唯一面差异是 port 0，模型面按统一裁决获得 `ask_user_question`/workspace context/模型标题，`bootHost`/`startHost` 随 `dsh-host-runtime` 包退役。profile 写入路径、profile 迁 `$DSH_HOME`、IPC 载体仍为挂账项。
+- [Headless 是直接 core 前门](2026-08-09-headless-direct-core-front-door.md)：其随附 profile 包含共享的 base Agent 能力，并省去 Host、HTTP、Web 与浏览器层。本笔记的传输划分是浏览器 surface 的契约。
 - 一个值得记住的 TypeScript 坑：`declare module 'cordis'` augmentation 所在文件若**没有任何 cordis import**，会被降级成独立 module declaration，无声打散全程序的 `Context` merge（`ctx.on`/`ctx.effect` 全程序消失）。用 `import type {} from 'cordis'` 锚定。
 
 ## 考虑过的替代方案
 
 | 弃案 | 一行理由 |
 |---|---|
-| 专门的 `dsh-host-profile` 受体包 | profile json 在 patch 阶段消费完；`{provider, model}` 的唯一运行时消费方是网关自己——受体即网关 config |
+| 专门的 `dsh-host-profile` 受体包 | 用户模型状态归 Settings 支撑的 `ctx.agentDefaultModel` 所有；额外的 Host 受体会重复归属，并排除直接前门 |
 | 运行时里的 `assembly` 垫层插件（provide `apiHandler`） | 它的存在只因 `createApiProxy` 住运行时；本体迁入 apiproxy 后网关自持插件身份，且 `toFetchHandler` 是绑定方自己调的纯函数 |
 | 全量重扫与增量扫描并存 | 两条实现两份语义；单包路径足以覆盖激活初扫 |
 | modules 包特设 `./impl` 出口 | 出口面不统一；标准 `./client` 承载完整浏览器半 |

.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.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-05-profile-plugin-bundles.md
-2026-08-05-profile-plugin-bundles.md: 8613e600ad633818abb4319e614230340c3b3876
-2026-08-05-profile-plugin-bundles.zh.md: 3a35f944e115371b5f4702bbe81ec9bc3c314ef0
+2026-08-05-profile-plugin-bundles.md: f183fc5ff5f3c8d850e913d9a9b836f075da7a3b
+2026-08-05-profile-plugin-bundles.zh.md: 294082249c2d3244321cb7efabf0eb286d11ef46

.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.md

@@ -12,7 +12,7 @@ The `dsh` launcher hardcoded its compositions: `base.cordis.yml` + `web.cordis.y
 
 Everything becomes a **profile**: a directory `$DSH_HOME/profiles/<name>` with a `package.json` (pnpm-managed out-of-tree plugin `dependencies` plus the profile manifest `dsh.profile` with its ordered `bundles` layer list) and a user `cordis.patch.yml`. A **bundle** is an npm package declaring `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`; the two manifest kinds live under distinct `dsh.profile` / `dsh.bundle` keys so a package.json states which role it plays. The tree composes over an empty root by applying each bundle's patch in `dsh.profile.bundles` order, then the user layer, then `--patch` overlays, then flag patches — one `applyEntryPatches` call, identical for boot, flag derivation, and `--dump-config`.
 
-The shipped compositions became bundles: `@deepseek-ai/dsh-base` (the former base rows as one insert), `@deepseek-ai/dsh-web-app` (the former web overlay plus a runtime glue plugin that owns what used to be launcher code — frontend-dist resolution, the web-surface prompt section, bash runtime variables, the URL line), and `@deepseek-ai/dsh-headless` (a one-shot runner plugin over base + web-app). `dsh web` stays as an alias for `--profile web` carrying the Web flag family; `dsh run [--profile <name>] "task"` owns one-shot execution and defaults to the headless profile, while generic `dsh --profile <name>` boots without a task; `dsh --config` is removed (its uses migrate to `--patch`). `dsh plugin --profile <name> <args...>` is a thin pnpm forwarder that initializes the profile and reconciles `dsh.profile.bundles` after `add`/`remove` (a bundle-less package warns and stays a plain dependency).
+The shipped bundles are `@deepseek-ai/dsh-base` (shared core rows), `@deepseek-ai/dsh-web-app` (browser Host rows and Web runtime glue), and `@deepseek-ai/dsh-headless` (a direct one-shot runner over base, without web-app). `dsh web` is the Web-flag alias for `--profile web`; `dsh run [--profile <name>] "task"` owns one-shot execution and defaults to the headless profile; generic `dsh --profile <name>` boots without a task. Patch overlays use `--patch`. `dsh plugin --profile <name> <args...>` is a thin pnpm forwarder that initializes the profile and reconciles `dsh.profile.bundles` with installed bundle declarations; a package without a bundle declaration remains a plain dependency. [Headless as a direct core front door](2026-08-09-headless-direct-core-front-door.md) owns the headless composition contract.
 
 The [`dsh run` command decision](../feature/2026-08-08-dsh-run-headless-command.md) owns the one-shot grammar; this note owns the profile composition it selects.
 

.agents/notes/implemented/architecture/2026-08-05-profile-plugin-bundles.zh.md

@@ -12,7 +12,7 @@ Status: implemented
 
 一切都变成 **profile**：即目录 `$DSH_HOME/profiles/<name>`，其中包含一个 `package.json`（pnpm 管理的树外插件 `dependencies`，加上 profile manifest（元数据清单）`dsh.profile` 及其有序的 `bundles` 层列表）和一份用户 `cordis.patch.yml`。**组合包**（bundle）是声明了 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包；两种 manifest 分别位于互不相同的 `dsh.profile` / `dsh.bundle` 键下，因此一份 package.json 能说明自己扮演哪种角色。配置树在空的根之上组合：按 `dsh.profile.bundles` 顺序应用每个组合包的 patch，然后是用户层，然后是 `--patch` overlay，最后是 flag patch——全部收敛为一次 `applyEntryPatches` 调用，启动、flag 派生与 `--dump-config` 使用完全相同的路径。
 
-已交付的组合改造成了组合包：`@deepseek-ai/dsh-base`（原有基础行合并为一次插入）、`@deepseek-ai/dsh-web-app`（原 web overlay，外加一个接管原启动器代码的运行时粘合插件——前端 dist 解析、web 表层提示词段落、bash 运行时变量、URL 行）、`@deepseek-ai/dsh-headless`（叠加在 base + web-app 之上的一次性 runner 插件）。`dsh web` 保留为携带 Web flag 家族的 `--profile web` 别名；`dsh run [--profile <name>] "task"` 负责一次性执行，默认使用 headless profile，而通用的 `dsh --profile <name>` 只启动 profile，不携带任务；`dsh --config` 被移除（其用途迁移到 `--patch`）。`dsh plugin --profile <name> <args...>` 是一层薄薄的 pnpm 转发器，负责初始化 profile，并在 `add`／`remove` 后调和 `dsh.profile.bundles`（没有组合包声明的包会给出警告，保持为普通依赖）。
+随附的组合包是 `@deepseek-ai/dsh-base`（共享核心配置行）、`@deepseek-ai/dsh-web-app`（浏览器 Host 配置行与 Web 运行时粘合层）和 `@deepseek-ai/dsh-headless`（直接叠加在 base 上且不含 web-app 的一次性 runner）。`dsh web` 是携带 Web flag 家族的 `--profile web` 别名；`dsh run [--profile <name>] "task"` 负责一次性执行，默认使用 headless profile；通用的 `dsh --profile <name>` 启动 profile 而不携带任务。patch overlay 使用 `--patch`。`dsh plugin --profile <name> <args...>` 是一层薄薄的 pnpm 转发器，负责初始化 profile，并依据已安装包的组合包声明调和 `dsh.profile.bundles`；没有组合包声明的包保持为普通依赖。[Headless 作为直接 core 前门](2026-08-09-headless-direct-core-front-door.md)负责 headless 组合契约。
 
 [`dsh run` 命令决策](../feature/2026-08-08-dsh-run-headless-command.md)负责一次性语法；本 Agent Note 负责该语法所选择的 profile 组合。
 

.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.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-09-headless-direct-core-front-door.md
+2026-08-09-headless-direct-core-front-door.md: 875939b424059907949e350d50d88ded331f3dc9
+2026-08-09-headless-direct-core-front-door.zh.md: 7de5efbe172c0c43c03d55724d27e32d08c11e9f

.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.md

@@ -0,0 +1,44 @@
+# Agent Note: headless is a direct core front door
+
+Status: implemented
+
+English | [中文](2026-08-09-headless-direct-core-front-door.zh.md)
+
+## Problem
+
+The `headless` product contract is one local task with final assistant text on stdout, a success-sensitive exit code, empty stderr on success, and no listening port. A composition containing Workspace Host services, ApiProxy, HTTP, the Web runtime, or browser plugins contradicts that contract and makes local completion depend on an unrelated transport tree.
+
+The direct front door still needs the same deployment model state as Web-created Agents. A separate provider/model default would give one deployment two answers, while deriving completion before the Agent and Session persistence are quiescent permits stdout and the exit code to observe incomplete state.
+
+## Decision
+
+The shipped `headless` profile contains `dsh-base` and `dsh-headless`. The headless bundle supplies its persona and tool mode, disables HMR, mounts the Code Mode worker explicitly, and inserts `headless-runner`. Its tree contains no `@deepseek-ai/dsh-host-*` package, ApiProxy, HTTP server, Web runtime, or browser client. Code Mode and Session persistence are one-shot Agent capabilities independent of Web presentation.
+
+`headless-runner` is a direct core front door. After Loader settlement, it reads `ctx.agentDefaultModel.currentSelection()`, creates a fresh persisted Agent through `ctx.agents.create`, installs that `ModelSelection` in the Agent scope, waits for startup quiescence, anchors the Session sequence, submits one ordinary user message, and waits for quiescence again. It awaits `ctx.sessions.flush`, folds its durable event interval for the last non-empty assistant text and final `turn/end` reason, writes the text plus one newline to stdout, and requests bounded launcher shutdown with exit 0 exactly when the reason is `completed`. A terminal `error` reason writes its durable code and message to stderr; unexpected driver failures also use stderr and exit 1.
+
+`@deepseek-ai/dsh-agent-default-model` owns the transport-independent default used for an Agent without a session-local selection. `AgentDefaultModelService` provides `ctx.agentDefaultModel` and registers the `agent-default-model` Settings section. Composition config supplies `{provider, model}`; user settings may also supply `reasoningEffort`. `currentSelection()` returns the live complete selection and `saveSelection()` writes it as a complete section, so a selection without an effort clears any stored effort. `dsh-base` supplies the composition entry. Direct and ApiProxy front doors consume this service; ApiProxy alone owns session-local precedence, model validation, and persistence of accepted Web selections.
+
+`loadProfile` recognizes the exact installation-owned headless tuple (`dsh-base`, `dsh-web-app`, `dsh-headless`) and normalizes it to the shipped headless template while preserving every other manifest field. Extra, missing, or reordered bundle lists are user-owned and remain untouched.
+
+This note owns the headless transport and completion contracts. [`dsh run` owns one-shot headless execution](../feature/2026-08-08-dsh-run-headless-command.md) owns the command grammar, [GUI layering and RPC protocol](2026-07-19-gui-layering-and-rpc-protocol.md) owns browser gateway boundaries, [web config-tree boot and transport layering](2026-07-24-web-config-tree-boot-and-transport-layering.md) owns the Web tree, and [the default model follows the picker](../feature/2026-08-07-default-model-follows-the-picker.md) owns persistence of the shared Agent default.
+
+## Verification
+
+Package tests use the real Session store and Agent registry around a scripted Agent factory to pin idle-to-idle aggregation, late asynchronous completion, terminal model diagnostics, other non-completed exits, direct failures, Loader-time disposal, and flush-before-exit ordering. The keyless assembled snapshots drive `dsh run` through a replayed tool round trip, record direct user-message provenance, and expose a terminal model failure on stderr. Built-bin acceptance reaches a mock provider through the published entry and requires final text on stdout, exit 0, and empty stderr. Config-dump acceptance excludes every Host, Web, and Client package from the shipped headless tree; PTY shutdown coverage requires no observation line and bounded disposal.
+
+## Alternatives considered
+
+| Alternative | Contract mismatch |
+|---|---|
+| Keep `dsh-web-app` but suppress its observation line | The process still opens a port and carries the Host, Web, and browser trees. |
+| Build a Host-only one-shot bundle around ApiProxy | ApiProxy is a client protocol gateway; a local one-shot front door has no client boundary. |
+| Use `InProcessApiClient` for product-level protocol coverage | Product execution would depend on an unrelated protocol solely to exercise that protocol. |
+| Give headless a separate provider/model config | Direct and Web creation would have independent defaults and persistence. |
+| Omit Code Mode and Session persistence | Both capabilities belong to one-shot Agent execution rather than Web presentation. |
+| Normalize every tuple containing Web and headless bundles | Bundle lists are an extension surface; only the exact installation-owned tuple is safe to classify. |
+
+## Consequences
+
+`dsh run` provides a local Agent task rather than browser observation, Host APIs, or HTTP. Users who need those capabilities choose `dsh web`. Successful stderr is empty, completion follows durable flush, and the persisted Session remains available to later tooling. Its initial user message has direct user provenance and therefore carries no ApiProxy `rpcId`.
+
+ApiProxy carrier coverage stays in the ApiProxy package. Custom one-shot profiles may include Host or Web bundles explicitly, while the shipped profile and the recognized installation-owned tuple are Web-free.

.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-front-door.zh.md

@@ -0,0 +1,44 @@
+# Agent Note: headless 是直接使用核心服务的入口
+
+Status: implemented
+
+[English](2026-08-09-headless-direct-core-front-door.md) | 中文
+
+## 问题
+
+`headless` 的产品契约是一个本地任务：最终 assistant 文本写入 stdout，退出状态反映成功与否，成功时 stderr 为空，并且不打开监听端口。包含 Workspace Host 服务、ApiProxy、HTTP、Web 运行时或浏览器插件的组合违背这一契约，也使本地完成状态依赖无关的传输树。
+
+直接前门仍需要与 Web 所创建 Agent 相同的部署模型状态。独立的提供方／模型默认值会让同一部署产生两种答案，而在 Agent 与会话持久化完全停稳之前推导完成状态，会让 stdout 与退出状态观察到不完整状态。
+
+## 决策
+
+随附的 `headless` profile 包含 `dsh-base` 与 `dsh-headless`。headless 组合包提供自身的 persona 与工具模式、禁用 HMR（热模块替换）、显式挂载 Code Mode worker，并插入 `headless-runner`。其插件树不包含任何 `@deepseek-ai/dsh-host-*` 包、ApiProxy、HTTP server、Web 运行时或浏览器客户端。Code Mode 与会话持久化均为独立于 Web 呈现的一次性 Agent 能力。
+
+`headless-runner` 是直接使用核心服务的入口。Loader 完全加载后，它读取 `ctx.agentDefaultModel.currentSelection()`，通过 `ctx.agents.create` 创建一个新的持久化 Agent，在 Agent 作用域中安装该 `ModelSelection`，等待启动工作完全停稳，锚定会话事件序号，提交一条普通用户消息，再次等待完全停稳。随后，它等待 `ctx.sessions.flush`，折叠自身持有的持久事件区间，以取得最后一条非空 assistant 文本和最终 `turn/end` 结束原因，将文本连同一个换行写入 stdout，并且仅在结束原因为 `completed` 时请求启动器以退出状态 0 有界关闭。结束原因为 `error` 时，其持久化错误码与消息写入 stderr；驱动器的意外失败也写入 stderr 并以 1 退出。
+
+`@deepseek-ai/dsh-agent-default-model` 拥有与传输无关的默认值，供没有会话级选择的 Agent 使用。`AgentDefaultModelService` 提供 `ctx.agentDefaultModel` 并注册 `agent-default-model` Settings 分节。组合配置提供 `{provider, model}`，用户设置还可以提供 `reasoningEffort`。`currentSelection()` 返回当前的完整选择，`saveSelection()` 则写入完整分节，因此不含强度的选择会清除已存强度。`dsh-base` 提供组合条目。直接前门与 ApiProxy 前门均消费该服务；只有 ApiProxy 负责会话级优先级、模型校验与已接受 Web 选择的持久化。
+
+`loadProfile` 识别安装过程拥有的精确 headless 元组（`dsh-base`、`dsh-web-app`、`dsh-headless`），将其规范化为随附的 headless 模板，并保留 manifest（元数据清单）的其他所有字段。带额外项、缺少项或顺序不同的组合包列表归用户所有，保持不变。
+
+本 Agent Note 负责 headless 的传输与完成契约。[`dsh run` 负责一次性 headless 执行](../feature/2026-08-08-dsh-run-headless-command.md)负责命令语法，[GUI 分层与 RPC 协议](2026-07-19-gui-layering-and-rpc-protocol.md)负责浏览器网关边界，[Web 配置树启动与传输分层](2026-07-24-web-config-tree-boot-and-transport-layering.md)负责 Web 插件树，[默认模型跟随选择器](../feature/2026-08-07-default-model-follows-the-picker.md)负责共享 Agent 默认值的持久化。
+
+## 验证
+
+包测试围绕脚本化 Agent 工厂使用真实的会话存储与 Agent 注册表，固定空闲态到空闲态的聚合、延迟异步完成、终止态模型诊断、其他未完成退出、直接失败、Loader 加载期间的 dispose（资源释放），以及退出前 flush 的顺序。组装后的无密钥快照通过回放的工具往返驱动 `dsh run`，记录直接用户消息的来源，并在 stderr 暴露终止态模型失败。构建后二进制验收通过已发布入口访问 mock 提供方，并要求最终文本出现在 stdout、退出状态为 0 且 stderr 为空。配置转储验收排除随附 headless 树中的所有 Host、Web 与 Client 包；PTY 关闭覆盖要求不出现观察行，并在有界时间内完成 dispose。
+
+## 考虑过的替代方案
+
+| 替代方案 | 契约不匹配之处 |
+|---|---|
+| 保留 `dsh-web-app`，但隐藏观察行 | 进程仍会打开端口并携带 Host、Web 与浏览器插件树。 |
+| 围绕 ApiProxy 构建纯 Host 一次性组合包 | ApiProxy 是客户端协议网关，而本地一次性前门没有客户端边界。 |
+| 使用 `InProcessApiClient` 实现产品级协议覆盖 | 产品执行会仅为测试无关协议而依赖该协议。 |
+| 为 headless 单独提供提供方／模型配置 | 直接创建与 Web 创建会拥有彼此独立的默认值和持久化。 |
+| 省略 Code Mode 与会话持久化 | 两项能力都属于一次性 Agent 执行，而不是 Web 呈现。 |
+| 规范化所有包含 Web 与 headless 组合包的元组 | 组合包列表是扩展面；只有精确的安装过程所属元组可以安全分类。 |
+
+## 后果
+
+`dsh run` 提供本地 Agent 任务，而不是浏览器观察、Host API 或 HTTP。需要这些能力的用户选择 `dsh web`。成功时 stderr 为空，完成结果在持久化 flush 后推导，持久化会话仍可供后续工具使用。初始用户消息直接来自用户，因此不携带 ApiProxy `rpcId`。
+
+ApiProxy 载体覆盖保留在 ApiProxy 包中。自定义一次性 profile 可以显式包含 Host 或 Web 组合包；随附 profile 与可识别的安装过程所属元组均不含 Web。

.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.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-web-session-model-selector.md
-2026-07-24-web-session-model-selector.md: 05e923fb3b5df72485ffb8d6ff5aa0104b19a8a0
-2026-07-24-web-session-model-selector.zh.md: c1fd59ada0340a984ddf4a9dcc4c357f9609acb1
+2026-07-24-web-session-model-selector.md: 78017b14a806f8e609a85e340094cd2a349d47e1
+2026-07-24-web-session-model-selector.zh.md: 87a342721f5e47f5bcedfafb578eb6916101d2f5

.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.md

@@ -6,17 +6,17 @@ English | [中文](2026-07-24-web-session-model-selector.zh.md)
 
 ## Problem
 
-The Web conversation displayed and sent through the Host's fixed provider/model route without exposing that route or letting a user change it. The TUI already had a session-local route target, but copying its presentation or hardcoding DeepSeek models in the browser would split model discovery and step-boundary semantics across front doors. A switch made while a response is running also needs one atomic boundary: prompt variables and request routing cannot observe different targets.
+The Web conversation needs a visible, mutable session model selection sourced from the Host. Copying TUI presentation or hardcoding DeepSeek models in the browser would split model discovery and step-boundary semantics across front doors. A switch made while a response is running also needs one atomic boundary: prompt variables and request routing cannot observe different selections.
 
 ## Decision
 
-The Web Host reuses `installAgentLlmTarget` for every created or resumed agent. The provider/model/reasoning target starts from the latest `request/header` when the session has used a model, otherwise from the Host default route. `session.selectModel` changes the session-local mutable target, and prompt assembly captures it with request routing; a switch during a running step therefore applies to the next assembled step. The next consumed target persists through the existing full `request/header` snapshot, while a choice that has not reached a request remains process-local.
+The Web Host installs `ModelSelection` for every created or resumed Agent. The provider/model/reasoning selection comes from the latest `request/header` when the session has used a model, otherwise from `ctx.agentDefaultModel`. `session.selectModel` assigns the session-local selection, and prompt assembly captures it with request routing; a switch during a running step therefore applies to the next assembled step. The next consumed selection persists through the full `request/header` snapshot, while a choice that has not reached a request remains process-local.
 
-The session RPC domain exposes a `session.models` directory and `session.selectModel`. The directory is built dynamically from the LLM registry and grouped by provider; each listed model's exact metadata adds adapter-owned reasoning effort ids, names, descriptions, and optional default. Provider catalogs and exact metadata load concurrently by provider and fail independently, so successful groups remain usable alongside retryable failure records. Catalog membership stays advisory: `session.models.current` is returned independently and can remain routable when absent from every group, but the Host does not synthesize an unlisted row after its provider stops advertising it. The two surfaces answer that state differently on purpose: the TUI still renders the unlisted current model as its own row and marks it current, while Web shows the unset trigger label and asks for a replacement. Web is the surface where a catalog is edited, so a target the user just deleted should read as a decision to make rather than a selection to keep; the TUI, which only picks from what exists, has no such edit to reconcile. The cost is real and accepted — a Web composer showing the unset label can still send to the routed target — and the divergence is deliberate, not a missed migration. Exact resolution decides whether a route and explicit effort are available. Selection uses `resolveCallConfig` to reject unsupported effort ids and materialize an adapter-configured default before updating the target.
+The session RPC domain exposes a `session.models` directory and `session.selectModel`. The directory is built dynamically from the LLM registry and grouped by provider; each listed model's exact metadata adds adapter-owned reasoning effort ids, names, descriptions, and optional default. Provider catalogs and exact metadata load concurrently by provider and fail independently, so successful groups remain usable alongside retryable failure records. Catalog membership stays advisory: `session.models.current` is returned independently and can remain routable when absent from every group, but the Host does not synthesize an unlisted row after its provider stops advertising it. The two surfaces answer that state differently: the TUI renders the unlisted current model as its own row, while Web shows the unset trigger label and asks for a replacement. Web is the surface where a catalog is edited, so an absent row presents a selection decision; the TUI only picks from existing rows. A Web composer showing the unset label can still send with its current routable selection. Exact resolution decides whether a provider/model pair and explicit effort are available. Selection uses `resolveCallConfig` to reject unsupported effort ids and materialize an adapter-configured default before assigning the selection.
 
-The browser `ModelService` owns one `ModelDirectory` per live session. Its snapshot contains the current complete target, grouped catalog, provider failures, operation error, and `idle`/`loading`/`ready`/`selecting`/`error` state. Mounting primes the trigger label and each menu open refreshes the directory. Directory and selection calls share an operation generation so older responses cannot replace a newer result; connection reset discards the process-local projection before restoring the Host target. Failures retain the previous current target and usable groups.
+The browser `ModelService` owns one `ModelDirectory` per live session. Its snapshot contains the current complete `ModelSelection`, grouped catalog, provider failures, operation error, and `idle`/`loading`/`ready`/`selecting`/`error` state. Mounting primes the trigger label and each menu open refreshes the directory. Directory and selection calls share an operation generation so an older response cannot replace a newer result; connection reset discards the process-local projection before restoring the Host selection. Failures retain the previous selection and usable groups.
 
-`@deepseek-ai/dsh-client-ui-conversation` declares the session-scoped single slot `conversation.input.model` as a child of its composer-bar entry. InputBar renders the seat in its trailing controls immediately before the pending indicator and primary button; the seat receives the bar's `locked` owner prop and session scope. `@deepseek-ai/dsh-client-ui-model` occupies that seat and also contributes `/model` over the same directory. Its compact trigger displays the exact catalog model name and effective reasoning label. When the current target is absent from the groups, the trigger instead displays `Select model`, the model list marks no row active, and the Effort row stays absent; choosing a listed model replaces the complete target through the existing selection path. The upward menu otherwise first offers Model and Effort; Model drills into provider groups, while Effort drills into the adapter-ordered levels. The provider-default row appears only when the adapter does not configure a model default.
+`@deepseek-ai/dsh-client-ui-conversation` declares the session-scoped single slot `conversation.input.model` as a child of its composer-bar entry. InputBar renders the seat in its trailing controls immediately before the pending indicator and primary button; the seat receives the bar's `locked` owner prop and session scope. `@deepseek-ai/dsh-client-ui-model` occupies that seat and also contributes `/model` over the same directory. Its compact trigger displays the exact catalog model name and effective reasoning label. When the current selection is absent from the groups, the trigger displays `Select model`, the model list marks no row active, and the Effort row stays absent; choosing a listed model assigns the complete selection through the shared selection path. The upward menu otherwise first offers Model and Effort; Model drills into provider groups, while Effort drills into the adapter-ordered levels. The provider-default row appears only when the adapter does not configure a model default.
 
 The production browser roster is assembled from `apps/cli/config/base.cordis.yml` plus `apps/cli/config/web.cordis.yml`; the model feature is one `dshClient` row rather than a package hardcoded in Web boot code. Its package manifest orders it after the runtime and command feature, while Cordis service injection waits for the conversation slot before registering the composer occupant.
 
@@ -26,18 +26,18 @@ The production browser roster is assembled from `apps/cli/config/base.cordis.yml
 
 **Hardcode the current DeepSeek catalog in the Web client.** This would drift from registered adapters and exclude deployment-owned providers. The LLM registry remains the source of provider and model metadata, including partial lookup failures.
 
-**Keep `High`/`Max` as client-local UI state.** Static DeepSeek labels cannot represent `off`, pi-ai provider vocabularies, adapter defaults, validation, resume, or the next provider request. Exact-model metadata owns the selectable vocabulary, and the session target owns the selected id.
+**Keep `High`/`Max` as client-local UI state.** Static DeepSeek labels cannot represent `off`, pi-ai provider vocabularies, adapter defaults, validation, resume, or the next provider request. Exact-model metadata owns the selectable vocabulary, and the session selection owns the selected id.
 
-**Make the selection a global default.** A global mutation would unexpectedly redirect other open conversations. The target belongs to one live session, while Host configuration remains the default for sessions without a logged request.
+**Use only a global default.** A default mutation would unexpectedly redirect blank conversations. The session selection belongs to one live session, while `ctx.agentDefaultModel` supplies the fallback for sessions without a logged request.
 
-**Reject changes while an agent is running.** The shared atomic target already separates the assembled step from the next selection. Keeping the selector available lets the user prepare the following step without altering the in-flight request.
+**Reject changes while an Agent is running.** The atomic selection snapshot separates the assembled step from the next selection. Keeping the selector available lets the user prepare the following step without altering the in-flight request.
 
 **Persist every click as a new session event.** A choice is not model-visible until prompt assembly consumes it. Persisting unused UI intent would add a durable event that does not reconstruct a model request; the existing `request/header` records the first request that actually uses the route.
 
 ## Consequences
 
-Any Host-backed Web conversation, including a blank session, can switch among dynamically discovered provider groups and adapter-owned reasoning levels without displaying duplicated `provider/model` labels. The current consumed target survives resume and reconnect; catalog names remain presentation-only, while selection and persistence use provider/model/effort ids. A provider catalog or exact-metadata outage degrades only that group. Route changes can reduce provider-side cache reuse, but the selector adds no prompt content and does not disturb the in-flight step. A model without reasoning metadata has no Effort row.
+Any Host-backed Web conversation, including a blank session, can switch among dynamically discovered provider groups and adapter-owned reasoning levels without displaying duplicated `provider/model` labels. The consumed selection survives resume and reconnect; catalog names remain presentation-only, while selection and persistence use provider/model/effort ids. A provider catalog or exact-metadata outage degrades only that group. Provider/model changes can reduce provider-side cache reuse, but the selector adds no prompt content and does not disturb the in-flight step. A model without reasoning metadata has no Effort row.
 
 ## Testing
 
-Host tests pin grouped discovery, catalog and exact-metadata failure isolation, logged effort restoration without stale-row injection, advisory unlisted selection, unsupported effort rejection, default materialization, and next-assembly switching. Client tests pin the shared directory, reconnect restoration, and complete-target submission. Component tests pin dynamic effort labels, descriptions, provider-default exposure, effort submission, and the `Select model` fallback for a removed row. The keyless built-app fixture loads the production model plugin, selects OpenAI's GPT-5 and its Max effort, sends a turn, and verifies that the next generated response reports both ids; the DeepSeek configuration fixture removes the active catalog row and pins the fallback before choosing a replacement.
+Host tests pin grouped discovery, catalog and exact-metadata failure isolation, logged effort restoration without stale-row injection, advisory unlisted selection, unsupported effort rejection, default materialization, and next-assembly switching. Client tests pin the shared directory, reconnect restoration, and complete-selection submission. Component tests pin dynamic effort labels, descriptions, provider-default exposure, effort submission, and the `Select model` fallback for an absent row. The keyless built-app fixture loads the production model plugin, selects OpenAI's GPT-5 and its Max effort, sends a turn, and verifies that the next generated response reports both ids; the DeepSeek configuration fixture omits the active catalog row and pins the fallback before choosing a replacement.

.agents/notes/implemented/feature/2026-07-24-web-session-model-selector.zh.md

@@ -6,17 +6,17 @@ Status: implemented
 
 ## 问题
 
-Web 对话原本通过 Host 固定的提供方与模型路由显示并发送消息，既不呈现该路由，也不允许用户更改。TUI 已经具备会话级的路由目标，但如果照搬其呈现方式，或在浏览器中硬编码 DeepSeek 模型，就会让模型发现逻辑和步骤边界语义分散到不同前门中。响应运行期间发生的切换还需要一个原子边界：提示词变量与请求路由不能观测到不同的目标。
+Web 对话需要一项由 Host 提供、可见且可更改的会话模型选择。如果照搬 TUI 的呈现方式，或在浏览器中硬编码 DeepSeek 模型，就会让模型发现逻辑和步骤边界语义分散到不同前门中。响应运行期间发生的切换还需要一个原子边界：提示词变量与请求路由不能观测到不同的选择。
 
 ## 决策
 
-Web Host 为每个新建或恢复的 agent（智能体）复用 `installAgentLlmTarget`。如果会话已经使用过模型，提供方／模型／推理（reasoning）目标从最新的 `request/header` 开始；否则采用 Host 默认路由。`session.selectModel` 会更改会话级可变目标，提示词组装则将该目标与请求路由一并捕获，因此运行中步骤发生的切换会应用于下一个组装步骤。下一个实际采用的目标通过现有的完整 `request/header` 快照持久化；尚未进入请求的选择则仅保存在当前进程中。
+Web Host 为每个新建或恢复的 Agent 安装 `ModelSelection`。如果会话已经使用过模型，提供方／模型／推理（reasoning）选择来自最新的 `request/header`；否则来自 `ctx.agentDefaultModel`。`session.selectModel` 会赋值会话级选择，提示词组装则将它与请求路由一并捕获，因此运行中步骤发生的切换会应用于下一个组装步骤。下一个实际采用的选择通过完整的 `request/header` 快照持久化；尚未进入请求的选择则仅保存在当前进程中。
 
-会话 RPC 领域公开 `session.models` 模型目录与 `session.selectModel`。该目录从 LLM（大语言模型）注册表动态构建，并按提供方分组；每个已列出模型的精确元数据还会加入由适配器持有的推理强度 ID、名称、说明和可选默认值。各提供方的目录与精确元数据会按提供方并发加载，且彼此独立失败，因此成功加载的分组仍可与可重试的失败记录一同使用。模型是否位于目录仅供参考：`session.models.current` 独立返回，即使不在任何分组中也仍然可以路由，但提供方停止公布该模型后，Host 不会合成未列出行。两个前门有意对这一状态给出不同回答：TUI 仍把未列出的当前模型渲染为独立一行并标记为当前，Web 则显示未设置状态的触发器标签并要求选择替代模型。Web 正是编辑目录所在的前门，因此用户刚刚删除的目标应当读作一个有待作出的决定，而不是一项可以保留的选择；TUI 只在已存在的模型中挑选，没有这类编辑需要调和。这一代价真实存在且已被接受——显示未设置标签的 Web composer 仍会发送到实际路由的目标——这一分歧是有意为之，而不是一处遗漏的迁移。精确解析决定路由与显式推理强度是否可用。选择操作通过 `resolveCallConfig` 拒绝不支持的推理强度 ID，并在更新目标前具体化适配器配置的默认值。
+会话 RPC 领域公开 `session.models` 模型目录与 `session.selectModel`。该目录从 LLM（大语言模型）注册表动态构建，并按提供方分组；每个已列出模型的精确元数据还会加入由适配器持有的推理强度 ID、名称、说明和可选默认值。各提供方的目录与精确元数据会按提供方并发加载，且彼此独立失败，因此成功加载的分组仍可与可重试的失败记录一同使用。模型是否位于目录仅供参考：`session.models.current` 独立返回，即使不在任何分组中也仍然可以路由，但提供方停止公布该模型后，Host 不会合成未列出行。两个前门对这一状态给出不同回答：TUI 把未列出的当前模型渲染为独立一行，Web 则显示未设置状态的触发器标签并要求选择替代模型。Web 是编辑目录的 surface，因此缺席的目录行代表一项待作出的选择；TUI 只从现有行中选择。显示未设置标签的 Web composer 仍可以使用当前可路由选择发送消息。精确解析决定提供方／模型组合与显式推理强度是否可用。选择操作通过 `resolveCallConfig` 拒绝不支持的推理强度 ID，并在赋值该选择前具体化适配器配置的默认值。
 
-浏览器中的 `ModelService` 为每个实时会话持有一个 `ModelDirectory`。其快照包含当前完整目标、分组目录、提供方失败记录、操作错误，以及 `idle`、`loading`、`ready`、`selecting`、`error` 状态。挂载时会预先填充触发器标签，此后每次打开菜单都会刷新目录。目录与选择调用共用操作代次，防止较早响应覆盖较新结果；连接重置会先丢弃当前进程中的投影，再恢复 Host 目标。失败时保留先前的当前目标和可用分组。
+浏览器中的 `ModelService` 为每个实时会话持有一个 `ModelDirectory`。其快照包含当前完整的 `ModelSelection`、分组目录、提供方失败记录、操作错误，以及 `idle`、`loading`、`ready`、`selecting`、`error` 状态。挂载时会预先填充触发器标签，此后每次打开菜单都会刷新目录。目录与选择调用共用操作代次，防止较早响应覆盖较新结果；连接重置会先丢弃当前进程中的投影，再恢复 Host 选择。失败时保留先前的选择和可用分组。
 
-`@deepseek-ai/dsh-client-ui-conversation` 将会话作用域的单实例 slot `conversation.input.model` 声明为其输入栏 entry 的子 slot。InputBar 在尾部控件区将该 seat 渲染于 pending 指示器与主按钮之前；该 seat 接收输入栏的 `locked` owner prop 与会话作用域。`@deepseek-ai/dsh-client-ui-model` 占用该 seat，并在同一目录上提供 `/model`。其紧凑型触发器显示目录中精确模型的名称与生效的推理强度标签。当前目标不在分组中时，触发器改为显示 `Select model`，模型列表不标记任何活动行，Effort 行也保持隐藏；选择一个已列出的模型，会通过现有选择路径替换完整目标。除此情形外，向上展开的菜单会首先提供 Model 与 Effort；Model 可深入提供方分组，Effort 可深入适配器排序的级别。仅当适配器没有配置模型默认值时，才显示提供方默认值行。
+`@deepseek-ai/dsh-client-ui-conversation` 将会话作用域的单实例 slot `conversation.input.model` 声明为其输入栏 entry 的子 slot。InputBar 在尾部控件区将该 seat 渲染于 pending 指示器与主按钮之前；该 seat 接收输入栏的 `locked` owner prop 与会话作用域。`@deepseek-ai/dsh-client-ui-model` 占用该 seat，并在同一目录上提供 `/model`。其紧凑型触发器显示目录中精确模型的名称与生效的推理强度标签。当前选择不在分组中时，触发器显示 `Select model`，模型列表不标记任何活动行，Effort 行也保持隐藏；选择一个已列出的模型，会通过共享的选择路径赋值完整选择。除此情形外，向上展开的菜单会首先提供 Model 与 Effort；Model 可深入提供方分组，Effort 可深入适配器排序的级别。仅当适配器没有配置模型默认值时，才显示提供方默认值行。
 
 生产环境的浏览器名册由 `apps/cli/config/base.cordis.yml` 与 `apps/cli/config/web.cordis.yml` 共同组装；模型功能对应其中一行 `dshClient` 配置项，而不是 Web boot 代码中硬编码的包。其包 manifest（元数据清单）将加载顺序置于运行时与命令功能之后；Cordis 服务注入则等待 conversation slot 可用，再注册 composer 占用方。
 
@@ -26,18 +26,18 @@ Web Host 为每个新建或恢复的 agent（智能体）复用 `installAgentLlm
 
 **在 Web 客户端中硬编码当前 DeepSeek 目录。** 该目录会与已注册适配器发生偏离，也会排除部署自有的提供方。LLM 注册表继续作为提供方与模型元数据的真源，也负责呈现部分查询失败。
 
-**将 `High`／`Max` 保留为客户端本地 UI 状态。** 静态 DeepSeek 标签无法覆盖 `off`、pi-ai 的提供方词汇、适配器默认值与校验，也不能参与恢复或下一次提供方请求。精确模型元数据拥有可选词汇，会话目标则拥有已选择的 ID。
+**将 `High`／`Max` 保留为客户端本地 UI 状态。** 静态 DeepSeek 标签无法覆盖 `off`、pi-ai 的提供方词汇、适配器默认值与校验，也不能参与恢复或下一次提供方请求。精确模型元数据拥有可选词汇，会话选择则拥有已选择的 ID。
 
-**将选择设为全局默认值。** 全局变更会意外改道其他已打开的对话。目标仅属于一个实时会话；对于没有已记录请求的会话，Host 配置仍是默认值。
+**只使用全局默认值。** 默认值变更会意外改道空白对话。会话选择仅属于一个实时会话；对于没有已记录请求的会话，`ctx.agentDefaultModel` 提供回退值。
 
-**agent 运行期间拒绝更改。** 共享原子目标已经将当前组装步骤与下一次选择分离。保持选择器可用，可以让用户为下一个步骤预先选择模型，而不会改变正在执行的请求。
+**Agent 运行期间拒绝更改。** 原子选择快照将当前组装步骤与下一次选择分离。保持选择器可用，可以让用户为下一个步骤预先选择模型，而不会改变正在执行的请求。
 
 **将每次点击作为新的会话事件持久化。** 只有提示词组装采用某项选择后，该选择才对模型可见。持久化尚未使用的 UI 意图，会增加一个无法重建模型请求的持久事件；现有 `request/header` 会记录首次实际使用该路由的请求。
 
 ## 影响
 
-任何由 Host 支撑的 Web 对话（包括空白会话）都可以在动态发现的提供方分组和适配器持有的推理级别之间切换，而无需显示重复的 `provider/model` 标签。当前实际采用的目标会在恢复和重连后保留；目录名称仅用于呈现，而选择和持久化使用提供方／模型／推理强度 ID。某个提供方的目录或精确元数据不可用时，只有相应分组会降级。路由变更可能降低提供方侧的缓存复用率，但选择器不会添加任何提示词内容，也不会干扰正在执行的步骤。没有推理元数据的模型不显示 Effort 行。
+任何由 Host 支撑的 Web 对话（包括空白会话）都可以在动态发现的提供方分组和适配器持有的推理级别之间切换，而无需显示重复的 `provider/model` 标签。实际采用的选择会在恢复和重连后保留；目录名称仅用于呈现，而选择和持久化使用提供方／模型／推理强度 ID。某个提供方的目录或精确元数据不可用时，只有相应分组会降级。提供方／模型变更可能降低提供方侧的缓存复用率，但选择器不会添加任何提示词内容，也不会干扰正在执行的步骤。没有推理元数据的模型不显示 Effort 行。
 
 ## 测试
 
-Host 测试固定分组发现、目录与精确元数据失败隔离、已记录推理强度恢复且不注入陈旧行、不受目录约束的未列出模型选择、不支持的推理强度拒绝、默认值具体化，以及切换仅影响下一次组装。客户端测试固定共享目录、重连恢复与完整目标提交。组件测试固定动态推理强度标签、说明、提供方默认值展示、推理强度提交，以及已删除模型行的 `Select model` 回退。无密钥 built-app fixture（测试前置数据）加载生产模型插件，选择 OpenAI 的 GPT-5 及其 Max 推理强度，发起一个轮次，并验证下一条生成的响应会报告两个 ID；DeepSeek 配置 fixture 会删除活动目录行，在选择替代模型之前固定该回退。
+Host 测试固定分组发现、目录与精确元数据失败隔离、已记录推理强度恢复且不注入陈旧行、不受目录约束的未列出模型选择、不支持的推理强度拒绝、默认值具体化，以及切换仅影响下一次组装。客户端测试固定共享目录、重连恢复与完整选择提交。组件测试固定动态推理强度标签、说明、提供方默认值展示、推理强度提交，以及缺席模型行的 `Select model` 回退。无密钥 built-app fixture（测试前置数据）加载生产模型插件，选择 OpenAI 的 GPT-5 及其 Max 推理强度，发起一个轮次，并验证下一条生成的响应会报告两个 ID；DeepSeek 配置 fixture 会省略活动目录行，在选择替代模型之前固定该回退。

.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.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-07-default-model-follows-the-picker.md
-2026-08-07-default-model-follows-the-picker.md: d20f0ab8b8c8bd19f596e6ef73f0a58d96c24d38
-2026-08-07-default-model-follows-the-picker.zh.md: fd27a0ce67a8e7f41d1a6b397039014f0ddb4854
+2026-08-07-default-model-follows-the-picker.md: ed7e7a424d2cacadea890506fd9150ffdf7a993c
+2026-08-07-default-model-follows-the-picker.zh.md: 523c6f917dedf21c726ce5631226ba545126c757

.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.md

@@ -6,38 +6,42 @@ English | [中文](2026-08-07-default-model-follows-the-picker.zh.md)
 
 ## Problem
 
-The route a new session started from was frozen into the gateway's composition entry (`api-gateway` in the web-app bundle patch). Switching models in a conversation reached that conversation only: the next session went back to the shipped default, and the only way to change it was to hand-edit a `cordis.yml` row and restart. There was no user-settings tier between the composition and the per-session choice.
+A session model picker and a deployment default are two layers of the same preference. If the picker affects only its addressed session, the next blank session can select a different model with no user-facing way to align the default. If the default lives inside a Host gateway, direct Agent front doors cannot share it without depending on Host or duplicating state.
+
+Reasoning effort makes the persistence shape significant: a model selection without an effort must clear a stored effort, or the next Agent may apply an effort that its selected model does not accept.
 
 ## Decision
 
-`ApiProxyService` registers its `{provider, model, reasoningEffort?}` slice as the `api-gateway` settings section: the composition entry is the `base` layer and `settings.yaml` layers the user's choice over it. `workspaceRoot` stays outside the section — a launcher fact, not a preference. `reasoningEffort` is the mirror case: it lives in the section but NOT in the plugin config, because the seam merges the user layer over the composition entry per field and an absent key cannot override a present one. A composition-set effort would therefore survive every later switch to a model without one — precisely the stranding the wholesale `replace` exists to prevent. Effort is a per-model fact anyway; a deployment default for it belongs on the adapter profile, which resolves per model.
+`AgentDefaultModelService` provides `ctx.agentDefaultModel` and registers `{provider, model, reasoningEffort?}` as the `agent-default-model` Settings section. Its `{provider, model}` composition entry is the base layer and `settings.yaml` supplies the user layer. The service is front-door-neutral, so direct creation and ApiProxy-backed creation share one default ([headless direct core front door](../architecture/2026-08-09-headless-direct-core-front-door.md)). `workspaceRoot` remains ApiProxy config because it is a Host launcher fact rather than model state.
 
-`session.selectModel` records an accepted switch as the new default. There is no separate gesture: switching models in the composer IS how the default is chosen. The write is `replace`, not `update` — switching to a model with no reasoning effort has to clear a stored one, and a merged patch would strand it for the next session to fail on. A storage failure is logged without undoing the switch, which already applies to its own session, and a deployment with no settings provider keeps the entry with the switch staying process-local.
+`reasoningEffort` belongs to the Settings section but not to the plugin config. Settings layers merge by field, so a configured effort would survive a user selection that omits it. `saveSelection()` instead writes the complete user section; absence therefore clears a stored effort. A deployment-wide effort default belongs to the adapter profile, which resolves it per model.
 
-`ApiProxyDefaults` carries `defaultTarget()` and `persistDefaultTarget()` closures instead of flat `provider`/`model` fields, so `createApiProxy` needs no knowledge of the settings seam.
+`session.selectModel` applies an accepted `ModelSelection` to its session and calls `saveDefaultModelSelection()` for the shared Agent default. A storage failure is logged without undoing the session selection. A deployment with no settings provider retains the composition entry and keeps the accepted selection only in that session.
 
-`targetFor` resolves its tiers on **every** read rather than seeding a ref once: an explicit selection in this process, else the session's own latest logged `request/header`, else the live default. Both directions depend on the re-read. A session that has run a turn derives from its log forever after, so changing the default never retargets it. A session still blank starts from a default saved after it was created — which matters because New Session reuses a blank session rather than minting another, so a creation-time seed would show the superseded model in exactly the flow the feature exists for.
+`ApiProxyDefaults` carries `defaultModelSelection()` and `saveDefaultModelSelection()` closures, so `createApiProxy` has no dependency on the Settings seam. `ApiProxyService` wires them to `ctx.agentDefaultModel.currentSelection()` and `ctx.agentDefaultModel.saveSelection()`.
 
-The stored route is not validated against the registry. A default naming a route the Models page has since removed still reaches `session.models` as `current`, matching no advertised group — which is what makes the composer seat's existing fallback prompt for a selection instead of naming a model the deployment cannot reach.
+`selectionFor(agent)` resolves its tiers on every read: a process-local session selection, otherwise the session's latest logged `request/header`, otherwise the live Agent default. A session with a logged request remains bound to that durable selection. A blank session observes the current default even when it was created before the preference was saved; this matches the New Session surface, which may reuse a blank session.
 
-## Consequences
+The stored selection does not require catalog membership. A provider route may serve a model omitted from its advisory catalog. `session.models` therefore reports the stored selection independently of advertised groups and separately reports whether an adapter serves its provider.
 
-`ApiProxyDefaults` changed shape, updating ~40 test construction sites. `host.describe` now reports the live default rather than a captured one, which is what it always meant. `settings.yaml` gains an `api-gateway:` section the moment a user switches models; the `api-gateway` namespace is deliberately NOT added to the gateway's exposed-namespace allowlist, so the Settings page neither reads nor writes it — the model picker is its editor.
+## Consequences
 
-## Follow-up: blocking a session that cannot send
+`host.describe` reports the live Agent default. A successful model switch stores an `agent-default-model:` section in `settings.yaml`. The gateway does not expose that namespace through its Settings-page allowlist; the model picker is its editor.
 
-A default naming a route the Models page has since removed leaves the composer saying "Select model" while the input still accepts a message, which then fails inside the adapter mid-turn. Two changes close it.
+## A session that cannot send
 
-The Host refuses. `session.prompt` checks whether an adapter serves the session's route and answers `model-unavailable` before opening a turn. This is the enforcement boundary: a client that disables its composer is an affordance, and the method stays callable regardless.
+`session.prompt` refuses with `model-unavailable` before opening a turn when no adapter serves the session's selected provider. This method is the enforcement boundary; a disabled composer is only a client affordance.
 
-The composer goes inert. `session.models` reports `routable`, and ui-model pushes a block through the new `ctx.conversation.blocks` registry; the bar renders the same disabled textarea it already renders without a workspace, with the blocker's own localized reason as the placeholder — except the model seat, which a block deliberately leaves live, because choosing a model is how the user clears it. The push direction is forced — ui-model already depends on ui-conversation, so ui-conversation cannot read it back.
+`session.models` reports `routable`. The ui-model plugin projects an unroutable selection through `ctx.conversation.blocks`, and the composer becomes inert while leaving the model seat available. An unknown client-side routability state, including an initial or failed catalog load, does not block input.
 
-The gate is `routable`, NOT "the current target matches no advertised group". Catalog membership is advisory by design: a route serving a model it stopped advertising is absent from the groups yet perfectly usable, and blocking there would break a supported configuration (a narrowed `models` list over a live route). `routable` is also three-valued on the client — `null` before the first load or after a failed one never blocks, so a slow or unreachable Host cannot lock a working composer.
+Routability is distinct from catalog membership. A live provider route can serve an unadvertised model, so absence from catalog groups does not imply that the session is unusable.
 
 ## Alternatives considered
 
-- **Falling back to the composition entry when the stored route is unregistered.** Rejected: the composer would then name the shipped DeepSeek model instead of prompting, which is both a silent switch to a provider the user did not pick and the opposite of the requested behavior.
-- **Validating and clearing a stale default.** Rejected: catalog membership is advisory by design (`buildModelCatalog` documents it), so an adapter may serve a model its own catalog stopped advertising; self-healing would break that deliberate case.
-- **A `settings.update` merge patch.** Rejected: it cannot clear `reasoningEffort`, so a switch from a reasoning model to a plain one leaves an effort the next session fails on.
-- **Persisting only from blank sessions.** Rejected: the most informative switch is the one made mid-conversation after seeing a model underperform, and that one would never be saved.
-- **A separate "set as default" affordance.** Rejected for now: it adds a second gesture for what every comparable product infers from the switch itself. The cost is that a temporary switch in an old session also moves the default.
+| Alternative | Contract mismatch |
+|---|---|
+| Fall back to the composition entry when the stored provider is unavailable | The product silently switches away from the user's selection. |
+| Validate the stored selection against catalog membership | Catalogs are advisory and may omit requestable models. |
+| Save with a merge patch | An omitted `reasoningEffort` cannot clear the stored field. |
+| Save only selections made in blank sessions | An informed mid-conversation selection never becomes the deployment default. |
+| Add a separate “set as default” gesture | The session picker and future-session preference can diverge despite representing the same user choice. |

.agents/notes/implemented/feature/2026-08-07-default-model-follows-the-picker.zh.md

@@ -6,38 +6,42 @@ Status: implemented
 
 ## 问题
 
-新会话的起始路由被冻结在网关的组合条目里（web-app bundle patch 中的 `api-gateway` 行）。在一段对话里切换模型只影响这段对话：下一个会话又回到出厂默认，而要改这个默认值，唯一的办法是手工编辑一条 `cordis.yml` 行并重启。组合层与每会话选择之间没有用户设置这一层。
+会话模型选择器与部署默认值是同一项偏好的两个层次。如果选择器只影响其所在会话，下一个空白会话可能选择不同模型，用户却没有途径使默认值与选择器一致。如果默认值位于 Host 网关内部，直接创建 Agent 的前门只有依赖 Host 或复制状态才能共享它。
+
+推理强度使持久化形态成为约定的一部分：不含强度的模型选择必须清除已存强度，否则下一个 Agent 可能会采用所选模型不接受的强度。
 
 ## 决定
 
-`ApiProxyService` 把自己的 `{provider, model, reasoningEffort?}` 切片注册为 `api-gateway` 设置段：组合条目是 `base` 层，`settings.yaml` 把用户的选择叠加其上。`workspaceRoot` 留在段外——它是启动器事实，不是偏好。`reasoningEffort` 则是相反的情形：它在段里、但**不在**插件配置里，因为 seam 是按字段把用户层合并到组合条目之上的，缺席的键覆盖不了存在的键。组合层设的推理等级因此会在此后每一次切到不支持推理的模型时继续存活——正是整段 `replace` 想要杜绝的那种滞留。何况推理等级本就是按模型的事实，它的部署级默认值属于适配器 profile，那里是按模型解析的。
+`AgentDefaultModelService` 提供 `ctx.agentDefaultModel`，并把 `{provider, model, reasoningEffort?}` 注册为 `agent-default-model` Settings 分节。其 `{provider, model}` 组合条目是 base 层，`settings.yaml` 提供用户层。该服务不偏向特定前门，因此直接创建与 ApiProxy 支撑的创建共享同一个默认值（[headless 直接 core 前门](../architecture/2026-08-09-headless-direct-core-front-door.md)）。`workspaceRoot` 仍是 ApiProxy 配置，因为它是 Host 启动器事实，而不是模型状态。
 
-`session.selectModel` 把被接受的切换记录为新的默认值。没有另一个单独的手势：在输入框切模型**就是**选定默认值的方式。写入用 `replace` 而非 `update`——切到一个不支持推理的模型必须清掉已存的等级，而合并补丁会把它滞留下来，让下一个会话在它上面失败。存储失败只记日志，不撤销这次切换（它对自己所在的会话已经生效）；没有设置提供方的部署保留组合条目，切换只停留在进程内。
+`reasoningEffort` 属于 Settings 分节，但不属于插件配置。Settings 层按字段合并，因此已配置的强度会在用户选择省略它时继续存在。`saveSelection()` 写入完整的用户分节；缺席值由此清除已存强度。部署级强度默认值属于适配器 profile，并由它按模型解析。
 
-`ApiProxyDefaults` 改为携带 `defaultTarget()` 与 `persistDefaultTarget()` 两个闭包，而不是扁平的 `provider`／`model` 字段，这样 `createApiProxy` 不需要知道设置 seam 的存在。
+`session.selectModel` 把被接受的 `ModelSelection` 应用于所在会话，并调用 `saveDefaultModelSelection()` 保存共享的 Agent 默认值。存储失败只记日志，不撤销会话选择。没有 Settings 提供方的部署保留组合条目，被接受的选择只停留在该会话中。
 
-`targetFor` 在**每一次**读取时解析各级，而不是只在创建时种一次 ref：本进程内的显式选择，其次是该会话自己最新记录的 `request/header`，最后才是活的默认值。两个方向都依赖这次重新读取。已经跑过一个轮次的会话此后永远从自己的日志推导，改默认值不会重定向它；而仍然空白的会话会用上它创建之后才保存的默认值——这一点很关键，因为新建会话是复用空白会话而不是再开一个，创建时种下的值恰好会在这个功能存在的意义所在的流程里显示已被取代的模型。
+`ApiProxyDefaults` 携带 `defaultModelSelection()` 与 `saveDefaultModelSelection()` 闭包，因此 `createApiProxy` 不依赖 Settings seam。`ApiProxyService` 将它们分别接到 `ctx.agentDefaultModel.currentSelection()` 与 `ctx.agentDefaultModel.saveSelection()`。
 
-存下来的路由不做注册表校验。默认值指向一条模型页已经删除的路由时，它照样作为 `current` 送到 `session.models`，匹配不到任何已公布的分组——而这正是让输入框选择器已有的回退提示重新选择、而不是显示一个部署根本够不着的模型的原因。
+`selectionFor(agent)` 每次读取时都解析各层：先取进程内的会话选择，其次取会话最新记录的 `request/header`，最后取当前 Agent 默认值。已有请求日志的会话持续绑定到该持久选择。空白会话即使创建于偏好保存之前，也会观察到当前默认值；这与 New Session surface 可能复用空白会话的行为一致。
 
-## 影响
+已存选择不要求属于目录。某条提供方路由可能服务其咨询性目录未列出的模型。因此，`session.models` 会在已公布分组之外单独报告已存选择，并另行报告适配器是否服务其提供方。
 
-`ApiProxyDefaults` 形状变了，约 40 处测试构造点随之更新。`host.describe` 现在报告的是活的默认值而非捕获的快照，这本就是它一直想表达的含义。用户一旦切换模型，`settings.yaml` 就会多出一个 `api-gateway:` 段；`api-gateway` 这个 namespace 刻意**没有**加进网关的暴露名单，因此设置页既不读也不写它——模型选择器就是它的编辑器。
+## 影响
 
-## 后续：让发不出消息的会话禁止输入
+`host.describe` 报告当前 Agent 默认值。模型切换成功后，`settings.yaml` 中会存有一个 `agent-default-model:` 分节。网关不通过 Settings 页 allowlist 暴露该 namespace；模型选择器是它的编辑器。
 
-默认值指向一条模型页已删除的路由时，编辑器显示「选择模型」，输入框却仍接受消息，然后该轮次会在适配器内部进行到一半时失败。两处改动关掉这个口子。
+## 无法发送消息的会话
 
-宿主拒绝。`session.prompt` 检查是否有适配器服务该会话的路由，在开启轮次之前就以 `model-unavailable` 应答。这是执行边界：客户端禁用编辑器只是提示性设计，这个方法始终可被调用。
+当没有适配器服务会话所选提供方时，`session.prompt` 会在开启轮次前以 `model-unavailable` 拒绝。这一方法是执行边界；禁用 composer 只是客户端提供的便利。
 
-编辑器停止接受消息。`session.models` 报告 `routable`，ui-model 经新的 `ctx.conversation.blocks` 注册表推送一个块；输入栏渲染的仍是它在没有工作区时就会渲染的那个禁用 textarea，只是把阻断方自己的本地化理由作为 placeholder——唯独模型 seat 被块刻意保留可用，因为用户正是靠选模型来解除它。推送方向是被迫的——ui-model 本就依赖 ui-conversation，因此 ui-conversation 读不回去。
+`session.models` 报告 `routable`。ui-model 插件通过 `ctx.conversation.blocks` 投影不可路由的选择，composer 随之变为不可操作，同时保留模型 seat 可用。客户端不知道是否可路由时不会阻断输入，包括目录首次加载或加载失败的情况。
 
-闸门是 `routable`，**不是**「当前目标匹配不到任何已公布分组」。目录成员关系按设计只作参考：一条仍在服务、只是不再公布该模型的路由不在分组里，却完全可用，在那里阻断会破坏一种受支持的配置（对一条活着的路由收窄 `models` 列表）。`routable` 在客户端还是三值的——首次加载之前或加载失败之后的 `null` 绝不阻断，因此慢的或够不着的宿主锁不死一个本来能用的编辑器。
+可路由性与目录成员关系不同。仍在服务的提供方路由可以处理未公布的模型，因此不在目录分组中并不代表会话不可用。
 
 ## 考虑过的替代方案
 
-- **存下来的路由未注册时回落到组合条目。** 否决：那样输入框会显示出厂的 DeepSeek 模型而不是提示选择，既是静默切到用户没选的提供方，也与要求的行为正好相反。
-- **校验并清空陈旧的默认值。** 否决：目录成员关系按设计只作参考（`buildModelCatalog` 有注释说明），适配器可以服务一个自己目录已不再公布的模型；自动修复会破坏这个刻意保留的情形。
-- **用 `settings.update` 合并补丁。** 否决：它清不掉 `reasoningEffort`，于是从推理模型切到普通模型会留下一个等级，让下一个会话在它上面失败。
-- **只在空白会话里持久化。** 否决：最有信息量的切换恰恰是对话到一半发现模型不行时做的那一次，而它永远存不下来。
-- **单独做一个「设为默认」的入口。** 目前否决：同类产品都从切换本身推断的事情，它却要多一个手势。代价是在老会话里的临时切换也会移动默认值。
+| 替代方案 | 约定不匹配之处 |
+|---|---|
+| 已存提供方不可用时回落到组合条目 | 产品会静默切离用户选择。 |
+| 根据目录成员关系校验已存选择 | 目录仅供参考，可能省略仍可请求的模型。 |
+| 使用合并 patch 保存 | 省略的 `reasoningEffort` 无法清除已存字段。 |
+| 只保存空白会话中的选择 | 对话期间知情作出的选择不会成为部署默认值。 |
+| 增加单独的「设为默认」手势 | 会话选择器与未来会话偏好虽然代表同一用户选择，却仍可能分歧。 |

.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.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-08-dsh-run-headless-command.md
-2026-08-08-dsh-run-headless-command.md: d1cc0573d1d94bb7b30e98aa685d2b7d89878a99
-2026-08-08-dsh-run-headless-command.zh.md: afb18fea6ac46064b6720d3bb68d7bc53a81d3f2
+2026-08-08-dsh-run-headless-command.md: 566eeb5b2a09a0d07d72a68e4a5f449d2822e708
+2026-08-08-dsh-run-headless-command.zh.md: 177410e783a37026940829da5f81343ddc61cb29

.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.md

@@ -6,36 +6,36 @@ English | [中文](2026-08-08-dsh-run-headless-command.zh.md)
 
 ## Problem
 
-The product launcher attached optional task text to its generic profile boot: `dsh --profile headless "task"`. That made one argv shape mean either a long-lived profile or a one-shot run according to a row discovered only after composition. The parser's `ProfileInvocation` carried optional task state, help presented a profile implementation detail as the user command, and a custom profile could accept a task only through the same overloaded root.
+Generic profile boot and one-shot task execution have different lifecycle contracts. A root grammar that accepts optional task text makes one argv shape mean either a long-lived process or a terminating task according to a plugin row discovered only after composition. It also exposes a profile implementation detail as the primary user command and gives custom profiles no explicit one-shot entry.
 
-The former `dsh -p` spelling was already absent from the parser, so restoring it or detecting it specially would add compatibility machinery to a pre-release interface. A separate application-file proposal also used the `run` verb, leaving two incompatible owners for one top-level command.
+The `run` verb must have one top-level meaning. Sharing it with application-file execution or inferring its meaning from positional shape creates the same ambiguity.
 
 ## Decision
 
-One-shot execution owns an explicit grammar:
+One-shot execution owns this grammar:
 
 ```text
 dsh run [--profile <name>] [--patch <path>...] <task...>
 ```
 
-`--profile` defaults to `headless` and remains available for custom one-shot compositions. `--patch` is repeatable and occupies the existing overlay layer. Commander joins the variadic task arguments with spaces and rejects a missing or blank task before boot.
+`--profile` defaults to `headless` and supports custom one-shot compositions. `--patch` is repeatable and occupies the normal overlay layer. Commander joins the variadic task arguments with spaces and rejects a missing or blank task before boot.
 
-The [profile plugin bundle decision](../architecture/2026-08-05-profile-plugin-bundles.md) owns the composition selected by this grammar.
+`RunInvocation` is a distinct `DshInvocation` member. The generic profile invocation carries no task state and accepts no positional arguments. Both dispatch paths use `runProfile`: profile boot omits `task`, while `run` supplies it. A one-shot profile without `headless-runner` fails through the composed-row check, and profile boot containing that row without a task points to `dsh run --profile <name> "<task>"`.
 
-`RunInvocation` is a separate `DshInvocation` member. The generic profile invocation no longer carries task text, and its root command accepts no positional arguments. Both dispatch paths call the existing deep `runProfile` module: `profile` omits `task`, while `run` supplies it. There is no shallow `run.ts` forwarding module and no alias, warning, or custom detector for former spellings; they fail through the ordinary Commander grammar. A one-shot profile without `headless-runner` still fails through the existing composed-row check, while booting a profile that contains that row without a task points to `dsh run --profile <name> "<task>"`.
+The [profile plugin bundle decision](../architecture/2026-08-05-profile-plugin-bundles.md) owns composition. [Headless is a direct core front door](../architecture/2026-08-09-headless-direct-core-front-door.md) owns the execution contract: one fresh persisted Session, final assistant text on stdout, completed/non-completed exit mapping, empty stderr on success, no listening port, and bounded signal shutdown after Agent quiescence and Session flush.
 
-The `run` verb belongs to one-shot task execution. Launching an application file must choose another command name; two top-level meanings selected by positional shape would recreate the ambiguity this command removes.
-
-The runner's user-visible contract stays the same: a fresh persisted session, browser observation URL on stderr, final assistant text on stdout, completed/non-completed exit mapping, and bounded signal shutdown. The product-level keyless acceptance exposed that the in-process mux consumer could lag the same-process `agent/status: idle` notification and derive output before reading the final frames. The idle notification now captures the authoritative final session sequence, and the runner waits until the ordered mux reaches that boundary (or the stream ends) before deriving text and exit reason. This enforces the existing idle-to-idle contract without adding a wire field or a timing delay.
+The `run` verb belongs only to one-shot task execution. Application-file launch requires a distinct command name.
 
 ## Alternatives considered
 
-- **Keep task text on `dsh --profile`.** Rejected because profile boot and one-shot execution remain one grammar whose meaning depends on a late composition check.
-- **Preserve `dsh -p` or the positional profile form as aliases.** Rejected under the pre-release stance: compatibility branches would outlive the interface they were meant to retire.
-- **Make `--profile headless` mandatory under `run`.** Rejected because the shipped one-shot surface should have the shortest canonical spelling, while optional `--profile` preserves plugin-defined one-shot compositions.
-- **Give `dsh run` to application-file launch and choose another headless verb.** Rejected because `run` describes executing a task through the harness; application-file ownership would make the product's primary one-shot command less direct and collide with custom one-shot profiles.
-- **Add `apps/cli/src/run.ts`.** Rejected because it would only forward to `runProfile`, splitting command ownership without hiding any complexity.
+| Alternative | Contract mismatch |
+|---|---|
+| Put task text on root profile boot | Lifecycle meaning depends on a plugin row discovered after parsing. |
+| Accept root aliases such as `dsh -p` | The pre-release grammar acquires compatibility branches with no current command ownership. |
+| Require `--profile headless` | The shipped one-shot surface loses its shortest canonical spelling. |
+| Use `dsh run` for application files | One top-level verb has two meanings and the primary task command becomes indirect. |
+| Add a shallow `apps/cli/src/run.ts` forwarder | Command ownership splits without hiding any complexity. |
 
 ## Consequences
 
-This is an intentional breaking CLI change. Documentation, help, parser tests, built-bin acceptance, PTY shutdown coverage, and the assembled keyless snapshot use `dsh run`. Existing custom one-shot profiles keep working through `--profile`; long-lived profiles and config dumps retain their existing root grammar. The competing application-file command must be renamed and rebased separately rather than sharing or overloading `run`.
+Help, documentation, parser tests, built-bin acceptance, PTY shutdown coverage, and the assembled keyless snapshot use `dsh run`. Custom one-shot profiles use `--profile`; long-lived profile boot and config dumps keep the root profile grammar. Application-file execution is a separate command concern.

.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.zh.md

@@ -6,36 +6,36 @@ Status: implemented
 
 ## 问题
 
-产品启动器过去把可选任务文本挂在通用 profile 启动命令上：`dsh --profile headless "task"`。于是，同一种 argv 形态会表示常驻 profile 或一次性运行，具体含义取决于组合完成后才发现的配置行。解析器的 `ProfileInvocation` 携带可选任务状态，帮助信息把 profile 的实现细节呈现为用户命令，自定义 profile 也只能通过同一个过载的根命令接收任务。
+通用 profile 启动与一次性任务执行具有不同的生命周期约定。若根语法接受可选任务文本，同一种 argv 形态会表示常驻进程或终止式任务，具体含义取决于组合完成后才发现的插件配置行。它还会把 profile 实现细节暴露成主要用户命令，并使自定义 profile 缺少明确的一次性入口。
 
-解析器中已经没有原来的 `dsh -p` 写法，因此恢复该写法或加入特殊检测，会给预发布接口增加兼容机制。另一个应用文件提案也使用 `run` 动词，使同一个顶层命令同时归属两个互不兼容的功能。
+`run` 动词必须只有一种顶层含义。与应用文件执行共用该动词，或根据位置参数形态推断含义，都会产生相同的歧义。
 
 ## 决策
 
-一次性执行采用明确语法：
+一次性执行采用以下语法：
 
 ```text
 dsh run [--profile <name>] [--patch <path>...] <task...>
 ```
 
-`--profile` 默认为 `headless`，同时保留对自定义一次性组合的支持。`--patch` 可重复使用，并沿用既有 overlay 层的位置。Commander 用空格拼接可变数量的任务参数，并在启动前拒绝缺失或空白任务。
+`--profile` 默认为 `headless`，并支持自定义一次性组合。`--patch` 可重复使用，并占据正常的 overlay 层。Commander 用空格拼接可变数量的任务参数，并在启动前拒绝缺失或空白任务。
 
-[profile 插件组合包决策](../architecture/2026-08-05-profile-plugin-bundles.md)负责该语法所选择的组合。
+`RunInvocation` 是单独的 `DshInvocation` 成员。通用 profile 调用不携带任务状态，也不接受位置参数。两条分派路径都使用 `runProfile`：profile 启动省略 `task`，而 `run` 提供该字段。缺少 `headless-runner` 的一次性 profile 会触发组合行检查；如果启动的 profile 包含该行却未提供任务，错误会指向 `dsh run --profile <name> "<task>"`。
 
-`RunInvocation` 是单独的 `DshInvocation` 成员。通用 profile 调用不再携带任务文本，其根命令也不接受位置参数。两条分派路径都调用已有的深层 `runProfile` 模块：`profile` 省略 `task`，`run` 则提供该字段。实现中没有只负责转发的浅层 `run.ts` 模块，也没有面向旧写法的别名、警告或自定义检测器；旧写法会按普通 Commander 语法失败。缺少 `headless-runner` 的一次性 profile 仍会触发既有的组合行检查；如果启动的 profile 包含该行却未提供任务，错误会指向 `dsh run --profile <name> "<task>"`。
+[profile 插件组合包决策](../architecture/2026-08-05-profile-plugin-bundles.md)负责组合。[Headless 是直接 core 前门](../architecture/2026-08-09-headless-direct-core-front-door.md)负责执行约定：一个新的持久化会话、stdout 上的最终 assistant 文本、completed／非 completed 的退出状态映射、成功时为空的 stderr、无监听端口，以及 Agent 完全停稳且会话 flush 后的有界信号关闭。
 
-`run` 动词只负责一次性任务执行。应用文件启动必须选择其他命令名；如果让两个顶层含义由位置参数形态决定，就会重新引入本命令消除的歧义。
-
-运行器面向用户的约定保持不变：创建新的持久化会话，在 stderr 打印浏览器观察 URL，在 stdout 打印最终 assistant 文本，将完成／未完成映射为退出状态，并执行有界的信号关闭。产品级无密钥验收用例发现，进程内 mux 消费方可能落后于同进程的 `agent/status: idle` 通知，在读到最终帧之前就生成输出。idle 通知现在会捕获权威的会话最终事件序号，运行器则等待有序 mux 到达该边界（或流结束），再生成文本和退出原因。这一机制在不增加 wire 字段或定时延迟的前提下，落实了既有的 idle-to-idle 约定。
+`run` 动词只负责一次性任务执行。应用文件启动需要不同的命令名。
 
 ## 考虑过的替代方案
 
-- **把任务文本保留在 `dsh --profile` 上。** 不予采纳：profile 启动和一次性执行仍共用同一套语法，其含义取决于较晚发生的组合检查。
-- **保留 `dsh -p` 或位置参数 profile 形式作为别名。** 不予采纳：根据预发布立场，这些兼容分支会比本应退役的接口存续更久。
-- **要求在 `run` 下必须指定 `--profile headless`。** 不予采纳：已交付的一次性接口应采用最短的规范写法，同时用可选的 `--profile` 保留插件定义的一次性组合。
-- **把 `dsh run` 交给应用文件启动，并为 headless 选择另一个动词。** 不予采纳：`run` 描述的是通过 harness 执行任务；若归应用文件所有，产品的主要一次性命令会更不直接，并与自定义一次性 profile 冲突。
-- **新增 `apps/cli/src/run.ts`。** 不予采纳：它只会转发到 `runProfile`，拆分命令归属，却没有隐藏任何复杂度。
+| 替代方案 | 约定不匹配之处 |
+|---|---|
+| 把任务文本放在根 profile 启动命令上 | 生命周期含义依赖解析后才发现的插件配置行。 |
+| 接受 `dsh -p` 等根命令别名 | 预发布语法获得不属于任何当前命令的兼容分支。 |
+| 要求指定 `--profile headless` | 随附的一次性 surface 失去最短的规范写法。 |
+| 将 `dsh run` 用于应用文件 | 一个顶层动词具有两种含义，主要任务命令也变得间接。 |
+| 添加仅转发的 `apps/cli/src/run.ts` | 命令归属被拆分，却没有隐藏任何复杂度。 |
 
 ## 后果
 
-这是一次有意为之的 CLI（命令行界面）破坏性变更。文档、帮助信息、解析器测试、构建后二进制验收、PTY 关闭覆盖和组装应用的无密钥快照都使用 `dsh run`。现有自定义一次性 profile 可继续通过 `--profile` 工作；常驻 profile 和配置 dump 保留既有的根命令语法。与之竞争的应用文件命令必须单独改名并 rebase，不得共享或重载 `run`。
+帮助信息、文档、解析器测试、构建后二进制验收、PTY 关闭覆盖和组装应用的无密钥快照均使用 `dsh run`。自定义一次性 profile 使用 `--profile`；常驻 profile 启动与配置 dump 使用根 profile 语法。应用文件执行是独立的命令关注点。

apps/cli/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 apps/cli/README.md
-README.md: 12108fcbff4e649d0bcb3e01e688fa334ab91b14
-README.zh.md: 37967973ed40143db0bc747875dbb6dad11d73b4
+README.md: dd29f7fc03a783079ea3194de99589c1f545be5b
+README.zh.md: 60e7aa1ec1ea2fad7e3f3d97a0f6bf42355adffc

apps/cli/README.md

@@ -9,7 +9,7 @@ The `dsh` command is the product launcher for profiles: ordered stacks of plugin
 | Command | Purpose |
 |---|---|
 | `dsh --profile <name>` | Boot the named profile under `$DSH_HOME/profiles/<name>`. |
-| `dsh run [--profile <name>] [--patch <path>...] "task"` | Run one fresh persisted session, print the final answer, and exit; the profile defaults to `headless`. |
+| `dsh run [--profile <name>] [--patch <path>...] "task"` | Run one fresh persisted session directly over core, print the final answer, and exit; the profile defaults to `headless` and mounts no Web server. |
 | `dsh web` | Alias of `--profile web` with the Web flag family (`--host`, `--port`, `--dev`, ...). |
 | `dsh plugin --profile <name> <pnpm args>` | Manage a profile's plugins by forwarding to pnpm in the profile directory. |
 

apps/cli/README.zh.md

@@ -9,7 +9,7 @@
 | 命令 | 用途 |
 |---|---|
 | `dsh --profile <name>` | 启动位于 `$DSH_HOME/profiles/<name>` 的指定 profile。 |
-| `dsh run [--profile <name>] [--patch <path>...] "task"` | 运行一个新的持久化会话，打印最终答案并退出；profile 默认为 `headless`。 |
+| `dsh run [--profile <name>] [--patch <path>...] "task"` | 直接在 core 上运行一个新的持久化会话，打印最终答案并退出；profile 默认为 `headless`，且不挂载 Web server。 |
 | `dsh web` | `--profile web` 的别名，附带 Web flag 系列（`--host`、`--port`、`--dev` 等）。 |
 | `dsh plugin --profile <name> <pnpm args>` | 通过在 profile 目录中转发给 pnpm 来管理该 profile 的插件。 |
 

apps/cli/composition.md

@@ -32,6 +32,8 @@ flowchart LR
   cfg --> plugin_dsh_base_user_interaction
   plugin_dsh_base_agent["agent<br/>@deepseek-ai/dsh-agent"]
   cfg --> plugin_dsh_base_agent
+  plugin_dsh_base_agent_default_model["agent-default-model<br/>@deepseek-ai/dsh-agent-default-model"]
+  cfg --> plugin_dsh_base_agent_default_model
   plugin_dsh_base_tasks["tasks<br/>@deepseek-ai/dsh-tasks-local"]
   cfg --> plugin_dsh_base_tasks
   plugin_dsh_base_llm_retry["llm-retry<br/>@deepseek-ai/dsh-llm-retry"]
@@ -174,6 +176,7 @@ flowchart LR
 | `session-title-llm` | `@deepseek-ai/dsh-session-title-first-message-llm` |
 | `user-interaction` | `@deepseek-ai/dsh-user-interaction` |
 | `agent` | `@deepseek-ai/dsh-agent` |
+| `agent-default-model` | `@deepseek-ai/dsh-agent-default-model` |
 | `tasks` | `@deepseek-ai/dsh-tasks-local` |
 | `llm-retry` | `@deepseek-ai/dsh-llm-retry` |
 | `settings` | `@deepseek-ai/dsh-settings-local` |

apps/cli/reference/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 apps/cli/reference/README.md
-README.md: e616b420d60e0fa372bf38950207245cb60ced98
-README.zh.md: 81320ecbd19012123ab7e69967cbadb088356cfe
+README.md: 4f8aa86c0f6cdb91eb843048cd5ed4943a896c73
+README.zh.md: 09bc19220a869bedfcaa98baccbf6d4f6a3f3223

apps/cli/reference/README.md

@@ -10,7 +10,7 @@ This reference defines the profile, one-shot run, web-alias, plugin-management,
 
 Bundle names resolve from the dsh installation first, then from the profile directory. In-box bundles (`@deepseek-ai/dsh-base`, `@deepseek-ai/dsh-web-app`, `@deepseek-ai/dsh-headless`) therefore always come from the same installation as the running `dsh`; out-of-tree bundles come from the profile's pnpm-managed `node_modules`. A bare plugin `name` in any patch row resolves through the profile directory's Node parent-walk, which reaches the maintained installation fallback `$DSH_HOME/profiles/node_modules` (one symlink per package the installation's app and bundles depend on, healed on every launch).
 
-The `web` and `headless` profiles auto-initialize from shipped templates on first use (`web`: base + web-app; `headless`: base + web-app + headless). Any other missing profile fails loud with a hint to run `dsh plugin --profile <name> add <package>`.
+The `web` and `headless` profiles auto-initialize from shipped templates on first use (`web`: base + web-app; `headless`: base + headless). On load, the exact installation-owned headless tuple (base + web-app + headless) normalizes to the shipped template; extra, missing, or reordered bundle lists are user-owned and remain untouched. Any other missing profile fails loud with a hint to run `dsh plugin --profile <name> add <package>`.
 
 Profile boot accepts no positional task. A profile that mounts the one-shot runner row (`headless-runner`) therefore fails loud with the canonical `dsh run --profile <name> "<task>"` command instead of reaching the row's raw required-field error.
 
@@ -27,7 +27,7 @@ dsh --profile web --patch ./extra.yml --dump-config
 
 `dsh run [--profile <name>] [--patch <path>...] <task...>` joins the task arguments with spaces, rejects a missing or blank task, and defaults `--profile` to `headless`. Repeatable `--patch` overlays occupy the same layer position as profile-boot overlays. A custom selected profile must mount `headless-runner`; otherwise launch fails before boot with a diagnostic naming that missing row.
 
-The launcher patches the task text into the runner row, which drives one fresh persisted session through the in-process API carrier, prints the final assistant text on stdout, and exits 0 on a completed turn, else 1. At the idle boundary, the runner waits until its mux consumer has observed the session's final event sequence before deriving that output and exit reason. The session's Web host runs on an OS-assigned port and is announced on stderr, so the run is observable in a browser.
+The launcher patches the task text into the runner row. After Loader settlement, the runner reads the shared `ctx.agentDefaultModel` default, creates one fresh persisted Agent through `ctx.agents`, submits the task, waits for quiescence, and flushes the Session before deriving the last non-empty assistant text and final `turn/end` reason from its durable interval. It prints the text on stdout and exits 0 for `completed`, else 1. The shipped headless profile mounts no ApiProxy, Host, HTTP server, Web runtime, or browser client; a successful run writes nothing to stderr and opens no listening port.
 
 ## Plugin management
 

apps/cli/reference/README.zh.md

@@ -10,7 +10,7 @@
 
 组合包名称先从 dsh 安装解析，再从 profile 目录解析。因此内置组合包（`@deepseek-ai/dsh-base`、`@deepseek-ai/dsh-web-app`、`@deepseek-ai/dsh-headless`）总是来自与正在运行的 `dsh` 相同的安装；树外组合包来自 profile 由 pnpm 管理的 `node_modules`。任何 patch 行中的裸插件 `name` 通过 profile 目录的 Node 父目录逐级查找解析，该查找可达到持续维护的安装后备目录 `$DSH_HOME/profiles/node_modules`（安装的应用和组合包所依赖的每个包对应一个符号链接，每次启动时修复）。
 
-`web` 和 `headless` profile 首次使用时会从随附模板自动初始化（`web`：base + web-app；`headless`：base + web-app + headless）。其他缺失的 profile 会显式报错，并提示运行 `dsh plugin --profile <name> add <package>`。
+`web` 和 `headless` profile 首次使用时会从随附模板自动初始化（`web`：base + web-app；`headless`：base + headless）。加载时，与安装所管理的 headless 元组（base + web-app + headless）完全一致的列表会规范化为随附模板；包含额外项、缺少项或调整过顺序的组合包列表由用户拥有，保持不变。其他缺失的 profile 会显式报错，并提示运行 `dsh plugin --profile <name> add <package>`。
 
 Profile 启动不接受位置参数任务。因此，挂载了一次性运行器行（`headless-runner`）的 profile 会显式报错，并提示规范命令 `dsh run --profile <name> "<task>"`，而不会触发该行原始的必填字段错误。
 
@@ -27,7 +27,7 @@ dsh --profile web --patch ./extra.yml --dump-config
 
 `dsh run [--profile <name>] [--patch <path>...] <task...>` 会用空格拼接任务参数，拒绝缺失或空白任务，并让 `--profile` 默认为 `headless`。可重复使用的 `--patch` overlay 与 profile 启动的 overlay 位于同一层。所选的自定义 profile 必须挂载 `headless-runner`；否则启动器会在启动前失败，并在诊断中指明缺少该行。
 
-启动器把任务文本 patch 进运行器行，运行器再通过进程内 API 载体驱动一个全新的持久化会话，在 stdout 打印最终 assistant 文本，并在轮次完成时以 0 退出，否则以 1 退出。到达 idle 边界时，运行器会等到 mux 消费方观察到会话的最终事件序号，再生成输出与退出原因。会话的 Web 宿主运行在 OS 分配的端口上并公布到 stderr，因此该次运行可在浏览器中观察。
+启动器把任务文本 patch 进运行器行。Loader 结算后，运行器读取共享的 `ctx.agentDefaultModel` 默认值，通过 `ctx.agents` 创建一个全新的持久化 Agent（智能体），提交任务、等待完全停稳并对 Session 执行 flush，再从其持久化事件区间中推导最后一个非空 assistant 文本与最终 `turn/end` 原因。它在 stdout 打印文本，并在原因为 `completed` 时以 0 退出，否则以 1 退出。随附 headless profile 不挂载 ApiProxy、Host、HTTP 服务器、Web 运行时或浏览器客户端；成功运行不会向 stderr 写入任何内容，也不会打开监听端口。
 
 ## 插件管理
 

apps/cli/tests/built-bin.e2e.ts

@@ -222,7 +222,7 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
       })
       expect(result.code, result.stderr).toBe(0)
       expect(result.stdout).toBe('published dsh run reached the mock')
-      expect(result.stderr).toMatch(/^dsh: observing at http:\/\/127\.0\.0\.1:\d+$/u)
+      expect(result.stderr).toBe('')
       expect(server.requests.length).toBeGreaterThan(0)
       expect(server.requests.every(request => request.path === '/chat/completions')).toBe(true)
       expect(JSON.stringify(server.requests.map(request => request.body))).toContain('answer from the published entry')
@@ -470,6 +470,20 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
       expect(stdout).toContain("name: '@deepseek-ai/dsh-host-webserver'")
     }, 30_000)
 
+    it('prints a headless profile with no Host, HTTP, or browser rows', async () => {
+      const { stdout, code, stderr } = await runBuiltBin(
+        ['--profile', 'headless', '--dump-default-config'],
+        { DSH_HOME: home },
+      )
+      expect(code).toBe(0)
+      expect(stderr).toBe('')
+      expect(stdout).toContain("name: '@deepseek-ai/dsh-agent-default-model'")
+      expect(stdout).toContain("name: '@deepseek-ai/dsh-headless'")
+      expect(stdout).not.toContain("name: '@deepseek-ai/dsh-host-")
+      expect(stdout).not.toContain("name: '@deepseek-ai/dsh-web-app'")
+      expect(stdout).not.toContain("name: '@deepseek-ai/dsh-client-")
+    }, 30_000)
+
     it('composes the profile user layer and a --patch overlay in order', async () => {
       // Auto-init the web profile first, then write its user layer.
       const init = await runBuiltBin(['--profile', 'web', '--dump-default-config'], { DSH_HOME: home })

apps/cli/tests/fixtures/never-dispose.mjs

@@ -8,6 +8,7 @@ import { existsSync } from 'node:fs'
  */
 export function apply(ctx) {
   const keepAlive = setInterval(() => {}, 60_000)
+  process.stderr.write('dsh-test: never-dispose ready\n')
   ctx.effect(() => async () => {
     clearInterval(keepAlive)
     const armFile = process.env.DSH_TEST_SHUTDOWN_ARM_FILE

apps/cli/tests/headless-shutdown.e2e.ts

@@ -22,7 +22,7 @@ if pid == 0:
     os.chdir(cwd)
     os.execvpe(node, [node, *json.loads(launch_args_json)], env)
 
-markers = [b"dsh: observing at ", b"dsh-test: never-dispose started"]
+markers = [b"dsh-test: never-dispose ready", b"dsh-test: never-dispose started"]
 output = bytearray()
 marker_index = 0
 deadline = time.monotonic() + float(timeout_seconds)
@@ -73,7 +73,7 @@ async function runHeadlessPtySmoke(): Promise<string> {
       name: 'dsh-profile-headless',
       private: true,
       dependencies: {},
-      dsh: { profile: { bundles: ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app', '@deepseek-ai/dsh-headless'] } },
+      dsh: { profile: { bundles: ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-headless'] } },
     }, undefined, 2))
     await writeFile(join(profileDir, 'cordis.patch.yml'), [
       '- insert:',
@@ -124,7 +124,8 @@ async function runHeadlessPtySmoke(): Promise<string> {
 describe.skipIf(process.platform === 'win32')('headless process shutdown (real Loader tree in a PTY)', () => {
   it('lets a second Ctrl+C force exit while the first signal is draining', async () => {
     const output = await runHeadlessPtySmoke()
-    expect(output).toContain('dsh: observing at ')
+    expect(output).not.toContain('dsh: observing at ')
+    expect(output).toContain('dsh-test: never-dispose ready')
     expect(output).toContain('dsh-test: never-dispose started')
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 })

apps/web/tests/declared-reasoning.e2e.ts

@@ -1,6 +1,6 @@
 // Web e2e scenario: a hand-declared model's `reasoningEfforts` reaches the
 // composer's effort pane — the levels a settings profile declares are exactly
-// what the picker offers, and picking one records it with the default route.
+// what the picker offers, and picking one records it with the Agent default.
 // Zero model calls: declaring, describing, and switching are settings/llm
 // traffic only, so there is no fixture and a stray stream would fail loud.
 import { readFile } from 'node:fs/promises'
@@ -77,8 +77,8 @@ describe.skipIf(MODE === 'record')('web e2e: declared reasoning efforts reach th
     const snapshot = await captureStableAria(page, '[role="menu"]', scaffold.workspaceCwd)
     await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE)
 
-    // Picking a level is the same gesture that saves the default target, so
-    // the effort lands in the gateway's settings section beside the route.
+    // Picking a level is the same gesture that saves the default selection, so
+    // the effort lands in the Agent default Settings section beside provider/model.
     await page.getByRole('menuitemradio', { name: 'High' }).click()
     await expect.poll(
       async () => readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8'),

apps/web/tests/declared-reasoning.overlay.yml

@@ -2,7 +2,7 @@
 # deepseek-official default would be a route nothing serves. This scenario
 # starts the default on its own declared reasoning model so the effort pane
 # describes that model from the first open.
-- id: api-gateway
+- id: agent-default-model
   config:
     provider: acme-gateway
     model: acme-think

apps/web/tests/default-model.e2e.ts

@@ -1,5 +1,5 @@
 // Web e2e scenario: switching models in the composer is how this deployment's
-// default is chosen. The gesture writes the `api-gateway` settings section, a
+// default is chosen. The gesture writes the shared `agent-default-model` settings section, a
 // session created afterwards starts from it, and a session that already logged
 // a route keeps deriving from its own log — the tier order the gateway
 // resolves on every read.
@@ -21,7 +21,7 @@ import { settingsNamespace } from '@deepseek-ai/dsh-settings'
 import { launchWebScaffold, watchConsole, type WebScaffold } from './scaffold.ts'
 import { ZH_BROWSER_LOCALE, connectFreshWorkspaceZh, saveFailureShot } from './support.ts'
 
-/** Points the shipped `api-gateway` default at this scenario's own route. */
+/** Points the shipped shared Agent default at this scenario's own route. */
 const OVERLAY = fileURLToPath(new URL('./default-model.overlay.yml', import.meta.url))
 
 /** The route this scenario starts on, patched over the shipped default. */
@@ -110,12 +110,12 @@ describe('web e2e: the composer model switch is the default for later sessions',
     await page.getByRole('menuitem', { name: /模型/ }).click()
     await page.getByRole('menuitemradio', { name: 'Acme Large' }).click()
 
-    // The switch is what sets the default: the gateway's own settings section
+    // The switch is what sets the default: the shared Agent-route settings section
     // now names it, beside the provider profiles the Models page writes.
     await expect.poll(
       async () => readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8'),
       { timeout: 10_000 },
-    ).toContain('api-gateway:')
+    ).toContain('agent-default-model:')
     const document = await readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8')
     expect(document).toContain(`provider: ${ROUTE}`)
     expect(document).toContain(`model: ${MODEL}`)

apps/web/tests/default-model.overlay.yml

@@ -2,7 +2,7 @@
 # deepseek-official default would be a route nothing serves — which the
 # composer now correctly refuses to type into. This scenario declares its own
 # pi-ai routes and starts the default on one of them.
-- id: api-gateway
+- id: agent-default-model
   config:
     provider: origin-gateway
     model: origin-large

docs/architecture.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/architecture.md
-architecture.md: 06c15f204b3a695de49df29938781f8f033c4a7e
-architecture.zh.md: 5d00d78899498cc6b7bdf52c826fb194f4e662f2
+architecture.md: ed33fb215c3b4fd830bef219da74f4ee98dec81d
+architecture.zh.md: 8cf55392ac56bcdb80d7386320198c51e2d25a1f

docs/architecture.md

@@ -17,6 +17,7 @@ Harnesses are [Cordis](cordis-primer.md) contexts; packages contribute services,
 | `ctx.systemPrompt` | `dsh-system-prompt` | ordered prompt sections, tool schemas, and variables |
 | `ctx.tools` | `dsh-tools` | tool registry and [execution pipeline](tool-execution-pipeline.md) |
 | `ctx.agents` | `dsh-agent` | live agents, delegated creation, `agent/*` events, process-local initiator scope |
+| `ctx.agentDefaultModel` | [`dsh-agent-default-model`](../packages/core/agent-default-model/README.md) | Settings-backed model selection shared by Agent front doors |
 | `ctx.agentLoop` | `dsh-agent-loop` | concrete `Agent` driver |
 
 ### Capability Services

docs/architecture.zh.md

@@ -17,6 +17,7 @@
 | `ctx.systemPrompt` | `dsh-system-prompt` | 有序的提示词片段、工具 schema 和变量 |
 | `ctx.tools` | `dsh-tools` | 工具注册表和[执行流水线](tool-execution-pipeline.md) |
 | `ctx.agents` | `dsh-agent` | 活跃 agent（智能体）、委托创建、`agent/*` 事件、进程内发起方作用域 |
+| `ctx.agentDefaultModel` | [`dsh-agent-default-model`](../packages/core/agent-default-model/README.md) | 由 Settings 支撑、供 Agent 入口共享的模型选择 |
 | `ctx.agentLoop` | `dsh-agent-loop` | 具体 `Agent` 驱动器 |
 
 ### 能力服务

docs/capability-seams.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/capability-seams.md
-capability-seams.md: 4b46a6566ba795d89d6fdf7261c42574af286faf
-capability-seams.zh.md: 23f270c7463a45b5892ead8e34260b375a9fe3e5
+capability-seams.md: d61353210eedb3de68dd19caa866d4efb9deb19a
+capability-seams.zh.md: 75bf176952a8c06c723e9f7cda535c1ca8b69819

docs/capability-seams.md

@@ -94,6 +94,9 @@ flowchart LR
   pkg_skill_local["skill-local"]
   svc_agents["ctx.agents<br/>Agent service"]
   pkg_acp["acp"]
+  pkg_agent_default_model["agent-default-model"]
+  svc_agentDefaultModel["ctx.agentDefaultModel<br/>Default Agent model selection"]
+  pkg_headless["headless"]
   svc_agentLoop["ctx.agentLoop<br/>Concrete loop driver"]
   pkg_agent_spine_demo["agent-spine-demo"]
   pkg_goal["goal"]
@@ -176,6 +179,7 @@ flowchart LR
   pkg_tool_workflow["tool-workflow"]
   pkg_acp --> svc_approval
   pkg_agent --> svc_agents
+  pkg_agent_default_model --> svc_agentDefaultModel
   pkg_agent_loop --> svc_agentLoop
   pkg_api_gateway --> svc_typertGateway
   pkg_approval --> svc_approval
@@ -265,6 +269,8 @@ flowchart LR
   pkg_workflow --> svc_workflows
   pkg_workflow_workerthread --> svc_workflows
   pkg_workspace --> svc_workspace
+  svc_agentDefaultModel --> pkg_headless
+  svc_agentDefaultModel --> pkg_host_apiproxy
   svc_agentLoop --> pkg_agent_spine_demo
   svc_agents --> pkg_acp
   svc_agents --> pkg_agent_loop
@@ -397,6 +403,7 @@ flowchart LR
 | `ctx.sessionProjectionCache` | `core` | [`session-projection-cache`](../packages/session/session-projection-cache) | - | [`host-apiproxy`](../packages/host/apiproxy) | - | Durably checkpoints projection unit states per session (throttled + turn/end/detach mandatory points) and serves the cold-read ladder: cache row + persistence tail replay, so listings never load full logs. |
 | `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-badge`](../packages/skill/skill-badge), [`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies. |
 | `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/acp/acp), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. |
+| `ctx.agentDefaultModel` | `core` | [`agent-default-model`](../packages/core/agent-default-model) | - | [`headless`](../packages/bundle/headless), [`host-apiproxy`](../packages/host/apiproxy) | - | Layers the default ModelSelection through settings so direct and Host-backed Agent front doors share one state owner. |
 | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. |
 | `ctx.goals` | `core` | [`goal`](../packages/goal/goal) | - | - | - | Folds revisioned objective state from the session log and keeps live continuation activation process-local. |
 | `ctx.e2b` | `core` | [`e2b`](../packages/e2b/e2b) | - | [`fs-e2b`](../packages/e2b/fs-e2b), [`subprocess-e2b`](../packages/e2b/subprocess-e2b) | - | Owns one shared E2B SDK handle, remote working directory, and final sandbox disposition so both fundamental E2B providers inhabit the same Linux runtime. |

docs/capability-seams.zh.md

@@ -96,6 +96,9 @@ flowchart LR
   pkg_skill_local["skill-local"]
   svc_agents["ctx.agents<br/>Agent service"]
   pkg_acp["acp"]
+  pkg_agent_default_model["agent-default-model"]
+  svc_agentDefaultModel["ctx.agentDefaultModel<br/>Default Agent model selection"]
+  pkg_headless["headless"]
   svc_agentLoop["ctx.agentLoop<br/>Concrete loop driver"]
   pkg_agent_spine_demo["agent-spine-demo"]
   pkg_goal["goal"]
@@ -178,6 +181,7 @@ flowchart LR
   pkg_tool_workflow["tool-workflow"]
   pkg_acp --> svc_approval
   pkg_agent --> svc_agents
+  pkg_agent_default_model --> svc_agentDefaultModel
   pkg_agent_loop --> svc_agentLoop
   pkg_api_gateway --> svc_typertGateway
   pkg_approval --> svc_approval
@@ -267,6 +271,8 @@ flowchart LR
   pkg_workflow --> svc_workflows
   pkg_workflow_workerthread --> svc_workflows
   pkg_workspace --> svc_workspace
+  svc_agentDefaultModel --> pkg_headless
+  svc_agentDefaultModel --> pkg_host_apiproxy
   svc_agentLoop --> pkg_agent_spine_demo
   svc_agents --> pkg_acp
   svc_agents --> pkg_agent_loop
@@ -399,6 +405,7 @@ flowchart LR
 | `ctx.sessionProjectionCache` | `core` | [`session-projection-cache`](../packages/session/session-projection-cache) | - | [`host-apiproxy`](../packages/host/apiproxy) | - | 按会话持久保存投影单元状态的检查点（节流检查点，以及轮次／结束／分离时的必选检查点），并提供冷读取阶梯：缓存行加持久化尾部回放，因此列表读取永远不需要加载完整日志。 |
 | `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-badge`](../packages/skill/skill-badge)、[`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | 合并提供方的 skill（技能）目录；tool-skill 渲染会话前缀目录，并加载完整的 skill 正文。 |
 | `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop)、[`acp`](../packages/acp/acp)、[`subagent-inprocess`](../packages/subagent/subagent-inprocess) | - | 拥有实时 Agent 句柄、创建／恢复工厂 seam，以及进程本地的发起方传播。 |
+| `ctx.agentDefaultModel` | `core` | [`agent-default-model`](../packages/core/agent-default-model) | - | [`headless`](../packages/bundle/headless)、[`host-apiproxy`](../packages/host/apiproxy) | - | 通过 settings 分层默认 `ModelSelection`，让直接前门与 Host 支撑的 Agent 前门共享同一个状态所有者。 |
 | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | - | 唯一的具体循环插件；扩展包依赖 dsh-agent 的事件和服务，而不依赖此包。 |
 | `ctx.goals` | `core` | [`goal`](../packages/goal/goal) | - | - | - | 从会话日志折叠带修订版本的目标状态，并将实时延续激活保留在进程本地。 |
 | `ctx.e2b` | `core` | [`e2b`](../packages/e2b/e2b) | - | [`fs-e2b`](../packages/e2b/fs-e2b)、[`subprocess-e2b`](../packages/e2b/subprocess-e2b) | - | 拥有一个共享的 E2B SDK 句柄、远程工作目录和最终沙箱处置，使两个基础 E2B 提供方处于同一个 Linux 运行时中。 |

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: 0a5d0f75191240cf5057f1d9a026af32c870f589
-config-catalog.zh.md: 5d9e3587a84535e54ebdddb363b4b80c5acfed38
+config-catalog.md: 6219a0080f539f5f9865f8b6191ad8413672574d
+config-catalog.zh.md: 81542d94c774d42dd9ddbc2840027ddf3f498dd8

docs/config-catalog.md

@@ -14,7 +14,7 @@ A `Requires:` line lists the service keys the plugin `inject`s: its `cordis.yml`
 Requires: `agents`
 
 ```ts config-catalog
-/** Plugin config: the provider/model target used for each ACP-created agent. */
+/** Plugin config: the provider/model selection used for each ACP-created agent. */
 export interface AcpConfig {
   /** Provider route for created agents. */
   provider?: string
@@ -80,6 +80,20 @@ Depends on: [`agentCore`](../packages/examples/agent-spine-demo/src/index.ts) ·
 
 Source: [`packages/examples/acp-demo/src/index.ts:39`](../packages/examples/acp-demo/src/index.ts)
 
+## `@deepseek-ai/dsh-agent-default-model`
+
+```ts config-catalog
+/** Composition entry for the default model selection. */
+export interface Config {
+  /** Registered provider route. */
+  provider: string
+  /** Provider-owned model id. */
+  model: string
+}
+```
+
+Source: [`packages/core/agent-default-model/src/index.ts:41`](../packages/core/agent-default-model/src/index.ts)
+
 ## `@deepseek-ai/dsh-agent-loop`
 
 Requires: `agents` · `sessions` · `llm` · `tools` · `systemPrompt`
@@ -475,17 +489,17 @@ Source: [`packages/goal/goal/src/index.ts:116`](../packages/goal/goal/src/index.
 
 ## `@deepseek-ai/dsh-headless`
 
-Requires: `apiProxy` · `httpServer`
+Requires: `agentDefaultModel` · `agents` · `sessions`
 
 ```ts config-catalog
 /** Plugin config: the task, patched in by the launcher. */
 export interface Config {
-  /** The prompt text for the single turn. */
+  /** The prompt text for the single run. */
   task: string
 }
 ```
 
-Source: [`packages/bundle/headless/src/index.ts:32`](../packages/bundle/headless/src/index.ts)
+Source: [`packages/bundle/headless/src/index.ts:29`](../packages/bundle/headless/src/index.ts)
 
 ## `@deepseek-ai/dsh-hooks-claude`
 
@@ -550,32 +564,17 @@ Source: [`packages/hooks/hooks-codex/src/index.ts:44`](../packages/hooks/hooks-c
 
 ## `@deepseek-ai/dsh-host-apiproxy`
 
-Requires: `agents` · `directoryPicker` · `llm` · `sessions` · `subagents` · `sessionQuery` · `tools` · `userInteraction` · `workspace`
+Requires: `agentDefaultModel` · `agents` · `directoryPicker` · `llm` · `sessions` · `subagents` · `sessionQuery` · `tools` · `userInteraction` · `workspace`
 
 ```ts config-catalog
-/**
- * Gateway plugin config: host-level agent routing and Workspace creation root.
- *
- * `reasoningEffort` is deliberately absent, so the section carries one field
- * the composition cannot. The seam resolves a section by MERGING the user
- * layer over the composition entry per field, and an absent key cannot
- * override a present one — so a composition-set effort would survive every
- * later switch to a model that has none, and strand it for the next session
- * to fail on. Effort is a per-model fact anyway: a deployment default belongs
- * on the adapter profile (`llm-pi-ai`'s `reasoning`, `llm-deepseek`'s own),
- * which resolves per model rather than per gateway.
- */
+/** Gateway plugin config: the Host-only Workspace creation root. */
 export interface Config {
-  /** Default provider route for created agents. */
-  provider: string
-  /** Default model id. */
-  model: string
   /** Parent directory for name-created Workspaces; defaults to the Host cwd. */
   workspaceRoot?: string
 }
 ```
 
-Source: [`packages/host/apiproxy/src/index.ts:67`](../packages/host/apiproxy/src/index.ts)
+Source: [`packages/host/apiproxy/src/index.ts:38`](../packages/host/apiproxy/src/index.ts)
 
 ## `@deepseek-ai/dsh-host-directory-picker-browse`
 

docs/config-catalog.zh.md

@@ -16,7 +16,7 @@
 需要：`agents`
 
 ```ts config-catalog
-/** Plugin config: the provider/model target used for each ACP-created agent. */
+/** Plugin config: the provider/model selection used for each ACP-created agent. */
 export interface AcpConfig {
   /** Provider route for created agents. */
   provider?: string
@@ -82,6 +82,20 @@ export interface Config {
 
 来源：[`packages/examples/acp-demo/src/index.ts:39`](../packages/examples/acp-demo/src/index.ts)
 
+## `@deepseek-ai/dsh-agent-default-model`
+
+```ts config-catalog
+/** Composition entry for the default model selection. */
+export interface Config {
+  /** Registered provider route. */
+  provider: string
+  /** Provider-owned model id. */
+  model: string
+}
+```
+
+来源：[`packages/core/agent-default-model/src/index.ts:41`](../packages/core/agent-default-model/src/index.ts)
+
 ## `@deepseek-ai/dsh-agent-loop`
 
 需要：`agents` · `sessions` · `llm` · `tools` · `systemPrompt`
@@ -477,17 +491,17 @@ export interface Config {
 
 ## `@deepseek-ai/dsh-headless`
 
-需要：`apiProxy` · `httpServer`
+需要：`agentDefaultModel` · `agents` · `sessions`
 
 ```ts config-catalog
 /** Plugin config: the task, patched in by the launcher. */
 export interface Config {
-  /** The prompt text for the single turn. */
+  /** The prompt text for the single run. */
   task: string
 }
 ```
 
-来源：[`packages/bundle/headless/src/index.ts:32`](../packages/bundle/headless/src/index.ts)
+来源：[`packages/bundle/headless/src/index.ts:29`](../packages/bundle/headless/src/index.ts)
 
 ## `@deepseek-ai/dsh-hooks-claude`
 
@@ -552,32 +566,17 @@ export interface Config {
 
 ## `@deepseek-ai/dsh-host-apiproxy`
 
-需要：`agents` · `directoryPicker` · `llm` · `sessions` · `subagents` · `sessionQuery` · `tools` · `userInteraction` · `workspace`
+需要：`agentDefaultModel` · `agents` · `directoryPicker` · `llm` · `sessions` · `subagents` · `sessionQuery` · `tools` · `userInteraction` · `workspace`
 
 ```ts config-catalog
-/**
- * Gateway plugin config: host-level agent routing and Workspace creation root.
- *
- * `reasoningEffort` is deliberately absent, so the section carries one field
- * the composition cannot. The seam resolves a section by MERGING the user
- * layer over the composition entry per field, and an absent key cannot
- * override a present one — so a composition-set effort would survive every
- * later switch to a model that has none, and strand it for the next session
- * to fail on. Effort is a per-model fact anyway: a deployment default belongs
- * on the adapter profile (`llm-pi-ai`'s `reasoning`, `llm-deepseek`'s own),
- * which resolves per model rather than per gateway.
- */
+/** Gateway plugin config: the Host-only Workspace creation root. */
 export interface Config {
-  /** Default provider route for created agents. */
-  provider: string
-  /** Default model id. */
-  model: string
   /** Parent directory for name-created Workspaces; defaults to the Host cwd. */
   workspaceRoot?: string
 }
 ```
 
-来源：[`packages/host/apiproxy/src/index.ts:67`](../packages/host/apiproxy/src/index.ts)
+来源：[`packages/host/apiproxy/src/index.ts:38`](../packages/host/apiproxy/src/index.ts)
 
 ## `@deepseek-ai/dsh-host-directory-picker-browse`
 

docs/event-producer-consumer.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/event-producer-consumer.md
-event-producer-consumer.md: f5ea3eba36f46b87d9a8f5fc9537c40622da8cc9
-event-producer-consumer.zh.md: e2bb889d5a4319fc31c1ed0b3e06b68e320081f5
+event-producer-consumer.md: 628750959e9c165006e221655cacb2de2dfcf637
+event-producer-consumer.zh.md: f09d8dc0b877c2c1d167b1aaad391bfe524828ed

docs/event-producer-consumer.md

@@ -18,7 +18,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:243`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent`](../packages/core/agent) |
 | `agent/request-error` | `waterfall` | [`packages/core/agent/src/types.ts:259`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) |
 | `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:216`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
-| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:177`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`headless`](../packages/bundle/headless), `server` |
+| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:177`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), `server` |
 | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/types.ts:277`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/index.ts:30`](../packages/interaction/user-approval/src/index.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` |
 | `commands/change` | `emit` | [`packages/interaction/commands/src/index.ts:172`](../packages/interaction/commands/src/index.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |

docs/event-producer-consumer.zh.md

@@ -20,7 +20,7 @@
 | `agent/request` | `waterfall` | [`packages/core/agent/src/types.ts:243`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`agent`](../packages/core/agent) |
 | `agent/request-error` | `waterfall` | [`packages/core/agent/src/types.ts:259`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`waterfall`) | [`compact-basic`](../packages/compact/compact-basic), [`llm-retry`](../packages/llm/llm-retry) |
 | `agent/session-start` | `emit` | [`packages/core/agent/src/types.ts:216`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emitAgentEvent`) | [`goal`](../packages/goal/goal), [`goal-session`](../packages/goal/goal-session), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
-| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:177`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), [`headless`](../packages/bundle/headless), `server` |
+| `agent/status` | `emit` | [`packages/core/agent/src/types.ts:177`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`emit`) | [`agent`](../packages/core/agent), `apiproxy`, [`compact-basic`](../packages/compact/compact-basic), [`goal-session`](../packages/goal/goal-session), `server` |
 | `agent/turn-stopping` | `serial` | [`packages/core/agent/src/types.ts:277`](../packages/core/agent/src/types.ts) | [`agent-loop`](../packages/core/agent-loop) (`serial`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) |
 | `approval/request` | `waterfall` | [`packages/interaction/user-approval/src/index.ts:30`](../packages/interaction/user-approval/src/index.ts) | [`user-approval`](../packages/interaction/user-approval) (`waterfall`) | [`acp`](../packages/acp/acp), `apiproxy` |
 | `commands/change` | `emit` | [`packages/interaction/commands/src/index.ts:172`](../packages/interaction/commands/src/index.ts) | [`commands`](../packages/interaction/commands) (`events.dispatch`) | `apiproxy` |

docs/i18n/terminology.md

@@ -137,6 +137,7 @@
 | message | 消息 | | | |
 | mod | 模组 | | | |
 | model provider | 模型提供方 | | | |
+| model selection | 模型选择 | | 模型目标 | 面向 Agent 的提供方、模型和可选推理强度选择。 |
 | module | 模块 | | | |
 | non-escalation | 非升权 | | 非升级、不可升级 | 仅用于安全与权限语境，指主体不得获得超出既有授权的权限；普通升级不适用此行 |
 | npm dependency | NPM 依赖 | | | `package.json` 中的包关系；`dependencies`、`devDependencies` 等字段保持原样 |

docs/module-graph.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/module-graph.md
-module-graph.md: 6f47c36e970009838e1ab921f4abe013eaeded5f
-module-graph.zh.md: 644305dbde58f5c35ec57fb9c313dcb78fae9938
+module-graph.md: e7d6b47e709c3edf4dcdb506bd8f2be0c717aaab
+module-graph.zh.md: 255253bcfa9cfad1ab85602dfa9f953a02dfc427

docs/module-graph.md

@@ -25,6 +25,7 @@ flowchart TD
   end
   subgraph group_core["packages/core"]
     pkg_agent["agent"]
+    pkg_agent_default_model["agent-default-model"]
     pkg_agent_loop["agent-loop"]
     pkg_scope["scope"]
     pkg_session["session"]
@@ -510,6 +511,10 @@ flowchart TD
   pkg_token_meter --> pkg_llm
   pkg_token_meter --> pkg_session
   pkg_token_meter --> pkg_session_projection
+  pkg_agent_default_model --> pkg_agent
+  pkg_agent_default_model --> pkg_invariants
+  pkg_agent_default_model --> pkg_llm
+  pkg_agent_default_model --> pkg_settings
   pkg_goal --> pkg_agent
   pkg_goal --> pkg_brand
   pkg_goal --> pkg_invariants
@@ -553,11 +558,6 @@ flowchart TD
   pkg_loader_smoke --> pkg_invariants
   pkg_loader_smoke --> pkg_llm
   pkg_loader_smoke --> pkg_session
-  pkg_headless --> pkg_agent
-  pkg_headless --> pkg_host_apiproxy
-  pkg_headless --> pkg_host_webserver
-  pkg_headless --> pkg_invariants
-  pkg_headless --> pkg_session
   pkg_client_ui_layout --> pkg_client_runtime
   pkg_client_ui_layout --> pkg_client_ui_slots
   pkg_client_ui_layout --> pkg_client_ui_theme
@@ -698,6 +698,11 @@ flowchart TD
   pkg_api_remotes --> pkg_session
   pkg_api_remotes --> pkg_session_persistence
   pkg_api_remotes --> pkg_typert_registry
+  pkg_headless --> pkg_agent
+  pkg_headless --> pkg_agent_default_model
+  pkg_headless --> pkg_invariants
+  pkg_headless --> pkg_llm
+  pkg_headless --> pkg_session
   pkg_client_ui_conversation --> pkg_client_locale
   pkg_client_ui_conversation --> pkg_client_runtime
   pkg_client_ui_conversation --> pkg_client_ui_primitives
@@ -1252,6 +1257,7 @@ flowchart TD
 | [`session-projection`](../packages/session/session-projection) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`llm-retry`](../packages/llm/llm-retry) | `llm` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
 | [`token-meter`](../packages/llm/token-meter) | `llm` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
+| [`agent-default-model`](../packages/core/agent-default-model) | `core` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings) |
 | [`goal`](../packages/goal/goal) | `goal` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`type-meta`](../packages/typert/type-meta) |
 | [`bash-local`](../packages/bash/bash-local) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`pwsh-local`](../packages/bash/pwsh-local) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
@@ -1263,7 +1269,6 @@ flowchart TD
 | [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`llm-replay`](../packages/support/llm-replay) | `support` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`loader-smoke`](../packages/support/loader-smoke) | `support` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
-| [`headless`](../packages/bundle/headless) | `bundle` | [`agent`](../packages/core/agent), [`host-apiproxy`](../packages/host/apiproxy), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/support/invariants) |
 | [`time-context`](../packages/context/time-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`tmux-context`](../packages/context/tmux-context) | `context` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
@@ -1295,6 +1300,7 @@ flowchart TD
 | [`session-query`](../packages/session-query/session-query) | `session-query` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-title`](../packages/session/session-title) |
 | [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`user-approval`](../packages/interaction/user-approval) |
 | [`api-remotes`](../packages/api/remotes) | `api` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`typert-registry`](../packages/typert/registry) |
+| [`headless`](../packages/bundle/headless) | `bundle` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`token-meter`](../packages/llm/token-meter) |
 | [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`commands`](../packages/interaction/commands), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`host-directory-picker-auto`](../packages/host/directory-picker-auto) | `host` | [`host-directory-picker-browse`](../packages/host/directory-picker-browse), [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |

docs/module-graph.zh.md

@@ -27,6 +27,7 @@ flowchart TD
   end
   subgraph group_core["packages/core"]
     pkg_agent["agent"]
+    pkg_agent_default_model["agent-default-model"]
     pkg_agent_loop["agent-loop"]
     pkg_scope["scope"]
     pkg_session["session"]
@@ -512,6 +513,10 @@ flowchart TD
   pkg_token_meter --> pkg_llm
   pkg_token_meter --> pkg_session
   pkg_token_meter --> pkg_session_projection
+  pkg_agent_default_model --> pkg_agent
+  pkg_agent_default_model --> pkg_invariants
+  pkg_agent_default_model --> pkg_llm
+  pkg_agent_default_model --> pkg_settings
   pkg_goal --> pkg_agent
   pkg_goal --> pkg_brand
   pkg_goal --> pkg_invariants
@@ -555,11 +560,6 @@ flowchart TD
   pkg_loader_smoke --> pkg_invariants
   pkg_loader_smoke --> pkg_llm
   pkg_loader_smoke --> pkg_session
-  pkg_headless --> pkg_agent
-  pkg_headless --> pkg_host_apiproxy
-  pkg_headless --> pkg_host_webserver
-  pkg_headless --> pkg_invariants
-  pkg_headless --> pkg_session
   pkg_client_ui_layout --> pkg_client_runtime
   pkg_client_ui_layout --> pkg_client_ui_slots
   pkg_client_ui_layout --> pkg_client_ui_theme
@@ -700,6 +700,11 @@ flowchart TD
   pkg_api_remotes --> pkg_session
   pkg_api_remotes --> pkg_session_persistence
   pkg_api_remotes --> pkg_typert_registry
+  pkg_headless --> pkg_agent
+  pkg_headless --> pkg_agent_default_model
+  pkg_headless --> pkg_invariants
+  pkg_headless --> pkg_llm
+  pkg_headless --> pkg_session
   pkg_client_ui_conversation --> pkg_client_locale
   pkg_client_ui_conversation --> pkg_client_runtime
   pkg_client_ui_conversation --> pkg_client_ui_primitives
@@ -1254,6 +1259,7 @@ flowchart TD
 | [`session-projection`](../packages/session/session-projection) | `session` | [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`llm-retry`](../packages/llm/llm-retry) | `llm` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`timeout`](../packages/util/timeout) |
 | [`token-meter`](../packages/llm/token-meter) | `llm` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection) |
+| [`agent-default-model`](../packages/core/agent-default-model) | `core` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`settings`](../packages/settings/settings) |
 | [`goal`](../packages/goal/goal) | `goal` | [`agent`](../packages/core/agent), [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`scope`](../packages/core/scope), [`session`](../packages/core/session), [`session-projection`](../packages/session/session-projection), [`type-meta`](../packages/typert/type-meta) |
 | [`bash-local`](../packages/bash/bash-local) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
 | [`pwsh-local`](../packages/bash/pwsh-local) | `bash` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`subprocess`](../packages/subprocess/subprocess), [`timeout`](../packages/util/timeout) |
@@ -1265,7 +1271,6 @@ flowchart TD
 | [`hook-protocol`](../packages/hooks/hook-protocol) | `hooks` | [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`llm-replay`](../packages/support/llm-replay) | `support` | [`compact`](../packages/compact/compact), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`loader-smoke`](../packages/support/loader-smoke) | `support` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
-| [`headless`](../packages/bundle/headless) | `bundle` | [`agent`](../packages/core/agent), [`host-apiproxy`](../packages/host/apiproxy), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`client-ui-layout`](../packages/client/ui-layout) | `client` | [`client-runtime`](../packages/client/runtime), [`client-ui-slots`](../packages/client/ui-slots), [`client-ui-theme`](../packages/client/ui-theme), [`invariants`](../packages/support/invariants) |
 | [`time-context`](../packages/context/time-context) | `context` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`tmux-context`](../packages/context/tmux-context) | `context` | [`agent`](../packages/core/agent), [`bash`](../packages/bash/bash), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
@@ -1297,6 +1302,7 @@ flowchart TD
 | [`session-query`](../packages/session-query/session-query) | `session-query` | [`brand`](../packages/util/brand), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`session-title`](../packages/session/session-title) |
 | [`acp`](../packages/acp/acp) | `acp` | [`agent`](../packages/core/agent), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`user-approval`](../packages/interaction/user-approval) |
 | [`api-remotes`](../packages/api/remotes) | `api` | [`agent`](../packages/core/agent), [`goal`](../packages/goal/goal), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session), [`session-persistence`](../packages/session/session-persistence), [`typert-registry`](../packages/typert/registry) |
+| [`headless`](../packages/bundle/headless) | `bundle` | [`agent`](../packages/core/agent), [`agent-default-model`](../packages/core/agent-default-model), [`invariants`](../packages/support/invariants), [`llm`](../packages/llm/llm), [`session`](../packages/core/session) |
 | [`client-ui-conversation`](../packages/client/ui-conversation) | `client` | [`client-locale`](../packages/client/locale), [`client-runtime`](../packages/client/runtime), [`client-ui-primitives`](../packages/client/ui-primitives), [`client-ui-slash`](../packages/client/ui-slash), [`client-ui-slots`](../packages/client/ui-slots), [`invariants`](../packages/support/invariants), [`token-meter`](../packages/llm/token-meter) |
 | [`command-feedback`](../packages/feedback/command-feedback) | `feedback` | [`commands`](../packages/interaction/commands), [`invariants`](../packages/support/invariants), [`session`](../packages/core/session) |
 | [`host-directory-picker-auto`](../packages/host/directory-picker-auto) | `host` | [`host-directory-picker-browse`](../packages/host/directory-picker-browse), [`host-directory-picker-native`](../packages/host/directory-picker-native), [`host-webserver`](../packages/host/webserver), [`invariants`](../packages/support/invariants) |

docs/subsystems/core.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/core.md
-core.md: cc9cc30677b0b657492d8a5118489e8b801f3fd3
-core.zh.md: 60d363f9421b846ccc8096ef38861a8fdea255c0
+core.md: b09e5b4f0a076a7f95a751a6204836a81a4c31e9
+core.zh.md: 9058e08854423c42d69d23284d719718fa0b445c

docs/subsystems/core.md

@@ -314,6 +314,30 @@ The two core IDs are `CallId` (correlates a tool call with its result; dsh-llm)
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
+<a id="ctxagentdefaultmodel--agentdefaultmodelservice"></a>
+
+### `ctx.agentDefaultModel` — `AgentDefaultModelService`
+
+Owns the default model selection independently of any Host or transport. The composition entry remains usable without a settings provider; when one is mounted, its user layer is read live.
+
+```ts cordis-catalog
+/**
+ * Read the current default model selection.
+ * @returns a detached provider, model, and optional reasoning selection.
+ */
+currentSelection(): ModelSelection
+
+/**
+ * Save the complete default model selection. A deployment without a settings
+ * provider keeps its composition entry.
+ * @param next - resolved selection accepted by a front door.
+ * @returns fulfillment after the optional settings write settles.
+ */
+async saveSelection(next: ModelSelection): Promise<void>
+```
+
+Source: [`packages/core/agent-default-model/src/index.ts:64`](../../packages/core/agent-default-model/src/index.ts)
+
 <a id="ctxagentloop--agentloop"></a>
 
 ### `ctx.agentLoop` — `AgentLoop`

docs/subsystems/core.zh.md

@@ -322,6 +322,30 @@ type Branded<B extends string> = string & { readonly [BRAND]: B }
 
 Generated from source by `scripts/gen-cordis-catalog.ts` (verified fresh by `pnpm run verify-cordis-catalog` in doc-sync; regenerate with `pnpm run gen-cordis-catalog`) — this section is byte-identical in both language sides of the page. Signature blocks use a `ts cordis-catalog` fence and keep the original source JSDoc; dispatch modes are defined in the [primer](../cordis-primer.md#dispatch-modes), and the framework-inherited `ctx` surface lives in [cordis-api/inherited.md](../cordis-api/inherited.md).
 
+<a id="ctxagentdefaultmodel--agentdefaultmodelservice"></a>
+
+### `ctx.agentDefaultModel` — `AgentDefaultModelService`
+
+Owns the default model selection independently of any Host or transport. The composition entry remains usable without a settings provider; when one is mounted, its user layer is read live.
+
+```ts cordis-catalog
+/**
+ * Read the current default model selection.
+ * @returns a detached provider, model, and optional reasoning selection.
+ */
+currentSelection(): ModelSelection
+
+/**
+ * Save the complete default model selection. A deployment without a settings
+ * provider keeps its composition entry.
+ * @param next - resolved selection accepted by a front door.
+ * @returns fulfillment after the optional settings write settles.
+ */
+async saveSelection(next: ModelSelection): Promise<void>
+```
+
+Source: [`packages/core/agent-default-model/src/index.ts:64`](../../packages/core/agent-default-model/src/index.ts)
+
 <a id="ctxagentloop--agentloop"></a>
 
 ### `ctx.agentLoop` — `AgentLoop`

docs/user/guide/providers.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/user/guide/providers.md
-providers.md: 8b52044e64411e3081d56c1ee1849d0b24cd1cda
-providers.zh.md: 0e48c31c7006a5c9c0b014e46bc7915d625389db
+providers.md: ad0bd3696dbbdc4a89334932196d72a0afd3d209
+providers.zh.md: 84c01b9b79768f8e3b84faf3ff32bbdb0dfbe74d

docs/user/guide/providers.md

@@ -124,16 +124,16 @@ Under `dsh`, references resolve from the inherited environment, the Models page'
 
 A configured route appears in the web model picker and can be switched at any time, which is how most people use it.
 
-Switching there also sets the default: the model you pick becomes the one the next new session starts on, recorded in `settings.yaml` under `api-gateway`. There is no separate gesture.
+Switching there also sets the default: the model you pick becomes the one the next new session starts on, recorded in `settings.yaml` under `agent-default-model`. There is no separate gesture.
 
 ```yaml
-api-gateway:
+agent-default-model:
   provider: acme-gateway
   model: acme-large
   reasoningEffort: high   # optional
 ```
 
-A session that has already run a turn is never retargeted by it — that session derives its route from its own log, so changing the default only reaches sessions that have not started. The shipped fallback under this section is the `api-gateway` composition entry (`deepseek-official` / `deepseek-v4-flash`), which a self-assembled `cordis.yml` may override; a composition you assemble yourself — headless, for instance — sets `agent-loop`'s `agents` instead.
+After a session has run a turn, its own log remains authoritative for its model selection; the default applies only to sessions without a recorded request. The shipped fallback under this section is the base bundle's `agent-default-model` composition entry (`deepseek-official` / `deepseek-v4-flash`). A self-assembled `cordis.yml` mounts and configures `@deepseek-ai/dsh-agent-default-model`; both direct front doors and Host-backed front doors read that same service.
 
 If the provider a saved default names is later removed, the composer says **Select model** and refuses input until you pick one, rather than sending to a route nothing serves.
 

docs/user/guide/providers.zh.md

@@ -124,16 +124,16 @@ settings 段落**逐个提供方**地盖在 `cordis.yml` 的同名配置之上
 
 配好的路由会出现在 Web 的模型选择器里，随时可切，这也是最常用的方式。
 
-在那里切换同时也就选定了默认值：你选的模型会成为下一个新会话的起点，记录在 `settings.yaml` 的 `api-gateway` 段里。没有另一个单独的手势。
+在那里切换同时也就选定了默认值：你选的模型会成为下一个新会话的起点，记录在 `settings.yaml` 的 `agent-default-model` 段里。没有另一个单独的手势。
 
 ```yaml
-api-gateway:
+agent-default-model:
   provider: acme-gateway
   model: acme-large
   reasoningEffort: high   # optional
 ```
 
-已经跑过一个轮次的会话不会被它重定向——那个会话从自己的日志推导路由，因此改默认值只影响还没开始的会话。这个段落之下的出厂兜底是 `api-gateway` 组合条目（`deepseek-official` / `deepseek-v4-flash`），自行组装的 `cordis.yml` 可以覆盖它；自行组装的组合（例如 headless）改的则是 `agent-loop` 的 `agents`。
+会话跑过一轮后，其自身日志仍是模型选择的权威；默认值只适用于尚无请求记录的会话。这个段落之下的出厂兜底是 base 组合包的 `agent-default-model` 组合条目（`deepseek-official` / `deepseek-v4-flash`）。自行组装的 `cordis.yml` 会挂载并配置 `@deepseek-ai/dsh-agent-default-model`；直接前门与 Host 支撑的前门都读取同一服务。
 
 如果某个已存默认值指向的提供方后来被删掉了，输入框会显示**选择模型**并拒绝输入，而不是把消息发给一个没人服务的路由。
 

docs/user/guide/quickstart.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/user/guide/quickstart.md
-quickstart.md: 9d1a04f0a094919bb008a7e94564a6612e10732d
-quickstart.zh.md: 4c62b0a9deda3559f29ad214903ca55aea8b970e
+quickstart.md: ce196641f205324334533c025b4ac1dc791f857d
+quickstart.zh.md: 3a5d6d0748ec0c7ec83c74570d0fad1e8d66a97c

docs/user/guide/quickstart.md

@@ -39,7 +39,7 @@ Run a non-interactive task and print its final answer:
 pnpm run dsh run "summarize the architecture of this workspace"
 ```
 
-`dsh run` creates and persists a fresh session, prints the final assistant answer, and exits. While it runs, stderr prints the local browser URL where the session can be observed.
+`dsh run` creates and persists a fresh session, prints the final assistant answer, and exits. It starts no Web server or listening port, and a successful run leaves stderr empty.
 
 ## Step 3: use the Web UI
 
@@ -53,7 +53,7 @@ Open `http://127.0.0.1:3080`. The agent can read and write files, run commands,
 
 ## What happened
 
-`dsh run` boots the `headless` profile: [`dsh-base`](../../../packages/bundle/base/cordis.patch.yml), [`dsh-web-app`](../../../packages/bundle/web-app/cordis.patch.yml), and [`dsh-headless`](../../../packages/bundle/headless/cordis.patch.yml) compose over an empty root. `dsh web` uses the first two layers without the one-shot runner. Both select the DeepSeek model and capability plugins appropriate to their entry mode.
+`dsh run` boots the `headless` profile: [`dsh-base`](../../../packages/bundle/base/cordis.patch.yml) and [`dsh-headless`](../../../packages/bundle/headless/cordis.patch.yml) compose over an empty root, then the runner drives the core Agent and Session services directly. `dsh web` instead composes `dsh-base` with [`dsh-web-app`](../../../packages/bundle/web-app/cordis.patch.yml), which owns the Host, HTTP, and browser layers. Both read the same default DeepSeek model route from `dsh-base`.
 
 ## Next steps
 

docs/user/guide/quickstart.zh.md

@@ -39,7 +39,7 @@ DEEPSEEK_API_KEY=sk-your-key-here
 pnpm run dsh run "summarize the architecture of this workspace"
 ```
 
-`dsh run` 创建并持久化一个新会话，打印最终助手回答，然后退出。运行期间，stderr 会打印可用于观察该会话的本地浏览器 URL。
+`dsh run` 创建并持久化一个新会话，打印最终助手回答，然后退出。它不会启动 Web 服务器或监听端口；成功运行时 stderr 为空。
 
 ## 第三步：使用 Web UI
 
@@ -53,7 +53,7 @@ pnpm run dsh web
 
 ## 运行原理
 
-`dsh run` 启动 `headless` profile：[`dsh-base`](../../../packages/bundle/base/cordis.patch.yml)、[`dsh-web-app`](../../../packages/bundle/web-app/cordis.patch.yml) 和 [`dsh-headless`](../../../packages/bundle/headless/cordis.patch.yml) 在空根之上组合。`dsh web` 使用前两层，不包含一次性运行器。二者都会根据各自入口模式选择 DeepSeek 模型和能力插件。
+`dsh run` 启动 `headless` profile：[`dsh-base`](../../../packages/bundle/base/cordis.patch.yml) 和 [`dsh-headless`](../../../packages/bundle/headless/cordis.patch.yml) 在空根之上组合，随后 runner 直接驱动 core Agent 与 Session 服务。`dsh web` 则由 `dsh-base` 与 [`dsh-web-app`](../../../packages/bundle/web-app/cordis.patch.yml) 组合，后者拥有 Host、HTTP 与浏览器层。二者都从 `dsh-base` 读取同一个默认 DeepSeek 模型路由。
 
 ## 下一步
 

examples/headless-agent/tests/fixtures/cli-mock-llm.ts

@@ -29,6 +29,10 @@ class CliMockAdapter extends LlmAdapter {
   }
 
   async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    if (process.env.DSH_CLI_MOCK_FAILURE === '1') {
+      yield { type: 'finish', reason: { kind: 'error', failure: { code: 'SERVER', message: 'CLI mock provider failed' } } }
+      return
+    }
     const toolResult = options.messages.at(-1)?.content.find(block => block.type === 'tool-result')
     if (toolResult === undefined) {
       const args = JSON.stringify({ command: 'printf CLI_TOOL_ROUND_TRIP', description: 'Prove the CLI tool round trip.' })

examples/headless-agent/tests/fixtures/dsh-run.cordis.yml

@@ -1,4 +1,4 @@
-- id: api-gateway
+- id: agent-default-model
   config:
     provider: cli-mock
     model: cli-mock

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

@@ -54,6 +54,7 @@ const reasoningConfigPath = fileURLToPath(new URL('./fixtures/cli.cordis.yml', i
 const deepseekDefaultsConfigPath = fileURLToPath(new URL('./fixtures/deepseek-defaults.cordis.yml', import.meta.url))
 const dshRunOverlayPath = fileURLToPath(new URL('./fixtures/dsh-run.cordis.yml', import.meta.url))
 const dshRunSessionExpected = join(snapshotsDir, 'dsh-run', 'session.expected.jsonl')
+const dshRunFailureExpected = join(snapshotsDir, 'dsh-run', 'stderr.expected.txt')
 const cliMockLlmPluginPath = fileURLToPath(new URL('./fixtures/cli-mock-llm.ts', import.meta.url))
 const refreshing = process.env.DSH_SNAPSHOT === 'refresh'
 
@@ -196,6 +197,16 @@ async function persistedLogs(cwd: string, root: string = join(cwd, '.sessions'))
   }))
 }
 
+/** Install the keyless product-CLI adapter into the temporary headless profile. */
+async function prepareCliMockFixture(cwd: string): Promise<void> {
+  const fixtureDir = join(cwd, '.dsh', 'profiles', 'headless', 'snapshot-fixtures')
+  await mkdir(fixtureDir, { recursive: true })
+  await Promise.all([
+    copyFile(cliMockLlmPluginPath, join(fixtureDir, 'cli-mock-llm.ts')),
+    writeFile(join(fixtureDir, 'package.json'), '{"type":"module"}\n'),
+  ])
+}
+
 describe('headless stream-json snapshots', () => {
   it('runs one task through the product dsh run command', async () => {
     const task = 'Prove the product dsh run path with one real tool round trip.'
@@ -211,14 +222,7 @@ describe('headless stream-json snapshots', () => {
         DSH_TELEMETRY_DISABLED: '1',
         NODE_OPTIONS: [process.env.NODE_OPTIONS, '--disable-warning=ExperimentalWarning'].filter(Boolean).join(' '),
       },
-      prepare: async (cwd) => {
-        const fixtureDir = join(cwd, '.dsh', 'profiles', 'headless', 'snapshot-fixtures')
-        await mkdir(fixtureDir, { recursive: true })
-        await Promise.all([
-          copyFile(cliMockLlmPluginPath, join(fixtureDir, 'cli-mock-llm.ts')),
-          writeFile(join(fixtureDir, 'package.json'), '{"type":"module"}\n'),
-        ])
-      },
+      prepare: prepareCliMockFixture,
       inspect: async (cwd) => {
         const logs = await persistedLogs(cwd, join(cwd, '.dsh', 'sessions'))
         expect(logs).toHaveLength(1)
@@ -234,7 +238,28 @@ describe('headless stream-json snapshots', () => {
     })
 
     expect(result.stdout).toBe('CLI tool round trip complete: CLI_TOOL_ROUND_TRIP\n')
-    expect(result.stderr).toMatch(/^dsh: observing at http:\/\/127\.0\.0\.1:\d+\n$/u)
+    expect(result.stderr).toBe('')
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+
+  it('prints a terminal model failure through the product dsh run command', async () => {
+    const result = await runLoaderSmoke({
+      label: 'product dsh run model failure snapshot',
+      tempDirPrefix: 'headless-snapshot-dsh-run-failure-',
+      binScript: dshBinScript,
+      configPath: dshRunOverlayPath,
+      binArgs: ['run', '--patch', dshRunOverlayPath, 'Trigger the keyless model failure.'],
+      tsconfigPath,
+      expectedExitCode: 1,
+      env: {
+        DSH_CLI_MOCK_FAILURE: '1',
+        DSH_TELEMETRY_DISABLED: '1',
+        NODE_OPTIONS: [process.env.NODE_OPTIONS, '--disable-warning=ExperimentalWarning'].filter(Boolean).join(' '),
+      },
+      prepare: prepareCliMockFixture,
+    })
+
+    expect(result.stdout).toBe('\n')
+    await expect(result.stderr).toMatchFileSnapshot(dshRunFailureExpected)
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 
   it('prints the original Loader activation error through the assembled one-shot app', async () => {

examples/headless-agent/tests/snapshots/dsh-run/session.expected.jsonl

@@ -2,11 +2,11 @@
 {"type":"permission/preset","seq":0,"time":0,"data":{"preset":"danger-full-access"}}
 {"type":"sandbox/mode","seq":1,"time":0,"data":{"mode":"danger-full-access"}}
 {"type":"approval/policy","seq":2,"time":0,"data":{"policy":"never"}}
-{"type":"agent/inbox/spliced","seq":3,"time":0,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Prove the product dsh run path with one real tool round trip."}],"source":{"kind":"user","rpcId":"{{sessionId}}"},"role":"user","id":"{{sessionId}}"}]}}
+{"type":"agent/inbox/spliced","seq":3,"time":0,"data":{"target":"next-turn","start":0,"inserted":[{"content":[{"type":"text","text":"Prove the product dsh run path with one real tool round trip."}],"source":{"kind":"user"},"role":"user","id":"{{sessionId}}"}]}}
 {"type":"turn/start","seq":4,"time":0,"data":{"turn":1}}
 {"type":"agent/inbox/spliced","seq":5,"time":0,"data":{"target":"next-turn","start":0,"removedCount":1,"inserted":[]}}
 {"type":"step/start","seq":6,"time":0,"data":{"turn":1,"step":1}}
-{"type":"user/message","seq":7,"time":0,"data":{"content":[{"type":"text","text":"Prove the product dsh run path with one real tool round trip."}],"source":{"kind":"user","rpcId":"{{sessionId}}"},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}
+{"type":"user/message","seq":7,"time":0,"data":{"content":[{"type":"text","text":"Prove the product dsh run path with one real tool round trip."}],"source":{"kind":"user"},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}
 {"type":"user/message","seq":8,"time":0,"data":{"content":[{"type":"text","text":"Current runtime context. This snapshot supersedes earlier runtime-context snapshots.\n\nCurrent DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations.\n\nApproval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}],"source":{"kind":"plugin","plugin":"@deepseek-ai/dsh-system-prompt","form":"snapshot","sections":[{"name":"sandbox:policy","text":"Current DSH file policy: danger-full-access. The DSH file sandbox does not restrict file modifications by available operations."},{"name":"approval:policy","text":"Approval prompts are disabled in this session: actions that require approval are rejected automatically — do not request sandbox escalation (do not set `sandbox_permissions`)."}]},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}
 {"type":"session/title","seq":9,"time":0,"data":{"title":"Prove the product dsh run","messageSeqs":[7],"source":{"kind":"fallback"}}}
 {"type":"request/header","seq":10,"time":0,"data":{"header":{"config":{"provider":"cli-mock","model":"cli-mock","reasoningEffort":"high"},"adapterDefaults":{"reasoningEffort":true},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}

examples/headless-agent/tests/snapshots/dsh-run/stderr.expected.txt

@@ -0,0 +1 @@
+dsh: SERVER: CLI mock provider failed

knip.json

@@ -751,6 +751,11 @@
         "@cordisjs/.+"
       ]
     },
+    "packages/bundle/headless": {
+      "ignoreDependencies": [
+        "@deepseek-ai/dsh-code-runtime-worker"
+      ]
+    },
     "packages/bundle/web-app": {
       "ignoreDependencies": [
         "@deepseek-ai/.+"

packages/acp/acp/src/index.ts

@@ -66,7 +66,7 @@ function internalError(detail: string): RequestError {
   return RequestError.internalError(undefined, detail)
 }
 
-/** Plugin config: the provider/model target used for each ACP-created agent. */
+/** Plugin config: the provider/model selection used for each ACP-created agent. */
 export interface AcpConfig {
   /** Provider route for created agents. */
   provider?: string
@@ -100,7 +100,7 @@ interface SessionRecord {
 /**
  * Mount the automation-only ACP server.
  * @param ctx - Cordis context carrying the agent factory and session events.
- * @param config - Initial provider/model target and optional test transport.
+ * @param config - Initial provider/model selection and optional test transport.
  */
 export function apply(ctx: Context, config: AcpConfig): void {
   // ACP handlers execute outside this plugin's injection scope, so capture the

packages/boot/app-boot/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/boot/app-boot/README.md
-README.md: c256b89288e3e384c1dd3e64629a06d7cfef31f6
-README.zh.md: 6ff915c618f636f05f1f8591433feb3aef9151a8
+README.md: c060e99acb8cc40b8de92806727eea9e3723b7d2
+README.zh.md: 006eb0f0705cf4904afe90b7d4ffbeee347b4110

packages/boot/app-boot/README.md

@@ -33,7 +33,7 @@ This package carries no loader hooks and no dev-mode surface. The [`dsh` app](..
 
 ## Profiles
 
-A profile is a directory under `$DSH_HOME/profiles/<name>` (the Harness home resolves through [`resolveDshHome`](../../util/paths/README.md): `$DSH_HOME`, else `~/.dsh`) holding a `package.json` — out-of-tree plugin `dependencies` plus the profile manifest `dsh.profile` with its ordered `bundles` layer list — and the user's own `cordis.patch.yml`. A bundle is an npm package whose manifest declares `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`; `loadProfile` resolves each `dsh.profile.bundles` name two-anchored (the dsh installation first, then the profile directory) and fails loud on a listed package without a bundle declaration. `composeEntries` applies patch layers over an empty entry list through the include's own `applyEntryPatches`, so composition, flag derivation, and config dumps can never drift from what boots. `healProfilesModuleFallback` maintains the flat `$DSH_HOME/profiles/node_modules` directory — one symlink per package the installation's app and bundles depend on — so bare plugin names in any profile resolve through Node's ordinary parent-walk without pnpm ever managing in-box packages. `PROFILE_TEMPLATES` (`web`, `headless`) auto-initialize on first use; other names fail loud until `initProfile` creates them (the `dsh plugin` path).
+A profile is a directory under `$DSH_HOME/profiles/<name>` (the Harness home resolves through [`resolveDshHome`](../../util/paths/README.md): `$DSH_HOME`, else `~/.dsh`) holding a `package.json` — out-of-tree plugin `dependencies` plus the profile manifest `dsh.profile` with its ordered `bundles` layer list — and the user's own `cordis.patch.yml`. A bundle is an npm package whose manifest declares `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`; `loadProfile` resolves each `dsh.profile.bundles` name two-anchored (the dsh installation first, then the profile directory) and fails loud on a listed package without a bundle declaration. `composeEntries` applies patch layers over an empty entry list through the include's own `applyEntryPatches`, so composition, flag derivation, and config dumps cannot drift from what boots. `healProfilesModuleFallback` maintains the flat `$DSH_HOME/profiles/node_modules` directory — one symlink per package the installation's app and bundles depend on — so bare plugin names in any profile resolve through Node's ordinary parent-walk without pnpm managing in-box packages. `PROFILE_TEMPLATES` (`web`, `headless`) auto-initialize on first use; other names fail loud until `initProfile` creates them (the `dsh plugin` path). `loadProfile` normalizes an exact installation-owned bundle tuple to its shipped template while preserving every other manifest field; any extra, missing, or reordered entry makes the list user-owned and leaves it unchanged.
 
 User-level machine-local preferences also live in the Harness home:
 

packages/boot/app-boot/README.zh.md

@@ -33,7 +33,7 @@ Loader 并发挂载各个条目，因此当其他环节失败时，某个界面
 
 ## Profiles
 
-profile 是位于 `$DSH_HOME/profiles/<name>` 下的目录（Harness home 由 [`resolveDshHome`](../../util/paths/README.md) 解析：先取 `$DSH_HOME`，否则取 `~/.dsh`），其中包含一个 `package.json`（树外插件 `dependencies`，加上 profile manifest `dsh.profile` 及其有序的 `bundles` 层列表）和用户自己的 `cordis.patch.yml`。组合包是在 manifest 中声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包；`loadProfile` 以双锚点解析每个 `dsh.profile.bundles` 名称（先从 dsh 安装目录，再从 profile 目录），列出的包若没有组合包声明则明确报错。`composeEntries` 通过 include 自己的 `applyEntryPatches` 在空条目列表之上应用各 patch 层，因此组合、标志推导和配置 dump 绝不会与实际启动内容发生偏离。`healProfilesModuleFallback` 维护扁平的 `$DSH_HOME/profiles/node_modules` 目录（安装目录的应用与各组合包依赖的每个包对应一个符号链接），使任意 profile 中的裸插件名都能经 Node 常规的逐级向上查找解析，而 pnpm 从不管理随安装内置的包。`PROFILE_TEMPLATES`（`web`、`headless`）在首次使用时自动初始化；其他名称在 `initProfile` 创建之前都会明确报错（即 `dsh plugin` 路径）。
+profile 是位于 `$DSH_HOME/profiles/<name>` 下的目录（Harness home 由 [`resolveDshHome`](../../util/paths/README.md) 解析：先取 `$DSH_HOME`，否则取 `~/.dsh`），其中包含一个 `package.json`（树外插件 `dependencies`，加上 profile manifest `dsh.profile` 及其有序的 `bundles` 层列表）和用户自己的 `cordis.patch.yml`。组合包是在 manifest 中声明 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` 的 npm 包；`loadProfile` 以双锚点解析每个 `dsh.profile.bundles` 名称（先从 dsh 安装目录，再从 profile 目录），列出的包若没有组合包声明则明确报错。`composeEntries` 通过 include 自己的 `applyEntryPatches` 在空条目列表之上应用各 patch 层，因此组合、标志推导和配置 dump 绝不会与实际启动内容发生偏离。`healProfilesModuleFallback` 维护扁平的 `$DSH_HOME/profiles/node_modules` 目录（安装目录的应用与各组合包依赖的每个包对应一个符号链接），使任意 profile 中的裸插件名都能经 Node 常规的逐级向上查找解析，而 pnpm 从不管理随安装内置的包。`PROFILE_TEMPLATES`（`web`、`headless`）在首次使用时自动初始化；其他名称在 `initProfile` 创建之前都会明确报错（即 `dsh plugin` 路径）。`loadProfile` 会将与安装自有组合包元组完全一致的列表规范化为随发行版交付的模板，同时保留 manifest 中其他所有字段；一旦条目有任何额外、缺失或重排，该列表就归用户所有并保持不变。
 
 用户级的机器本地偏好同样位于 Harness home 中：
 

packages/boot/app-boot/src/profile.ts

@@ -114,6 +114,11 @@ export function resolveProfileDir(name: string, home: string = resolveDshHome())
 /** The shipped profile templates auto-initialized on first use, by name. */
 export const PROFILE_TEMPLATES: Record<string, readonly string[]> = {
   web: ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app'],
+  headless: ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-headless'],
+}
+
+/** Installation-owned bundle tuples normalized to the shipped template. */
+const INSTALLATION_OWNED_PROFILE_TUPLES: Record<string, readonly string[]> = {
   headless: ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app', '@deepseek-ai/dsh-headless'],
 }
 
@@ -279,6 +284,32 @@ export function writeProfileManifest(dir: string, manifest: ProfileManifest): vo
   writeFileSync(join(dir, 'package.json'), JSON.stringify(manifest, undefined, 2) + '\n')
 }
 
+/** Return whether two bundle lists have the same values in the same order. */
+function sameBundles(left: readonly string[], right: readonly string[]): boolean {
+  return left.length === right.length && left.every((value, index) => value === right[index])
+}
+
+/**
+ * Normalize an exact installation-owned bundle tuple to its shipped template
+ * while preserving every other manifest field. Any other list is user-owned.
+ */
+function normalizeShippedProfile(name: string, dir: string, manifest: ProfileManifest): ProfileManifest {
+  const installationOwned = INSTALLATION_OWNED_PROFILE_TUPLES[name]
+  const current = PROFILE_TEMPLATES[name]
+  const bundles = manifest.dsh?.profile?.bundles
+  if (installationOwned === undefined || current === undefined || bundles === undefined
+    || !sameBundles(bundles, installationOwned)) return manifest
+  const normalized: ProfileManifest = {
+    ...manifest,
+    dsh: {
+      ...manifest.dsh,
+      profile: { ...manifest.dsh?.profile, bundles: [...current] },
+    },
+  }
+  writeProfileManifest(dir, normalized)
+  return normalized
+}
+
 /**
  * Resolve a package's root directory from one anchor without depending on the
  * package exporting `./package.json` (`require.resolve` would need that):
@@ -350,7 +381,7 @@ export function loadProfile(
     }
     initProfile(dir, template)
   }
-  const manifest = readProfileManifest(binName, dir)
+  const manifest = normalizeShippedProfile(name, dir, readProfileManifest(binName, dir))
   // A hand-written profile manifest may omit the dsh section entirely.
   const bundles = manifest.dsh?.profile?.bundles ?? []
   const layers = bundles.map((packageName): ProfileLayer => {

packages/boot/app-boot/tests/profile.spec.ts

@@ -161,6 +161,33 @@ describe('loadProfile', () => {
       .toEqual([...PROFILE_TEMPLATES.web ?? []])
   })
 
+  it('normalizes only the exact installation-owned headless bundle tuple', () => {
+    const anchor = stageInstallation({
+      '@deepseek-ai/dsh-base': { patch: '[]\n' },
+      '@deepseek-ai/dsh-web-app': { patch: '[]\n' },
+      '@deepseek-ai/dsh-headless': { patch: '[]\n' },
+      'custom-bundle': { patch: '[]\n' },
+    })
+    const home = tmp()
+    const stock = resolveProfileDir('headless', home)
+    initProfile(stock, [
+      '@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app', '@deepseek-ai/dsh-headless',
+    ])
+    loadProfile('t', 'headless', anchor, home)
+    expect(readProfileManifest('t', stock).dsh?.profile?.bundles)
+      .toEqual(['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-headless'])
+
+    const customHome = tmp()
+    const custom = resolveProfileDir('headless', customHome)
+    initProfile(custom, [
+      '@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app', '@deepseek-ai/dsh-headless', 'custom-bundle',
+    ])
+    loadProfile('t', 'headless', anchor, customHome)
+    expect(readProfileManifest('t', custom).dsh?.profile?.bundles).toEqual([
+      '@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app', '@deepseek-ai/dsh-headless', 'custom-bundle',
+    ])
+  })
+
   it('fails loud when a listed bundle declares no dsh.bundle', () => {
     const anchor = stageInstallation({ 'not-a-bundle': {} })
     const home = tmp()

packages/bundle/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/README.md
-README.md: af06fe921a66378894a4ab0174ef403499f5f68c
-README.zh.md: b9656649782a638a3b39b4e1e6d330476b0732ba
+README.md: 696aa9ef7bbed23774f2b9ab2648ca83edcf0978
+README.zh.md: 2bb22c7949d759f404288548ea0eccfa0aac866b

packages/bundle/README.md

@@ -8,6 +8,6 @@ Profile bundles: npm packages whose manifest declares `"dsh": { "bundle": { "pat
 |---|---|---|
 | [`base/`](base/README.md) | The shared dsh core every profile applies first | — (patch only) |
 | [`web-app/`](web-app/README.md) | Browser surface: web patch layer + runtime glue plugin | mounts rows |
-| [`headless/`](headless/README.md) | One-shot task mode over base + web-app | mounts `headless-runner` |
+| [`headless/`](headless/README.md) | Direct one-shot task mode over base, with no Host or Web layer | mounts `headless-runner` |
 
 In-box bundles resolve from the dsh installation; out-of-tree bundles install into a profile through `dsh plugin --profile <name> add <package>`.

packages/bundle/README.zh.md

@@ -8,6 +8,6 @@ Profile 组合包：在 manifest（元数据清单）中声明 `"dsh": { "bundle
 |---|---|---|
 | [`base/`](base/README.md) | 每个 profile 最先应用的共享 dsh 核心 | —（仅 patch） |
 | [`web-app/`](web-app/README.md) | 浏览器表层：web patch 层 + 运行时粘合插件 | 挂载多条配置行 |
-| [`headless/`](headless/README.md) | 叠加在 base + web-app 之上的一次性任务模式 | 挂载 `headless-runner` |
+| [`headless/`](headless/README.md) | 直接运行在 base 之上的一次性任务模式，不含 Host 或 Web 层 | 挂载 `headless-runner` |
 
 内置组合包从 dsh 安装目录解析；树外（out-of-tree）组合包通过 `dsh plugin --profile <name> add <package>` 安装进 profile。

packages/bundle/base/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/base/README.md
-README.md: 301d397d4c87687b382665cf63af47ab5e3f85be
-README.zh.md: f007bc817b6cbad84725fe8abe72549cf67d8cd7
+README.md: fb003908a262dc21edd3c9d49c972e487534f367
+README.zh.md: 13e64db6d34374fac63bf9bfd60544fc46b86f35

packages/bundle/base/README.md

@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-The shared dsh core as a profile bundle: [`cordis.patch.yml`](cordis.patch.yml) inserts every base plugin row — model adapters, tools, persistence, policy, settings/credentials, repository Plugins, telemetry — over the empty profile root, as the first layer of every profile's `dsh.profile.bundles` list. Later bundle layers (e.g. [`dsh-web-app`](../web-app/README.md)) and the user's profile `cordis.patch.yml` override these rows by id; a patch replaces a row's whole `config`, so mode-specific values live in mode bundles, not here. The package has no runtime API; the profile composer resolves the patch through the `dsh.bundle.patch` manifest field, never through code.
+The shared dsh core as a profile bundle: [`cordis.patch.yml`](cordis.patch.yml) inserts every base plugin row — model adapters, the shared [`agent-default-model`](../../core/agent-default-model/README.md) selection, tools, persistence, policy, settings/credentials, repository Plugins, telemetry — over the empty profile root, as the first layer of every profile's `dsh.profile.bundles` list. Later bundle layers (e.g. [`dsh-web-app`](../web-app/README.md)) and the user's profile `cordis.patch.yml` override these rows by id; a patch replaces a row's whole `config`, so mode-specific values live in mode bundles, not here. The package has no runtime API; the profile composer resolves the patch through the `dsh.bundle.patch` manifest field, never through code.
 
 The row set and its rationale are documented inline in the patch file; the [generated composition graph](../../../apps/cli/composition.md) renders it.
 

packages/bundle/base/README.zh.md

@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-以 profile 组合包形式交付的共享 dsh 核心：[`cordis.patch.yml`](cordis.patch.yml) 在空的 profile 根之上插入全部基础插件行——模型适配器、工具、持久化、策略、settings／credentials、repository 插件、遥测——作为每个 profile 的 `dsh.profile.bundles` 列表中的第一层。后续的组合包层（例如 [`dsh-web-app`](../web-app/README.md)）和用户 profile 的 `cordis.patch.yml` 按 id 覆盖这些行；patch 会替换目标行的整个 `config`，因此模式专属的值放在各模式组合包中，而不是这里。该包没有运行时 API；profile 组合器通过 manifest（元数据清单）的 `dsh.bundle.patch` 字段解析 patch，绝不通过代码。
+以 profile 组合包形式交付的共享 dsh 核心：[`cordis.patch.yml`](cordis.patch.yml) 在空的 profile 根之上插入全部基础插件行——模型适配器、共享的 [`agent-default-model`](../../core/agent-default-model/README.md) 选择、工具、持久化、策略、settings／credentials、repository 插件、遥测——作为每个 profile 的 `dsh.profile.bundles` 列表中的第一层。后续的组合包层（例如 [`dsh-web-app`](../web-app/README.md)）和用户 profile 的 `cordis.patch.yml` 按 id 覆盖这些行；patch 会替换目标行的整个 `config`，因此模式专属的值放在各模式组合包中，而不是这里。该包没有运行时 API；profile 组合器通过 manifest（元数据清单）的 `dsh.bundle.patch` 字段解析 patch，绝不通过代码。
 
 行集合及其设计依据以行内注释写在 patch 文件里；[生成的组合图](../../../apps/cli/composition.md)负责渲染它。
 

packages/bundle/base/cordis.patch.yml

@@ -65,6 +65,14 @@
     - id: agent
       name: '@deepseek-ai/dsh-agent'
 
+    # The transport-independent default for Agents created by front doors.
+    # Settings may supply a saved selection; consumers read it at creation time.
+    - id: agent-default-model
+      name: '@deepseek-ai/dsh-agent-default-model'
+      config:
+        provider: deepseek-official
+        model: deepseek-v4-flash
+
     - id: tasks
       name: '@deepseek-ai/dsh-tasks-local'
 

packages/bundle/base/package.json

@@ -35,6 +35,7 @@
     "@cordisjs/plugin-hmr": "workspace:*",
     "@cordisjs/plugin-timer": "workspace:*",
     "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-agent-default-model": "workspace:^",
     "@deepseek-ai/dsh-agent-loop": "workspace:^",
     "@deepseek-ai/dsh-bash-env": "workspace:^",
     "@deepseek-ai/dsh-bash-sandbox": "workspace:^",

packages/bundle/headless/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/headless/README.md
-README.md: 661b377817482d22f58f22b573075722646729a2
-README.zh.md: 8d3ed1c0f99b9245d27c68887aa7b2301368a17b
+README.md: fbdf80be3d587b0ef526c1a36952a761035f7312
+README.zh.md: fa1b5ac280eb9020d71035cc6b09ab2508bff45d

packages/bundle/headless/README.md

@@ -2,11 +2,13 @@
 
 English | [中文](README.zh.md)
 
-The dsh one-shot bundle. [`cordis.patch.yml`](cordis.patch.yml) rides over [`dsh-base`](../base/README.md) + [`dsh-web-app`](../web-app/README.md): it moves the webserver to an OS-assigned port (parallel runs never collide), silences the URL line, and inserts this package's `headless-runner` plugin (config `{task}`). The runner drives one task turn through the in-process API carrier (`InProcessApiClient` over `toFetchHandler(ctx.apiProxy)`, so the full wire chain — serialization, zod, SSE framing — really runs), waits at idle until that mux has consumed the session's final event sequence, aggregates the turn's final assistant text, writes it to stdout, and requests exit (completed → 0, else 1) through the launcher-provided `ctx.headlessIo` seam. The Web composition stays mounted, so the running session is observable in a browser at the stderr-announced URL. The launcher patches the task text in (`dsh run "task"`), and fails loud when the selected profile lacks this row.
+The dsh one-shot bundle. [`cordis.patch.yml`](cordis.patch.yml) rides directly over [`dsh-base`](../base/README.md): it supplies the coding persona and tool mode, disables HMR, mounts Code Mode's worker as a core execution capability, and inserts this package's `headless-runner` plugin (config `{task}`). It mounts no Host, HTTP server, Web runtime, or browser plugin.
+
+After the Loader settles, the runner reads the shared [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md), creates one fresh persisted Agent through `ctx.agents`, submits the task as an ordinary user message, and waits for quiescence. It flushes the Session before folding the owned durable event interval, writes the last non-empty assistant text to stdout, and requests exit through the launcher-provided `ctx.headlessIo` seam (final `turn/end` completed → 0, otherwise 1). A terminal `error` reason also writes its code and message to stderr; successful runs keep stderr empty. The process opens no listening port. The launcher patches the task text in (`dsh run "task"`) and fails loud when the selected profile lacks this row.
 
 ## Model Experience
 
-None, as the runner submits the task as an ordinary user message over the shared composition; prompts and tools belong to the base/web bundles.
+None, as the runner submits the task as an ordinary user message; prompts and tools belong to the base and headless bundle rows.
 
 #### KV Cache effect
 
@@ -14,5 +16,5 @@ None; the runner adds nothing to the request prefix.
 
 ## Known Limitations and Deferred Work
 
-- **One turn only** — the runner anchors on the first message-triggered turn and exits at its end; queued follow-ups and multi-turn tasks are out of scope.
+- **One submitted task only** — the runner has no interactive follow-up surface; it waits through any work the Agent completes before returning to idle and prints the last non-empty assistant message in that interval.
 - **`ctx.headlessIo` is launcher-owned** — booting the headless profile outside the `dsh` launcher fails loud at activation until the host provides the seam.

packages/bundle/headless/README.zh.md

@@ -2,11 +2,13 @@
 
 [English](README.md) | 中文
 
-dsh 一次性任务组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在 [`dsh-base`](../base/README.md) + [`dsh-web-app`](../web-app/README.md) 之上：把 webserver 移到 OS 分配的端口（并行运行绝不冲突），关闭 URL 行输出，并插入本包的 `headless-runner` 插件（配置为 `{task}`）。runner 通过进程内 API 载体（架在 `toFetchHandler(ctx.apiProxy)` 之上的 `InProcessApiClient`，因此序列化、zod、SSE（Server-Sent Events）帧封装这整条 wire 链路都会真实运行）驱动一个任务轮次，在 idle 时等待该 mux 消费完会话的最终事件序号，再聚合该轮次最终的 assistant 文本，写到 stdout，并经启动器提供的 `ctx.headlessIo` seam 请求退出（完成 → 0，否则 1）。Web 组合保持挂载，因此运行中的会话可在浏览器中通过 stderr 公告的 URL 观察。启动器把任务文本 patch 进来（`dsh run "task"`）；若所选 profile 缺少该行，则显式报错。
+dsh 一次性任务组合包。[`cordis.patch.yml`](cordis.patch.yml) 直接叠加在 [`dsh-base`](../base/README.md) 之上：提供编码 persona 和工具模式、禁用 HMR（热模块替换）、将 Code Mode 的 worker 作为核心执行能力挂载，并插入本包的 `headless-runner` 插件（配置为 `{task}`）。它不挂载任何 Host、HTTP server、Web runtime 或浏览器插件。
+
+Loader 结算后，runner 读取共享的 [`ctx.agentDefaultModel`](../../core/agent-default-model/README.md)，通过 `ctx.agents` 创建一个全新的持久化 Agent（智能体），将任务作为普通用户消息提交，并等待完全停稳。它对 Session 执行 flush 后再汇总自身持有的持久化事件区间，将最后一条非空 assistant 文本写入 stdout，再经启动器提供的 `ctx.headlessIo` seam 请求退出（最终 `turn/end` 完成 → 0，否则为 1）。最终 reason 为 `error` 时，还会将持久化的 code 与 message 写入 stderr；成功运行时 stderr 保持为空。进程不会打开监听端口。启动器把任务文本 patch 进来（`dsh run "task"`）；若所选 profile 缺少该行，则显式报错。
 
 ## 模型体验
 
-无。runner 把任务作为普通用户消息经共享组合提交；提示词与工具归 base／web 组合包所有。
+无影响，因为 runner 把任务作为普通用户消息提交；提示词与工具归 base 和 headless 组合包中的相应行所有。
 
 #### KV Cache 影响
 
@@ -14,5 +16,5 @@ dsh 一次性任务组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在
 
 ## 已知限制与延期工作
 
-- **只运行一个轮次**：runner 锚定第一个由消息触发的轮次，并在其结束时退出；排队的后续消息与多轮任务不在范围内。
+- **只提交一个任务**：runner 没有用于交互式后续输入的 surface；它会等待 Agent 在返回 idle 前完成的所有工作，并打印该区间内最后一条非空 assistant 消息。
 - **`ctx.headlessIo` 由启动器持有**：在 `dsh` 启动器之外启动 headless profile 会在激活时明确报错，直到宿主提供该 seam。

packages/bundle/headless/cordis.patch.yml

@@ -1,21 +1,26 @@
-# The dsh-headless bundle patch: one-shot task mode over dsh-base +
-# dsh-web-app. The web composition stays mounted (the session is observable
-# in a browser while it runs); this layer silences the URL line and the
-# GUI-orientation surface context (this user is not in the GUI), moves the
-# webserver to an OS-assigned port so parallel headless runs never collide,
-# and mounts the one-shot runner. The launcher patches the runner's `task`.
+# The dsh-headless bundle patch: one-shot task mode directly over dsh-base.
+# It mounts no Host, HTTP server, Web runtime, or browser plugin. The launcher
+# patches the runner's `task`; the direct driver creates an Agent through the
+# core registry and prints the final durable assistant message.
 
-- id: webserver
+- id: system-prompt
   config:
-    host: 127.0.0.1
-    port: 0
+    persona: >-
+      You are a coding agent powered by the {{model}} model. Your working directory is {{cwd}}.
 
-- id: web-runtime
+# One-shot runs never watch or reload their composition.
+- id: hmr
+  disabled: true
+
+- id: tools
   config:
-    mode: production
-    printUrl: false
-    surfaceContext: false
+    # Keep the same temporary process-wide Code Mode opt-in as the Web surface.
+    mode: !!js process.env.DSH_TOOLS_MODE
 
 - insert:
+    # Code Mode is a core execution capability, not a Web component.
+    - id: code-runtime
+      name: '@deepseek-ai/dsh-code-runtime-worker'
+
     - id: headless-runner
       name: '@deepseek-ai/dsh-headless'

packages/bundle/headless/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-headless",
-  "description": "The dsh one-shot bundle: a patch layer over dsh-base + dsh-web-app plus the runner plugin driving one task turn through the in-process API carrier",
+  "description": "The dsh one-shot bundle: a direct core Agent/Session runner over dsh-base with no Host, HTTP, or browser layer",
   "version": "0.0.1",
   "private": true,
   "type": "module",
@@ -32,22 +32,23 @@
     }
   },
   "dependencies": {
+    "@deepseek-ai/dsh-code-runtime-worker": "workspace:^",
     "schemastery": "^3.18.0"
   },
   "peerDependencies": {
     "@deepseek-ai/dsh-agent": "^0.0.1",
-    "@deepseek-ai/dsh-host-apiproxy": "^0.0.1",
-    "@deepseek-ai/dsh-host-webserver": "^0.0.1",
+    "@deepseek-ai/dsh-agent-default-model": "^0.0.1",
     "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
     "@deepseek-ai/dsh-session": "^0.0.1",
     "cordis": "^4.0.0-rc.7"
   },
   "devDependencies": {
     "@cordisjs/plugin-loader": "workspace:^",
     "@deepseek-ai/dsh-agent": "workspace:^",
-    "@deepseek-ai/dsh-host-apiproxy": "workspace:^",
-    "@deepseek-ai/dsh-host-webserver": "workspace:^",
+    "@deepseek-ai/dsh-agent-default-model": "workspace:^",
     "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
     "@deepseek-ai/dsh-session": "workspace:^",
     "cordis": "^4.0.0-rc.7"
   }

packages/bundle/headless/src/index.ts

@@ -1,36 +1,33 @@
 /**
- * @deepseek-ai/dsh-headless — the one-shot headless bundle: the bundle patch
- * (`cordis.patch.yml`) rides over dsh-base + dsh-web-app (the headless
- * session is web-observable while it runs — same composition), and this
- * runner plugin drives one task through the in-process API carrier
- * (InProcessApiClient over toFetchHandler(ctx.apiProxy), so the full wire
- * chain — serialization, zod, SSE framing — really runs), prints the final
- * assistant text at agent quiescence, and exits (completed → 0, else 1). The
- * task text arrives as launcher-patched config (`dsh run "task"`).
+ * @deepseek-ai/dsh-headless — one-shot direct Agent driver. The bundle patch
+ * rides over dsh-base without Host, HTTP, or browser plugins; this runner
+ * creates one Agent through the core registry, drives the task to quiescence,
+ * flushes its Session, prints the final assistant text, and exits.
+ *
  * @module @deepseek-ai/dsh-headless
  */
 
+import { randomUUID } from 'node:crypto'
 import type { Context } from 'cordis'
 import z from 'schemastery'
-import { InProcessApiClient, toFetchHandler } from '@deepseek-ai/dsh-host-apiproxy'
-// Empty type imports carry the httpServer and agent/status Context merges used below.
-import type {} from '@deepseek-ai/dsh-host-webserver'
-import type {} from '@deepseek-ai/dsh-agent'
+import { installModelSelection } from '@deepseek-ai/dsh-agent'
+import type { ModelSelectionRef } from '@deepseek-ai/dsh-agent'
+import type {} from '@deepseek-ai/dsh-agent-default-model'
+import { createUserMessage } from '@deepseek-ai/dsh-llm'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
 // Empty type import carries the loader Context merge for the settlement await.
 import type {} from '@cordisjs/plugin-loader'
-import type { MuxFrame } from '@deepseek-ai/dsh-host-apiproxy/api'
-import type { RpcRequest, RpcResponse } from '@deepseek-ai/dsh-host-apiproxy/api/rpc'
-import type { SessionId } from '@deepseek-ai/dsh-session'
 
 /** Stable Cordis plugin name. */
 export const name = 'headless-runner'
 
-/** Services required before the one-shot turn can start. */
-export const inject = ['apiProxy', 'httpServer']
+/** Core services required before the one-shot turn can start. */
+export const inject = ['agentDefaultModel', 'agents', 'sessions']
 
 /** Plugin config: the task, patched in by the launcher. */
 export interface Config {
-  /** The prompt text for the single turn. */
+  /** The prompt text for the single run. */
   task: string
 }
 
@@ -38,16 +35,15 @@ export const Config: z<Config> = z.object({
   task: z.string().required(),
 })
 
-/** Outcome of one headless run: aggregated final text plus the last turn-end reason kind. */
-interface TurnOutcome {
+/** Outcome of one owned run interval. */
+interface RunOutcome {
   text: string
-  reason: string
+  reason: SessionEvent<'turn/end'>['data']['reason'] | undefined
 }
 
 /**
- * The process-facing effects of one run, injectable for tests: output
- * streams and the exit request (the launcher wires it to its bounded
- * shutdown controller).
+ * Process-facing effects of one run, injectable for tests. The launcher owns
+ * bounded tree shutdown and wires `exit()` to it.
  */
 export interface HeadlessIo {
   stdout: { write(chunk: string): unknown }
@@ -56,127 +52,94 @@ export interface HeadlessIo {
   exit(code: number): void
 }
 
-/** Host seam: the launcher provides the exit wiring before the tree mounts. */
 declare module 'cordis' {
   interface Context {
-    /** Process-facing effects for the one-shot headless runner. */
+    /** Process-facing effects provided before the headless tree mounts. */
     headlessIo?: HeadlessIo
   }
 }
 
-/** Unwrap an RpcResponse or fail loud: business errors print and exit 1. */
-async function unwrap<T>(response: RpcResponse<T>, io: HeadlessIo): Promise<T> {
-  if (response.result.ok) return response.result.value
-  const { code, message } = response.result.error
-  io.stderr.write(`dsh: ${code}: ${message}\n`)
+/** Aggregate the last assistant text and turn outcome in one owned interval. */
+function summarize(events: readonly SessionEvent[], firstSeq: number): RunOutcome {
+  let started = false
+  let text = ''
+  let reason: SessionEvent<'turn/end'>['data']['reason'] | undefined
+  for (const event of events) {
+    if (event.seq < firstSeq) continue
+    if (event.type === 'turn/start') {
+      started = true
+      continue
+    }
+    if (!started) continue
+    if (event.type === 'assistant/message') {
+      const joined = event.data.message.content
+        .filter(block => block.type === 'text')
+        .map(block => block.text)
+        .join('')
+      if (joined !== '') text = joined
+    }
+    if (event.type === 'turn/end') reason = event.data.reason
+  }
+  return { text, reason }
+}
+
+/** Report an unexpected direct-driver failure and request a failing exit. */
+function fail(io: HeadlessIo, error: unknown): void {
+  io.stderr.write(`dsh: ${error instanceof Error ? error.message : String(error)}\n`)
   io.exit(1)
-  // Exit is asynchronous (bounded tree disposal); park this turn forever so
-  // no further request rides a session that is already being torn down.
-  return new Promise<never>(() => {})
 }
 
 /**
- * Consume mux frames until the agent reaches idle, per the one-shot CLI
- * idle-to-idle contract: the stream opens immediately before the prompt, and
- * its first observed turn/start begins the task. Text is the last committed
- * assistant message of the whole interval (steering or injected work may run
- * further turns before quiescence), and the outcome reason is the final
- * turn/end's kind. Idleness is signalled out of band by the caller's
- * `agent/status` subscription; the stream itself carries no status frame.
- * @param frames - the mux stream opened before the prompt.
- * @param sessionId - the headless session.
- * @param idle - resolves to the final session-event sequence when the agent reaches quiescence.
- * @param io - process-facing effects for stream diagnostics.
- * @returns the aggregated outcome.
+ * Run one task through a freshly created Agent and request process exit.
+ * @param ctx - plugin context carrying the Agent, default model, Session, and launcher IO services.
+ * @param task - one-shot task text.
+ * @param io - process-facing effects.
  */
-async function consumeUntilIdle(
-  frames: AsyncIterable<RpcRequest<MuxFrame>>,
-  sessionId: SessionId,
-  idle: Promise<number>,
-  io: HeadlessIo,
-): Promise<TurnOutcome> {
-  let started = false
-  let text = ''
-  let reason: string = 'error'
-  let observedSeq = -1
-  let resolveProgress: (() => void) | undefined
-  const streamDone = (async () => {
-    try {
-      for await (const frame of frames) {
-        const payload = frame.payload
-        if (payload.type === 'stream/error') return
-        if (payload.type !== 'session/event' || payload.sessionId !== sessionId) continue
-        const event = payload.event
-        observedSeq = event.seq
-        resolveProgress?.()
-        resolveProgress = undefined
-        if (event.type === 'turn/start') {
-          started = true
-          continue
-        }
-        if (!started) continue
-        if (event.type === 'assistant/message') {
-          const joined = event.data.message.content.filter(block => block.type === 'text').map(block => block.text).join('')
-          if (joined !== '') text = joined
-        }
-        if (event.type === 'turn/end') reason = event.data.reason.kind
-      }
-    } catch (error: unknown) {
-      io.stderr.write(`dsh: event stream failed: ${String(error)}\n`)
-    }
-  })()
-  const streamEnded = streamDone.then(() => 'ended' as const)
-  const idleSeq = await idle
-  while (observedSeq < idleSeq) {
-    const progress = new Promise<'progress'>((resolve) => { resolveProgress = () => { resolve('progress') } })
-    if (await Promise.race([progress, streamEnded]) === 'ended') break
+async function run(ctx: Context, task: string, io: HeadlessIo): Promise<void> {
+  // Loader siblings mount concurrently. Await the complete application before
+  // creating an Agent so its scoped tools and adapters are not half-composed.
+  await ctx.get('loader')?.await()
+  const agents = ctx.get('agents')
+  const defaultModel = ctx.get('agentDefaultModel')
+  const sessions = ctx.get('sessions')
+  // Early process shutdown can dispose the tree while settlement is pending.
+  if (agents === undefined || defaultModel === undefined || sessions === undefined) return
+
+  const selection = defaultModel.currentSelection()
+  const { agent } = await agents.create({
+    sessionId: SessionId(`session-${randomUUID()}`),
+    meta: { cwd: process.cwd() },
+    agentOptions: { provider: selection.provider, model: selection.model },
+    setup: (agentCtx) => {
+      const selected: ModelSelectionRef = { current: selection, assembled: undefined }
+      installModelSelection(agentCtx, selected)
+    },
+  })
+  await agent.whenIdle()
+  const firstSeq = agent.session.seq
+  agent.followup(createUserMessage({
+    content: [{ type: 'text', text: task }],
+    source: { kind: 'user' },
+  }))
+  await agent.whenIdle()
+  await sessions.flush(agent.session)
+  const outcome = summarize(agent.session.events, firstSeq)
+  io.stdout.write(outcome.text + '\n')
+  if (outcome.reason?.kind === 'error') {
+    io.stderr.write(`dsh: ${outcome.reason.error.code}: ${outcome.reason.error.message}\n`)
   }
-  return { text, reason }
+  io.exit(outcome.reason?.kind === 'completed' ? 0 : 1)
 }
 
 /**
- * Run one headless task to quiescence and request exit (completed → 0, else 1).
- * @param ctx - plugin context carrying apiProxy, httpServer, and the launcher's headlessIo.
- * @param config - validated {@link Config}.
+ * Mount the one-shot direct driver.
+ * @param ctx - plugin context carrying core services and the launcher-owned IO seam.
+ * @param config - validated task config.
  */
 export function apply(ctx: Context, config: Config): void {
   const io = ctx.headlessIo
   if (io === undefined) {
     throw new Error('headless-runner: the launcher must provide ctx.headlessIo before the tree mounts')
   }
-  // Fire-and-forget by design: the run outlives plugin activation, and every
-  // failure path inside ends in io.exit, not a rejection.
-  void (async () => {
-    // The Loader mounts sibling rows concurrently and this plugin's inject
-    // gate covers only apiProxy/httpServer; prompting before the agent loop,
-    // adapters, and tools settle would fail the turn on a half-mounted tree.
-    // The old launcher ran strictly after settled boot — preserve that.
-    // A tree disposed mid-settlement (early SIGTERM) has nothing to run.
-    await ctx.get('loader')?.await()
-    if (ctx.get('httpServer') === undefined) return
-    // The headless session is web-observable while it runs (same composition).
-    io.stderr.write(`dsh: observing at http://127.0.0.1:${String(ctx.httpServer.port)}\n`)
-    const api = new InProcessApiClient(toFetchHandler(ctx.apiProxy))
-    const created = await unwrap(await api.sessions.create({}), io)
-    // Open the stream before prompting so no frame is lost. The quiescence
-    // anchor below is an in-process ctx subscription, so a remote-carrier
-    // port of this runner must replace it with a wire-visible idle signal.
-    const abort = new AbortController()
-    const frames = api.events.mux({}, abort.signal)
-    const idle = new Promise<number>((resolve) => {
-      ctx.on('agent/status', ({ agent, status }) => {
-        if (agent.id === created.sessionId && status === 'idle') resolve(agent.session.seq - 1)
-      })
-    })
-    const done = consumeUntilIdle(frames, created.sessionId, idle, io)
-    await unwrap(await api.sessions.prompt({
-      sessionId: created.sessionId,
-      mode: 'queue',
-      content: [{ type: 'text', text: config.task }],
-    }), io)
-    const outcome = await done
-    io.stdout.write(outcome.text + '\n')
-    abort.abort()
-    io.exit(outcome.reason === 'completed' ? 0 : 1)
-  })()
+  void run(ctx, config.task, io).catch((error: unknown) => { fail(io, error) })
 }

packages/bundle/headless/tests/headless.spec.ts

@@ -1,170 +1,184 @@
-/**
- * One-shot runner behavior over a scripted in-process API: idle-to-idle
- * aggregation (last text of the whole interval), exit-code mapping by the
- * final turn-end reason, stream-error and RPC-error paths, and the
- * launcher-owned `ctx.headlessIo` requirement.
- */
+/** Direct one-shot Agent driving, durable aggregation, flushing, and exit mapping. */
 
 import { describe, expect, it } from 'vitest'
 import { Context } from 'cordis'
-import type { Agent } from '@deepseek-ai/dsh-agent'
+import AgentRegistry, { Inbox } from '@deepseek-ai/dsh-agent'
+import type { Agent, AgentHandle, CreateAgentOptions } from '@deepseek-ai/dsh-agent'
+import AgentDefaultModelService from '@deepseek-ai/dsh-agent-default-model'
+import { createAssistantMessage } from '@deepseek-ai/dsh-llm'
+import SessionStore from '@deepseek-ai/dsh-session'
+import type { Session, UserMessage } from '@deepseek-ai/dsh-session'
 import { apply, Config, type HeadlessIo } from '../src/index.ts'
 
-interface ScriptedEvent { type: string; seq?: number; time?: number; sessionId?: string; data: Record<string, unknown> }
-
-let nextSeq = 0
-/** Stamp the envelope fields the wire schema requires. */
-function stamped(event: ScriptedEvent): ScriptedEvent {
-  nextSeq += 1
-  return { seq: nextSeq, time: nextSeq, ...event }
+interface Script {
+  before?(session: Session): void
+  afterPrompt(session: Session, message: UserMessage): Promise<void> | void
 }
 
-interface RpcShapedRequest { rpcId: string }
-
-interface ScriptedApiOptions {
-  promptFails?: boolean
-  framesAfterPrompt?: boolean
-  onPrompt?: () => void
+function appendTurn(
+  session: Session,
+  turn: number,
+  message: UserMessage,
+  text: string | undefined,
+  completed: boolean,
+): void {
+  session.append('turn/start', { turn })
+  session.append('step/start', { turn, step: 1 })
+  session.append('user/message', message, { surfaceOp: 'append' })
+  if (text !== undefined) {
+    session.append('assistant/message', {
+      turn,
+      step: 1,
+      message: createAssistantMessage({
+        content: [{ type: 'text', text }],
+        source: { provider: 'test-provider', model: 'test-model' },
+      }),
+    }, { surfaceOp: 'append' })
+  }
+  session.append('step/end', { turn, step: 1 })
+  session.append('turn/end', {
+    turn,
+    reason: completed
+      ? { kind: 'completed' }
+      : { kind: 'aborted', reason: { kind: 'user' } },
+  })
 }
 
-/** Build a fake apiProxy (echoing rpcIds like the real gateway) whose mux stream replays `events` for the created session. */
-function scriptedApi(events: ScriptedEvent[], options: ScriptedApiOptions = {}): unknown {
-  let releaseFrames = (): void => {}
-  const framesReady = options.framesAfterPrompt === true
-    ? new Promise<void>((resolve) => { releaseFrames = resolve })
-    : Promise.resolve()
-  const prepared = events.map((event) => {
-    if (event.type === 'stream/error') return { streamError: true } as const
-    const { sessionId = 'S1', ...rest } = event
-    return { streamError: false, sessionId, event: stamped(rest) } as const
+/** Mount the real registries around a small scripted Agent factory. */
+async function bench(script: Script): Promise<{
+  ctx: Context
+  run(): Promise<{ code: number; out: string; err: string; order: string[] }>
+}> {
+  const ctx = new Context()
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(AgentRegistry)
+  await ctx.plugin(AgentDefaultModelService, { provider: 'test-provider', model: 'test-model' })
+  ctx.agents.setFactory({
+    async createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle> {
+      const session = ctx.sessions.create(options.sessionId, {
+        ...options.meta === undefined ? {} : { meta: options.meta },
+      })
+      let idle = Promise.resolve()
+      const agent = {} as Agent
+      const agentCtx = ownerCtx.extend({ agent })
+      Object.assign(agent, {
+        id: session.id,
+        options: options.agentOptions ?? {},
+        session,
+        inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
+        status: 'idle',
+        ctx: agentCtx,
+        cancel: () => {},
+        runMaintenance: () => Promise.reject(new Error('not used')),
+        send: () => {},
+        followup: (message: UserMessage) => {
+          agent.inbox.append('next-turn', message)
+          idle = Promise.resolve().then(() => script.afterPrompt(session, message))
+        },
+        steer: () => {},
+        inject: () => {},
+        whenIdle: () => idle,
+      } satisfies Partial<Agent>)
+      await options.setup?.(agentCtx)
+      script.before?.(session)
+      ctx.agents.register(agent)
+      return { agent, dispose: () => Promise.resolve() }
+    },
+    resume: () => Promise.reject(new Error('not used')),
   })
   return {
-    sessions: {
-      create: (request: RpcShapedRequest) =>
-        Promise.resolve({ rpcId: request.rpcId, result: { ok: true, value: { sessionId: 'S1' } } }),
-      prompt: (request: RpcShapedRequest) => {
-        releaseFrames()
-        options.onPrompt?.()
-        return Promise.resolve(options.promptFails === true
-          // A code from the closed wire union: the carrier schema rejects invented codes.
-          ? { rpcId: request.rpcId, result: { ok: false, error: { code: 'agent-busy', message: 'agent is busy', details: { reason: 'test' } } } }
-          : { rpcId: request.rpcId, result: { ok: true, value: { accepted: true } } })
-      },
-    },
-    events: {
-      mux: async function* () {
-        await framesReady
-        for (const item of prepared) {
-          if (item.streamError) {
-            yield { rpcId: 'e', payload: { type: 'stream/error', error: { code: 'cancelled', message: 'stream broke', details: {} } } }
-            continue
-          }
-          yield { rpcId: 'e', payload: { type: 'session/event', sessionId: item.sessionId, event: item.event } }
+    ctx,
+    run: async () => {
+      let out = ''
+      let err = ''
+      const order: string[] = []
+      ctx.on('session/flush', () => { order.push('flush') })
+      const exited = new Promise<number>((resolve) => {
+        const io: HeadlessIo = {
+          stdout: { write: (chunk: string) => { out += chunk; return true } },
+          stderr: { write: (chunk: string) => { err += chunk; return true } },
+          exit: (code) => { order.push('exit'); resolve(code) },
         }
-      },
+        ctx.provide('headlessIo', io)
+      })
+      apply(ctx, { task: 'do the thing' })
+      return { code: await exited, out, err, order }
     },
   }
 }
 
-/**
- * Mount the runner against a scripted API, emit the idle transition after the
- * scripted frames drain, and wait for its exit request.
- */
-async function run(
-  events: ScriptedEvent[],
-  options: { promptFails?: boolean; framesAfterPrompt?: boolean; idleInPrompt?: boolean } = {},
-): Promise<{ code: number; out: string; err: string }> {
-  const ctx = new Context()
-  let out = ''
-  let err = ''
-  const exited = new Promise<number>((resolve) => {
-    const io: HeadlessIo = {
-      stdout: { write: (chunk: string) => { out += chunk; return true } },
-      stderr: { write: (chunk: string) => { err += chunk; return true } },
-      exit: resolve,
-    }
-    ctx.provide('headlessIo', io)
-  })
-  const emitIdle = (): void => {
-    ctx.emit('agent/status', { agent: { id: 'S1', session: { seq: nextSeq + 1 } } as Agent, status: 'idle' })
-  }
-  ctx.provide('apiProxy', scriptedApi(events, {
-    ...options.promptFails === undefined ? {} : { promptFails: options.promptFails },
-    ...options.framesAfterPrompt === undefined ? {} : { framesAfterPrompt: options.framesAfterPrompt },
-    ...options.idleInPrompt === true ? { onPrompt: emitIdle } : {},
-  }) as never)
-  ctx.provide('httpServer', { port: 12345 } as never)
-  apply(ctx, { task: 'do the thing' })
-  // Quiescence is out of band: give the scripted stream a beat to drain, then
-  // flip the agent idle exactly as the loop would. Foreign agents and
-  // non-idle transitions must not settle the run.
-  if (options.idleInPrompt !== true) {
-    await new Promise(resolve => setTimeout(resolve, 10))
-    ctx.emit('agent/status', { agent: { id: 'OTHER' } as Agent, status: 'idle' })
-    ctx.emit('agent/status', { agent: { id: 'S1' } as Agent, status: 'running' })
-    emitIdle()
-  }
-  const code = await exited
-  await ctx.fiber.dispose()
-  return { code, out, err }
-}
-
-const startupTurn: ScriptedEvent = { type: 'turn/start', data: { turn: 0, trigger: { kind: 'startup' } } }
-const messageTurn: ScriptedEvent = { type: 'turn/start', data: { turn: 1, trigger: { kind: 'message' } } }
-const text = (turn: number, value: string): ScriptedEvent => ({
-  type: 'assistant/message',
-  data: { turn, message: { content: [{ type: 'text', text: value }] } },
-})
-const end = (turn: number, reason: string): ScriptedEvent => ({ type: 'turn/end', data: { turn, reason: { kind: reason } } })
-
 describe('headless runner', () => {
-  it('aggregates to quiescence: last text wins across turns, final turn-end reason maps to exit 0', async () => {
-    const { code, out, err } = await run([
-      // Frames before the first turn/start are outside the task interval.
-      { type: 'assistant/message', data: { turn: 0, message: { content: [{ type: 'text', text: 'pre-task noise' }] } } },
-      startupTurn,
-      // Off-session, non-text, and text-empty frames never affect the aggregate.
-      { type: 'assistant/message', sessionId: 'OTHER', data: { turn: 1, message: { content: [{ type: 'text', text: 'other session' }] } } },
-      { type: 'assistant/message', data: { turn: 1, message: { content: [{ type: 'tool_call', text: 'ignored' }] } } },
-      text(0, 'draft'),
-      end(0, 'completed'),
-      messageTurn,
-      text(1, 'final answer'),
-      end(1, 'completed'),
-    ])
-    expect(code).toBe(0)
-    expect(out).toBe('final answer\n')
-    expect(err).toContain('observing at http://127.0.0.1:12345')
+  it('aggregates the final text across the complete idle-to-idle interval and flushes before exit', async () => {
+    const test = await bench({
+      before(session) {
+        const setupMessage = {
+          role: 'user', content: [{ type: 'text', text: 'setup' }], source: { kind: 'user' }, id: 'setup',
+        } as UserMessage
+        appendTurn(session, 0, setupMessage, 'pre-task noise', true)
+      },
+      async afterPrompt(session, message) {
+        await Promise.resolve()
+        appendTurn(session, 1, message, '', true)
+        appendTurn(session, 2, message, 'final answer', true)
+      },
+    })
+    const result = await test.run()
+    expect(result).toEqual({
+      code: 0,
+      out: 'final answer\n',
+      err: '',
+      order: ['flush', 'exit'],
+    })
+    await test.ctx.fiber.dispose()
   })
 
-  it('consumes through the idle sequence when queued frames arrive after the status transition', async () => {
-    const { code, out } = await run(
-      [messageTurn, text(1, 'race-free answer'), end(1, 'completed')],
-      { framesAfterPrompt: true, idleInPrompt: true },
-    )
-    expect(code).toBe(0)
-    expect(out).toBe('race-free answer\n')
+  it('waits for asynchronously appended events instead of racing Agent idleness', async () => {
+    const test = await bench({
+      afterPrompt: async (session, message) => {
+        await new Promise(resolve => setTimeout(resolve, 5))
+        appendTurn(session, 1, message, 'race-free answer', true)
+      },
+    })
+    expect(await test.run()).toMatchObject({ code: 0, out: 'race-free answer\n', err: '' })
+    await test.ctx.fiber.dispose()
   })
 
-  it('exits 1 when the final turn ends for any other reason', async () => {
-    const { code } = await run([messageTurn, end(1, 'aborted')])
-    expect(code).toBe(1)
+  it('exits 1 when the final turn does not complete', async () => {
+    const test = await bench({
+      afterPrompt(session, message) { appendTurn(session, 1, message, undefined, false) },
+    })
+    expect(await test.run()).toMatchObject({ code: 1, out: '\n', err: '' })
+    await test.ctx.fiber.dispose()
   })
 
-  it('exits 1 when no turn ever starts (idle without work)', async () => {
-    const { code, out } = await run([])
-    expect(code).toBe(1)
-    expect(out).toBe('\n')
+  it('prints the durable model failure when the final turn ends in error', async () => {
+    const test = await bench({
+      afterPrompt(session, message) {
+        session.append('turn/start', { turn: 1 })
+        session.append('step/start', { turn: 1, step: 1 })
+        session.append('user/message', message, { surfaceOp: 'append' })
+        session.append('step/end', { turn: 1, step: 1 })
+        session.append('turn/end', {
+          turn: 1,
+          reason: { kind: 'error', error: { code: 'SERVER', message: 'provider unavailable' } },
+        })
+      },
+    })
+    expect(await test.run()).toMatchObject({
+      code: 1,
+      out: '\n',
+      err: 'dsh: SERVER: provider unavailable\n',
+    })
+    await test.ctx.fiber.dispose()
   })
 
-  it('keeps the error outcome after a stream error ends the frame consumer early', async () => {
-    const { code } = await run([messageTurn, { type: 'stream/error', data: {} }, end(1, 'completed')])
-    // The consumer stopped at the stream error; the completed turn-end after
-    // it is never observed, so the reason stays 'error'.
-    expect(code).toBe(1)
+  it('exits 1 when the owned interval contains no turn', async () => {
+    const test = await bench({ afterPrompt: () => {} })
+    expect(await test.run()).toMatchObject({ code: 1, out: '\n', err: '' })
+    await test.ctx.fiber.dispose()
   })
 
-  it('prints an RPC business error and exits 1 without waiting for idle', async () => {
+  it('reports a direct Agent creation failure', async () => {
     const ctx = new Context()
     let err = ''
     const exited = new Promise<number>((resolve) => {
@@ -174,15 +188,16 @@ describe('headless runner', () => {
         exit: resolve,
       } satisfies HeadlessIo)
     })
-    ctx.provide('apiProxy', scriptedApi([messageTurn, end(1, 'completed')], { promptFails: true }) as never)
-    ctx.provide('httpServer', { port: 1 } as never)
+    ctx.provide('agentDefaultModel', { currentSelection: () => ({ provider: 'p', model: 'm' }) } as never)
+    ctx.provide('sessions', { flush: () => Promise.resolve(true) } as never)
+    ctx.provide('agents', { create: () => Promise.reject(new Error('factory exploded')) } as never)
     apply(ctx, { task: 't' })
     expect(await exited).toBe(1)
-    expect(err).toContain('agent-busy')
+    expect(err).toBe('dsh: factory exploded\n')
     await ctx.fiber.dispose()
   })
 
-  it('reports the stream-failed diagnostic when the event channel dies, still settling at idle', async () => {
+  it('stringifies a non-Error Agent creation failure', async () => {
     const ctx = new Context()
     let err = ''
     const exited = new Promise<number>((resolve) => {
@@ -192,67 +207,52 @@ describe('headless runner', () => {
         exit: resolve,
       } satisfies HeadlessIo)
     })
-    ctx.provide('apiProxy', {
-      sessions: {
-        create: (request: RpcShapedRequest) =>
-          Promise.resolve({ rpcId: request.rpcId, result: { ok: true, value: { sessionId: 'S1' } } }),
-        prompt: (request: RpcShapedRequest) =>
-          Promise.resolve({ rpcId: request.rpcId, result: { ok: true, value: { accepted: true } } }),
+    ctx.provide('agentDefaultModel', { currentSelection: () => ({ provider: 'p', model: 'm' }) } as never)
+    ctx.provide('sessions', { flush: () => Promise.resolve(true) } as never)
+    const rejected = {
+      then(_resolve: (value: never) => void, reject: (reason: unknown) => void): void {
+        reject('factory exploded')
       },
-      events: {
-        // Synchronous throw: the SSE response never forms, so the client-side
-        // iterable rejects — the runner's own catch path, not a carrier frame.
-        mux: () => { throw new Error('channel exploded') },
-      },
-    } as never)
-    ctx.provide('httpServer', { port: 1 } as never)
+    }
+    ctx.provide('agents', { create: () => rejected } as never)
     apply(ctx, { task: 't' })
-    await new Promise(resolve => setTimeout(resolve, 10))
-    ctx.emit('agent/status', { agent: { id: 'S1', session: { seq: nextSeq + 1 } } as Agent, status: 'idle' })
     expect(await exited).toBe(1)
-    expect(err).toContain('event stream failed')
+    expect(err).toBe('dsh: factory exploded\n')
     await ctx.fiber.dispose()
   })
 
-  it('waits for Loader settlement and abandons the run when the tree died during it', async () => {
+  it('abandons a run when the tree is disposed during Loader settlement', async () => {
     const ctx = new Context()
-    let err = ''
     let exited = false
     ctx.provide('headlessIo', {
       stdout: { write: () => true },
-      stderr: { write: (chunk: string) => { err += chunk; return true } },
+      stderr: { write: () => true },
       exit: () => { exited = true },
     } satisfies HeadlessIo)
-    ctx.provide('apiProxy', scriptedApi([]) as never)
-    // The webserver is provided by a child fiber whose disposal (early
-    // SIGTERM during the boot window) removes the service; settlement
-    // resolves only afterwards, and the runner must abandon rather than
-    // crash on the torn-down port read.
-    const webserverFiber = ctx.plugin((childCtx: Context) => {
-      childCtx.provide('httpServer', { port: 1 } as never)
+    const services = ctx.plugin((child: Context) => {
+      child.provide('agentDefaultModel', { currentSelection: () => ({ provider: 'p', model: 'm' }) } as never)
+      child.provide('sessions', {} as never)
+      child.provide('agents', {} as never)
     })
-    await webserverFiber
+    await services
     let release: () => void
     const settlement = new Promise<void>((resolve) => { release = resolve })
     ctx.provide('loader', { await: () => settlement } as never)
     apply(ctx, { task: 't' })
-    await webserverFiber.dispose()
+    await services.dispose()
     release!()
     await new Promise(resolve => setTimeout(resolve, 10))
-    expect(err).toBe('')
     expect(exited).toBe(false)
     await ctx.fiber.dispose()
   })
 
   it('fails loud without the launcher-owned headlessIo seam', () => {
     const ctx = new Context()
-    ctx.provide('apiProxy', scriptedApi([]) as never)
-    ctx.provide('httpServer', { port: 1 } as never)
     expect(() => { apply(ctx, { task: 't' }) }).toThrow('must provide ctx.headlessIo')
   })
 
   it('validates config: the task is required', () => {
-    expect(() => new Config({ } as never)).toThrow()
+    expect(() => new Config({} as never)).toThrow()
     expect(new Config({ task: 'x' })).toEqual({ task: 'x' })
   })
 })

packages/bundle/headless/tsconfig.json

@@ -18,13 +18,13 @@
       "path": "../../../vendor/schemastery"
     },
     {
-      "path": "../../host/apiproxy"
+      "path": "../../core/agent"
     },
     {
-      "path": "../../host/webserver"
+      "path": "../../core/agent-default-model"
     },
     {
-      "path": "../../core/agent"
+      "path": "../../llm/llm"
     },
     {
       "path": "../../core/session"

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: dc35cb4b596b265b70cea81aa5d6784fc1eff65b
-README.zh.md: c9fc86522da9c6b2ea79d1d079c71e5b26007f0a
+README.md: d89ae4a7e28506166498caf0032f864bbb109cc5
+README.zh.md: 746ec2e8b6748a0d72f697d0aea5f3809e7106ee

packages/bundle/web-app/README.md

@@ -2,7 +2,7 @@
 
 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, and mounts this package's own `web-runtime` glue plugin (config `{mode, printUrl, surfaceContext, lanAddresses}`). That plugin owns what used to be launcher code: it resolves the built frontend dist through `@deepseek-ai/dsh-frontend`'s exports (workspace knowledge of this bundle, never user config), mounts the [`frontend-static`](../../host/frontend-static/README.md) fallback owner over it, registers the web-surface prompt section and the bash-visible `DSH_WEB_URL`/`DSH_WEB_MODE` runtime variables when `surfaceContext` is true, and prints the `dsh web:` URL line when `printUrl` is true. The `dsh web` launcher alias patches `mode`/`lanAddresses` and the flag family over these rows; [`dsh-headless`](../headless/README.md) layers on top, silences the URL line, and disables the surface context.
+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, and mounts this package's `web-runtime` glue plugin (config `{mode, printUrl, surfaceContext, lanAddresses}`). That plugin resolves the built frontend dist through `@deepseek-ai/dsh-frontend`'s exports, mounts the [`frontend-static`](../../host/frontend-static/README.md) fallback owner over it, registers the web-surface prompt section and the bash-visible `DSH_WEB_URL`/`DSH_WEB_MODE` runtime variables when `surfaceContext` is true, and prints the `dsh web:` URL line when `printUrl` is true. The `dsh web` launcher alias patches `mode`/`lanAddresses` and the flag family over these rows. [`dsh-headless`](../headless/README.md) is a sibling surface over the same base and does not mount this bundle.
 
 ## Model Experience
 

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

@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-dsh 浏览器表层组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在 [`dsh-base`](../base/README.md) 之上：设置 coding persona，插入 Web 宿主行（webserver、API 网关、workspace、投影缓存、存储）与浏览器插件名录，并挂载本包自己的 `web-runtime` 粘合插件（配置为 `{mode, printUrl, surfaceContext, lanAddresses}`）。该插件接管了原先属于启动器的代码：它通过 `@deepseek-ai/dsh-frontend` 的 exports 解析已构建的前端 dist（这是本组合包的 workspace 知识，绝不是用户配置），在其上挂载 [`frontend-static`](../../host/frontend-static/README.md) 回退席位所有者，在 `surfaceContext` 为 true 时注册 web 表层提示词段落和 bash 可见的 `DSH_WEB_URL`／`DSH_WEB_MODE` 运行时变量，并在 `printUrl` 为 true 时打印 `dsh web:` URL 行。`dsh web` 启动器别名把 `mode`／`lanAddresses` 与相应 flag 家族 patch 到这些行上；[`dsh-headless`](../headless/README.md) 再叠加一层，关闭 URL 行并禁用表层上下文。
+dsh 浏览器表层组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在 [`dsh-base`](../base/README.md) 之上：设置 coding persona，插入 Web 宿主行（webserver、API 网关、workspace、投影缓存、存储）与浏览器插件名录，并挂载本包的 `web-runtime` 粘合插件（配置为 `{mode, printUrl, surfaceContext, lanAddresses}`）。该插件通过 `@deepseek-ai/dsh-frontend` 的 exports 解析已构建的前端 dist，挂载 [`frontend-static`](../../host/frontend-static/README.md) 回退席位所有者，在 `surfaceContext` 为 true 时注册 web 表层提示词段落和 bash 可见的 `DSH_WEB_URL`／`DSH_WEB_MODE` 运行时变量，并在 `printUrl` 为 true 时打印 `dsh web:` URL 行。`dsh web` 启动器别名把 `mode`／`lanAddresses` 与相应 flag 家族 patch 到这些行上。[`dsh-headless`](../headless/README.md) 是同一 base 之上的同级表层，不挂载本组合包。
 
 ## 模型体验
 

packages/bundle/web-app/cordis.patch.yml

@@ -72,13 +72,9 @@
       name: '@deepseek-ai/dsh-host-directory-picker-auto'
 
     # The API gateway: the transport-agnostic dispatch face every client shape
-    # shares. provider/model are the host default routing — the profile json's
-    # mapping target (user config overrides these engineering defaults).
+    # shares. The base layer's agent-default-model service owns the default model.
     - id: api-gateway
       name: '@deepseek-ai/dsh-host-apiproxy'
-      config:
-        provider: deepseek-official
-        model: deepseek-v4-flash
 
     # ── layer 2: transport/service ──────────────────────────────────────────────
 

packages/client/connection/src/client/api.ts

@@ -12,7 +12,7 @@ export type {
   WorkspaceApi, WorkspaceId, WorkspaceView,
   CommandsApi, CommandDescriptor, SkillsApi, SkillEntry,
   ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
-  ModelReasoningEffort, ModelTarget, QueueAction, QueuedInboxItem, SessionModels,
+  ModelReasoningEffort, ModelSelection, QueueAction, QueuedInboxItem, SessionModels,
   GoalsApi, GoalRef,
   SettingsApi, SettingsNamespaceView, SettingsPathOpView, SettingsSecretView,
   CredentialsApi, CredentialView, ConfigurableProviderView, DiscoveredModelView, LlmApi,

packages/client/connection/src/client/fixture.ts

@@ -30,7 +30,7 @@ import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import { deriveEventMessage, foldSurface } from '@deepseek-ai/dsh-session/surface'
 import type {
   ApiProxy, ClientRequest, ClientResponse, HistoryEntry, HostFrame, MuxFrame, RpcReceipt,
-  ModelProviderGroup, ModelTarget, RpcRequest, RpcResponse, RpcResult, ServerRequest, ServerResponse, SessionSummary,
+  ModelProviderGroup, ModelSelection, RpcRequest, RpcResponse, RpcResult, ServerRequest, ServerResponse, SessionSummary,
   ToolCallView, ToolEventView, ToolResultView, WorkspaceId, WorkspaceView,
 } from './api.ts'
 import type { RequestPayload, ResponseValue, RpcMethodMap } from '@deepseek-ai/dsh-host-apiproxy/api'
@@ -1347,7 +1347,7 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
     { sessionId: sid('fx-gamma'), updatedAt: Date.now() - 120_000, running: false, blank: false, cwd: '/tmp/fixture' },
   ]
   const logs = new Map<SessionId, SessionEvent[]>([[sid('fx-alpha'), buildAlphaLog()]])
-  const modelTargets = new Map<SessionId, ModelTarget>(sessions.map(session => [
+  const modelSelections = new Map<SessionId, ModelSelection>(sessions.map(session => [
     session.sessionId,
     { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
   ]))
@@ -1989,7 +1989,7 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
           sessionId: requestedId ?? sid(`fx-${nextSession++}`), updatedAt: Date.now(), running: false, blank: true, cwd,
         }
         sessions.push(created)
-        modelTargets.set(created.sessionId, { provider: 'deepseek-official', model: 'deepseek-v4-flash' })
+        modelSelections.set(created.sessionId, { provider: 'deepseek-official', model: 'deepseek-v4-flash' })
         attachedSessions += 1
         const emitSession = (): void => {
           // Mirrors the host: the frame fires at creation, so blank is constantly true.
@@ -2098,7 +2098,7 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
         return ok(request, { ...page, ...projections === undefined ? {} : { projections } })
       },
       models: request => ok(request, {
-        current: modelTargets.get(request.payload.sessionId)
+        current: modelSelections.get(request.payload.sessionId)
           ?? { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
         // The fixture's routes all serve; a surface exercising the blocked
         // posture drives it through its own stub.
@@ -2107,14 +2107,14 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
         failures: [],
       }),
       selectModel: (request) => {
-        const selected: ModelTarget = {
+        const selected: ModelSelection = {
           provider: request.payload.provider,
           model: request.payload.model,
           ...request.payload.reasoningEffort === undefined
             ? {}
             : { reasoningEffort: request.payload.reasoningEffort },
         }
-        modelTargets.set(request.payload.sessionId, selected)
+        modelSelections.set(request.payload.sessionId, selected)
         return ok(request, { selected })
       },
       prompt: (request) => {
@@ -2153,11 +2153,11 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
         // Capacity parallel of the host token-meter's request/context record:
         // log-only, appended inside the open turn, and deduplicated against the
         // route already recorded (the fixture never varies contextWindow).
-        const target = modelTargets.get(id) ?? { provider: 'deepseek', model: 'deepseek-v4-flash' }
-        if (lastRequestContext(logOf(id))?.model !== target.model) {
+        const selection = modelSelections.get(id) ?? { provider: 'deepseek', model: 'deepseek-v4-flash' }
+        if (lastRequestContext(logOf(id))?.model !== selection.model) {
           append(id, {
             type: 'request/context',
-            data: { provider: target.provider, model: target.model, contextWindow: 128_000 },
+            data: { provider: selection.provider, model: selection.model, contextWindow: 128_000 },
           })
         }
         startReply(
@@ -2167,9 +2167,9 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
             ? MARKDOWN_FIXTURE
             : userText === 'report model'
               ? (() => {
-                const target = modelTargets.get(id)
-                return `当前模型：${target?.provider ?? 'unknown'}/${target?.model ?? 'unknown'}`
-                  + (target?.reasoningEffort === undefined ? '' : ` · 推理等级：${target.reasoningEffort}`)
+                const selection = modelSelections.get(id)
+                return `当前模型：${selection?.provider ?? 'unknown'}/${selection?.model ?? 'unknown'}`
+                  + (selection?.reasoningEffort === undefined ? '' : ` · 推理等级：${selection.reasoningEffort}`)
               })()
               : `回声：${userText}。这是 fixture 的流式回复，用于验证打字机增长与定稿切换。`,
         )

packages/client/connection/src/client/index.ts

@@ -20,7 +20,7 @@ export type {
   ToolCallView, ToolResultView, WorkspaceApi, WorkspaceId, WorkspaceView,
   CommandsApi, CommandDescriptor, SkillsApi, SkillEntry,
   ModelCatalogFailure, ModelCatalogModel, ModelProviderGroup, ModelReasoning,
-  MessageId, ModelReasoningEffort, ModelTarget, QueueAction, QueuedInboxItem, SessionModels,
+  MessageId, ModelReasoningEffort, ModelSelection, QueueAction, QueuedInboxItem, SessionModels,
   SubagentsApi, SubagentAddress, SubagentCatalog, SubagentListEntry, SubagentPromptReceipt,
   RpcRequest, RpcResponse, RpcResult, RpcError, RpcErrorCode,
   ClientRequest, ServerResponse, ServerRequest, ClientResponse, RpcMessage, RpcReceipt,

packages/client/connection/tests/fake-api.ts

@@ -3,7 +3,7 @@
 // deferred-controlled timing). Streams are hand pumps: pushMux/pushHost.
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import type {
-  CommandDescriptor, HostFrame, IApiClient, ModelTarget, MuxFrame,
+  CommandDescriptor, HostFrame, IApiClient, ModelSelection, MuxFrame,
   RpcRequest, RpcResponse, SessionId, SessionModels, SessionSearchItem, SkillEntry,
 } from '../src/client/api.ts'
 import { RpcId } from '../src/client/api.ts'
@@ -50,11 +50,11 @@ export class FakeApiClient implements IApiClient {
   onRename: (payload: unknown) => Promise<RpcResponse<{ title: string; seq: number }>> = () => Promise.resolve(ok({ title: 'fk-renamed', seq: 0 }))
   onFork: (payload: unknown) => Promise<RpcResponse<{ sessionId: SessionId }>> = () => Promise.resolve(ok({ sessionId: 'fk-fork' as SessionId }))
   onHistory: (payload: { sessionId: SessionId; beforeSeq?: number; maxMessages?: number })
-  => Promise<RpcResponse<{ events: never[]; hasMore: boolean; modelTarget: ModelTarget }>> =
+  => Promise<RpcResponse<{ events: never[]; hasMore: boolean; modelSelection: ModelSelection }>> =
     () => Promise.resolve(ok({
       events: [],
       hasMore: false,
-      modelTarget: { provider: 'deepseek-official', model: 'deepseek-chat' },
+      modelSelection: { provider: 'deepseek-official', model: 'deepseek-chat' },
     }))
 
   onModels: (payload: unknown) => Promise<RpcResponse<SessionModels>> = () => Promise.resolve(ok({
@@ -63,8 +63,8 @@ export class FakeApiClient implements IApiClient {
     groups: [],
     failures: [],
   }))
-  onSelectModel: (payload: ModelTarget & { sessionId: SessionId })
-  => Promise<RpcResponse<{ selected: ModelTarget }>> =
+  onSelectModel: (payload: ModelSelection & { sessionId: SessionId })
+  => Promise<RpcResponse<{ selected: ModelSelection }>> =
     payload => Promise.resolve(ok({ selected: { provider: payload.provider, model: payload.model } }))
   onPrompt: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>> = () => Promise.resolve(ok({ accepted: true as const }))
   onUpdateQueue: (payload: unknown) => Promise<RpcResponse<{ accepted: true }>> = () => Promise.resolve(ok({ accepted: true as const }))
@@ -105,7 +105,7 @@ export class FakeApiClient implements IApiClient {
     history: (payload: { sessionId: SessionId; beforeSeq?: number; maxMessages?: number }) =>
       this.record('session.history', payload, this.onHistory(payload)),
     models: (payload: unknown) => this.record('session.models', payload, this.onModels(payload)),
-    selectModel: (payload: ModelTarget & { sessionId: SessionId }) =>
+    selectModel: (payload: ModelSelection & { sessionId: SessionId }) =>
       this.record('session.selectModel', payload, this.onSelectModel(payload)),
     rename: (payload: unknown) => this.record('session.rename', payload, this.onRename(payload)),
     fork: (payload: unknown) => this.record('session.fork', payload, this.onFork(payload)),

packages/client/connection/tests/fixture.spec.ts

@@ -168,7 +168,7 @@ describe('createFixtureApi', () => {
     })
   })
 
-  it('serves grouped models and keeps a selected target for later history and fixture requests', async () => {
+  it('serves grouped models and keeps a selection for later history and fixture requests', async () => {
     const api = createFixtureApi()
     const sessionId = sid('fx-alpha')
     const catalog = await api.sessions.models(req({ sessionId }))