Merge remote-tracking branch 'origin/master' into worktree/event-driven-issue-review-status-20260810

.agents/notes/archived/feature/2026-08-08-dsh-run-headless-command.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/archived/feature/2026-08-08-dsh-run-headless-command.md
+2026-08-08-dsh-run-headless-command.md: ce9cff965192357022c49655983fe6ff8d554b9f
+2026-08-08-dsh-run-headless-command.zh.md: 0484c069ed6365235e4616542a4fb3d5ceb2d880

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

@@ -1,9 +1,12 @@
 # Agent Note: `dsh run` owns one-shot headless execution
 
 Status: implemented
+Archived: 2026-08-10
 
 English | [中文](2026-08-08-dsh-run-headless-command.zh.md)
 
+> **Superseded command grammar.** [Apps now own their command lines](../architecture/2026-08-06-app-owned-command-line.md): the headless startup row parses the task from `dsh --profile headless <task...>`, and the launcher no longer has a `run` invocation or patches task text into rows. This note remains the rejected launcher-owned design context; the direct execution and completion contract it selected remains current in [headless is a direct core entry point](../architecture/2026-08-09-headless-direct-core-entry-point.md).
+
 ## Problem
 
 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.

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

@@ -1,9 +1,12 @@
 # Agent Note: `dsh run` 负责一次性 headless 执行
 
 Status: implemented
+Archived: 2026-08-10
 
 [English](2026-08-08-dsh-run-headless-command.md) | 中文
 
+> **命令语法已被取代。** [应用现在持有自己的命令行](../architecture/2026-08-06-app-owned-command-line.md)：headless 启动行从 `dsh --profile headless <task...>` 解析任务，启动器不再包含 `run` 调用，也不再把任务文本 patch 进配置行。本笔记保留被否决的启动器持有设计背景；它选定的直接执行与完成约定仍由 [headless 是直接 core 入口](../architecture/2026-08-09-headless-direct-core-entry-point.md)持有。
+
 ## 问题
 
 通用 profile 启动与一次性任务执行具有不同的生命周期约定。若根语法接受可选任务文本，同一种 argv 形态会表示常驻进程或终止式任务，具体含义取决于组合完成后才发现的插件配置行。它还会把 profile 实现细节暴露成主要用户命令，并使自定义 profile 缺少明确的一次性入口。

.agents/notes/archived/manifest.json

@@ -253,6 +253,9 @@
     "feature/2026-07-31-web-cards-toolrow.i18n.yaml": "sha256:f9a6ab72a77934cdcc02167c7313f08d7e9925362017b34bed7ad56c8c70fbaa",
     "feature/2026-07-31-web-cards-toolrow.md": "sha256:5058f7cec4497d1cb0a5c8e77b88fddacac6eead034f3edec88e8514919b8a3e",
     "feature/2026-07-31-web-cards-toolrow.zh.md": "sha256:ba84ef2e1be61211ab5ba6950b78ede3d3a979f252bc068d3e04e2c025f7bc03",
+    "feature/2026-08-08-dsh-run-headless-command.i18n.yaml": "sha256:1c2b4c5b61b9263b6267275d6fc69faeaad3cc887f0728a7ed4172d817af812b",
+    "feature/2026-08-08-dsh-run-headless-command.md": "sha256:7695fe7fd322377d5986f14e35f13337f4cd376405c758218a81230f6d182d1c",
+    "feature/2026-08-08-dsh-run-headless-command.zh.md": "sha256:113c14a36c64d2facc8ae46f37c7aa76359d8cacb9c18fcba26a723f15d036fb",
     "process/2026-06-11-doc-sync-enforcement.i18n.yaml": "sha256:33b6d5874427bd7a2bd82e7e2f4f482b12448b2464aef15a9c57975edb48554d",
     "process/2026-06-11-doc-sync-enforcement.md": "sha256:aa2fe83d519fc30d48dff19e596e83c8922aacc9e063e14fe2cc35b769b9100e",
     "process/2026-06-11-doc-sync-enforcement.zh.md": "sha256:698017bd35f030fdea3eac51df9e43138c48140f504739d687b7251d13fced2b",

.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: 514deb890d4e08d465db869669078473d32fb215
-2026-07-19-gui-layering-and-rpc-protocol.zh.md: f6fa71e3dac25f48b2ad4744a0cc695417528b34
+2026-07-19-gui-layering-and-rpc-protocol.md: da96ae97f2a2d64aeef7794bd82ccbd86602b1ad
+2026-07-19-gui-layering-and-rpc-protocol.zh.md: 36dc7391bc3f9bb0d5105fea14a2763d0b7159a1

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

@@ -10,7 +10,7 @@ English | [中文](2026-07-19-gui-layering-and-rpc-protocol.zh.md)
 
 We need a UI integration layer. Beyond the existing ACP/stdio baseline, more product clients are coming — Web (server), Electron, and others. We call them Clients and want the following capabilities:
 
-- One `dsh` process supporting both `dsh web` (serve) and `dsh run` (headless) — one process, two modes (a design reservation)
+- One `dsh` process supporting both `dsh web` (serve) and `dsh --profile headless` (headless) — one process, two modes (a design reservation)
 - Launching inside Electron with the same Web technologies as `dsh web`
 
 That demands a stable layered responsibility model in the engineering codebase, so future clients plug in cleanly.
@@ -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 `dsh.client` 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 applications, 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 commands: `dsh web` = Host + webserver + the built `dsh-frontend` dist; `dsh run` = [a direct core Agent/Session entry point](2026-08-09-headless-direct-core-entry-point.md), with zero Host, HTTP, or browser layer.
+    - `apps/cli` (`@deepseek-ai/dsh`) dispatches commands: `dsh web` = Host + webserver + the built `dsh-frontend` dist; `dsh --profile headless` = [a direct core Agent/Session entry point](2026-08-09-headless-direct-core-entry-point.md), with zero Host, HTTP, or browser layer.
     - A future Electron application 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 application'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 applications preserve the division: the Web application 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 and mount directly via `ctx.plugin(entry-point plugin)` without fetch.
+The two existing applications preserve the division: the Web application mounts Host, carrier, and browser composition, while `dsh --profile headless` 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 and mount directly via `ctx.plugin(entry-point plugin)` without 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; carrier tests and callers can exercise the protocol without opening a port, while product `dsh run` drives core directly |
+| `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 --profile headless` drives core directly |
 | `WebApiClient` | dsh-client-connection | `globalThis.fetch` uplink + one same-origin WebSocket downlink per logical stream | the browser client; 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) |
 | IPC bridge subclass (hypothetical example — no such shell exists) | an Electron shell | IPC serialization round trip | would swap only doFetch; contract and base class unchanged |

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

@@ -9,7 +9,7 @@ Status: implemented
 ## Problem
 
 需要提供 UI 对接层，除已有 ACP（Agent Client Protocol）/stdio 基线外，还需要 Web（server）、Electron 等其他产品客户端。我们把它们统一称为 Client。希望具备以下能力：
-- 一个 `dsh` 进程同时支持 `dsh web`（启动）和 `dsh run`（headless），一个进程两种模式（设计预留）
+- 一个 `dsh` 进程同时支持 `dsh web`（启动）和 `dsh --profile headless`（headless），一个进程两种模式（设计预留）
 - 在 Electron 中使用与 `dsh web` 相同的 Web 技术启动
 
 那么当前的工程代码需要稳定的分层职责模型，便于以后接入各类 client。
@@ -29,7 +29,7 @@ Status: implemented
     - **fetch 到达插件包**（`ui-layout`、`ui-sidebar`、`ui-conversation`、`ui-trajectory`）：双入口——根入口是 node 半边（空 `apply`，其存在是为了让 host Loader 管辖生命周期、让 web 插件注册表发现 package.json 的 `dsh.client` 声明）；实现住在 `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` = Host + webserver + 构建出的 `dsh-frontend` dist；`dsh run` = [直接使用核心 Agent／Session 的入口](2026-08-09-headless-direct-core-entry-point.md)，不含 Host、HTTP 或浏览器层。
+    - `apps/cli`（`@deepseek-ai/dsh`）分发命令：`dsh web` = Host + webserver + 构建出的 `dsh-frontend` dist；`dsh --profile headless` = [直接使用核心 Agent／Session 的入口](2026-08-09-headless-direct-core-entry-point.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`**，否则零端口。
 
-现有两个应用保持这一区分：Web 应用挂载 Host、载体与浏览器组合，而 `dsh run` 挂载直接使用核心服务的 runner，不包含 Host、HTTP 或端口。ACP 类协议桥不遵循 client 载体清单：它把 core 暴露给外部生态，直接通过 `ctx.plugin(入口插件)` 挂载，不使用 fetch。
+现有两个应用保持这一区分：Web 应用挂载 Host、载体与浏览器组合，而 `dsh --profile headless` 挂载直接使用核心服务的 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` 直接驱动 core |
+| `InProcessApiClient` | apiproxy 本包 | 注入的 `{ fetch }` handler | **同构点**：`new InProcessApiClient(toFetchHandler(api))` 全程不过网络但真跑 wire 序列化/zod/SSE 帧；载体测试与调用方可以在不打开端口的情况下运行这套协议，而产品 `dsh --profile headless` 直接驱动 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 桥子类（假想示例——尚无此形态） | Electron 壳 | IPC 序列化往返 | 只需换 doFetch，约定/基类零改 |

.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.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-29-dsh-source-launch-tsx-esm.md
-2026-07-29-dsh-source-launch-tsx-esm.md: ed22e51d59a25db130b3760ce484c116bade4348
-2026-07-29-dsh-source-launch-tsx-esm.zh.md: bdd549092eb30f7749c8f7561068daafe3548b28
+2026-07-29-dsh-source-launch-tsx-esm.md: 5cf4a227f388a1ac8315594af4e0256864ef17f5
+2026-07-29-dsh-source-launch-tsx-esm.zh.md: b5a52b3d01840337c0091310e50d8fac34245519

.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.md

@@ -35,4 +35,4 @@ The node-compat CI matrix (Node 22.19 and 26) gains `dsh-source-launch-smoke` (`
 - One launch vector across the whole engines range, including future Node lines that change native TypeScript support; the smoke gate enforces it per matrix line.
 - TypeScript transformation is delegated to tsx/esbuild again, reversing the prior note's goal of proving Node-native transformation; that goal is unreachable while vendored sources use non-erasable syntax and Node ships no transform mode.
 - The runtime declared-dependency enforcement in source launches is gone; undeclared workspace imports now surface only through static gates or built-mode resolution failures.
-- Startup improves ~0.4s over the full tsx default (`demo:headless` now aliases the same `dsh run` source launch; ACP keeps `--import tsx` because its graph was not audited for CJS-hook dependence and its launch latency is not on the interactive path).
+- Startup improves ~0.4s over the full tsx default (`demo:headless` now aliases the same `dsh --profile headless` source launch; ACP keeps `--import tsx` because its graph was not audited for CJS-hook dependence and its launch latency is not on the interactive path).

.agents/notes/implemented/architecture/2026-07-29-dsh-source-launch-tsx-esm.zh.md

@@ -35,4 +35,4 @@ node-compat CI 矩阵（Node 22.19 与 26）新增 `dsh-source-launch-smoke`（`
 - 整个 engines 范围（包括未来改变原生 TypeScript 支持的 Node 版本线）只有一个启动向量；冒烟门禁按矩阵行强制执行。
 - TypeScript 转换重新委托给 tsx/esbuild，逆转了前一篇 Agent Note「证明 Node 原生转换可用」的目标；在 vendor 源码使用不可擦除语法且 Node 不再提供 transform 模式的情况下，该目标不可达。
 - 源码启动中的运行时依赖声明强制不复存在；未声明的 workspace import 现在只能通过静态门禁或构建模式的解析失败暴露。
-- 启动相比完整 tsx 默认形态快约 0.4s（`demo:headless` 现为同一条 `dsh run` 源码启动命令的别名；ACP 保留 `--import tsx`，因为它的依赖图尚未就 CJS 钩子依赖性做审计，且其启动延迟不在交互路径上）。
+- 启动相比完整 tsx 默认形态快约 0.4s（`demo:headless` 现为同一条 `dsh --profile headless` 源码启动命令的别名；ACP 保留 `--import tsx`，因为它的依赖图尚未就 CJS 钩子依赖性做审计，且其启动延迟不在交互路径上）。

.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: 2924b3cb445064fd47d82bcc94ec8d77ded5721b
-2026-08-05-profile-plugin-bundles.zh.md: b2287034010bcac1048bb385b2266f1bc75921da
+2026-08-05-profile-plugin-bundles.md: 54626e3f48a2ba7db19813e6e883f0e77499d0e2
+2026-08-05-profile-plugin-bundles.zh.md: 357e0f63d4eba0f0985c9e14aad54595c7b41c77

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

@@ -10,11 +10,9 @@ The `dsh` launcher hardcoded its compositions: `base.cordis.yml` + `web.cordis.y
 
 ## Decision
 
-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`.
+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 and `--patch` overlays — one `applyEntryPatches` call shared by boot and `--dump-config`. App invocation values later moved from launcher-derived patches to startup services in the [app-owned command-line decision](2026-08-06-app-owned-command-line.md).
 
-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 entry point](2026-08-09-headless-direct-core-entry-point.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.
+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). Generic `dsh --profile <name>` hands its remaining arguments to that profile's command-line startup row: Web owns its flag family, while headless owns its task positional. Patch overlays use launcher-owned `--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 entry point](2026-08-09-headless-direct-core-entry-point.md) owns the headless composition contract.
 
 Resolution is two-anchored by construction: `dsh.profile.bundles` names resolve from the dsh installation first, then the profile directory — so in-box bundles always come from the same installation as the running `dsh` and pnpm never manages them — while bare plugin names in patch rows resolve through the profile directory's Node parent-walk into the maintained flat fallback `$DSH_HOME/profiles/node_modules` (one symlink per package the installation's app and bundles depend on, healed on every launch).
 
@@ -24,7 +22,7 @@ Two supporting refactors: the webserver's built-in static dist serving became th
 
 - **Dependency-scan plus partial `patchOrder`** (the original sketch): scanning `dependencies` for bundles and ordering unlisted ones alphabetically has two sources of truth and an implicit tie-break; one explicit ordered `dsh.profile.bundles` list is smaller and fully deterministic. A raw `pnpm add` inside the profile installs a library without activating any patch — explicit, no spooky scan.
 - **`link:` entries for in-box bundles**: pnpm cannot version, install, or update a `link:` into the installation, it embeds a machine path in a user file, and it breaks when the installation moves. The two-anchor resolution plus healed symlink fallback gives the same guarantee ("bundles come from the installation") without ceremony.
-- **A pre-boot `context` module in the bundle manifest** for boot-time values (dist path, flag facts): rejected in favor of pure plugins — the glue is ordinary rows the launcher patches, so the composition stays fully dumpable and the manifest stays data-only. The launcher-owned `ctx.headlessIo` host hook is the one host-provided slot, and it is provided in `boot()`'s `prepare` hook, before any config-tree entry mounts.
+- **A pre-boot `context` module in the bundle manifest** for boot-time values (dist path, flag facts): rejected in favor of pure plugins — the glue is ordinary rows and app-owned startup services, so the composition stays fully dumpable and the manifest stays data-only. The launcher-owned `ctx.headlessIo` host hook is the one host-provided slot, and it is provided in `boot()`'s `prepare` hook, before any config-tree entry mounts.
 - **Transitive bundle auto-application**: only direct `dsh.profile.bundles` entries contribute layers; a meta-bundle wanting to re-export another bundle's patch must do so explicitly in its own patch file.
 
 ## Consequences

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

@@ -10,11 +10,9 @@ Status: implemented
 
 ## Decision
 
-一切都变成 **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` 使用完全相同的路径。
+一切都变成 **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——启动与 `--dump-config` 共享同一条 `applyEntryPatches` 路径。随后，[应用持有命令行的决策](2026-08-06-app-owned-command-line.md)又把调用期取值从启动器派生的 patch 迁移到了启动服务。
 
-随附的组合包是 `@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-entry-point.md)负责 headless 组合约定。
-
-[`dsh run` 命令决策](../feature/2026-08-08-dsh-run-headless-command.md)负责一次性语法；本 Agent Note 负责该语法所选择的 profile 组合。
+随附的组合包是 `@deepseek-ai/dsh-base`（共享核心配置行）、`@deepseek-ai/dsh-web-app`（浏览器 Host 配置行与 Web 运行时粘合层）和 `@deepseek-ai/dsh-headless`（直接叠加在 base 上且不含 web-app 的一次性 runner）。通用的 `dsh --profile <name>` 把剩余参数交给该 profile 的命令行启动行：Web 持有自己的 flag 家族，headless 则持有任务位置参数。patch overlay 使用启动器持有的 `--patch`。`dsh plugin --profile <name> <args...>` 是一层薄薄的 pnpm 转发器，负责初始化 profile，并依据已安装包的组合包声明调和 `dsh.profile.bundles`；没有组合包声明的包保持为普通依赖。[Headless 作为直接 core 入口](2026-08-09-headless-direct-core-entry-point.md)负责 headless 组合约定。
 
 解析在构造上就是双锚点的：`dsh.profile.bundles` 中的名称先从 dsh 安装目录解析，再从 profile 目录解析——因此内置组合包始终来自与运行中 `dsh` 相同的安装，pnpm 从不管理它们——而 patch 行中的裸插件名称经 profile 目录的 Node 父目录逐级查找，落到受维护的扁平回退目录 `$DSH_HOME/profiles/node_modules`（安装目录的应用与各组合包所依赖的每个包各一个符号链接，每次启动时修复）。
 
@@ -24,7 +22,7 @@ Status: implemented
 
 - **依赖扫描加部分 `patchOrder`**（最初的草案）：扫描 `dependencies` 找出组合包、未列出者按字母序排列，会产生两个真源和一条隐式决胜规则；一份显式有序的 `dsh.profile.bundles` 列表更小、完全确定。在 profile 内直接 `pnpm add` 只会安装一个库，不激活任何 patch——行为显式，没有暗中扫描。
 - **内置组合包使用 `link:` 条目**：pnpm 无法对指向安装目录的 `link:` 做版本管理、安装或更新，它会把机器路径嵌进用户文件，并且在安装目录移动后失效。双锚点解析加上每次启动修复的符号链接回退提供了同样的保证（「组合包来自安装目录」），且没有这些繁文缛节。
-- **在组合包 manifest 中放一个启动前 `context` 模块**承载启动期取值（dist 路径、flag 事实）：否决，改用纯插件——粘合逻辑就是启动器 patch 的普通配置行，因此组合始终可完整 dump，manifest 保持纯数据。启动器持有的 `ctx.headlessIo` 宿主钩子是唯一由宿主提供的 slot，且在任何配置树条目挂载之前，于 `boot()` 的 `prepare` 钩子中提供。
+- **在组合包 manifest 中放一个启动前 `context` 模块**承载启动期取值（dist 路径、flag 事实）：否决，改用纯插件——粘合逻辑就是普通配置行和由应用持有的启动服务，因此组合始终可完整 dump，manifest 保持纯数据。启动器持有的 `ctx.headlessIo` 宿主钩子是唯一由宿主提供的 slot，且在任何配置树条目挂载之前，于 `boot()` 的 `prepare` 钩子中提供。
 - **组合包的传递式自动应用**：只有直接列在 `dsh.profile.bundles` 中的条目才贡献层；想重新导出另一个组合包 patch 的元组合包，必须在自己的 patch 文件中显式完成。
 
 ## Consequences

.agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.i18n.yaml → .agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.i18n.yaml

@@ -1,6 +1,6 @@
 # Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-08-dsh-run-headless-command.md
-2026-08-08-dsh-run-headless-command.md: ed095f4077a23e51bffb647d24eed19ba09e11ed
-2026-08-08-dsh-run-headless-command.zh.md: 89d54e35573f14786e05d648f2b42891ca27a043
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.md
+2026-08-06-app-owned-command-line.md: 4a05cac5ed7f44fb55c2d4498bf28a43befdb073
+2026-08-06-app-owned-command-line.zh.md: 86a37f416d17c4615152b29d73f171803f24c4c3

.agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.md

@@ -0,0 +1,51 @@
+# Agent Note: Apps own their command line through `ctx.cmdlineArgs`
+
+Status: implemented
+
+English | [中文](2026-08-06-app-owned-command-line.zh.md)
+
+## Problem
+
+After profiles, compositions were installable but their command lines were not. `apps/cli` still declared the Web flag family (`--host`, `--port`, `--dev`, `--workspace-root`, `--trusted-host`) and the one-shot task positional, then derived patches for row ids it hardcoded (`webserver`, `api-gateway`, `connection`, `web-runtime`). An out-of-tree app such as [turtle-ui](https://github.com/deepseek-harness/turtle-ui) could contribute rows but had no way to accept a flag: `dsh --profile tui --resume <session>` had nowhere to be parsed, and `dsh --profile web --help` printed the launcher's help rather than the web app's.
+
+## Decision
+
+The launcher parses only what it owns — `--profile`, `--patch`, the config dumps — and hands **everything after its own flags** to the booted tree verbatim. The split is positional: the first token the launcher does not recognize starts the app's arguments (commander's `passThroughOptions` + `allowUnknownOption` + `helpOption(false)`). A bare `dsh -h`, which has no app to hand the flag to, still prints the launcher's own help.
+
+The new `@deepseek-ai/dsh-cmdline` package owns the handoff. A launcher calls `provideCmdline(ctx, host)` before any entry mounts, providing `ctx.cmdlineArgs` (whose whole interface is `get(): readonly string[]`) and `ctx.appExit`. Any ordinary app plugin may inject `cmdlineArgs`, call `parseCmdline(ctx, program, plan)` with its own commander program, and provide the returned value as an app-owned service. Its Loader row carries no launcher marker or special kind, and the launcher does not inspect the composition for an owner. Multiple plugins may read the same immutable snapshot; a profile with no reader ignores its app arguments. Rows configured from a provider inject its service and read direct lazy config expressions (`port: !!js ctx.webStartup.port ?? 3080`), so a flag beats the value written beside it and nothing is written back into any row.
+
+The boot mounts the composition once. Cordis holds each row until its injections are active; Loader then interpolates that row's `!!js` against the injection-ready plugin context immediately before activation. Include keeps nested row expressions raw until their target row reaches this point. `--help` leaves the provider's service absent, so dependent rows never activate, and a live patch reload interpolates again against the service that remains active, so a served port cannot be silently reset.
+
+The shipped apps moved their flags into their bundles: `dsh-web-app` owns the Web family (and enables the `client-hmr` row it now ships disabled, for `--dev`), and `dsh-headless` owns the task positional and rejects a missing task as a usage error. `apps/cli/src/web.ts` is gone; `runProfile` no longer knows any flag-target row id. Out of tree, turtle-ui gained `--resume <session>` / `--session <id>` the same way, which is the design's real validation: an installed plugin added a flag with no launcher change.
+
+Two further consequences. Loader mounts sibling rows concurrently, so one row can activate while another still mounts or while the whole boot is rolling back; the Web bundle therefore publishes its URL only after its own Loader tree settles. The Web bundle's runtime plugin owns the harness-source prompt section too, so `dsh web` and `dsh --profile web` boot identically without Web-specific launcher setup.
+
+## Why Loader owns the ordering
+
+Four framework facts shape the mechanism:
+
+- **A profile's rows arrive inside the root include's `patches` option.** Include is an entry-tree owner, so its static entry-config resolver interpolates Include's own options while preserving nested `!!js` nodes for their target rows instead of recursively evaluating them in the Include context.
+- **Cordis activates a fiber only after all declared injections are active.** Immediately before each activation, Cordis runs the `internal/config` waterfall against the fiber's own context; Loader's listener interpolates the raw config after Cordis snapshots its injected services.
+- **Provider replacement and HMR must preserve the same contract.** Fiber reactivation re-runs the waterfall, HMR carries the raw config to the replacement fiber, and a pending row accepts option changes without prematurely evaluating expressions against absent services.
+- **A row cannot be inserted from inside a mounting plugin** — `tree.create` returns a prefixed id it then fails to resolve — so a conditional row ships `disabled: true` and an active row enables it (`dsh web --dev` and its reload chain). Enablement is an in-memory Loader override rather than an options rewrite, so Include reapplication cannot silently disable it. The Web bundle also starts client discovery only after enabling the optional row, ensuring the first browser graph already contains its HMR receiver.
+
+This leaves dependency ordering in Cordis activation and Loader interpolation, which own it. Rows keep their `inject` and config, Loader mounts the composition once, and the launcher only provides argv and process-lifecycle services.
+
+## Alternatives considered
+
+- **Writing the resolved values into each row** (a config update per row, plus a patch layer handed back to the launcher so a reload could not undo it): it worked, but it meant patches travelling from an app to the launcher and back, two mechanisms for one fact, and a recycle whose correctness depended on Loader restart internals. The maintainer rejected the round trip; the service the rows read replaced all of it.
+- **Releasing rows by clearing their `inject`**: it worked in isolation and failed on the real web tree, because clearing `inject` is exactly what loses the plugin's static injections. The failure is silent until a plugin reads a service it declared.
+- **Launcher-managed two-pass mounting**: it can make a provider active before readers are applied, but duplicates the composition, makes ordering a launcher concern, and conceals the Loader defect that nested expressions were evaluated in the include context rather than the target row's injected context.
+- **The launcher running each bundle's command function before boot** (no Cordis involvement): strictly earlier than "boot, then help", but it makes app startup a second plugin protocol outside the tree. An ordinary `cmdlineArgs`-injected provider keeps one protocol and remains dumpable and patchable.
+- **A launcher-enforced command-line owner**: rejecting zero or multiple readers would arbitrate overlaps such as `-h`, but `get()` is an immutable read and normal composition may need several app-owned services. Plugins therefore share the snapshot and own any parser interaction through ordinary composition.
+- **`instanceof CommanderError`**: an out-of-tree plugin brings its own commander copy, so the class identity differs and a printed `--help` was rethrown as a fatal load failure. Commander's control-flow errors are detected structurally instead.
+
+## Consequences
+
+- An app's flags, help text, and usage errors live with the rows they configure; adding a flag to an installed plugin needs no launcher change.
+- The launcher still recognizes the headless runner for one-shot process lifetime and the telemetry row for its environment switch; neither path interprets app arguments.
+- `--help` leaves every row that depends on the provider's service pending and requests bounded exit; unrelated rows may activate concurrently before teardown.
+- An app-owned service has no statically declared provider: a bundle shipping consumer rows without that provider fails at settlement with pending entries naming the service, not at load.
+- A user patch that replaces a row's whole `config` drops its expressions, and with them the flag's precedence for that row.
+- Launcher flags must precede app arguments; a first app argument equal to `web` or `plugin` selects that subcommand instead, `-V`/`--version` remains launcher-owned before that boundary, and the launcher's parser consumes one `--`, so a literal `--` for the app needs `-- --`.
+- `--dump-config` never runs app command-line providers, so it prints the composition before any app argument is resolved and rejects an invocation that carries app arguments.

.agents/notes/implemented/architecture/2026-08-06-app-owned-command-line.zh.md

@@ -0,0 +1,51 @@
+# Agent Note: 应用通过 `ctx.cmdlineArgs` 持有自己的命令行
+
+Status: implemented
+
+[English](2026-08-06-app-owned-command-line.md) | 中文
+
+## 问题
+
+profile 落地之后，组合可以安装，命令行却不能。`apps/cli` 仍然声明着 Web flag 家族（`--host`、`--port`、`--dev`、`--workspace-root`、`--trusted-host`）和一次性任务位置参数，再为自己硬编码的行 id（`webserver`、`api-gateway`、`connection`、`web-runtime`）派生 patch。像 [turtle-ui](https://github.com/deepseek-harness/turtle-ui) 这样的树外应用能贡献行，却无处接受一个 flag：`dsh --profile tui --resume <session>` 没有地方可供解析，而 `dsh --profile web --help` 打印的是启动器的 help，而不是 web 应用的 help。
+
+## 决策
+
+启动器只解析属于自己的部分（`--profile`、`--patch`、配置 dump），并把**自己 flag 之后的一切**原样交给引导起来的配置树。切分按位置进行：启动器不认识的第一个 token 就是应用参数的起点（依靠 commander 的 `passThroughOptions` + `allowUnknownOption` + `helpOption(false)`）。裸的 `dsh -h` 没有可交付的应用，仍然打印启动器自己的 help。
+
+新包 `@deepseek-ai/dsh-cmdline` 持有这次交接。启动器在任何条目挂载之前调用 `provideCmdline(ctx, host)`，提供 `ctx.cmdlineArgs`（其全部接口就是 `get(): readonly string[]`）与 `ctx.appExit`。任何普通应用插件都可以注入 `cmdlineArgs`，用自己的 commander program 调用 `parseCmdline(ctx, program, plan)`，再把返回值作为应用自有服务提供出去。它的 Loader 行不携带启动器标记或特殊类型，启动器也不会检查组合中的所有者。多个插件可以读取同一份不可变快照；没有读取方的 profile 会忽略自己的应用参数。由提供方配置的行注入其服务，并在惰性配置表达式中直接读取它（`port: !!js ctx.webStartup.port ?? 3080`），因此 flag 胜过写在它旁边的值，也没有任何东西被写回任何一行。
+
+boot 只挂载一次整套组合。Cordis 让每一行等待其注入激活；Loader 随后在激活前一刻，基于已注入就绪的插件上下文插值该行的 `!!js`。Include 会保留嵌套的行表达式，直到目标行到达这一时点。`--help` 会让提供方服务保持缺失，因此依赖行永不激活；活动 patch 重载会针对仍然在线的服务再次插值，所以已经服务中的端口不会被悄悄重置。
+
+已交付的各应用把自己的 flag 搬进了组合包：`dsh-web-app` 持有 Web 家族（并为 `--dev` 启用它如今以禁用状态交付的 `client-hmr` 行），`dsh-headless` 持有任务位置参数，缺少任务时按用法错误拒绝。`apps/cli/src/web.ts` 已删除；`runProfile` 不再知道任何 flag 目标行 id。在树外，turtle-ui 以同样的方式获得了 `--resume <session>` / `--session <id>`，这才是这套设计的真正验证：一个已安装的插件加上了一个 flag，启动器毫无改动。
+
+还有两条后果。Loader 会并发挂载兄弟行，因此一行可能已经激活，而另一行仍在挂载，或整次 boot 正在回滚；所以 Web 组合包只会在自身的 Loader 配置树结算后公布 URL。另外，Web 组合包的运行时插件也持有 harness 源码提示词段，因此 `dsh web` 与 `dsh --profile web` 无需 Web 专用启动器设置即可按完全相同的方式启动。
+
+## 为什么由 Loader 持有顺序
+
+四条框架事实塑造了这套机制：
+
+- **profile 的各行位于根 include 的 `patches` 选项内部。** Include 是条目树所有者，因此它的静态条目配置解析器会插值 Include 自身的选项，同时为目标行保留嵌套的 `!!js` 节点，而不是在 Include 上下文中递归求值。
+- **Cordis 只在所有声明的注入都已激活后才激活 fiber。** 每次激活前一刻，Cordis 会基于 fiber 自身上下文运行 `internal/config` waterfall；Cordis 快照注入服务之后，Loader 的监听器再插值原始配置。
+- **提供方替换与 HMR 必须保持相同契约。** fiber 重新激活时会重跑 waterfall，HMR 会把原始配置带给替换 fiber，而待处理行可以接受选项变更，不会针对缺失服务提前求值表达式。
+- **不能从正在挂载的插件内部插入一行**——`tree.create` 返回一个带前缀的 id，随后它自己解析不出来——因此条件性的行以 `disabled: true` 交付，再由活跃行启用（`dsh web --dev` 及其重载链路）。启用采用 Loader 的内存覆盖而非改写选项，因此 Include 重新应用配置时不会悄然将其禁用。Web 组合包还会在启用可选行之后才启动客户端发现，确保首份浏览器图中已经包含 HMR 接收端。
+
+这样，依赖顺序仍由负责它的 Cordis 激活与 Loader 插值流程处理。各行保留自己的 `inject` 和配置，Loader 只挂载一次组合，启动器只提供 argv 与进程生命周期服务。
+
+## 曾考虑的替代方案
+
+- **把解析出的取值写进每一行**（逐行一次配置更新，外加交还给启动器的一层 patch，使重载无法撤销它）：它能工作，但这意味着 patch 在应用与启动器之间来回传递、同一件事有两套机制，以及一套其正确性依赖 Loader 重启内部细节的回收重建。维护者否决了这次往返；供各行读取的服务取代了这一切。
+- **通过清空行的 `inject` 来放行**：孤立测试可行，在真实 web 树上失败，因为清空 `inject` 恰恰会丢失插件的静态注入。在插件真的去读它声明过的服务之前，这个失败是静默的。
+- **由启动器管理两趟挂载**：它可以让提供方先于读取行激活，但会重复组合、把顺序变成启动器职责，还掩盖了 Loader 的缺陷——嵌套表达式在 include 上下文而不是目标行的注入上下文中求值。
+- **由启动器在 boot 之前运行每个组合包的命令函数**（完全不经过 Cordis）：严格早于「先 boot 再 help」，但这会让应用启动成为配置树之外的第二套插件协议。使用注入 `cmdlineArgs` 的普通提供方只保留一套协议，并且仍可 dump、可 patch。
+- **由启动器强制指定命令行所有者**：拒绝零个或多个读取方可以裁决 `-h` 等重叠项，但 `get()` 是不可变读取，普通组合也可能需要多个应用自有服务。因此插件共享该快照，并通过普通组合持有各自解析器的交互。
+- **`instanceof CommanderError`**：树外插件会带来自己的一份 commander 副本，类身份因此不同，已经打印出来的 `--help` 会被重新抛成致命的加载失败。改为按结构识别 commander 的控制流错误。
+
+## 后果
+
+- 应用的 flag、help 文本和用法错误与它们所配置的行放在一起；给已安装的插件加一个 flag 不需要改动启动器。
+- 启动器仍会识别 headless runner 以管理一次性进程生命周期，并识别 telemetry 行以应用环境开关；两条路径都不解析应用参数。
+- `--help` 会让所有依赖提供方服务的行保持待处理并请求有边界的退出；无关行可能在拆除前并发激活。
+- 应用自有服务没有静态声明的提供方：交付了消费行却缺少对应提供方的组合包会在结算时失败，报出指向该服务的待处理条目，而不是在加载时失败。
+- 用户 patch 若整体替换某行的 `config`，会连同其中的表达式一起丢掉，该行上 flag 的优先级也随之消失。
+- 启动器的 flag 必须写在应用参数之前；如果应用的第一个参数恰好等于 `web` 或 `plugin`，会选择对应的子命令；`-V`／`--version` 在该边界之前仍归启动器持有；而且启动器的解析器会消耗掉一个 `--`，因此要给应用传一个字面量 `--` 需要写成 `-- --`。
+- `--dump-config` 从不运行应用命令行提供方，因此它在任何应用参数被解析之前打印组合，并拒绝携带应用参数的调用。

.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-entry-point.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-09-headless-direct-core-entry-point.md
-2026-08-09-headless-direct-core-entry-point.md: 49afe2993de7302adbedcdf9e8e2347d6424ee2a
-2026-08-09-headless-direct-core-entry-point.zh.md: 73c1cbe5ac777025f63f46751b1d5ccebbfe9676
+2026-08-09-headless-direct-core-entry-point.md: b705df2e6d88e096ee3ba50a6156b815dbd98b98
+2026-08-09-headless-direct-core-entry-point.zh.md: 439f4c21a2ce1741e8d483bc307508550da1bec7

.agents/notes/implemented/architecture/2026-08-09-headless-direct-core-entry-point.md

@@ -20,11 +20,11 @@ The shipped `headless` profile contains `dsh-base` and `dsh-headless`. The headl
 
 `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.
+This note owns the headless transport and completion contracts. [Apps own their command lines](2026-08-06-app-owned-command-line.md) owns the current `dsh --profile headless` grammar; the former [`dsh run` decision](../../archived/feature/2026-08-08-dsh-run-headless-command.md) records the superseded launcher-owned 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 a `user/message` with `source.kind: 'user'`, 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.
+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 --profile headless` through a replayed tool round trip, record a `user/message` with `source.kind: 'user'`, 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
 
@@ -39,6 +39,6 @@ Package tests use the real Session store and Agent registry around a scripted Ag
 
 ## 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 records `source.kind: 'user'` and therefore carries no ApiProxy `rpcId`.
+`dsh --profile headless` 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 records `source.kind: 'user'` 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-entry-point.zh.md

@@ -20,11 +20,11 @@ Status: implemented
 
 `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 Note 负责 headless 的传输与完成约定。[应用持有自己的命令行](2026-08-06-app-owned-command-line.md)负责当前的 `dsh --profile headless` 语法；原 [`dsh run` 决策](../../archived/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`，记录一条带 `source.kind: 'user'` 的 `user/message`，并在 stderr 暴露终止态模型失败。构建后二进制验收通过已发布入口访问 mock 提供方，并要求最终文本出现在 stdout、退出状态为 0 且 stderr 为空。配置转储验收排除随附 headless 树中的所有 Host、Web 与 Client 包；PTY 关闭覆盖要求不出现观察行，并在有界时间内完成 dispose。
+包测试围绕脚本化 Agent 工厂使用真实的会话存储与 Agent 注册表，固定空闲态到空闲态的聚合、延迟异步完成、终止态模型诊断、其他未完成退出、直接失败、Loader 加载期间的 dispose（资源释放），以及退出前 flush 的顺序。组装后的无密钥快照通过回放的工具往返驱动 `dsh --profile headless`，记录一条带 `source.kind: 'user'` 的 `user/message`，并在 stderr 暴露终止态模型失败。构建后二进制验收通过已发布入口访问 mock 提供方，并要求最终文本出现在 stdout、退出状态为 0 且 stderr 为空。配置转储验收排除随附 headless 树中的所有 Host、Web 与 Client 包；PTY 关闭覆盖要求不出现观察行，并在有界时间内完成 dispose。
 
 ## 考虑过的替代方案
 
@@ -39,6 +39,6 @@ Status: implemented
 
 ## 后果
 
-`dsh run` 提供本地 Agent 任务，而不是浏览器观察、Host API 或 HTTP。需要这些能力的用户选择 `dsh web`。成功时 stderr 为空，完成结果在持久化 flush 后推导，持久化会话仍可供后续工具使用。初始用户消息记录 `source.kind: 'user'`，因此不携带 ApiProxy `rpcId`。
+`dsh --profile headless` 提供本地 Agent 任务，而不是浏览器观察、Host API 或 HTTP。需要这些能力的用户选择 `dsh web`。成功时 stderr 为空，完成结果在持久化 flush 后推导，持久化会话仍可供后续工具使用。初始用户消息记录 `source.kind: 'user'`，因此不携带 ApiProxy `rpcId`。
 
 ApiProxy 载体覆盖保留在 ApiProxy 包中。自定义一次性 profile 可以显式包含 Host 或 Web 组合包；随附 profile 与可识别的安装过程所属元组均不含 Web。

.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.md
-2026-08-03-cli-signal-shutdown-escalation.md: 55917400fac2728d13dc2cdd799a7e234b6ed661
-2026-08-03-cli-signal-shutdown-escalation.zh.md: c7897a8d77e8c2ebad43cec4e12170b04c837350
+2026-08-03-cli-signal-shutdown-escalation.md: 173d06482cd8a1fcbb985763cc313e3f9b170bc6
+2026-08-03-cli-signal-shutdown-escalation.zh.md: efa52524199906cf636cb2b55cb4249857dc1348

.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.md

@@ -6,7 +6,7 @@ English | [中文](2026-08-03-cli-signal-shutdown-escalation.zh.md)
 
 ## Problem
 
-The default telemetry mount added SIGINT/SIGTERM handlers to `dsh web` and the headless command (now `dsh run`) so process exit could drain the Cordis tree instead of dropping queued telemetry. Each handler used a one-way boolean latch and exited only after `ctx.fiber.dispose()` settled. Headless normal completion also awaited that disposal without a bound.
+The default telemetry mount added SIGINT/SIGTERM handlers to `dsh web` and the headless command (now `dsh --profile headless`) so process exit could drain the Cordis tree instead of dropping queued telemetry. Each handler used a one-way boolean latch and exited only after `ctx.fiber.dispose()` settled. Headless normal completion also awaited that disposal without a bound.
 
 A user then reproduced the headless command hanging immediately after the observation URL and ignoring repeated `Ctrl+C`; `DSH_TELEMETRY_DISABLED=1` removed the hang, while a standalone Node handler in the same Linux sandbox received SIGINT. This isolated the pending disposer to telemetry rather than terminal signal forwarding. OTel's `BatchLogRecordProcessor.shutdown()` awaits `exporter.forceFlush()` before the `exportTimeoutMillis`-bounded completion promise, and the OTLP exporter's `forceFlush()` waits directly on its in-flight HTTP Promise. A proxy/sandbox connection that never obtains a socket can therefore leave provider shutdown pending despite both configured SDK timeouts.
 

.agents/notes/implemented/bug-fix/2026-08-03-cli-signal-shutdown-escalation.zh.md

@@ -6,7 +6,7 @@ Status: implemented
 
 ## 问题
 
-默认挂载遥测后，`dsh web` 与 headless 命令（现为 `dsh run`）新增了 SIGINT/SIGTERM 处理器，使进程退出时可以排空 Cordis 插件树，而不是丢弃排队中的遥测数据。每个处理器都使用单向布尔闩锁（latch），并且只有在 `ctx.fiber.dispose()` 结算后才退出。headless 正常完成时同样会无界等待整棵树执行 dispose（资源释放）。
+默认挂载遥测后，`dsh web` 与 headless 命令（现为 `dsh --profile headless`）新增了 SIGINT/SIGTERM 处理器，使进程退出时可以排空 Cordis 插件树，而不是丢弃排队中的遥测数据。每个处理器都使用单向布尔闩锁（latch），并且只有在 `ctx.fiber.dispose()` 结算后才退出。headless 正常完成时同样会无界等待整棵树执行 dispose（资源释放）。
 
 随后有用户复现，headless 命令在打印观察 URL 后立即卡死，重复按 `Ctrl+C` 也没有反应；设置 `DSH_TELEMETRY_DISABLED=1` 后不再卡死，而同一 Linux 沙箱中的独立 Node 信号处理器能够收到 SIGINT。这将待结算的 disposer 定位到遥测，而非终端信号转发。OTel 的 `BatchLogRecordProcessor.shutdown()` 会先等待 `exporter.forceFlush()`，再进入受 `exportTimeoutMillis` 限制的完成 promise；OTLP 导出器的 `forceFlush()` 则直接等待正在进行的 HTTP Promise。因此，代理／沙箱连接始终无法取得 socket 时，即使已经配置两项 SDK 超时，也会让提供方关闭一直待结算。
 

.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.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/simplification/2026-07-20-remove-stdio-and-echo-agents.md
-2026-07-20-remove-stdio-and-echo-agents.md: 256e626f4ff41016d0227eef7cc3e4e51e15058b
-2026-07-20-remove-stdio-and-echo-agents.zh.md: 013135eff5d1dbbc570561e70c751ff4de289989
+2026-07-20-remove-stdio-and-echo-agents.md: 23fcb90599c2ff96cd7ac0e6f7ee8fd508a6d1ad
+2026-07-20-remove-stdio-and-echo-agents.zh.md: 7aabf5612a54245327da9af804f745237472cb88

.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.md

@@ -19,7 +19,7 @@ The stdio and Echo agents are removed without compatibility packages, modes, com
 The remaining application roles are explicit:
 
 - `@deepseek-ai/dsh-tui` owns terminal-interactive execution. It rejects non-TTY streams before Loader boot; `apps/cli/config/base.cordis.yml` plus the `tui.cordis.yml` overlay own the complete coding composition, with PTY plus terminal-snapshot coverage in `apps/cli/tests/`.
-- [`dsh run`](../../../../apps/cli/README.md) owns non-interactive execution. Its `headless` profile is the product composition; `examples/headless-agent` owns replay snapshots, generic real-agent suites, and an unexported keyless Loader driver.
+- [`dsh --profile headless`](../../../../apps/cli/README.md) owns non-interactive execution. Its `headless` profile is the product composition; `examples/headless-agent` owns replay snapshots, generic real-agent suites, and an unexported keyless Loader driver.
 - [`@deepseek-ai/dsh-acp-demo`](../../../../packages/examples/acp-demo/README.md) and `@deepseek-ai/dsh-jsonrpc` own their framed protocol integrations.
 
 The SDK project model and create/config workflows replace the `stdio` run-interface option with `tui`; generated TUI projects compose `@deepseek-ai/dsh-tui` and create or resume one exact session. Repository-facing demo documentation requires a DeepSeek API key and leads with the real Headless or TUI agents.
@@ -30,7 +30,7 @@ Keyless validation is test-owned. The Headless Loader smoke uses a fixture adapt
 
 TUI and Headless Loader coverage run the real app packages in source and built modes. PTY-driven subprocess coverage is reserved for the TUI lifecycle; other entry-point smokes use the one-shot pipe protocol. Headless proves its task/result and tool-call contracts. Generated graphs and repository searches reject stale package, command, leaf, SDK-interface, `createStdioChat`, and `StdioRuntime` references.
 
-The built `dsh` bin rejects a piped TUI launch before Loader boot and points at `dsh run`; `apps/cli/tests/built-bin.e2e.ts` pins the product one-shot entry under plain Node, including output and invalid arguments. `examples/headless-agent/tests/headless.snapshot.ts` pins product persistence, while `apps/cli/tests/headless-shutdown.e2e.ts` owns bounded signal escalation. The headless example's test-only JSONL driver preserves assembled canonical-event snapshots without creating a second CLI contract. Code Mode has programmatic TUI snapshots and an ACP overlay demo. Time-context integration uses the explicit Headless test composition for two ordered turns, while its package tests own finer elapsed-time behavior.
+The built `dsh` bin rejects a piped TUI launch before Loader boot and points at `dsh --profile headless`; `apps/cli/tests/built-bin.e2e.ts` pins the product one-shot entry under plain Node, including output and invalid arguments. `examples/headless-agent/tests/headless.snapshot.ts` pins product persistence, while `apps/cli/tests/headless-shutdown.e2e.ts` owns bounded signal escalation. The headless example's test-only JSONL driver preserves assembled canonical-event snapshots without creating a second CLI contract. Code Mode has programmatic TUI snapshots and an ACP overlay demo. Time-context integration uses the explicit Headless test composition for two ordered turns, while its package tests own finer elapsed-time behavior.
 
 ## Alternatives considered
 

.agents/notes/implemented/simplification/2026-07-20-remove-stdio-and-echo-agents.zh.md

@@ -19,7 +19,7 @@ DeepSeek Harness 在 TUI 和 Headless coding agent 之外，还提供了两个
 保留的应用角色均有明确归属：
 
 - `@deepseek-ai/dsh-tui` 负责终端交互式执行。它会在 Loader 启动前拒绝非 TTY 流；`apps/cli/config/base.cordis.yml` 与 `tui.cordis.yml` overlay 拥有完整 coding 组装，PTY 与终端快照覆盖则位于 `apps/cli/tests/`。
-- [`dsh run`](../../../../apps/cli/README.md) 负责非交互式执行。其 `headless` profile 是产品组装；`examples/headless-agent` 负责回放快照、通用真实 agent 测试套件和未导出的无密钥 Loader driver。
+- [`dsh --profile headless`](../../../../apps/cli/README.md) 负责非交互式执行。其 `headless` profile 是产品组装；`examples/headless-agent` 负责回放快照、通用真实 agent 测试套件和未导出的无密钥 Loader driver。
 - [`@deepseek-ai/dsh-acp-demo`](../../../../packages/examples/acp-demo/README.md) 和 `@deepseek-ai/dsh-jsonrpc` 负责各自的分帧协议集成。
 
 SDK 工程模型与 create/config 工作流将 `stdio` 运行接口选项替换为 `tui`；生成的 TUI 工程组合 `@deepseek-ai/dsh-tui`，并创建或恢复一个确切会话。仓库中的演示文档要求 DeepSeek API key，并优先引导到真实的 Headless 或 TUI agent。
@@ -30,7 +30,7 @@ SDK 工程模型与 create/config 工作流将 `stdio` 运行接口选项替换
 
 TUI 与 Headless 的 Loader 覆盖以源码和构建产物两种模式运行真实 app 包。由 PTY 驱动的子进程覆盖仅用于 TUI 生命周期；其他入口冒烟测试使用单次管道协议。Headless 验证任务/结果约定和工具调用约定。生成图谱与仓库搜索会拒绝陈旧的包、命令、叶节点、SDK 接口、`createStdioChat` 和 `StdioRuntime` 引用。
 
-构建后的 `dsh` 可执行文件会在 Loader 启动前拒绝通过管道启动 TUI，并指向 `dsh run`；`apps/cli/tests/built-bin.e2e.ts` 在普通 Node 下固定产品的一次性入口，包括输出和无效参数。`examples/headless-agent/tests/headless.snapshot.ts` 固定产品持久化，`apps/cli/tests/headless-shutdown.e2e.ts` 则负责有界信号升级。headless 示例仅供测试的 JSONL driver 保留组装后的规范事件快照，而不会创建第二套 CLI（命令行界面）约定。Code Mode 由程序化 TUI 快照与 ACP overlay demo 覆盖。时间上下文集成通过显式的 Headless 测试组装执行两个有序轮次，而更细粒度的耗时行为由时间上下文的包级测试负责。
+构建后的 `dsh` 可执行文件会在 Loader 启动前拒绝通过管道启动 TUI，并指向 `dsh --profile headless`；`apps/cli/tests/built-bin.e2e.ts` 在普通 Node 下固定产品的一次性入口，包括输出和无效参数。`examples/headless-agent/tests/headless.snapshot.ts` 固定产品持久化，`apps/cli/tests/headless-shutdown.e2e.ts` 则负责有界信号升级。headless 示例仅供测试的 JSONL driver 保留组装后的规范事件快照，而不会创建第二套 CLI（命令行界面）约定。Code Mode 由程序化 TUI 快照与 ACP overlay demo 覆盖。时间上下文集成通过显式的 Headless 测试组装执行两个有序轮次，而更细粒度的耗时行为由时间上下文的包级测试负责。
 
 ## 曾考虑的替代方案
 

.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.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/simplification/2026-08-08-remove-cli-demo.md
-2026-08-08-remove-cli-demo.md: 403e01f94c976d2d17eb391830721b31675cd6a9
-2026-08-08-remove-cli-demo.zh.md: 7f11e0c17a15454b99b32d14ea6eda177f4b01f6
+2026-08-08-remove-cli-demo.md: 31879e8284daf5f34af6731b09fce743f9eb5391
+2026-08-08-remove-cli-demo.zh.md: d4dfef1ba8c4d27cd667e319519cfa1ace74baef

.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.md

@@ -6,29 +6,29 @@ English | [中文](2026-08-08-remove-cli-demo.zh.md)
 
 ## Problem
 
-After [`dsh run`](../feature/2026-08-08-dsh-run-headless-command.md) became the product one-shot command, `@deepseek-ai/dsh-cli-demo` remained a second application package for the same job. It carried another executable, argument grammar, app composition, cancellation lifecycle, text/JSON/stream-JSON output contract, built artifact, documentation surface, and test suite. The two entry points also assembled different trees, so a successful demo did not prove the shipped `headless` profile and users had to choose between overlapping commands.
+After [`dsh --profile headless`](../architecture/2026-08-06-app-owned-command-line.md) became the product one-shot command, `@deepseek-ai/dsh-cli-demo` remained a second application package for the same job. It carried another executable, argument grammar, app composition, cancellation lifecycle, text/JSON/stream-JSON output contract, built artifact, documentation surface, and test suite. The two entry points also assembled different trees, so a successful demo did not prove the shipped `headless` profile and users had to choose between overlapping commands.
 
 The replay suites still need canonical session events to pin assembled backend behavior. That testing need does not require a published command or compatibility contract.
 
 ## Decision
 
-Delete `@deepseek-ai/dsh-cli-demo` completely: its package, bin, parser, app plugin, output formats, tests, workspace references, generated-catalog entries, and active documentation. No alias or compatibility package remains. The root `demo:headless` script is retained only as a direct alias of `dsh run`; the product command owns final-text stdout, the observation URL on stderr, persistence, exit status, and shutdown.
+Delete `@deepseek-ai/dsh-cli-demo` completely: its package, bin, parser, app plugin, output formats, tests, workspace references, generated-catalog entries, and active documentation. No alias or compatibility package remains. The root `demo:headless` script is retained only as a direct alias of `dsh --profile headless`; the product command owns final-text stdout, failure diagnostics on stderr, persistence, exit status, and shutdown.
 
 `examples/headless-agent` becomes an explicit test composition. Its Loader configs mount `@deepseek-ai/dsh-agent-spine-demo`, one root agent, JSONL persistence, and checkpoint policy as separate rows instead of hiding them behind an app bundle. The support-tier `@deepseek-ai/dsh-loader-smoke` package owns the shared direct-agent turn helper; unexported example-local drivers select their Loader configuration and render canonical events as JSONL. They are launched only by tests, have no bin, and do not define a supported product output format.
 
 ## Alternatives considered
 
-- **Keep `dsh-cli-demo` as an alias or wrapper around `dsh run`.** Rejected because a second bin and package would preserve two discoverable owners without adding capability.
-- **Move JSON and stream-JSON flags onto `dsh run`.** Rejected because no current product consumer requires them; adopting the old demo protocol would enlarge the canonical CLI contract solely to save test machinery.
+- **Keep `dsh-cli-demo` as an alias or wrapper around `dsh --profile headless`.** Rejected because a second bin and package would preserve two discoverable owners without adding capability.
+- **Move JSON and stream-JSON flags onto `dsh --profile headless`.** Rejected because no current product consumer requires them; adopting the old demo protocol would enlarge the canonical CLI contract solely to save test machinery.
 - **Delete the canonical-event snapshots with the package.** Rejected because they pin model-visible assembled behavior that final-text product acceptance cannot observe.
 - **Keep the app plugin but delete only its bin.** Rejected because the hidden composition would still duplicate the explicit headless profile and conceal which services the test leaf mounts.
 
 ## Consequences
 
-This is intentionally breaking. `dsh-cli-demo`, its `--output-format` choices, and imports from `@deepseek-ai/dsh-cli-demo/src/cli.ts` no longer resolve. There is no public event-stream replacement in this change; callers use `dsh run` for one-shot execution and must choose an existing protocol surface when they need structured automation.
+This is intentionally breaking. `dsh-cli-demo`, its `--output-format` choices, and imports from `@deepseek-ai/dsh-cli-demo/src/cli.ts` no longer resolve. There is no public event-stream replacement in this change; callers use `dsh --profile headless` for one-shot execution and must choose an existing protocol surface when they need structured automation.
 
-The repository retains backend replay coverage through test-only infrastructure, while product smoke and built-bin acceptance exercise `dsh run`. A separate one-shot package may return only if it owns a genuinely independent, versioned protocol that cannot belong to the product launcher; a second spelling or output shim is not enough.
+The repository retains backend replay coverage through test-only infrastructure, while product smoke and built-bin acceptance exercise `dsh --profile headless`. A separate one-shot package may return only if it owns a genuinely independent, versioned protocol that cannot belong to the product launcher; a second spelling or output shim is not enough.
 
 ## Verification
 
-Focused Loader smokes cover the explicit composition in source and plain-Node built modes, snapshot tests diff its canonical JSONL and persisted logs, product acceptance covers `dsh run`, and documentation plus generated graph/catalog gates reject live references to the removed package. The frozen Agent Note archive remains historical evidence and is not rewritten.
+Focused Loader smokes cover the explicit composition in source and plain-Node built modes, snapshot tests diff its canonical JSONL and persisted logs, product acceptance covers `dsh --profile headless`, and documentation plus generated graph/catalog gates reject live references to the removed package. The frozen Agent Note archive remains historical evidence and is not rewritten.

.agents/notes/implemented/simplification/2026-08-08-remove-cli-demo.zh.md

@@ -6,29 +6,29 @@ Status: implemented
 
 ## 问题
 
-在 [`dsh run`](../feature/2026-08-08-dsh-run-headless-command.md) 成为产品的一次性命令后，`@deepseek-ai/dsh-cli-demo` 仍是承担同一工作的第二个应用包。它另行拥有一套可执行文件、参数语法、应用组装、取消生命周期、文本／JSON／stream-JSON 输出约定、构建产物、配套文档和测试套件。两个入口组装的树也不相同，因此 demo 成功不能证明已交付的 `headless` profile 可用，用户还必须在功能重叠的命令之间作出选择。
+在 [`dsh --profile headless`](../architecture/2026-08-06-app-owned-command-line.md) 成为产品的一次性命令后，`@deepseek-ai/dsh-cli-demo` 仍是承担同一工作的第二个应用包。它另行拥有一套可执行文件、参数语法、应用组装、取消生命周期、文本／JSON／stream-JSON 输出约定、构建产物、配套文档和测试套件。两个入口组装的树也不相同，因此 demo 成功不能证明已交付的 `headless` profile 可用，用户还必须在功能重叠的命令之间作出选择。
 
 回放套件仍需要规范会话事件来固定组装后的后端行为。这一测试需求不需要已发布命令或兼容性约定。
 
 ## 决策
 
-彻底删除 `@deepseek-ai/dsh-cli-demo`：包括它的包、bin、解析器、应用插件、输出格式、测试、workspace 引用、生成目录条目和现行文档。不保留别名或兼容包。根目录的 `demo:headless` 脚本仅作为 `dsh run` 的直接别名保留；stdout 上的最终文本、stderr 上的观察 URL、持久化、退出状态和关闭行为均由产品命令负责。
+彻底删除 `@deepseek-ai/dsh-cli-demo`：包括它的包、bin、解析器、应用插件、输出格式、测试、workspace 引用、生成目录条目和现行文档。不保留别名或兼容包。根目录的 `demo:headless` 脚本仅作为 `dsh --profile headless` 的直接别名保留；stdout 上的最终文本、stderr 上的失败诊断、持久化、退出状态和关闭行为均由产品命令负责。
 
 `examples/headless-agent` 成为显式测试组装。其 Loader 配置把 `@deepseek-ai/dsh-agent-spine-demo`、一个根 agent（智能体）、JSONL 持久化和检查点策略挂载为独立配置行，不再将其隐藏在应用组合包之后。支持层的 `@deepseek-ai/dsh-loader-smoke` 包负责共享的直接 agent 轮次 helper；未导出的示例本地 driver 选择各自的 Loader 配置，并将规范事件渲染为 JSONL。这些 driver 只由测试启动，不提供 bin，也不定义受支持的产品输出格式。
 
 ## 考虑过的替代方案
 
-- **保留 `dsh-cli-demo` 作为 `dsh run` 的别名或包装层。** 不予采纳：第二个 bin 和包会让同一功能继续存在两个可发现的归属方，却没有增加任何能力。
-- **把 JSON 和 stream-JSON 标志移到 `dsh run`。** 不予采纳：当前没有产品消费方需要这些标志；沿用旧 demo 协议，只会为了保留测试机制而扩大规范 CLI（命令行界面）约定。
+- **保留 `dsh-cli-demo` 作为 `dsh --profile headless` 的别名或包装层。** 不予采纳：第二个 bin 和包会让同一功能继续存在两个可发现的归属方，却没有增加任何能力。
+- **把 JSON 和 stream-JSON 标志移到 `dsh --profile headless`。** 不予采纳：当前没有产品消费方需要这些标志；沿用旧 demo 协议，只会为了保留测试机制而扩大规范 CLI（命令行界面）约定。
 - **随包一并删除规范事件快照。** 不予采纳：这些快照固定了模型可见的组装行为，而只检查最终文本的产品验收无法观察这些行为。
 - **保留应用插件，只删除它的 bin。** 不予采纳：隐藏的组装仍会重复显式的 headless profile，并掩盖测试叶节点挂载了哪些服务。
 
 ## 后果
 
-这是有意为之的破坏性变更。`dsh-cli-demo`、它的 `--output-format` 选项以及对 `@deepseek-ai/dsh-cli-demo/src/cli.ts` 的导入都不再可解析。本变更不提供公开的事件流替代接口；调用方使用 `dsh run` 执行一次性任务，需要结构化自动化时则必须选择现有的协议接口。
+这是有意为之的破坏性变更。`dsh-cli-demo`、它的 `--output-format` 选项以及对 `@deepseek-ai/dsh-cli-demo/src/cli.ts` 的导入都不再可解析。本变更不提供公开的事件流替代接口；调用方使用 `dsh --profile headless` 执行一次性任务，需要结构化自动化时则必须选择现有的协议接口。
 
-仓库通过仅供测试的基础设施保留后端回放覆盖，产品冒烟测试和 built-bin 验收则运行 `dsh run`。只有当独立的一次性包负责一套真正独立、带版本且不能归产品启动器所有的协议时，它才可以重新引入；第二种命令写法或输出 shim 并不足以构成理由。
+仓库通过仅供测试的基础设施保留后端回放覆盖，产品冒烟测试和 built-bin 验收则运行 `dsh --profile headless`。只有当独立的一次性包负责一套真正独立、带版本且不能归产品启动器所有的协议时，它才可以重新引入；第二种命令写法或输出 shim 并不足以构成理由。
 
 ## 验证
 
-聚焦的 Loader 冒烟测试在源码模式和由普通 Node 启动的构建模式下覆盖显式组装，快照测试对比其规范 JSONL 和持久化日志，产品验收覆盖 `dsh run`，文档检查及生成图谱／目录门禁则拒绝对已移除包的活跃引用。冻结的 Agent Note 归档保留为历史证据，不会被重写。
+聚焦的 Loader 冒烟测试在源码模式和由普通 Node 启动的构建模式下覆盖显式组装，快照测试对比其规范 JSONL 和持久化日志，产品验收覆盖 `dsh --profile headless`，文档检查及生成图谱／目录门禁则拒绝对已移除包的活跃引用。冻结的 Agent Note 归档保留为历史证据，不会被重写。

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 README.md
-README.md: 3174630d021b3868986d6ad9989d257fe8ac29fb
-README.zh.md: 377ea6372a9a531c1400d08b0ef33792b452dc65
+README.md: 9b8944027572072e08a39bd9e482996f8128224c
+README.zh.md: a1b2b6a36c4baac8a49b88a42c9f17c986287ff1

README.md

@@ -56,7 +56,7 @@ The [CLI reference](apps/cli/README.md#profiles) describes profile layout, layer
 Run one task, print the final answer, and exit:
 
 ```sh
-dsh run "summarize this workspace"
+dsh --profile headless "summarize this workspace"
 ```
 
 ### Automation and SDKs

README.zh.md

@@ -56,7 +56,7 @@ profile 布局、层语义与配置输出命令详见 [CLI（命令行界面）
 运行一项任务，打印最终答案后退出：
 
 ```sh
-dsh run "summarize this workspace"
+dsh --profile headless "summarize this workspace"
 ```
 
 ### 自动化与 SDK

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: dd29f7fc03a783079ea3194de99589c1f545be5b
-README.zh.md: 60e7aa1ec1ea2fad7e3f3d97a0f6bf42355adffc
+README.md: 4fae5338a89ce12c2620e123530acf883ae9efff
+README.zh.md: a2d086b8ff12fb07f2446fc4162de09739bcdeab

apps/cli/README.md

@@ -9,15 +9,27 @@ 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 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 --profile headless "task"` | Run one fresh persisted session, print the final answer, and exit. |
+| `dsh web` | Alias of `--profile web`. |
 | `dsh plugin --profile <name> <pnpm args>` | Manage a profile's plugins by forwarding to pnpm in the profile directory. |
 
-The invoking directory is the default workspace root. `dsh run` requires non-blank task text and the selected profile must mount the `headless-runner` row; `--profile` preserves custom one-shot profiles. The `web` and `headless` profiles auto-initialize on first use from shipped templates; any other profile must be created through `dsh plugin`.
+The invoking directory is the default workspace root. The `web` and `headless` profiles auto-initialize on first use from shipped templates; any other profile must be created through `dsh plugin`.
+
+## App arguments
+
+The launcher parses only its own flags and hands everything after them to the booted profile, where any injected app plugin may parse the shared immutable snapshot ([`dsh-cmdline`](../../packages/boot/cmdline/README.md)). Launcher flags therefore come first, and the first token the launcher does not recognize starts the app's arguments:
+
+```sh
+dsh --profile web --port 8080       # --port belongs to the web app
+dsh --profile tui --resume <id>     # --resume belongs to the terminal app
+dsh --profile headless "run the tests"
+dsh --profile web --help            # the web app's flags, not the launcher's
+dsh --help                          # the launcher's own help
+```
 
 ## Profiles
 
-A profile directory holds a `package.json` (out-of-tree plugin dependencies plus the profile manifest `dsh.profile` with its ordered `bundles` list) and a `cordis.patch.yml` (the user's own patch layer, hot-reloaded on long-lived surfaces). The tree composes over an empty root: each bundle's patch in `dsh.profile.bundles` order, then the profile's `cordis.patch.yml`, then the home-level `$DSH_HOME/cordis.patch.yml`, then `--patch` overlays, then flag patches. Bundles named in `dsh.profile.bundles` resolve from the dsh installation first (`@deepseek-ai/dsh-base`, `@deepseek-ai/dsh-web-app`, `@deepseek-ai/dsh-headless`), then from the profile's own `node_modules`, where pnpm installs out-of-tree plugins. Use `--dump-default-config` and `--dump-config` to inspect the composed tree without booting it.
+A profile directory holds a `package.json` (out-of-tree plugin dependencies plus the profile manifest `dsh.profile` with its ordered `bundles` list) and a `cordis.patch.yml` (the user's own patch layer, hot-reloaded on long-lived surfaces). The tree composes over an empty root: each bundle's patch in `dsh.profile.bundles` order, then the profile's `cordis.patch.yml`, then the home-level `$DSH_HOME/cordis.patch.yml`, then `--patch` overlays. Bundles named in `dsh.profile.bundles` resolve from the dsh installation first (`@deepseek-ai/dsh-base`, `@deepseek-ai/dsh-web-app`, `@deepseek-ai/dsh-headless`), then from the profile's own `node_modules`, where pnpm installs out-of-tree plugins. Use `--dump-default-config` and `--dump-config` to inspect the composed tree without booting it.
 
 The [CLI behavior reference](reference/README.md) owns exact layer precedence, flags, shutdown behavior, deployment defaults, and the source launcher.
 

apps/cli/README.zh.md

@@ -9,18 +9,30 @@
 | 命令 | 用途 |
 |---|---|
 | `dsh --profile <name>` | 启动位于 `$DSH_HOME/profiles/<name>` 的指定 profile。 |
-| `dsh run [--profile <name>] [--patch <path>...] "task"` | 直接在 core 上运行一个新的持久化会话，打印最终答案并退出；profile 默认为 `headless`，且不挂载 Web server。 |
-| `dsh web` | `--profile web` 的别名，附带 Web flag 系列（`--host`、`--port`、`--dev` 等）。 |
+| `dsh --profile headless "task"` | 运行一个新的持久化会话，打印最终答案并退出。 |
+| `dsh web` | `--profile web` 的别名。 |
 | `dsh plugin --profile <name> <pnpm args>` | 通过在 profile 目录中转发给 pnpm 来管理该 profile 的插件。 |
 
-调用目录是默认 workspace 根目录。`dsh run` 要求任务文本非空白，且所选 profile 必须挂载 `headless-runner` 行；`--profile` 保留对自定义一次性 profile 的支持。`web` 和 `headless` profile 在首次使用时会从随附模板自动初始化；其他任何 profile 都必须通过 `dsh plugin` 创建。
+调用目录是默认 workspace 根目录。`web` 和 `headless` profile 在首次使用时会从随附模板自动初始化；其他任何 profile 都必须通过 `dsh plugin` 创建。
+
+## 应用参数
+
+启动器只解析属于自己的 flag,并把其后的一切交给启动起来的 profile,任何注入它的应用插件都可以解析这份共享的不可变快照([`dsh-cmdline`](../../packages/boot/cmdline/README.md))。因此启动器的 flag 必须写在前面,而启动器不认识的第一个 token 就是应用参数的起点:
+
+```sh
+dsh --profile web --port 8080       # --port belongs to the web app
+dsh --profile tui --resume <id>     # --resume belongs to the terminal app
+dsh --profile headless "run the tests"
+dsh --profile web --help            # the web app's flags, not the launcher's
+dsh --help                          # the launcher's own help
+```
 
 ## Profile
 
-profile 目录包含一个 `package.json`（树外插件依赖，加上 profile manifest（元数据清单）`dsh.profile` 及其有序的 `bundles` 列表）和一个 `cordis.patch.yml`（用户自己的 patch 层，在长期运行的 surface 上热重载）。配置树在空根之上组合：先按 `dsh.profile.bundles` 顺序应用各组合包的 patch，然后是 profile 的 `cordis.patch.yml`，然后是 home 级的 `$DSH_HOME/cordis.patch.yml`，然后是 `--patch` overlay，最后是 flag patch。`dsh.profile.bundles` 中列出的组合包先从 dsh 安装目录解析（`@deepseek-ai/dsh-base`、`@deepseek-ai/dsh-web-app`、`@deepseek-ai/dsh-headless`），再从 profile 自己的 `node_modules` 解析；pnpm 把树外插件安装在后者。使用 `--dump-default-config` 和 `--dump-config` 可在不启动的情况下检查组合后的配置树。
+profile 目录包含一个 `package.json`（树外插件依赖，加上 profile manifest（元数据清单）`dsh.profile` 及其有序的 `bundles` 列表）和一个 `cordis.patch.yml`（用户自己的 patch 层，在长期运行的 surface 上热重载）。配置树在空根之上组合：先按 `dsh.profile.bundles` 顺序应用各组合包的 patch，然后是 profile 的 `cordis.patch.yml`，然后是 home 级的 `$DSH_HOME/cordis.patch.yml`，然后是 `--patch` overlay。`dsh.profile.bundles` 中列出的组合包先从 dsh 安装目录解析（`@deepseek-ai/dsh-base`、`@deepseek-ai/dsh-web-app`、`@deepseek-ai/dsh-headless`），再从 profile 自己的 `node_modules` 解析；pnpm 把树外插件安装在后者。使用 `--dump-default-config` 和 `--dump-config` 可在不启动的情况下检查组合后的配置树。
 
 [CLI（命令行界面）行为参考](reference/README.md)负责确切的层优先级、flag、关闭行为、部署默认值和源码启动器。
 
 ## 开发
 
-生产运行需要已构建的包与前端产物。在 checkout 中，`pnpm run dsh` 会运行 TypeScript 入口并转发参数；[源码启动器参考](reference/README.md#source-launcher)说明 PATH 符号链接和模块解析约定。
+生产运行需要已构建的包与前端产物。在 checkout 中，`pnpm run dsh` 会运行 TypeScript 入口并转发参数；[源码启动器参考](reference/README.md#source-launcher)说明 PATH 符号链接和模块解析契约。

apps/cli/package.json

@@ -27,6 +27,8 @@
     "@deepseek-ai/dsh-compact-tool-result-prune": "workspace:^",
     "@deepseek-ai/dsh-goal": "workspace:^",
     "@deepseek-ai/dsh-goal-session": "workspace:^",
+    "@deepseek-ai/dsh-cmdline": "workspace:^",
+    "@deepseek-ai/dsh-environment": "workspace:^",
     "@deepseek-ai/dsh-headless": "workspace:^",
     "@deepseek-ai/dsh-mcp-client": "workspace:^",
     "@deepseek-ai/dsh-paths": "workspace:^",

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: 756fed1f1802600e82948ce8ca808706b2299660
-README.zh.md: edd20c7fc3a3103097aa5e3949418e373172cadb
+README.md: fd0647347312051a1814a5e3464b34032ae70dfc
+README.zh.md: afe4b9ba5651e962288ffebbe7c095ad20bcc617

apps/cli/reference/README.md

@@ -2,17 +2,32 @@
 
 English | [中文](README.zh.md)
 
-This reference defines the profile, one-shot run, web-alias, plugin-management, and config-dump command modes. Argv is parsed once through [`src/args.ts`](../src/args.ts), and [`src/bin.ts`](../src/bin.ts) dynamically imports only the selected runner.
+This reference defines the profile, web-alias, plugin-management, and config-dump command modes. Argv is parsed once through [`src/args.ts`](../src/args.ts), and [`src/bin.ts`](../src/bin.ts) dynamically imports only the selected runner.
 
 ## Profile boot
 
-`dsh --profile <name>` boots the profile at `$DSH_HOME/profiles/<name>`. The effective tree is composed over an empty root by applying, in order: each bundle patch named in the profile manifest's `dsh.profile.bundles` list, the profile's own `cordis.patch.yml`, the home-level `$DSH_HOME/cordis.patch.yml` (machine-local preferences shared by every profile, so it outranks the per-profile layer), each `--patch <path>` overlay in argv order, and launcher flag patches. Later layers win per row; a patch replaces the targeted row's complete `config` value rather than deep-merging keys, and may insert new rows. A parse, schema, resolution, or plugin boot failure is reported and exits nonzero. SIGINT and SIGTERM dispose the mounted root before exit.
+`dsh --profile <name>` boots the profile at `$DSH_HOME/profiles/<name>`. The effective tree is composed over an empty root by applying, in order: each bundle patch named in the profile manifest's `dsh.profile.bundles` list, the profile's own `cordis.patch.yml`, the home-level `$DSH_HOME/cordis.patch.yml` (machine-local preferences shared by every profile, so it outranks the per-profile layer), and each `--patch <path>` overlay in argv order. Later layers win per row; a patch replaces the targeted row's complete `config` value rather than deep-merging keys, and may insert new rows. A parse, schema, resolution, or plugin boot failure is reported and exits nonzero. SIGINT and SIGTERM dispose the mounted root before exit.
 
 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 + 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>`.
+The `web` and `headless` profiles auto-initialize from shipped templates on first use (`web`: base + web-app; `headless`: base + headless). 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.
+### App arguments
+
+The launcher's flags come first and end at the first token it does not recognize; everything from there on is handed to the booted profile verbatim through `ctx.cmdlineArgs`, where any injected app plugin may parse it ([`dsh-cmdline`](../../../packages/boot/cmdline/README.md)). `dsh --profile web --port 8080` therefore reaches the web app's `--port`, `dsh --profile web --help` prints that app's help and boots nothing, and `dsh --help` (no profile to hand it to) prints the launcher's own. `-V`/`--version` prints the launcher's version when it appears before the app-argument boundary.
+
+A composition mounts once. An ordinary plugin injects `cmdlineArgs`, parses this app's arguments, and provides what it resolved as a service; each row configured from flags injects that service, and Loader waits for it before evaluating the row's config (`port: !!js ctx.webStartup.port ?? 3080`). A flag therefore beats the value written beside it. This precedence requires the row to retain that expression; a user patch that replaces the whole `config` with literals removes the runtime read. Help and rejected arguments request exit — nonzero for a rejection, 0 for help — without activating rows that depend on the provider's service. A live `cordis.patch.yml` edit re-evaluates expressions against services that are still up, so it cannot reset a served port.
+
+Launcher flags must come before app arguments, and the launcher's parser consumes one `--`: an app argument that must arrive as a literal `--` needs `-- --`. A first app argument equal to `web` or `plugin` selects that subcommand instead. `ctx.cmdlineArgs.get()` is a shared immutable read: multiple plugins may parse the same snapshot, while a profile with no reader ignores its app arguments.
+
+The shipped apps own these command lines:
+
+| Profile | Arguments |
+|---|---|
+| `web` | `--host`, `--port`, `--dev`, repeatable `--trusted-host` |
+| `headless` | the task text, as the positional argument |
+
+A one-shot task (`dsh --profile headless "run the tests"`) creates one fresh persisted Agent through the core registry, 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. An invocation with no task is a usage error from that app. 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.
 
 Inspect the composed tree without booting it:
 
@@ -21,13 +36,7 @@ dsh --profile web --dump-default-config
 dsh --profile web --patch ./extra.yml --dump-config
 ```
 
-`--dump-default-config` prints only the bundle layers; `--dump-config` adds the profile's `cordis.patch.yml`, the home-level `$DSH_HOME/cordis.patch.yml`, and `--patch` overlays. Both print comments naming the file that supplied each row and every overlay that changed it; `!!js` expressions remain unevaluated, and unmatched patch targets are reported on stderr.
-
-## One-shot run
-
-`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. 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.
+`--dump-default-config` prints only the bundle layers; `--dump-config` adds the profile's `cordis.patch.yml`, the home-level `$DSH_HOME/cordis.patch.yml`, and `--patch` overlays. Both print comments naming the file that supplied each row and every overlay that changed it; `!!js` expressions remain unevaluated, and unmatched patch targets are reported on stderr. A dump never runs app command-line providers, so it shows the composed tree before any app argument is resolved and rejects an invocation that carries app arguments.
 
 ## Plugin management
 
@@ -43,12 +52,13 @@ Git-hosted plugins that ship sources build during install through their `prepare
 
 ## Web alias
 
-`dsh web` is a hardcoded alias for `--profile web` that additionally accepts the Web flag family. `--host`, `--port`, and repeatable `--trusted-host` values become patches over the composed rows; their owning plugin schemas validate them at boot. `--dev` switches the web-runtime row to development mode and inserts the client-plugin HMR receiver; it expects a separate `pnpm run dev:web` watcher for no-refresh client bundle updates.
+`dsh web` is a hardcoded alias for `--profile web`; the flags after it belong to the web app, whose ordinary bundle provider parses them. `--host` and `--port` override the composed values of the rows that carry them, repeatable `--trusted-host` contributes invocation authorities through `ctx.webRuntime.trustedHosts` (a deployment expression concatenates its own authorities), and `--dev` switches the web-runtime row to development mode and enables the client-plugin HMR receiver the bundle ships disabled; it expects a separate `pnpm run dev:web` watcher for no-refresh client bundle updates.
 
 ```sh
 dsh web
 dsh web --patch ./extra.cordis.yml
 dsh web --dump-config
+dsh web --help
 ```
 
 The production Web runner needs built package and frontend artifacts (`pnpm run build`). It serves `http://127.0.0.1:3080` by default. Binding all interfaces also trusts the machine's discovered LAN IP literals; `--trusted-host` adds named authorities accepted by the `/api` browser-trust fence.

apps/cli/reference/README.zh.md

@@ -2,17 +2,32 @@
 
 [English](README.md) | 中文
 
-本参考定义 profile、一次性运行、web 别名、插件管理和配置 dump 命令模式。参数由 [`src/args.ts`](../src/args.ts) 统一解析，[`src/bin.ts`](../src/bin.ts) 只动态导入选中的运行器。
+本参考定义 profile、web 别名、插件管理和配置 dump 命令模式。参数由 [`src/args.ts`](../src/args.ts) 统一解析，[`src/bin.ts`](../src/bin.ts) 只动态导入选中的运行器。
 
 ## Profile 启动
 
-`dsh --profile <name>` 启动位于 `$DSH_HOME/profiles/<name>` 的 profile。生效配置树在空根节点之上按以下顺序逐层组合：profile manifest（元数据清单）的 `dsh.profile.bundles` 列表所列的各个组合包 patch、profile 自身的 `cordis.patch.yml`、home 级的 `$DSH_HOME/cordis.patch.yml`（各 profile 共享的机器本地偏好，因此优先级高于逐 profile 的层）、按 argv 顺序的各个 `--patch <path>` overlay，以及启动器 flag patch。后应用的层按行胜出；patch 替换目标行完整的 `config` 值，而不是深度合并各键，并且可以插入新行。配置解析、schema 校验、模块解析或插件启动失败会得到报告并以非零状态退出。收到 SIGINT 或 SIGTERM 时，挂载的根节点会先 dispose（资源释放）再退出。
+`dsh --profile <name>` 启动位于 `$DSH_HOME/profiles/<name>` 的 profile。生效配置树在空根节点之上按以下顺序逐层组合：profile manifest（元数据清单）的 `dsh.profile.bundles` 列表所列的各个组合包 patch、profile 自身的 `cordis.patch.yml`、home 级的 `$DSH_HOME/cordis.patch.yml`（各 profile 共享的机器本地偏好，因此优先级高于逐 profile 的层）、以及按 argv 顺序的各个 `--patch <path>` overlay。后应用的层按行胜出；patch 替换目标行完整的 `config` 值，而不是深度合并各键，并且可以插入新行。配置解析、schema 校验、模块解析或插件启动失败会得到报告并以非零状态退出。收到 SIGINT 或 SIGTERM 时，挂载的根节点会先 dispose（资源释放）再退出。
 
 组合包名称先从 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 + headless）。加载时，与安装所管理的 headless 元组（base + web-app + headless）完全一致的列表会规范化为随附模板；包含额外项、缺少项或调整过顺序的组合包列表由用户拥有，保持不变。其他缺失的 profile 会显式报错，并提示运行 `dsh plugin --profile <name> add <package>`。
+`web` 和 `headless` profile 首次使用时会从随附模板自动初始化（`web`：base + web-app；`headless`：base + headless）。其他缺失的 profile 会显式报错，并提示运行 `dsh plugin --profile <name> add <package>`。
 
-Profile 启动不接受位置参数任务。因此，挂载了一次性运行器行（`headless-runner`）的 profile 会显式报错，并提示规范命令 `dsh run --profile <name> "<task>"`，而不会触发该行原始的必填字段错误。
+### 应用参数
+
+启动器自己的 flag 写在最前面,并在它不认识的第一个 token 处结束;从那里开始的一切都通过 `ctx.cmdlineArgs` 原样交给启动起来的 profile,任何注入它的应用插件都可以解析([`dsh-cmdline`](../../../packages/boot/cmdline/README.md))。因此 `dsh --profile web --port 8080` 到达的是 web 应用的 `--port`,`dsh --profile web --help` 打印的是该应用的 help 且什么也不启动,而 `dsh --help`(没有可以交付的 profile)打印的是启动器自己的 help。`-V`/`--version` 写在应用参数边界之前时会打印启动器的版本。
+
+一套组合只挂载一次。普通插件注入 `cmdlineArgs`、解析本应用参数，并把结果作为服务提供出去；由 flag 配置的每一行都会注入该服务，Loader 会等服务激活后再求值该行配置（`port: !!js ctx.webStartup.port ?? 3080`），因此 flag 胜过写在它旁边的值。该优先级要求配置行保留这一表达式；若用户 patch 用字面量替换整份 `config`，运行时读取也会随之消失。help 和被拒绝的参数会请求退出——拒绝时以非零状态，help 时以 0——且不会激活依赖提供方服务的行。在线编辑 `cordis.patch.yml` 会针对仍然在线的服务重新求值表达式，因此不会重置已在服务的端口。
+
+启动器的 flag 必须写在应用参数之前，且启动器的解析器会消耗掉一个 `--`：必须以字面量 `--` 送达应用的参数需要写成 `-- --`。如果应用的第一个参数恰好等于 `web` 或 `plugin`，会选择对应的子命令。`ctx.cmdlineArgs.get()` 是共享的不可变读取：多个插件可以解析同一份快照，没有读取方的 profile 则会忽略自己的应用参数。
+
+随附的各应用持有这些命令行：
+
+| Profile | 参数 |
+|---|---|
+| `web` | `--host`、`--port`、`--dev`、可重复的 `--trusted-host` |
+| `headless` | 任务文本，作为位置参数 |
+
+一次性任务（`dsh --profile headless "run the tests"`）通过核心注册表创建一个全新的持久化 Agent（智能体），提交任务、等待完全停稳并对 Session 执行 flush，再从其持久化事件区间中推导最后一个非空 assistant 文本与最终 `turn/end` 原因。它在 stdout 打印文本，并在原因为 `completed` 时以 0 退出，否则以 1 退出。没有任务的调用是该应用的用法错误。随附 headless profile 不挂载 ApiProxy、Host、HTTP 服务器、Web 运行时或浏览器客户端；成功运行不会向 stderr 写入任何内容，也不会打开监听端口。
 
 可在不启动的情况下检查组合出的配置树：
 
@@ -21,13 +36,7 @@ dsh --profile web --dump-default-config
 dsh --profile web --patch ./extra.yml --dump-config
 ```
 
-`--dump-default-config` 只打印组合包各层；`--dump-config` 额外加上 profile 的 `cordis.patch.yml`、home 级的 `$DSH_HOME/cordis.patch.yml` 和 `--patch` overlay。两者都会打印注释，标明每行由哪个文件提供，以及哪些 overlay 修改过它；`!!js` 表达式保持未求值，找不到目标的 patch 会报告到 stderr。
-
-## 一次性运行
-
-`dsh run [--profile <name>] [--patch <path>...] <task...>` 会用空格拼接任务参数，拒绝缺失或空白任务，并让 `--profile` 默认为 `headless`。可重复使用的 `--patch` overlay 与 profile 启动的 overlay 位于同一层。所选的自定义 profile 必须挂载 `headless-runner`；否则启动器会在启动前失败，并在诊断中指明缺少该行。
-
-启动器把任务文本 patch 进运行器行。Loader 结算后，运行器读取共享的 `ctx.agentDefaultModel` 默认值，通过 `ctx.agents` 创建一个全新的持久化 Agent（智能体），提交任务、等待完全停稳并对 Session 执行 flush，再从其持久化事件区间中推导最后一个非空 assistant 文本与最终 `turn/end` 原因。它在 stdout 打印文本，并在原因为 `completed` 时以 0 退出，否则以 1 退出。随附 headless profile 不挂载 ApiProxy、Host、HTTP 服务器、Web 运行时或浏览器客户端；成功运行不会向 stderr 写入任何内容，也不会打开监听端口。
+`--dump-default-config` 只打印组合包各层；`--dump-config` 额外加上 profile 的 `cordis.patch.yml`、home 级的 `$DSH_HOME/cordis.patch.yml` 和 `--patch` overlay。两者都会打印注释，标明每行由哪个文件提供，以及哪些 overlay 修改过它；`!!js` 表达式保持未求值，找不到目标的 patch 会报告到 stderr。dump 从不运行应用命令行提供方，因此它展示的是任何应用参数被解析之前的组合配置树，并拒绝携带应用参数的调用。
 
 ## 插件管理
 
@@ -43,12 +52,13 @@ Git 托管、随附源码的插件在安装期间通过其 `prepare` 脚本构
 
 ## Web 别名
 
-`dsh web` 是 `--profile web` 的硬编码别名，并额外接受 Web flag 系列。`--host`、`--port` 和可重复的 `--trusted-host` 值会成为作用在组合行之上的 patch；负责这些值的插件 schema 会在启动时验证它们。`--dev` 把 web-runtime 行切换到开发模式并插入客户端插件 HMR（热模块替换）接收器；若要无刷新更新客户端 bundle，还需单独运行 `pnpm run dev:web` watcher。
+`dsh web` 是 `--profile web` 的硬编码别名；写在它之后的 flag 属于 web 应用，由组合包中的普通提供方解析。`--host` 和 `--port` 覆盖承载它们的那些行的组合取值，可重复的 `--trusted-host` 通过 `ctx.webRuntime.trustedHosts` 提供本次调用的 authority（部署表达式会拼接自己的 authority），`--dev` 把 web-runtime 行切换到开发模式并启用组合包以禁用状态交付的客户端插件 HMR（热模块替换）接收器；若要无刷新更新客户端 bundle，还需单独运行 `pnpm run dev:web` watcher。
 
 ```sh
 dsh web
 dsh web --patch ./extra.cordis.yml
 dsh web --dump-config
+dsh web --help
 ```
 
 生产 Web 运行器需要已构建的包和前端产物（`pnpm run build`）。默认服务地址是 `http://127.0.0.1:3080`。绑定所有接口时，还会信任机器自动发现的 LAN IP 字面量；`--trusted-host` 可添加 `/api` 浏览器信任围栏接受的具名 authority。

apps/cli/src/args.ts

@@ -1,31 +1,30 @@
 /**
- * Commander adapter for the `dsh` command-line entry. The default command
- * boots a named profile (`--profile <name>`), optionally with extra `--patch`
- * overlays. `run` owns one-shot task execution, defaulting to the headless
- * profile; `web` is a hardcoded alias for `--profile web` that adds the Web
- * flag family; `plugin` manages a profile's plugin dependencies by forwarding
- * to pnpm. Commander owns help, version, and parse errors.
+ * Commander adapter for the `dsh` command line.
+ *
+ * The launcher parses only what it owns — which profile to boot, which extra
+ * patch overlays to apply, and the config dumps — and hands **everything after
+ * its own flags** to the booted tree verbatim, where injected app plugins parse
+ * their own flag families and print their own `--help` (see
+ * `@deepseek-ai/dsh-cmdline`). Launcher flags therefore come first: the first
+ * token this parser does not recognize starts the inner arguments, so
+ * `dsh --profile tui --resume abc` boots the tui profile with `--resume abc`,
+ * and `dsh --profile web -h` prints the web app's help, not this one's.
+ *
+ * `web` is a hardcoded alias for `--profile web`; `plugin` manages a profile's
+ * plugin dependencies by forwarding to pnpm.
  * @module @deepseek-ai/dsh/args
  */
 
 import { Command, CommanderError } from 'commander'
 
-/** Boot a named profile. */
+/** Boot a named profile and hand it the invocation's inner arguments. */
 interface ProfileInvocation {
   mode: 'profile'
   profile: string
   /** Extra patch-list overlays applied after the profile's own layer, in argv order. */
   patches: string[]
-}
-
-/** Run one task through a profile mounting the headless runner. */
-interface RunInvocation {
-  mode: 'run'
-  profile: string
-  /** Extra patch-list overlays applied after the profile's own layer, in argv order. */
-  patches: string[]
-  /** Non-blank task text joined from the variadic positional arguments. */
-  task: string
+  /** Everything after the launcher's own flags, verbatim, for injected app plugins. */
+  args: string[]
 }
 
 /** Print a composed profile tree and exit without booting. */
@@ -37,21 +36,6 @@ interface DumpConfigInvocation {
   patches: string[]
 }
 
-/**
- * Browser UI: `dsh web` (alias of `--profile web`). Host and port remain
- * unvalidated pass-throughs to the webserver schema; absent values leave the
- * shipped web bundle values intact.
- */
-interface WebInvocation {
-  mode: 'web'
-  patches: string[]
-  host?: string
-  port?: number
-  dev: boolean
-  /** Extra authorities for the /api browser-trust fence. */
-  trustedHosts?: string[]
-}
-
 /** Manage a profile's plugins: forward `args` to pnpm inside the profile directory. */
 interface PluginInvocation {
   mode: 'plugin'
@@ -61,31 +45,63 @@ interface PluginInvocation {
 }
 
 /** The resolved `dsh` invocation. Help, version, and errors exit inside {@link parseDshArgs}. */
-export type DshInvocation = ProfileInvocation | RunInvocation | DumpConfigInvocation | WebInvocation | PluginInvocation
+export type DshInvocation = ProfileInvocation | DumpConfigInvocation | PluginInvocation
 
-/** Raw web-subcommand options straight from Commander. */
-interface WebOptions {
+/** Launcher flags shared by the default command and the `web` alias. */
+interface BootOptions {
   patch?: string[]
-  host?: string
-  port?: string
-  dev?: boolean
-  trustedHost?: string[]
   dumpConfig?: boolean
   dumpDefaultConfig?: boolean
 }
 
-/** Raw run-subcommand options straight from Commander. */
-interface RunOptions {
-  profile: string
-  patch?: string[]
-}
-
 /**
  * Repeatable single-value collector: `--patch a.yml --patch b.yml`. Never
- * variadic — a variadic `--patch` would swallow a following positional task.
+ * variadic — a variadic `--patch` would swallow the inner arguments.
  */
 const collect = (value: string, previous: string[] = []): string[] => [...previous, value]
 
+/** The launcher's own help text; each app prints its own. */
+const HELP_EXAMPLES = `
+Examples:
+  dsh --profile web                          boot the web profile (same as: dsh web)
+  dsh --profile headless "run the tests"     answer one task, print the result, and exit
+  dsh --profile tui --patch ./extra.yml      boot a custom profile with one extra overlay
+  dsh --profile tui --resume <session>       arguments after the launcher flags reach the app
+  dsh --profile web --help                   the web app's own flags and help
+  dsh plugin --profile tui add <package>     install a plugin into the tui profile
+`
+
+/**
+ * Resolve a boot or dump invocation from the launcher flags and the leftover
+ * inner arguments.
+ * @param program - the command whose options were parsed (the root, or the `web` alias).
+ * @param profile - the profile these flags boot.
+ * @param options - the launcher flags commander collected.
+ * @param args - the leftover arguments, in argv order.
+ * @returns the resolved invocation.
+ */
+function resolveBoot(program: Command, profile: string, options: BootOptions, args: string[]): DshInvocation {
+  const patches = options.patch ?? []
+  if (patches.includes('')) program.error('error: --patch needs a path')
+  if (options.dumpConfig !== true && options.dumpDefaultConfig !== true) {
+    return { mode: 'profile', profile, patches, args }
+  }
+  if (options.dumpConfig === true && options.dumpDefaultConfig === true) {
+    program.error('error: --dump-config and --dump-default-config are mutually exclusive')
+  }
+  // The dump is boot-free: it never runs app command-line providers, so it
+  // cannot show what those flags would decide, and printing a tree that differs
+  // from the same invocation's boot would mislead.
+  if (args.length > 0) {
+    program.error(`error: config dumps take no app arguments, got ${args.map(argument => JSON.stringify(argument)).join(' ')}`)
+  }
+  const defaultOnly = options.dumpDefaultConfig === true
+  if (defaultOnly && patches.length > 0) {
+    program.error('error: --dump-default-config prints the bundle layers and takes no --patch')
+  }
+  return { mode: 'dump-config', profile, defaultOnly, patches }
+}
+
 /**
  * Resolve argv into one invocation, or print and exit for help, version, or an
  * error.
@@ -95,121 +111,61 @@ const collect = (value: string, previous: string[] = []): string[] => [...previo
  */
 export function parseDshArgs(argv: readonly string[], version: string): DshInvocation {
   let resolved: DshInvocation | undefined
-  const program = new Command()
+  // Annotated, not inferred: the actions below call back into `program`, and an
+  // inferred type would be circular through its own chain.
+  const program: Command = new Command()
+  program
     .name('dsh')
     .version(version, '-V, --version', 'output the version number')
     .description('dsh: boot a DeepSeek Harness profile — an ordered stack of plugin-bundle patch layers under your own overrides.')
-    .addHelpText('after', `
-Examples:
-  dsh --profile web                          boot the web profile (same as: dsh web)
-  dsh run "run the tests"                    answer one task, print the result, and exit
-  dsh run --profile custom "run the tests"   run one task through a custom one-shot profile
-  dsh --profile tui --patch ./extra.yml      boot a custom profile with one extra overlay
-  dsh plugin --profile tui add <package>     install a plugin into the tui profile
-  dsh web --port 8080                        the web alias with its flag family
-`)
+    .addHelpText('after', HELP_EXAMPLES)
     .exitOverride()
+    // The launcher's flags come first and end at the first token it does not
+    // know; everything from there on belongs to the booted app, including
+    // its -h. `dsh -h` with no profile still prints this help, below.
+    .helpOption(false)
+    .allowUnknownOption()
+    .passThroughOptions()
     .enablePositionalOptions()
+    .argument('[args...]', 'arguments for the booted profile\'s app (see: dsh --profile <name> --help)')
     .option('--profile <name>', 'the profile under $DSH_HOME/profiles to boot')
     .option('--patch <path>', 'extra patch-list overlay applied after the profile layer (repeatable)', collect)
     .option('--dump-config', 'print the composed profile tree and exit')
     .option('--dump-default-config', 'print the profile tree without its user layer or --patch overlays and exit')
-    .action((options: {
-      profile?: string
-      patch?: string[]
-      dumpConfig?: boolean
-      dumpDefaultConfig?: boolean
-    }) => {
-      const profile = options.profile ?? program.error('error: --profile <name> is required')
-      if (profile === '') program.error('error: --profile needs a name')
-      const patches = options.patch ?? []
-      if (patches.includes('')) program.error('error: --patch needs a path')
-      if (options.dumpConfig === true || options.dumpDefaultConfig === true) {
-        if (options.dumpConfig === true && options.dumpDefaultConfig === true) {
-          program.error('error: --dump-config and --dump-default-config are mutually exclusive')
-        }
-        const defaultOnly = options.dumpDefaultConfig === true
-        if (defaultOnly && patches.length > 0) {
-          program.error('error: --dump-default-config prints the bundle layers and takes no --patch')
-        }
-        resolved = { mode: 'dump-config', profile, defaultOnly, patches }
-        return
+    .action((args: string[], options: BootOptions & { profile?: string }) => {
+      // With the app owning -h, the launcher's own help is what a bare
+      // `dsh -h` (no profile to hand it to) must print.
+      if (options.profile === undefined) {
+        if (args.some(argument => argument === '-h' || argument === '--help')) program.help()
+        program.error('error: --profile <name> is required')
       }
-      resolved = { mode: 'profile', profile, patches }
+      const profile = options.profile
+      if (profile === '') program.error('error: --profile needs a name')
+      resolved = resolveBoot(program, profile, options, args)
     })
 
   /** Reject parent options supplied before a subcommand. */
   const rejectParentOptions = (command: string): void => {
-    const parent = program.opts<{
-      profile?: string
-      patch?: string[]
-      dumpConfig?: boolean
-      dumpDefaultConfig?: boolean
-    }>()
+    const parent = program.opts<BootOptions & { profile?: string }>()
     if (parent.profile !== undefined || parent.patch !== undefined
       || parent.dumpConfig !== undefined || parent.dumpDefaultConfig !== undefined) {
       program.error(`error: ${command} takes none of parent --profile, --patch, --dump-config, or --dump-default-config`)
     }
   }
 
-  const run = program.command('run').description('run one task through a profile mounting the headless runner')
-  run
-    .option('--profile <name>', 'one-shot profile under $DSH_HOME/profiles', 'headless')
-    .option('--patch <path>', 'extra patch-list overlay applied after the profile layer (repeatable)', collect)
-    .argument('<task...>', 'task text')
-    .action((task: string[], options: RunOptions) => {
-      rejectParentOptions('run')
-      const profile = options.profile
-      if (profile === '') program.error('error: --profile needs a name')
-      const patches = options.patch ?? []
-      if (patches.includes('')) program.error('error: --patch needs a path')
-      const joined = task.join(' ')
-      if (joined.trim() === '') program.error('error: run needs a non-blank task')
-      resolved = { mode: 'run', profile, patches, task: joined }
-    })
-
-  const web = program.command('web').description('serve the browser UI (alias of --profile web) on the configured host and port')
+  const web = program.command('web').description('boot the web profile (alias of --profile web); the web app\'s own flags follow')
   web
+    .helpOption(false)
+    .allowUnknownOption()
+    .passThroughOptions()
+    .enablePositionalOptions()
+    .argument('[args...]', 'arguments for the web app (see: dsh web --help)')
     .option('--patch <path>', 'extra patch-list overlay applied after the profile layer (repeatable)', collect)
-    .option('--host <host>', 'bind host; pass 0.0.0.0 to reach it from another machine')
-    .option('--port <port>', 'listen port; pass 0 to let the OS pick a free one')
-    .option('--dev', 'mount the client-plugin HMR receiver (run pnpm run dev:web separately to rebuild bundles)')
-    .option('--trusted-host <authority...>', 'extra authority the /api browser-trust fence accepts (host or host:port; repeatable)')
     .option('--dump-config', 'print the composed web-profile tree (with the user layer and any --patch) and exit')
     .option('--dump-default-config', 'print the web profile\'s bundle layers (no user layer) and exit')
-    .action((options: WebOptions) => {
+    .action((args: string[], options: BootOptions) => {
       rejectParentOptions('web')
-      const patches = options.patch ?? []
-      if (patches.includes('')) program.error('error: --patch needs a path')
-      if (options.dumpConfig === true || options.dumpDefaultConfig === true) {
-        if (options.dumpConfig === true && options.dumpDefaultConfig === true) {
-          program.error('error: --dump-config and --dump-default-config are mutually exclusive')
-        }
-        const defaultOnly = options.dumpDefaultConfig === true
-        if (defaultOnly && patches.length > 0) {
-          program.error('error: --dump-default-config prints the bundle layers and takes no --patch')
-        }
-        // The dump is boot-free and does not derive flag patches; silently
-        // dropping them would print a tree that differs from the same
-        // invocation's boot.
-        if (options.host !== undefined || options.port !== undefined || options.dev === true
-          || options.trustedHost !== undefined) {
-          program.error('error: config dumps take no web flags (--host/--port/--dev/--trusted-host)')
-        }
-        resolved = { mode: 'dump-config', profile: 'web', defaultOnly, patches }
-        return
-      }
-      if (options.port !== undefined && !/^\d+$/.test(options.port)) {
-        program.error(`error: --port must be a number, got ${JSON.stringify(options.port)}`)
-      }
-      resolved = {
-        mode: 'web',
-        patches,
-        ...options.host !== undefined && { host: options.host },
-        ...options.port !== undefined && { port: Number(options.port) },
-        dev: options.dev === true,
-        ...options.trustedHost !== undefined && { trustedHosts: options.trustedHost },
-      }
+      resolved = resolveBoot(web, 'web', options, args)
     })
 
   const plugin = program.command('plugin').description('manage a profile\'s plugins by forwarding the remaining arguments to pnpm in the profile directory')

apps/cli/src/bin.ts

@@ -33,24 +33,10 @@ switch (invocation.mode) {
       environment: loadLayeredEnv('dsh'),
       profile: invocation.profile,
       patchFiles: invocation.patches,
+      args: invocation.args,
     })
     break
   }
-  case 'run': {
-    const { runProfile } = await import('./profile-boot.ts')
-    await runProfile({
-      environment: loadLayeredEnv('dsh'),
-      profile: invocation.profile,
-      patchFiles: invocation.patches,
-      task: invocation.task,
-    })
-    break
-  }
-  case 'web': {
-    const { runWeb } = await import('./web.ts')
-    await runWeb(invocation, loadLayeredEnv('dsh'))
-    break
-  }
   case 'plugin': {
     const { runPlugin } = await import('./plugin.ts')
     process.exit(runPlugin(invocation.profile, invocation.args))

apps/cli/src/profile-boot.ts

@@ -1,9 +1,13 @@
 /**
  * Shared profile boot for every `dsh` surface: resolve the profile, stack its
- * patch layers (bundle layers in `dsh.profile.bundles` order, the profile's own
- * `cordis.patch.yml`, `--patch` overlays, flag-derived patches, the telemetry
- * switch), mount the tree over the profile's empty root config, keep the
- * profile patch layer live, and wire fail-loud plus bounded shutdown.
+ * patch layers (bundle layers in `dsh.profile.bundles` order, the profile's
+ * own `cordis.patch.yml`, `--patch` overlays, the telemetry switch), mount the
+ * tree over the profile's empty root config, keep the profile patch layer
+ * live, and wire fail-loud plus bounded shutdown.
+ *
+ * App flags are not the launcher's business: the invocation's inner arguments
+ * are provided to the tree through `ctx.cmdlineArgs`, where any injected app
+ * plugin may read the same immutable snapshot.
  * @module @deepseek-ai/dsh/profile-boot
  */
 
@@ -12,7 +16,7 @@ import { join, resolve } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { FiberState, type Context } from '@deepseek-ai/cordis'
 import type { PatchOptions } from '@deepseek-ai/cordis-plugin-include'
-import { dshHomePath } from '@deepseek-ai/dsh-paths'
+import type { EntryOptions } from '@deepseek-ai/cordis-plugin-loader'
 import {
   boot,
   composeEntries,
@@ -25,7 +29,7 @@ import {
   watchUserPatches,
   type Profile,
 } from '@deepseek-ai/dsh-app-boot'
-import { resolveDshHome } from '@deepseek-ai/dsh-paths'
+import { dshHomePath, resolveDshHome } from '@deepseek-ai/dsh-paths'
 
 /** Shipped agent-preset root: beside this app's own config, in both source and built layouts. */
 const SHIPPED_PRESET_ROOT = fileURLToPath(new URL('../config/agent-presets/', import.meta.url))
@@ -33,6 +37,7 @@ const SHIPPED_PRESET_ROOT = fileURLToPath(new URL('../config/agent-presets/', im
 /** Harness-home directory holding locally authored agent presets. */
 const USER_PRESET_DIR = '.agent-presets'
 import { DSH_ENVIRONMENT_KEY, type EnvironmentSnapshot } from '@deepseek-ai/dsh-environment'
+import { provideCmdline } from '@deepseek-ai/dsh-cmdline'
 import type { HeadlessIo } from '@deepseek-ai/dsh-headless'
 import { createProcessShutdown, type ProcessShutdown } from './process-shutdown.ts'
 import { resolveWindowsShellLayer } from './windows-shell.ts'
@@ -55,7 +60,7 @@ export const INSTALL_ANCHOR = fileURLToPath(new URL('../package.json', import.me
 /** The session-telemetry row id the DSH_TELEMETRY_DISABLED switch targets. */
 const TELEMETRY_ROW_ID = 'telemetry-otel'
 
-/** The one-shot runner row a `dsh run` task requires and configures. */
+/** The one-shot runner row: its presence means this composition exits by itself. */
 const HEADLESS_ROW_ID = 'headless-runner'
 
 /** The empty root entry list every profile tree patches over. */
@@ -104,9 +109,6 @@ export function prepareProfile(name: string, userLayer = true): Profile {
   return profile
 }
 
-/** Read-only row index of a profile composition before launcher flag patches. */
-export type ProfileRows = ReadonlyMap<string, { name?: string; config?: unknown }>
-
 /** One profile's patch layers (application order) and the row index of its pre-flag composition. */
 interface ComposedProfile {
   profile: Profile
@@ -116,14 +118,13 @@ interface ComposedProfile {
   windowsShellPatches: PatchOptions[]
   /** The home-level user layer (`$DSH_HOME/cordis.patch.yml`), applied after the profile's own. */
   homePatches: PatchOptions[]
-  /** Layers above the user layers on a live reload: --patch overlays, flag patches, the telemetry switch. */
-  overlayAndFlags: PatchOptions[]
+  /** Layers above the user layers on a live reload: `--patch` overlays and the telemetry switch. */
+  overlays: PatchOptions[]
   /**
-   * id → row of the pre-flag composition (bundles + user layers + overlays),
-   * for flag merges and row checks. Flag patches must not insert rows the
-   * launcher consults here (they only override values and insert dev glue).
+   * id → row of the composed tree (bundles + user layers + overlays), for the
+   * launcher's own row checks.
    */
-  rows: ProfileRows
+  rows: ReadonlyMap<string, EntryOptions>
 }
 
 /** The full patch stack of one composed profile, in application order. */
@@ -133,7 +134,7 @@ function allPatches(composed: ComposedProfile): PatchOptions[] {
     ...composed.windowsShellPatches,
     ...composed.profile.patches,
     ...composed.homePatches,
-    ...composed.overlayAndFlags,
+    ...composed.overlays,
   ]
 }
 
@@ -143,36 +144,28 @@ function allPatches(composed: ComposedProfile): PatchOptions[] {
  * is Windows), the profile's user layer, the home-level user layer
  * (`$DSH_HOME/cordis.patch.yml` — machine-local preferences that apply to
  * every profile, so it outranks the per-profile layer), `--patch` overlays,
- * then flag patches derived from the composed rows, then the telemetry
- * switch.
+ * then the telemetry switch.
  * @param name - the profile name.
  * @param patchFiles - `--patch` overlay paths, in argv order.
- * @param deriveFlagPatches - launcher hook turning composed rows into flag patches.
  * @returns the profile, its patch layers, and the composed row index.
  */
 function composeProfile(
   name: string,
   patchFiles: readonly string[],
-  deriveFlagPatches: (rows: ComposedProfile['rows']) => PatchOptions[] = () => [],
 ): ComposedProfile {
   const profile = prepareProfile(name)
   const homePatches = loadOptionalPatches(NAME, homePatchPath()) ?? []
   const overlays = patchFiles.flatMap(file => loadOverlayPatches(NAME, resolve(file)))
   const bundlePatches = profile.layers.flatMap(layer => layer.patches)
   const windowsShellPatches = resolveWindowsShellLayer(process.platform, profile.layers, NAME)?.patches ?? []
-  const rows = new Map<string, { name?: string; config?: unknown }>()
+  const rows = new Map<string, EntryOptions>()
   for (const row of composeEntries([bundlePatches, windowsShellPatches, profile.patches, homePatches, overlays])) {
     if (typeof row.id === 'string') rows.set(row.id, row)
   }
-  const overlayAndFlags = [...overlays, ...deriveFlagPatches(rows)]
-  // The agent-preset roots are an assembly fact of every dsh launcher, not a
-  // patch author's choice: the shipped set sits beside this app's config and
-  // the user's own under the Harness home. Resolved per boot ($DSH_HOME may
-  // differ per run) and only patched when the composed tree actually mounts
-  // the roster — a one-shot `dsh run` composes agents from the same roster
-  // `dsh web` offers.
+  const composedOverlays = [...overlays]
+  // Preset roots belong to every dsh composition that mounts the roster.
   if (rows.has('agent-presets')) {
-    overlayAndFlags.push({
+    composedOverlays.push({
       id: 'agent-presets',
       config: {
         ...(rows.get('agent-presets')?.config ?? {}) as Record<string, unknown>,
@@ -184,24 +177,20 @@ function composeProfile(
     })
   }
   const telemetryPatch = resolveTelemetryPatch(process.env.DSH_TELEMETRY_DISABLED, rows.has(TELEMETRY_ROW_ID))
-  if (telemetryPatch !== undefined) overlayAndFlags.push(telemetryPatch)
-  return { profile, bundlePatches, windowsShellPatches, homePatches, overlayAndFlags, rows }
+  if (telemetryPatch !== undefined) composedOverlays.push(telemetryPatch)
+  return { profile, bundlePatches, windowsShellPatches, homePatches, overlays: composedOverlays, rows }
 }
 
 /** Options for {@link runProfile}. */
 export interface RunProfileOptions {
+  /** This run's frozen environment snapshot, provided before any entry mounts. */
+  environment: EnvironmentSnapshot
   /** The profile name to boot. */
   profile: string
   /** `--patch` overlay paths, in argv order. */
   patchFiles: readonly string[]
-  /** Launcher hook turning the pre-flag composed rows into flag patches (the web alias's flag family). */
-  deriveFlagPatches?: (rows: ProfileRows) => PatchOptions[]
-  /** `dsh run` task text; requires the composition to mount the headless runner row. */
-  task?: string
-  /** Surface setup registered after Loader installation and before any config-tree entry mounts. */
-  prepare?: (ctx: Context, rows: ProfileRows) => Promise<void> | void
-  /** This run's frozen environment snapshot, provided to the tree before any entry mounts. */
-  environment: EnvironmentSnapshot
+  /** The invocation's inner arguments, handed to the tree through `ctx.cmdlineArgs`. */
+  args: readonly string[]
 }
 
 /** Re-throw setup failures unless this invocation's signal already owns shutdown. */
@@ -211,29 +200,16 @@ function suppressSignalShutdownError(signal: AbortSignal, error: unknown): void
 
 /**
  * Boot one profile invocation end to end and leave process lifetime to the
- * mounted plugins (or to the one-shot runner when `task` is present).
- * @param options - profile name, overlays, flag patches, and the optional task.
+ * mounted plugins (or to a one-shot runner the composition mounts).
+ * @param options - environment snapshot, profile name, overlays, and the booted app's own arguments.
  * @returns the settled root context and the shutdown controller.
  */
 export async function runProfile(options: RunProfileOptions): Promise<{ ctx: Context; shutdown: ProcessShutdown }> {
-  const composed = composeProfile(options.profile, options.patchFiles, options.deriveFlagPatches)
-  if (options.task !== undefined) {
-    if (!composed.rows.has(HEADLESS_ROW_ID)) {
-      throw new Error(
-        `dsh: profile ${JSON.stringify(options.profile)} takes no task — its composition mounts no "${HEADLESS_ROW_ID}" row `
-        + '(the headless profile does)',
-      )
-    }
-    composed.overlayAndFlags.push({ id: HEADLESS_ROW_ID, config: { task: options.task } })
-  } else if (composed.rows.has(HEADLESS_ROW_ID)) {
-    // The inverse misuse: a one-shot composition booted without its task
-    // would otherwise die in the runner row's schema with a raw "required"
-    // error naming no fix.
-    throw new Error(
-      `dsh: profile ${JSON.stringify(options.profile)} mounts the one-shot runner and needs a task: `
-      + `dsh run --profile ${options.profile} "<task>"`,
-    )
-  }
+  const composed = composeProfile(options.profile, options.patchFiles)
+  // A one-shot composition ends by itself, which changes what a signal means
+  // and makes watching the user's patch layer pointless.
+  const headlessRow = composed.rows.get(HEADLESS_ROW_ID)
+  const oneShot = headlessRow !== undefined && headlessRow.disabled !== true
 
   const app: { current?: Context } = {}
   const shutdown = createProcessShutdown(async () => { await app.current?.fiber.dispose() })
@@ -243,9 +219,8 @@ export async function runProfile(options: RunProfileOptions): Promise<{ ctx: Con
     shutdown.interrupt(code)
   }
   // Signals own teardown throughout the startup window, not only after boot()
-  // settles: an inserted entry point can publish readiness before sibling rows
-  // finish mounting.
-  process.on('SIGTERM', () => { interrupt(options.task === undefined ? 0 : 143) })
+  // settles: an inserted provider can publish before sibling rows finish mounting.
+  process.on('SIGTERM', () => { interrupt(oneShot ? 143 : 0) })
   process.on('SIGINT', () => { interrupt(130) })
   installFailLoud(NAME, process, async () => {
     await app.current?.fiber.dispose()
@@ -253,7 +228,9 @@ export async function runProfile(options: RunProfileOptions): Promise<{ ctx: Con
 
   const rootConfig = join(composed.profile.dir, PROFILE_ROOT_FILENAME)
   // Recomposition for the live user layers: bundle layers below, overlays
-  // and flag patches above, so a user edit can never displace them. BOTH
+  // above, so a user edit can never displace them. Parsed app arguments are
+  // not in here at all — they live in app-provided services that survive a
+  // recomposition. BOTH
   // user files are re-read per generation (the HMR watcher hands us only the
   // changed file's patches, which one of the reads duplicates — fresh reads
   // keep the two watchers from stitching in each other's stale copy).
@@ -267,19 +244,25 @@ export async function runProfile(options: RunProfileOptions): Promise<{ ctx: Con
     ...composed.windowsShellPatches,
     ...loadOptionalPatches(NAME, composed.profile.patchPath) ?? [],
     ...loadOptionalPatches(NAME, homePatchPath()) ?? [],
-    ...composed.overlayAndFlags,
+    ...composed.overlays,
   ])
   // One-shot runs exit through the runner; watching would only hold the
   // process open after its exit request.
-  const watchProfilePatch = options.task === undefined
+  const watchProfilePatch = !oneShot
   // Cloned for the same insert-aliasing reason as composeLive: the boot
   // application must not mutate the objects later reloads recompose from.
-  const ctx = await boot(NAME, rootConfig, structuredClone(allPatches(composed)), async (hostCtx) => {
+  const ctx = await boot(NAME, rootConfig, structuredClone(allPatches(composed)), (hostCtx) => {
     app.current = hostCtx
-    // Before any config-tree entry mounts, so a plugin that resolves a
-    // user-facing value at construction already sees this run's layers.
+    // Before any config-tree entry mounts, so plugins resolve all launch-time
+    // environment values from the same immutable provenance snapshot.
     hostCtx.provide(DSH_ENVIRONMENT_KEY, options.environment)
-    if (options.task !== undefined) {
+    // The command line and bounded exit request are launcher facts available
+    // to every app plugin that injects the argument snapshot.
+    provideCmdline(hostCtx, {
+      args: options.args,
+      exit: code => void shutdown.shutdown(code),
+    })
+    if (oneShot) {
       const io: HeadlessIo = {
         stdout: process.stdout,
         stderr: process.stderr,
@@ -287,11 +270,10 @@ export async function runProfile(options: RunProfileOptions): Promise<{ ctx: Con
       }
       hostCtx.provide('headlessIo', io)
     }
-    await options.prepare?.(hostCtx, composed.rows)
   })
   app.current = ctx
-  // A surface can dispose the whole tree while startup or this post-boot
-  // watcher setup is still in flight. Loader presence and fiber state own
+  // A surface can dispose the whole tree while boot or this post-boot watcher
+  // setup is still in flight. Loader presence and fiber state own
   // liveness; the local signal fact distinguishes that expected exit race
   // from a real HMR error.
   if (watchProfilePatch

apps/cli/src/web.ts

@@ -1,144 +0,0 @@
-/**
- * `dsh web` — the browser-surface alias over the profile boot: `--profile web`
- * plus the Web flag family (`--host/--port/--dev/--trusted-host`), each flag
- * becoming a patch over the composed profile
- * tree. All web runtime glue (dist serving, prompt section, URL line) lives
- * in the `@deepseek-ai/dsh-web-app` bundle; this launcher only derives
- * flag patches and the LAN-trust snapshot.
- * @module @deepseek-ai/dsh/web
- */
-
-import { networkInterfaces } from 'node:os'
-import { fileURLToPath } from 'node:url'
-import type { Context } from '@deepseek-ai/cordis'
-import type { PatchOptions } from '@deepseek-ai/cordis-plugin-include'
-import { addHarnessSourceSection } from '@deepseek-ai/dsh-app-boot'
-import type { EnvironmentSnapshot } from '@deepseek-ai/dsh-environment'
-import { runProfile, type ProfileRows } from './profile-boot.ts'
-
-const SOURCE_ROOT = fileURLToPath(new URL('../../..', import.meta.url))
-
-/** The webserver schema's all-interfaces bind literal: gates LAN-authority derivation. */
-const ALL_INTERFACES_HOST = '0.0.0.0'
-
-/**
- * Non-internal IPv4 interface addresses of this machine — the IP-literal
- * authorities an all-interfaces bind is reachable by on the LAN.
- * @returns the addresses in interface order (possibly empty).
- */
-function lanIPv4Addresses(): string[] {
-  return Object.values(networkInterfaces()).flat()
-    .filter((iface): iface is NonNullable<typeof iface> => iface !== undefined && iface.family === 'IPv4' && !iface.internal)
-    .map(iface => iface.address)
-}
-
-/**
- * One LAN-trust resolution for one invocation, sampled exactly once: the
- * machine's LAN IP literals when the effective bind is all-interfaces, and
- * the `trustedHosts` value built from them plus the explicit extras. The
- * single sample is deliberate — display must advertise only addresses the
- * fence was configured with, so the web-app row receives this same snapshot.
- * Derived entries are port-less IP literals: DNS rebinding needs an
- * attacker-controlled name, so an IP-literal Host is safe on any port, and
- * the bound port may be OS-assigned, unknowable pre-boot.
- * @param bindHost - the effective webserver bind host (CLI flag, else the composed row value).
- * @param extra - `--trusted-host` values, in argv order.
- * @returns the sampled LAN addresses and the connection row's `trustedHosts` value (each possibly empty).
- */
-export function resolveLanTrust(
-  bindHost: string | undefined,
-  extra: readonly string[],
-): { lanAddresses: string[]; trustedHosts: string[] } {
-  const lanAddresses = bindHost === ALL_INTERFACES_HOST ? lanIPv4Addresses() : []
-  return { lanAddresses, trustedHosts: [...lanAddresses, ...extra] }
-}
-
-/** The `dsh web` flag family, already parsed by the argument adapter. */
-export interface WebFlags {
-  patches: string[]
-  host?: string
-  port?: number
-  dev: boolean
-  trustedHosts?: string[]
-}
-
-/**
- * Derive the web alias's flag patches over an already-composed profile tree.
- * Patches replace a row's whole config, so each patched row's composed values
- * are re-read and merged under the overrides.
- * @param rows - the composed row index from {@link composeProfile}.
- * @param flags - the parsed flag family.
- * @returns the flag patch list, in application order.
- */
-function deriveWebFlagPatches(
-  rows: ProfileRows,
-  flags: WebFlags,
-): PatchOptions[] {
-  const overrides = new Map<string, Record<string, unknown>>()
-  const put = (entryId: string, key: string, value: unknown): void => {
-    const bag = overrides.get(entryId) ?? {}
-    bag[key] = value
-    overrides.set(entryId, bag)
-  }
-  if (flags.host !== undefined) put('webserver', 'host', flags.host)
-  if (flags.port !== undefined) put('webserver', 'port', flags.port)
-  const composedHost = (rows.get('webserver')?.config as { host?: string } | undefined)?.host
-  const { lanAddresses, trustedHosts } = resolveLanTrust(flags.host ?? composedHost, flags.trustedHosts ?? [])
-  if (trustedHosts.length > 0) {
-    // Additive over the composed value: a cordis.patch.yml-configured fence
-    // authority must survive the derived LAN literals and flag extras — a
-    // silent drop of security-relevant fence configuration.
-    const composedTrusted = (rows.get('connection')?.config as { trustedHosts?: string[] } | undefined)?.trustedHosts ?? []
-    put('connection', 'trustedHosts', [...composedTrusted, ...trustedHosts])
-  }
-  // mode and lanAddresses are launcher-derived on every boot (--dev also
-  // inserts the client-hmr row), never pass-throughs of composed values.
-  put('web-runtime', 'mode', flags.dev ? 'development' : 'production')
-  put('web-runtime', 'lanAddresses', lanAddresses)
-  // The agent-preset roots are patched by the shared profile boot: they are
-  // an assembly fact of every dsh launcher, and `dsh run` composes agents
-  // from the same roster this alias offers.
-  const patches = [...overrides.entries()].map(([id, bag]): PatchOptions => {
-    const composed = rows.get(id)
-    if (composed === undefined) throw new Error(`dsh: patch target row "${id}" not found in the web profile composition`)
-    return { id, config: { ...(composed.config ?? {}) as Record<string, unknown>, ...bag } }
-  })
-  if (flags.dev) patches.push({ insert: [{ id: 'client-hmr', name: '@deepseek-ai/dsh-client-hmr' }] })
-  return patches
-}
-
-/**
- * Whether the composed Web runtime keeps its model- and shell-visible surface
- * context. The bundle schema defaults the field to true, so only an explicit
- * false suppresses both the bundle contributions and the launcher-owned
- * source-checkout section.
- * @param rows - the composed Web profile rows before launcher flag patches.
- * @returns true unless the web-runtime row explicitly disables surface context.
- */
-export function webSurfaceContextEnabled(rows: ProfileRows): boolean {
-  return (rows.get('web-runtime')?.config as { surfaceContext?: boolean } | undefined)?.surfaceContext !== false
-}
-
-/**
- * Serve the browser UI from the web profile. Host/port flags are passed
- * through only when given (absent, the composed profile values
- * stand); `web-runtime.mode` and `lanAddresses` are launcher-derived on
- * every boot. The URL line is printed by the web-app bundle's runtime row
- * after Loader settlement.
- * @param flags - the parsed `dsh web` flag family.
- * @param environment - this run's frozen environment snapshot.
- */
-export async function runWeb(flags: WebFlags, environment: EnvironmentSnapshot): Promise<void> {
-  await runProfile({
-    environment,
-    profile: 'web',
-    patchFiles: flags.patches,
-    deriveFlagPatches: rows => deriveWebFlagPatches(rows, flags),
-    prepare: (ctx: Context, rows: ProfileRows) => {
-      if (!webSurfaceContextEnabled(rows)) return
-      ctx.inject(['systemPrompt'], (promptCtx) => {
-        addHarnessSourceSection(promptCtx, SOURCE_ROOT)
-      })
-    },
-  })
-}

apps/cli/tests/args.spec.ts

@@ -21,22 +21,28 @@ function exitCode(argv: string[]): number {
 afterEach(() => { vi.restoreAllMocks() })
 
 describe('parseDshArgs', () => {
-  it('routes profile boots, one-shot runs, and the web alias', () => {
-    expect(parse(['--profile', 'tui'])).toEqual({ mode: 'profile', profile: 'tui', patches: [] })
+  it('routes profile boots and the web alias, handing the rest to the app', () => {
+    expect(parse(['--profile', 'tui'])).toEqual({ mode: 'profile', profile: 'tui', patches: [], args: [] })
     expect(parse(['--profile', 'tui', '--patch', 'a.yml', '--patch', 'b.yml']))
-      .toEqual({ mode: 'profile', profile: 'tui', patches: ['a.yml', 'b.yml'] })
-    expect(parse(['run', 'run', 'the', 'tests']))
-      .toEqual({ mode: 'run', profile: 'headless', patches: [], task: 'run the tests' })
-    expect(parse(['run', '--profile', 'custom', '--patch', 'a.yml', '--patch', 'b.yml', 'run', 'the', 'tests']))
-      .toEqual({ mode: 'run', profile: 'custom', patches: ['a.yml', 'b.yml'], task: 'run the tests' })
-    expect(parse(['run', '--', '--profile', 'is', 'task', 'text']))
-      .toEqual({ mode: 'run', profile: 'headless', patches: [], task: '--profile is task text' })
-    expect(parse(['web'])).toEqual({ mode: 'web', dev: false, patches: [] })
-    expect(parse(['web', '--patch', 'web.yml'])).toEqual({ mode: 'web', dev: false, patches: ['web.yml'] })
+      .toEqual({ mode: 'profile', profile: 'tui', patches: ['a.yml', 'b.yml'], args: [] })
+    expect(parse(['web'])).toEqual({ mode: 'profile', profile: 'web', patches: [], args: [] })
+    expect(parse(['web', '--patch', 'web.yml']))
+      .toEqual({ mode: 'profile', profile: 'web', patches: ['web.yml'], args: [] })
+  })
+
+  it('ends the launcher flags at the first token it does not own', () => {
+    // App flags, including its -h, and positionals reach the app verbatim.
+    expect(parse(['--profile', 'tui', '--resume', 'abc']))
+      .toEqual({ mode: 'profile', profile: 'tui', patches: [], args: ['--resume', 'abc'] })
+    expect(parse(['--profile', 'web', '-h']))
+      .toEqual({ mode: 'profile', profile: 'web', patches: [], args: ['-h'] })
     expect(parse(['web', '--host', '0.0.0.0', '--port', '8080', '--dev']))
-      .toEqual({ mode: 'web', host: '0.0.0.0', port: 8080, dev: true, patches: [] })
-    expect(parse(['web', '--trusted-host', 'harness.internal:3080', 'lab.internal', '--trusted-host', '10.0.0.9']))
-      .toEqual({ mode: 'web', dev: false, patches: [], trustedHosts: ['harness.internal:3080', 'lab.internal', '10.0.0.9'] })
+      .toEqual({ mode: 'profile', profile: 'web', patches: [], args: ['--host', '0.0.0.0', '--port', '8080', '--dev'] })
+    expect(parse(['--profile', 'headless', 'run', 'the', 'tests']))
+      .toEqual({ mode: 'profile', profile: 'headless', patches: [], args: ['run', 'the', 'tests'] })
+    // Launcher flags placed after that boundary belong to the app too.
+    expect(parse(['--profile', 'tui', '--patch', 'a.yml', '--resume', 'b', '--patch', 'late.yml']))
+      .toEqual({ mode: 'profile', profile: 'tui', patches: ['a.yml'], args: ['--resume', 'b', '--patch', 'late.yml'] })
   })
 
   it('routes the plugin pnpm forwarder', () => {
@@ -64,18 +70,12 @@ describe('parseDshArgs', () => {
       .toEqual({ mode: 'dump-config', profile: 'web', defaultOnly: true, patches: [] })
   })
 
-  it('rejects missing profile, flags outside the current grammar, and contradictory inputs', () => {
+  it('rejects missing profile, removed flags, and contradictory inputs', () => {
     expect(exitCode([])).toBe(1)
-    expect(exitCode(['tui'])).toBe(1) // a bare word is a task without --profile
-    expect(exitCode(['--config', 'c.yml'])).toBe(1) // outside the current grammar
-    expect(exitCode(['-p', 'task'])).toBe(1) // outside the current grammar
-    expect(exitCode(['--profile', 'headless', 'task'])).toBe(1) // tasks belong to `run`
-    expect(exitCode(['run'])).toBe(1)
-    expect(exitCode(['run', ''])).toBe(1)
-    expect(exitCode(['run', '--profile', '', 'task'])).toBe(1)
-    expect(exitCode(['run', '--patch=', 'task'])).toBe(1)
-    expect(exitCode(['--profile', 'headless', 'run', 'task'])).toBe(1)
-    expect(exitCode(['--patch', 'parent.yml', 'run', 'task'])).toBe(1)
+    expect(exitCode(['tui'])).toBe(1) // an app argument without --profile has no app to reach
+    expect(exitCode(['--config', 'c.yml'])).toBe(1) // removed
+    expect(exitCode(['-p', 'task'])).toBe(1) // removed
+    expect(exitCode(['run', 'task'])).toBe(1) // app-owned task replaced the launcher subcommand
     expect(exitCode(['--profile', ''])).toBe(1)
     expect(exitCode(['--profile', 'x', '--patch='])).toBe(1)
     expect(exitCode(['--dump-config'])).toBe(1)
@@ -87,21 +87,20 @@ describe('parseDshArgs', () => {
     expect(exitCode(['web', '--dump-config', '--dump-default-config'])).toBe(1)
     expect(exitCode(['web', '--dump-default-config', '--patch', 'w.yml'])).toBe(1)
     expect(exitCode(['web', '--patch='])).toBe(1)
-    // Boot-free dumps derive no flag patches; silently dropping the flags
-    // would print a tree that differs from the same invocation's boot.
+    // A dump never runs app command-line providers, so it cannot show what
+    // those flags would decide; printing a tree that differs from the same
+    // invocation's boot would mislead.
     expect(exitCode(['web', '--dump-config', '--port', '8080'])).toBe(1)
-    expect(exitCode(['web', '--dump-config', '--dev'])).toBe(1)
-    // A non-numeric port fails at the flag, not deep in the webserver schema.
-    expect(exitCode(['web', '--port', 'abc'])).toBe(1)
+    expect(exitCode(['--profile', 'web', '--dump-config', '-h'])).toBe(1)
     expect(exitCode(['plugin', 'add', 'x'])).toBe(1) // --profile required
     expect(exitCode(['plugin', '--profile', 'tui'])).toBe(1) // nothing to forward
     expect(exitCode(['plugin', '--profile', ''])).toBe(1)
     expect(exitCode(['--profile', 'x', 'plugin', 'add', 'y'])).toBe(1)
   })
 
-  it('exits 0 for help and version', () => {
+  it('keeps its own help for an invocation with no app to hand it to', () => {
     expect(exitCode(['--help'])).toBe(0)
-    expect(exitCode(['run', '--help'])).toBe(0)
+    expect(exitCode(['-h'])).toBe(0)
     expect(exitCode(['--version'])).toBe(0)
   })
 })

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

@@ -128,8 +128,8 @@ function createProfileLifecycleFixture(): ProfileLifecycleFixture {
   return { home, ready, settled, disposed, interrupt }
 }
 
-function startProfileLifecycle(fixture: ProfileLifecycleFixture) {
-  return execa(process.execPath, [dshBin, '--profile', 'lifecycle'], {
+function startProfileLifecycle(fixture: ProfileLifecycleFixture, args: readonly string[] = []) {
+  return execa(process.execPath, [dshBin, '--profile', 'lifecycle', ...args], {
     cwd: fixture.home,
     input: '',
     reject: false,
@@ -144,8 +144,8 @@ function startProfileLifecycle(fixture: ProfileLifecycleFixture) {
 }
 
 function requestProfileShutdown(
-  child: ReturnType<typeof startProfileLifecycle>,
-  fixture: ProfileLifecycleFixture,
+  child: Pick<ReturnType<typeof startProfileLifecycle>, 'kill'>,
+  fixture: Pick<ProfileLifecycleFixture, 'interrupt'>,
 ): void {
   if (process.platform === 'win32') {
     writeFileSync(fixture.interrupt, 'interrupt')
@@ -193,8 +193,121 @@ function createEnvironmentProbeProfile(home: string, project: string): void {
   ].join('\n'))
 }
 
+interface StartupFixture {
+  home: string
+  ready: string
+  echo: string
+  interrupt: string
+  /** An always-running row's echo, used to observe that a user patch reload landed. */
+  witness: string
+}
+
+/**
+ * A custom profile whose ordinary provider plugin injects `cmdlineArgs`, plus
+ * a row that reads its app-owned service through a `!!js` config expression.
+ * Both plugin modules resolve
+ * `@deepseek-ai/dsh-cmdline` and `commander` through the profile module
+ * fallback, exactly as an installed out-of-tree bundle does.
+ */
+function createStartupFixture(): StartupFixture {
+  const home = mkdtempSync(join(tmpdir(), 'dsh-profile-startup-'))
+  const profileDir = join(home, 'profiles', 'startup')
+  // Written straight into the installed location: a row module resolves its
+  // own imports from where it is installed, and only inside the profile does
+  // Node's parent walk reach the installation fallback these plugins need.
+  const bundleDir = join(profileDir, 'node_modules', 'dsh-startup-bundle')
+  mkdirSync(bundleDir, { recursive: true })
+  writeFileSync(join(bundleDir, 'startup.mjs'), [
+    "import { Command } from 'commander'",
+    "import { parseCmdline } from '@deepseek-ai/dsh-cmdline'",
+    "export const name = 'fixture-startup'",
+    "export const inject = ['cmdlineArgs']",
+    'export function apply(ctx) {',
+    "  const program = new Command().name('fixture').option('--generation <value>', 'echoed generation')",
+    '  const values = parseCmdline(ctx, program, parsed => ({ generation: parsed.opts().generation }))',
+    '  if (values !== undefined) ctx.provide(\'fixtureStartup\', values)',
+    '}',
+    '',
+  ].join('\n'))
+  writeFileSync(join(bundleDir, 'waiting.mjs'), [
+    "import { existsSync, writeFileSync } from 'node:fs'",
+    "import { join } from 'node:path'",
+    "export const name = 'startup-fixture'",
+    'export function apply(ctx, config = {}) {',
+    '  let interrupted = false',
+    '  const heartbeat = setInterval(() => {',
+    '    if (interrupted || !existsSync(process.env.RAW_INTERRUPT_FILE)) return',
+    '    interrupted = true',
+    "    process.emit('SIGTERM')",
+    '  }, 20)',
+    "  writeFileSync(join(process.env.DSH_HOME, 'config-echo'), String(config.generation ?? 'bundle-default'))",
+    "  writeFileSync(process.env.RAW_READY_FILE, 'ready')",
+    '  ctx.effect(() => () => { clearInterval(heartbeat) })',
+    '}',
+    '',
+  ].join('\n'))
+  writeFileSync(join(bundleDir, 'witness.mjs'), [
+    "import { writeFileSync } from 'node:fs'",
+    "import { join } from 'node:path'",
+    "export const name = 'reload-witness'",
+    'export function apply(ctx, config = {}) {',
+    "  writeFileSync(join(process.env.DSH_HOME, 'witness'), String(config.generation ?? 'bundle-default'))",
+    '}',
+    '',
+  ].join('\n'))
+  writeFileSync(join(bundleDir, 'cordis.patch.yml'), [
+    '- insert:',
+    '    - id: startup-fixture',
+    `      name: ${pathToFileURL(join(bundleDir, 'waiting.mjs')).href}`,
+    '      inject: [fixtureStartup]',
+    '      config:',
+    // Lazy interpolation runs only after the provider's service is injected.
+    "        generation: !!js ctx.fixtureStartup.generation ?? 'bundle-default'",
+    '    - id: fixture-startup',
+    `      name: ${pathToFileURL(join(bundleDir, 'startup.mjs')).href}`,
+    '    - id: reload-witness',
+    `      name: ${pathToFileURL(join(bundleDir, 'witness.mjs')).href}`,
+    '',
+  ].join('\n'))
+  writeFileSync(join(bundleDir, 'package.json'), JSON.stringify({
+    name: 'dsh-startup-bundle',
+    version: '0.0.0',
+    type: 'module',
+    dsh: { bundle: { patch: './cordis.patch.yml' } },
+  }, undefined, 2))
+  writeFileSync(join(profileDir, 'package.json'), JSON.stringify({
+    name: 'dsh-profile-startup',
+    private: true,
+    dependencies: {},
+    dsh: { profile: { bundles: ['dsh-startup-bundle'] } },
+  }, undefined, 2))
+  writeFileSync(join(profileDir, 'cordis.patch.yml'), '[]\n')
+  return {
+    home,
+    ready: join(home, 'ready'),
+    echo: join(home, 'config-echo'),
+    interrupt: join(home, 'interrupt'),
+    witness: join(home, 'witness'),
+  }
+}
+
+function startStartupProfile(fixture: StartupFixture, args: readonly string[]) {
+  return execa(process.execPath, [dshBin, '--profile', 'startup', ...args], {
+    cwd: fixture.home,
+    input: '',
+    reject: false,
+    timeout: 25_000,
+    killSignal: 'SIGKILL',
+    env: {
+      DSH_HOME: fixture.home,
+      RAW_READY_FILE: fixture.ready,
+      RAW_INTERRUPT_FILE: fixture.interrupt,
+    },
+  })
+}
+
 describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)', () => {
-  it('requires --profile and rejects inputs outside the current grammar', async () => {
+  it('requires --profile and rejects removed commands', async () => {
     const bare = await runBuiltBin()
     expect(bare.code).toBe(1)
     expect(bare.stdout).toBe('')
@@ -202,46 +315,63 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
     const help = await runBuiltBin(['--help'])
     expect(help.code).toBe(0)
     expect(help.stdout).toContain('dsh --profile web')
-    expect(help.stdout).toContain('dsh run "run the tests"')
     expect(help.stdout).toContain('dsh plugin --profile')
     expect(help.stdout).not.toMatch(/^\s+(?:tui|meta|upgrade)\b/mu)
-    for (const outsideGrammar of [['tui'], ['--config', 'x.yml'], ['-p', 'task'], ['--profile', 'headless', 'task']]) {
-      const result = await runBuiltBin(outsideGrammar)
+    for (const removed of [['tui'], ['--config', 'x.yml'], ['-p', 'task'], ['run', 'task']]) {
+      const result = await runBuiltBin(removed)
       expect(result.code).toBe(1)
     }
   }, 30_000)
 
-  it('prints run help without initializing the selected profile', async () => {
-    const parent = mkdtempSync(join(tmpdir(), 'dsh-run-help-'))
-    const home = join(parent, 'not-created')
+  it('routes help and usage errors without activating startup-dependent rows', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'dsh-app-help-'))
     try {
-      const result = await runBuiltBin(['run', '--help'], { DSH_HOME: home })
-      expect(result.code).toBe(0)
-      expect(result.stderr).toBe('')
-      expect(result.stdout).toContain('Usage: dsh run [options] <task...>')
-      expect(existsSync(home)).toBe(false)
+      const web = await runBuiltBin(['--profile', 'web', '--help'], {
+        DSH_HOME: home,
+        DSH_TELEMETRY_DISABLED: '1',
+      })
+      expect(web.code).toBe(0)
+      expect(web.stderr).toBe('')
+      expect(web.stdout).toContain('Usage: dsh --profile web')
+      expect(web.stdout).toContain('--port <port>')
+      expect(web.stdout).not.toContain('dsh web: http://')
+
+      const headlessHelp = await runBuiltBin(['--profile', 'headless', '--help'], {
+        DSH_HOME: home,
+        DSH_TELEMETRY_DISABLED: '1',
+      })
+      expect(headlessHelp.code).toBe(0)
+      expect(headlessHelp.stderr).toBe('')
+      expect(headlessHelp.stdout).toContain('Usage: dsh --profile headless')
+
+      const missingTask = await runBuiltBin(['--profile', 'headless'], {
+        DSH_HOME: home,
+        DSH_TELEMETRY_DISABLED: '1',
+      })
+      expect(missingTask.code).toBe(1)
+      expect(missingTask.stderr).toContain('a task is required')
     } finally {
-      rmSync(parent, { recursive: true, force: true })
+      rmSync(home, { recursive: true, force: true })
     }
-  })
+  }, 30_000)
 
-  it('runs the default headless profile through the published run command', async () => {
-    const apiKey = 'built-dsh-run-key'
+  it('runs the headless profile through its app-owned task positional', async () => {
+    const apiKey = 'built-dsh-headless-key'
     const server = await startMockLlmServer({
       sequence: ['success'],
       apiKey,
-      successText: 'published dsh run reached the mock',
+      successText: 'published headless profile reached the mock',
     })
-    const home = mkdtempSync(join(tmpdir(), 'dsh-built-run-'))
+    const home = mkdtempSync(join(tmpdir(), 'dsh-built-headless-'))
     try {
-      const result = await runBuiltBin(['run', 'answer', 'from', 'the', 'published', 'entry'], {
+      const result = await runBuiltBin(['--profile', 'headless', 'answer', 'from', 'the', 'published', 'entry'], {
         DSH_HOME: home,
         DSH_TELEMETRY_DISABLED: '1',
         DEEPSEEK_API_KEY: apiKey,
         DEEPSEEK_BASE_URL: server.baseURL,
       })
       expect(result.code, result.stderr).toBe(0)
-      expect(result.stdout).toBe('published dsh run reached the mock')
+      expect(result.stdout).toBe('published headless profile reached the mock')
       expect(result.stderr).toBe('')
       expect(server.requests.length).toBeGreaterThan(0)
       expect(server.requests.every(request => request.path === '/chat/completions')).toBe(true)
@@ -317,9 +447,9 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
   }, 30_000)
 
   it('reports a patch-overlay boot failure without hanging', async () => {
-    // An HMR main-watcher initial scan that refreshes the include
-    // mid-initial-apply deadlocks the failing apply's rollback against the
-    // refresh drain: dsh exits 13 with no diagnostic instead of settling
+    // The HMR main watcher's initial scan once refreshed the include
+    // mid-initial-apply, deadlocking the failing apply's rollback against the
+    // refresh drain: dsh exited 13 with no diagnostic instead of settling
     // ([Agent Note](../../../.agents/notes/implemented/bug-fix/2026-08-03-hmr-initial-scan-boot-deadlock.md)).
     const home = mkdtempSync(join(tmpdir(), 'dsh-invalid-patch-'))
     try {
@@ -336,9 +466,9 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
     }
   }, 30_000)
 
-  it('applies a custom profile bundle and disposes it on a startup-time signal', async () => {
+  it('lets a profile without a parser ignore app arguments and dispose on a startup-time signal', async () => {
     const fixture = createProfileLifecycleFixture()
-    const child = startProfileLifecycle(fixture)
+    const child = startProfileLifecycle(fixture, ['--unclaimed'])
     try {
       await waitForFile(fixture.ready)
       requestProfileShutdown(child, fixture)
@@ -404,6 +534,83 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
     }
   }, 30_000)
 
+  it('hands the app arguments to the profile, which applies them before its rows start', async () => {
+    const fixture = createStartupFixture()
+    const child = startStartupProfile(fixture, ['--generation', 'flagged'])
+    try {
+      await waitForFile(fixture.ready)
+      // The consumer started once, already carrying the flag value: the
+      // launcher never saw --generation, and the app provider resolved it first.
+      expect(readFileSync(fixture.echo, 'utf8')).toBe('flagged')
+      requestProfileShutdown(child, fixture)
+      expect((await child).exitCode).toBe(0)
+    } finally {
+      child.kill('SIGKILL')
+      rmSync(fixture.home, { recursive: true, force: true })
+    }
+  }, 30_000)
+
+  it('starts a consumer on its composed value when the invocation carries no app arguments', async () => {
+    const fixture = createStartupFixture()
+    const child = startStartupProfile(fixture, [])
+    try {
+      await waitForFile(fixture.ready)
+      expect(readFileSync(fixture.echo, 'utf8')).toBe('bundle-default')
+      requestProfileShutdown(child, fixture)
+      expect((await child).exitCode).toBe(0)
+    } finally {
+      child.kill('SIGKILL')
+      rmSync(fixture.home, { recursive: true, force: true })
+    }
+  }, 30_000)
+
+  it('keeps the app arguments across a user patch reload', async () => {
+    // A live edit recomposes every row while the provider service remains
+    // active, so each config expression reads the same invocation value (a
+    // served port does not move back to its composed fallback).
+    const fixture = createStartupFixture()
+    const profilePatch = join(fixture.home, 'profiles', 'startup', 'cordis.patch.yml')
+    const child = startStartupProfile(fixture, ['--generation', 'flagged'])
+    try {
+      // Both rows: the waiting one carries the flag value, and the witness is
+      // what a reload will re-mount. They start independently, so neither
+      // marker implies the other.
+      await waitForFile(fixture.ready)
+      await waitForFile(fixture.witness)
+      expect(readFileSync(fixture.echo, 'utf8')).toBe('flagged')
+      // An edit to an unrelated row: the witness re-mounts, which is how this
+      // test knows the whole tree was recomposed.
+      rmSync(fixture.witness)
+      writeFileSync(profilePatch, [
+        '- id: reload-witness',
+        '  config:',
+        '    generation: reloaded',
+        '',
+      ].join('\n'))
+      await waitForFile(fixture.witness)
+      expect(readFileSync(fixture.witness, 'utf8')).toBe('reloaded')
+      expect(readFileSync(fixture.echo, 'utf8')).toBe('flagged')
+      requestProfileShutdown(child, fixture)
+      expect((await child).exitCode).toBe(0)
+    } finally {
+      child.kill('SIGKILL')
+      rmSync(fixture.home, { recursive: true, force: true })
+    }
+  }, 30_000)
+
+  it("prints the app's own help, starts none of its rows, and exits", async () => {
+    const fixture = createStartupFixture()
+    try {
+      const result = await startStartupProfile(fixture, ['--help'])
+      expect(result.exitCode).toBe(0)
+      expect(result.stdout).toContain('Usage: fixture')
+      expect(result.stdout).toContain('--generation')
+      expect(existsSync(fixture.ready)).toBe(false)
+    } finally {
+      rmSync(fixture.home, { recursive: true, force: true })
+    }
+  }, 30_000)
+
   it('anchors a relative add spec to the invoking directory, not the profile', async () => {
     // `dsh plugin --profile x add .` from a plugin checkout must install THAT
     // checkout — pnpm's cwd is the profile directory, so an un-anchored `.`
@@ -490,18 +697,17 @@ 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 () => {
+    it('prints the headless profile without Host or browser layers', 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.toMatch(/name: '@deepseek-ai\/dsh-host-/)
       expect(stdout).not.toContain("name: '@deepseek-ai/dsh-web-app'")
-      expect(stdout).not.toContain("name: '@deepseek-ai/dsh-client-")
+      expect(stdout).not.toMatch(/name: '@deepseek-ai\/dsh-client-/)
     }, 30_000)
 
     it('composes the profile user layer and a --patch overlay in order', async () => {

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

@@ -83,7 +83,7 @@ async function runHeadlessPtySmoke(): Promise<string> {
     ].join('\n'))
     const launch = resolveExampleLaunch({
       srcBin: dshBinScript,
-      configArgs: ['run', 'never complete'],
+      configArgs: ['--profile', 'headless', 'never complete'],
       tsconfigPath,
       env: {
         DSH_HOME: home,

apps/cli/tests/web-agent-presets.e2e.ts

@@ -5,6 +5,7 @@ import { fileURLToPath } from 'node:url'
 import { dirname, join } from 'node:path'
 import { Context } from '@deepseek-ai/cordis'
 import { boot, healProfilesModuleFallback, loadOverlayPatches } from '@deepseek-ai/dsh-app-boot'
+import { provideCmdline } from '@deepseek-ai/dsh-cmdline'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import type { PatchOptions } from '@deepseek-ai/cordis-plugin-include'
@@ -100,7 +101,9 @@ async function bootWeb(settingsFile: string, extra: PatchOptions[] = []): Promis
   await mkdir(profileDir, { recursive: true })
   const rootConfig = join(profileDir, 'cordis.yml')
   await writeFile(rootConfig, '[]\n')
-  return await boot('dsh-test', rootConfig, patches)
+  return await boot('dsh-test', rootConfig, patches, (bootCtx) => {
+    provideCmdline(bootCtx, { args: [], exit: () => {} })
+  })
 }
 
 const toolNames = (ctx: Context, agent?: Agent): string[] =>

apps/cli/tsconfig.json

@@ -20,6 +20,9 @@
     {
       "path": "../../packages/boot/app-boot"
     },
+    {
+      "path": "../../packages/boot/cmdline"
+    },
     {
       "path": "../../packages/bundle/base"
     },
@@ -47,6 +50,9 @@
     {
       "path": "../../packages/core/tools"
     },
+    {
+      "path": "../../packages/util/environment"
+    },
     {
       "path": "../../packages/util/paths"
     },

apps/web/package.json

@@ -28,6 +28,7 @@
     "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
     "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
     "@deepseek-ai/dsh-client-web-react": "workspace:^",
+    "@deepseek-ai/dsh-cmdline": "workspace:^",
     "@deepseek-ai/dsh-pwsh-local": "workspace:^",
     "@types/node": "^22.0.0",
     "@types/react": "~18.3.1",

apps/web/tests/scaffold.ts

@@ -35,7 +35,6 @@ import Include, { type PatchOptions } from '@deepseek-ai/cordis-plugin-include'
 import Group from '@deepseek-ai/cordis-plugin-group'
 import { scrubRequestHeaders, stabilizeFixtureMessageIds } from '@deepseek-ai/dsh-acp-snapshot'
 import {
-  addHarnessSourceSection,
   assertEntriesLoaded,
   composeEntries,
   healProfilesModuleFallback,
@@ -65,6 +64,7 @@ import * as ToolCordis from '@deepseek-ai/dsh-tool-cordis'
 // Empty type imports carry the httpServer/agents/sessionPersistence Context merges.
 import type {} from '@deepseek-ai/dsh-host-webserver'
 import type {} from '@deepseek-ai/dsh-agent'
+import { provideCmdline } from '@deepseek-ai/dsh-cmdline'
 import { REPO_ROOT, requireDist } from './support.ts'
 
 /** Snapshot mode for the lane, from $DSH_SNAPSHOT (same vocabulary as the other snapshot suites). */
@@ -459,6 +459,16 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
     ctx.baseUrl = pathToFileURL(profileDir).href + '/'
     // This direct Loader harness supplies the same root-path capability as app-boot.
     ctx.provide('dshHomePath', dshHomePath)
+    // A host with no command line still provides one: the web bundle's startup
+    // row releases the rows waiting on it, and with no arguments each starts on
+    // the values this scaffold composed above. An exit request can only come
+    // from a rejected argument, which a fixed empty list has none of.
+    provideCmdline(ctx, {
+      args: [],
+      exit: (code) => {
+        throw new Error(`web e2e scaffold: the web app requested exit ${String(code)} with no arguments to reject`)
+      },
+    })
     await ctx.plugin(Loader)
     ctx.loader.builtins.include = Include
     // `cordis:group` beside it, exactly as `boot()` registers it: a group row is
@@ -469,9 +479,6 @@ export async function launchWebScaffold(options: LaunchOptions = {}): Promise<We
     // The shipped CLI deliberately has no dependency on this opt-in package.
     // Keep the Loader row real without broadening the product installation.
     if (options.cordisTools === true) ctx.loader.builtins['tool-cordis'] = ToolCordis
-    if (surfaceContext) {
-      ctx.inject(['systemPrompt'], (promptCtx) => { addHarnessSourceSection(promptCtx, REPO_ROOT) })
-    }
     await ctx.loader.create({
       name: 'cordis:include',
       config: { path: pathToFileURL(rootConfig).href, patches },

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

@@ -485,10 +485,13 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY || notReady.length > 0)('web smoke
     child = spawn(
       process.execPath,
       [
-        '--import', tsxLoader, join(REPO_ROOT, 'apps/cli/src/bin.ts'), 'web', '--port', String(port),
+        '--import', tsxLoader, join(REPO_ROOT, 'apps/cli/src/bin.ts'), 'web',
+        // Launcher flags come first: the first token the launcher does not own
+        // starts the web app's own arguments.
         // Pin the in-browser picker: the shipped `-auto` row would resolve to
         // the native OS chooser on this bind, and no page can drive that.
         '--patch', fileURLToPath(new URL('./pin-browse-picker.overlay.yml', import.meta.url)),
+        '--port', String(port),
       ],
       {
         cwd: sessionsDir,

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: 64c7722a3cc3788d110eab8d9be161129684b942
-config-catalog.zh.md: 4cc146a38b408d9f1a7e5067419fead48520ae11
+config-catalog.md: 0813c9e1f1d761b69180bc919d0629e10c7661bc
+config-catalog.zh.md: cda44f7904196fe2bf401fed2dc5b5e8b28ccf1c

docs/config-catalog.md

@@ -572,7 +572,7 @@ Source: [`packages/goal/goal/src/index.ts:116`](../packages/goal/goal/src/index.
 Requires: `agentDefaultModel` · `agents` · `sessions`
 
 ```ts config-catalog
-/** Plugin config: the task, patched in by the launcher. */
+/** Plugin config: the task resolved from this app's injected provider service. */
 export interface Config {
   /** The prompt text for the single run. */
   task: string
@@ -2520,33 +2520,28 @@ Source: [`packages/web/web/src/index.ts:55`](../packages/web/web/src/index.ts)
 Requires: `httpServer`
 
 ```ts config-catalog
-/** Plugin config: the surface facts the launcher patches over this bundle's defaults. */
+/** Plugin config: composed deployment settings plus per-invocation command-line values. */
 export interface Config {
   /** Whether this process mounted the client-plugin HMR receiver (`dsh web --dev`). */
   mode: WebMode
-  /** Print the URL line on activation; a headless layer over this bundle turns it off. */
+  /** Print the URL line on activation; a non-interactive layer can turn it off. */
   printUrl: boolean
   /**
    * Register the model-visible surface context (the `app:web-surface` prompt
    * section and the `DSH_WEB_URL`/`DSH_WEB_MODE` bash variables). A one-shot
-   * layer turns it off: its user is not interacting through the GUI, so the
+   * non-interactive layer can turn it off when its user is not in the GUI, so the
    * orientation text would be false.
    */
   surfaceContext: boolean
-  /**
-   * LAN IPv4 addresses sampled once by the launcher when the effective bind
-   * is all-interfaces — the exact snapshot the /api trust fence was
-   * configured with, so the printed LAN URL can never name an address the
-   * fence rejects. Empty on a loopback bind.
-   */
-  lanAddresses: string[]
+  /** Explicit `--trusted-host` authorities from this invocation. */
+  trustedHosts: string[]
 }
 
 /** Web runtime mode: production, or development when the client-plugin HMR receiver is active. */
 export type WebMode = 'production' | 'development'
 ```
 
-Source: [`packages/bundle/web-app/src/index.ts:32`](../packages/bundle/web-app/src/index.ts)
+Source: [`packages/bundle/web-app/src/index.ts:43`](../packages/bundle/web-app/src/index.ts)
 
 ## `@deepseek-ai/dsh-web-fetch-local`
 
@@ -2792,6 +2787,7 @@ Imported as libraries by other packages; a `cordis.yml` cannot load them.
 - `@deepseek-ai/dsh-client-ui-slots` ([`packages/client/ui-slots/src/index.ts`](../packages/client/ui-slots/src/index.ts))
 - `@deepseek-ai/dsh-client-web` ([`packages/client/web/src/index.ts`](../packages/client/web/src/index.ts))
 - `@deepseek-ai/dsh-client-web-react` ([`packages/client/web-react/src/index.ts`](../packages/client/web-react/src/index.ts))
+- `@deepseek-ai/dsh-cmdline` ([`packages/boot/cmdline/src/index.ts`](../packages/boot/cmdline/src/index.ts))
 - `@deepseek-ai/dsh-environment` ([`packages/util/environment/src/index.ts`](../packages/util/environment/src/index.ts))
 - `@deepseek-ai/dsh-helper` ([`packages/scaffold/helper/src/index.ts`](../packages/scaffold/helper/src/index.ts))
 - `@deepseek-ai/dsh-hook-protocol` ([`packages/hooks/hook-protocol/src/index.ts`](../packages/hooks/hook-protocol/src/index.ts))

docs/config-catalog.zh.md

@@ -574,7 +574,7 @@ export interface Config {
 需要：`agentDefaultModel` · `agents` · `sessions`
 
 ```ts config-catalog
-/** Plugin config: the task, patched in by the launcher. */
+/** Plugin config: the task resolved from this app's injected provider service. */
 export interface Config {
   /** The prompt text for the single run. */
   task: string
@@ -2521,33 +2521,28 @@ export interface WebServiceConfig {
 需要：`httpServer`
 
 ```ts config-catalog
-/** Plugin config: the surface facts the launcher patches over this bundle's defaults. */
+/** Plugin config: composed deployment settings plus per-invocation command-line values. */
 export interface Config {
   /** Whether this process mounted the client-plugin HMR receiver (`dsh web --dev`). */
   mode: WebMode
-  /** Print the URL line on activation; a headless layer over this bundle turns it off. */
+  /** Print the URL line on activation; a non-interactive layer can turn it off. */
   printUrl: boolean
   /**
    * Register the model-visible surface context (the `app:web-surface` prompt
    * section and the `DSH_WEB_URL`/`DSH_WEB_MODE` bash variables). A one-shot
-   * layer turns it off: its user is not interacting through the GUI, so the
+   * non-interactive layer can turn it off when its user is not in the GUI, so the
    * orientation text would be false.
    */
   surfaceContext: boolean
-  /**
-   * LAN IPv4 addresses sampled once by the launcher when the effective bind
-   * is all-interfaces — the exact snapshot the /api trust fence was
-   * configured with, so the printed LAN URL can never name an address the
-   * fence rejects. Empty on a loopback bind.
-   */
-  lanAddresses: string[]
+  /** Explicit `--trusted-host` authorities from this invocation. */
+  trustedHosts: string[]
 }
 
 /** Web runtime mode: production, or development when the client-plugin HMR receiver is active. */
 export type WebMode = 'production' | 'development'
 ```
 
-来源：[`packages/bundle/web-app/src/index.ts:32`](../packages/bundle/web-app/src/index.ts)
+来源：[`packages/bundle/web-app/src/index.ts:43`](../packages/bundle/web-app/src/index.ts)
 
 ## `@deepseek-ai/dsh-web-fetch-local`
 
@@ -2792,6 +2787,7 @@ export interface Config {
 - `@deepseek-ai/dsh-client-ui-slots`（[`packages/client/ui-slots/src/index.ts`](../packages/client/ui-slots/src/index.ts)）
 - `@deepseek-ai/dsh-client-web`（[`packages/client/web/src/index.ts`](../packages/client/web/src/index.ts)）
 - `@deepseek-ai/dsh-client-web-react`（[`packages/client/web-react/src/index.ts`](../packages/client/web-react/src/index.ts)）
+- `@deepseek-ai/dsh-cmdline`（[`packages/boot/cmdline/src/index.ts`](../packages/boot/cmdline/src/index.ts)）
 - `@deepseek-ai/dsh-environment`（[`packages/util/environment/src/index.ts`](../packages/util/environment/src/index.ts)）
 - `@deepseek-ai/dsh-helper`（[`packages/scaffold/helper/src/index.ts`](../packages/scaffold/helper/src/index.ts)）
 - `@deepseek-ai/dsh-hook-protocol`（[`packages/hooks/hook-protocol/src/index.ts`](../packages/hooks/hook-protocol/src/index.ts)）

docs/cordis-api/fiber.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/cordis-api/fiber.md
-fiber.md: 36d2861ac6a53e8186a92d86c65ba228d4b59ee5
-fiber.zh.md: fafa559ca911677c43893862190009d82c39c56b
+fiber.md: 182b77390b29b8a90504437d0ccc2dfeba23921a
+fiber.zh.md: 9ed3e52618586dc3815b9d913439d11a227fb64b

docs/cordis-api/fiber.md

@@ -34,7 +34,7 @@ Register a cleanup-aware effect on this fiber.
 
 **Returns** a disposer that tears the effect down and settles once done.
 
-[Source](../../vendor/cordis/src/fiber.ts#L420)
+[Source](../../vendor/cordis/src/fiber.ts#L415)
 
 ### ctx.fiber
 
@@ -97,7 +97,7 @@ public state
 
 Current lifecycle state; transitions emit `internal/status`.
 
-[Source](../../vendor/cordis/src/fiber.ts#L192)
+[Source](../../vendor/cordis/src/fiber.ts#L194)
 
 ### fiber.dispose
 
@@ -108,7 +108,7 @@ public readonly dispose: () => Promise<void>
 
 Dispose this fiber: unload the plugin, then settle once cleanup finished.
 
-[Source](../../vendor/cordis/src/fiber.ts#L194)
+[Source](../../vendor/cordis/src/fiber.ts#L196)
 
 ### fiber.store
 
@@ -119,7 +119,7 @@ public store: Dict<Impl> | undefined
 
 Snapshot of required service implementations while loaded; `undefined` otherwise.
 
-[Source](../../vendor/cordis/src/fiber.ts#L196)
+[Source](../../vendor/cordis/src/fiber.ts#L198)
 
 ### fiber.inertia
 
@@ -130,7 +130,7 @@ public inertia: Promise<void> | undefined
 
 The in-flight load/unload transition, if one is currently running.
 
-[Source](../../vendor/cordis/src/fiber.ts#L198)
+[Source](../../vendor/cordis/src/fiber.ts#L200)
 
 ### fiber.name
 
@@ -141,7 +141,7 @@ get name()
 
 The plugin's display name, inherited from the nearest named ancestor, else `'root'`.
 
-[Source](../../vendor/cordis/src/fiber.ts#L341)
+[Source](../../vendor/cordis/src/fiber.ts#L336)
 
 ### fiber.assertActive()
 
@@ -159,7 +159,7 @@ Throw if the fiber has already been disposed.
 
 **Returns** nothing when the fiber is still active.
 
-[Source](../../vendor/cordis/src/fiber.ts#L356)
+[Source](../../vendor/cordis/src/fiber.ts#L351)
 
 ### fiber.effect(execute, label?)
 
@@ -190,7 +190,7 @@ Register a cleanup-aware effect on this fiber.
 
 **Returns** a disposer that tears the effect down and settles once done.
 
-[Source](../../vendor/cordis/src/fiber.ts#L420)
+[Source](../../vendor/cordis/src/fiber.ts#L415)
 
 ### fiber.getEffects()
 
@@ -207,7 +207,7 @@ Return metadata for currently registered effects.
 
 **Returns** one `EffectMeta` tree per labeled live effect.
 
-[Source](../../vendor/cordis/src/fiber.ts#L573)
+[Source](../../vendor/cordis/src/fiber.ts#L568)
 
 ### fiber.await()
 
@@ -225,7 +225,7 @@ Wait for current lifecycle work and rethrow startup errors.
 
 **Returns** this fiber, once it has settled into a stable state.
 
-[Source](../../vendor/cordis/src/fiber.ts#L702)
+[Source](../../vendor/cordis/src/fiber.ts#L704)
 
 ### fiber.restart()
 
@@ -243,7 +243,7 @@ Dispose and immediately reload this plugin with its current config.
 
 **Returns** a promise resolving once the reload settled.
 
-[Source](../../vendor/cordis/src/fiber.ts#L716)
+[Source](../../vendor/cordis/src/fiber.ts#L718)
 
 ### fiber.update(config, noSave?)
 
@@ -271,7 +271,7 @@ Runs the `internal/update` waterfall first, so update hooks (and HMR) can veto o
 
 **Returns** the update waterfall result; the default restart returns a promise.
 
-[Source](../../vendor/cordis/src/fiber.ts#L734)
+[Source](../../vendor/cordis/src/fiber.ts#L736)
 
 ## Effect
 

docs/cordis-api/fiber.zh.md

@@ -36,7 +36,7 @@ effect(execute: () => Effect, label?: string): AsyncDisposable<Promise<void>>
 
 **返回**一个用于撤销该作用的清理函数，并在清理完成后结算。
 
-[源码](../../vendor/cordis/src/fiber.ts#L420)
+[源码](../../vendor/cordis/src/fiber.ts#L415)
 
 ### ctx.fiber
 
@@ -99,7 +99,7 @@ public state
 
 当前生命周期状态；状态转换会发出 `internal/status`。
 
-[源码](../../vendor/cordis/src/fiber.ts#L192)
+[源码](../../vendor/cordis/src/fiber.ts#L194)
 
 ### fiber.dispose
 
@@ -110,7 +110,7 @@ public readonly dispose: () => Promise<void>
 
 dispose 此 fiber：卸载插件，并在清理完成后结算。
 
-[源码](../../vendor/cordis/src/fiber.ts#L194)
+[源码](../../vendor/cordis/src/fiber.ts#L196)
 
 ### fiber.store
 
@@ -121,7 +121,7 @@ public store: Dict<Impl> | undefined
 
 加载期间所需服务实现的快照；其他情况下为 `undefined`。
 
-[源码](../../vendor/cordis/src/fiber.ts#L196)
+[源码](../../vendor/cordis/src/fiber.ts#L198)
 
 ### fiber.inertia
 
@@ -132,7 +132,7 @@ public inertia: Promise<void> | undefined
 
 当前正在进行的加载或卸载转换；如果没有此类转换，则为 undefined。
 
-[源码](../../vendor/cordis/src/fiber.ts#L198)
+[源码](../../vendor/cordis/src/fiber.ts#L200)
 
 ### fiber.name
 
@@ -143,7 +143,7 @@ get name()
 
 插件的显示名称，继承自最近的具名祖先；如果不存在，则为 `'root'`。
 
-[源码](../../vendor/cordis/src/fiber.ts#L341)
+[源码](../../vendor/cordis/src/fiber.ts#L336)
 
 ### fiber.assertActive()
 
@@ -161,7 +161,7 @@ assertActive()
 
 **返回**：fiber 仍处于活动状态时不返回任何内容。
 
-[源码](../../vendor/cordis/src/fiber.ts#L356)
+[源码](../../vendor/cordis/src/fiber.ts#L351)
 
 ### fiber.effect(execute, label?)
 
@@ -192,7 +192,7 @@ effect(execute: () => Effect, label?: string): AsyncDisposable<Promise<void>>
 
 **返回**一个用于撤销该作用的清理函数，并在清理完成后结算。
 
-[源码](../../vendor/cordis/src/fiber.ts#L420)
+[源码](../../vendor/cordis/src/fiber.ts#L415)
 
 ### fiber.getEffects()
 
@@ -209,7 +209,7 @@ getEffects()
 
 **返回**：每个带标签的活动作用对应一棵 `EffectMeta` 树。
 
-[源码](../../vendor/cordis/src/fiber.ts#L573)
+[源码](../../vendor/cordis/src/fiber.ts#L568)
 
 ### fiber.await()
 
@@ -227,7 +227,7 @@ async await()
 
 **返回**：进入稳定状态后的此 fiber。
 
-[源码](../../vendor/cordis/src/fiber.ts#L702)
+[源码](../../vendor/cordis/src/fiber.ts#L704)
 
 ### fiber.restart()
 
@@ -245,7 +245,7 @@ dispose 此插件，并立即使用其当前配置重新加载。
 
 **返回**一个在重新加载完成后兑现的 promise。
 
-[源码](../../vendor/cordis/src/fiber.ts#L716)
+[源码](../../vendor/cordis/src/fiber.ts#L718)
 
 ### fiber.update(config, noSave?)
 
@@ -273,7 +273,7 @@ update(config: any, noSave = false)
 
 **返回**更新 waterfall 的结果；默认的重新启动操作返回一个 promise。
 
-[源码](../../vendor/cordis/src/fiber.ts#L734)
+[源码](../../vendor/cordis/src/fiber.ts#L736)
 
 ## Effect
 

docs/cordis-primer.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/cordis-primer.md
-cordis-primer.md: 93725949a9490f757edebcf3e8391db9e73321b1
-cordis-primer.zh.md: fd2a327b526b210986bc1574013fca2c0cec5dda
+cordis-primer.md: d1e7c5fd8eaaa89fe448d238359389d945cd6346
+cordis-primer.zh.md: d6ce0f2024f65b006c9505daffaa06a08bb56875

docs/cordis-primer.md

@@ -35,7 +35,7 @@ For single-decision events, short-circuiting is the design. A policy listener ca
 
 ## Loader Configuration
 
-`@deepseek-ai/cordis-plugin-include` parses `!!js` into expression nodes, but the Loader interpolates only an entry's `config` before mounting the plugin. Entry metadata (`id`, `name`, `group`, `disabled`, `inject`, `intercept`, and `isolate`) remains literal; `disabled: !!js ...` is therefore a truthy object that always disables the entry. Use explicit config overlays when environment selection changes which plugins are mounted.
+`@deepseek-ai/cordis-plugin-include` parses `!!js` into expression nodes. Loader interpolates only an entry's `config`, after declared injections activate, against that plugin context (`ctx.serviceName`); Include preserves nested row expressions until target activation. Entry metadata (`id`, `name`, `group`, `disabled`, `inject`, `intercept`, `isolate`) stays literal, so `disabled: !!js ...` always disables the entry. Use overlays when the environment selects plugins.
 
 ## Practical Rules
 

docs/cordis-primer.zh.md

@@ -39,7 +39,7 @@ Cordis 是 DeepSeek Harness SDK 底层以 vendor 方式引入的插件框架。
 
 ## Loader 配置
 
-`@deepseek-ai/cordis-plugin-include` 将 `!!js` 解析为表达式节点，但 Loader 仅在挂载插件前对条目的 `config` 做插值。条目元数据（`id`、`name`、`group`、`disabled`、`inject`、`intercept` 和 `isolate`）保持字面值；因此 `disabled: !!js ...` 是一个 truthy 对象，会始终禁用该条目。需要根据环境选择挂载哪些插件时，请使用显式的配置覆盖层。
+`@deepseek-ai/cordis-plugin-include` 将 `!!js` 解析为表达式节点。Loader 只在声明的注入激活后，基于该插件上下文（`ctx.serviceName`）插值条目的 `config`；Include 会保留嵌套行表达式，直到目标行激活。条目元数据（`id`、`name`、`group`、`disabled`、`inject`、`intercept`、`isolate`）保持字面值，因此 `disabled: !!js ...` 始终禁用该条目。由环境选择插件时，请使用 overlay。
 
 ## 实践规则
 

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: 2b1f8dd9d41ab5ad34a4787ffa54c6b7d13144af
-module-graph.zh.md: 192943312b672c1ae10d32182e9ccd7456eac90b
+module-graph.md: 3efb73d075f3d5d7a8bae990fc2f524dc710bcb7
+module-graph.zh.md: df3b9b38497893471b2613c0c95da409dda0262b

docs/module-graph.md

@@ -133,6 +133,7 @@ flowchart TD
   end
   subgraph group_boot["packages/boot"]
     pkg_app_boot["app-boot"]
+    pkg_cmdline["cmdline"]
   end
   subgraph group_bundle["packages/bundle"]
     pkg_base["base"]
@@ -313,6 +314,7 @@ flowchart TD
   pkg_timeout --> pkg_invariants
   pkg_scope --> pkg_invariants
   pkg_llm_mock_server --> pkg_invariants
+  pkg_cmdline --> pkg_invariants
   pkg_base --> pkg_invariants
   pkg_client_modules --> pkg_invariants
   pkg_client_schema_form --> pkg_invariants
@@ -1252,6 +1254,7 @@ flowchart TD
 | [`timeout`](../packages/util/timeout) | `util` | [`invariants`](../packages/support/invariants) |
 | [`scope`](../packages/core/scope) | `core` | [`invariants`](../packages/support/invariants) |
 | [`llm-mock-server`](../packages/support/llm-mock-server) | `support` | [`invariants`](../packages/support/invariants) |
+| [`cmdline`](../packages/boot/cmdline) | `boot` | [`invariants`](../packages/support/invariants) |
 | [`base`](../packages/bundle/base) | `bundle` | [`invariants`](../packages/support/invariants) |
 | [`client-modules`](../packages/client/modules) | `client` | [`invariants`](../packages/support/invariants) |
 | [`client-schema-form`](../packages/client/schema-form) | `client` | [`invariants`](../packages/support/invariants) |

docs/module-graph.zh.md

@@ -135,6 +135,7 @@ flowchart TD
   end
   subgraph group_boot["packages/boot"]
     pkg_app_boot["app-boot"]
+    pkg_cmdline["cmdline"]
   end
   subgraph group_bundle["packages/bundle"]
     pkg_base["base"]
@@ -315,6 +316,7 @@ flowchart TD
   pkg_timeout --> pkg_invariants
   pkg_scope --> pkg_invariants
   pkg_llm_mock_server --> pkg_invariants
+  pkg_cmdline --> pkg_invariants
   pkg_base --> pkg_invariants
   pkg_client_modules --> pkg_invariants
   pkg_client_schema_form --> pkg_invariants
@@ -1254,6 +1256,7 @@ flowchart TD
 | [`timeout`](../packages/util/timeout) | `util` | [`invariants`](../packages/support/invariants) |
 | [`scope`](../packages/core/scope) | `core` | [`invariants`](../packages/support/invariants) |
 | [`llm-mock-server`](../packages/support/llm-mock-server) | `support` | [`invariants`](../packages/support/invariants) |
+| [`cmdline`](../packages/boot/cmdline) | `boot` | [`invariants`](../packages/support/invariants) |
 | [`base`](../packages/bundle/base) | `bundle` | [`invariants`](../packages/support/invariants) |
 | [`client-modules`](../packages/client/modules) | `client` | [`invariants`](../packages/support/invariants) |
 | [`client-schema-form`](../packages/client/schema-form) | `client` | [`invariants`](../packages/support/invariants) |

docs/testing.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/testing.md
-testing.md: f5e8a478ec86c29c52f4127c51682c1c44fd23a7
-testing.zh.md: bd1fa7d23263d7c6e3bed65ef4ed09576ca47cc1
+testing.md: f330bb1e02f3613c63f3989a8f9128f737bf5c52
+testing.zh.md: db6facb4fa4bf07eda0a6ee7e558c8c60d4c331e

docs/testing.md

@@ -9,7 +9,7 @@ How this repo tests, tier by tier, and the rules that keep a green suite meaning
 - **Unit** (`pnpm run test`): vitest over package and example specs under their `tests/**` directories plus repository script specs under `scripts/**/*.spec.ts`; tests stay with the code area they exercise. Every registry gets an HMR-safety test (dispose the contributing fiber, assert cleanup). Prefer edge cases, error paths, event ordering, concurrency races, and permanent tests for contract regressions (see `packages/core/agent-loop/tests/contract-regressions.spec.ts`).
 - **Coverage gate** (`pnpm run test:coverage`): the gating run, per-file 100% on `packages/*/*/src`. An uncovered line is often dead code the gate is correctly flagging for deletion, not a missing test to bolt on. Line coverage is necessary, never sufficient — it proves lines ran, not that the feature works as shipped. Per-file 100% on `packages/bash/pwsh-local/src` needs a real `pwsh`: without one its executor suites self-skip and `vitest.config.ts` exempts the file so pwsh-less hosts stay green, while CI runners ship pwsh and enforce the full bar.
 - **Real-API e2e** (`pnpm run test:e2e`): with-key tests against live provider APIs — the DeepSeek model plus provider-specific smokes that gate on their own keys (`EXA_API_KEY`, `PERPLEXITY_API_KEY`, …); each suite self-skips without its key so keyless CI stays green ([real-API e2e Agent Note](../.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md)).
-- **Snapshot** (`pnpm run test:snapshot`): keyless expected outputs cover external behavior — transport contracts and presentation, while persisted logs pin assembled backend behavior. ACP boots the real automation-server example, replays a recorded session, and diffs normalized JSON-RPC plus the re-persisted log ([ACP snapshot Agent Note](../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md)); headless backend scenarios boot their explicit example composition through an unexported JSONL test driver, while `apps/cli` separately owns product `dsh run` acceptance. Use `pnpm run test:snapshot:record` when a model transcript changes and `pnpm run test:snapshot:refresh` when replay input remains valid; review every JSONL and expected-output diff. One ACP scenario (`text-turn`) pins full system-prompt/tool-schema content; other fixtures tokenize it so an edit churns one line ([pinned-header Agent Note](../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)).
+- **Snapshot** (`pnpm run test:snapshot`): keyless expected outputs cover external behavior — transport contracts and presentation, while persisted logs pin assembled backend behavior. ACP boots the real automation-server example, replays a recorded session, and diffs normalized JSON-RPC plus the re-persisted log ([ACP snapshot Agent Note](../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md)); headless backend scenarios boot their explicit example composition through an unexported JSONL test driver, while `apps/cli` separately owns product `dsh --profile headless` acceptance. Use `pnpm run test:snapshot:record` when a model transcript changes and `pnpm run test:snapshot:refresh` when replay input remains valid; review every JSONL and expected-output diff. One ACP scenario (`text-turn`) pins full system-prompt/tool-schema content; other fixtures tokenize it so an edit churns one line ([pinned-header Agent Note](../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)).
 - **Web browser snapshot** (`pnpm run test:web`; required Linux PR gate): Chromium compares replayed browser output with `apps/web/tests/snapshots/`. CI forces read-only `DSH_SNAPSHOT=replay`, never writing expected outputs; record/refresh stay local and every diff is reviewed ([web e2e lane](../.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md), [CI gate decision](../.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.md)). `test:web` [builds first](../.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md) for plugin CSS.
 
 Committed session-format JSONL uses the canonical packed-row layout, and the keyless snapshot gate discovers every such fixture by its `session` header; the [temporary migrator](../scripts/migrate-packed-session-fixtures.ts) rewrites older fixture layouts.

docs/testing.zh.md

@@ -9,7 +9,7 @@
 - **单元测试**（`pnpm run test`）：vitest 运行包（package）和示例各自的 `tests/**` 目录下的测试，以及匹配 `scripts/**/*.spec.ts` 的仓库脚本测试；测试文件与其所覆盖的代码区域放在一起。每个注册表都有一个 HMR（热模块替换）安全测试（dispose（资源释放）贡献的 fiber，断言清理完成）。优先覆盖边界情况、错误路径、事件顺序、并发竞态，以及针对约定回归的永久测试（见 `packages/core/agent-loop/tests/contract-regressions.spec.ts`）。
 - **覆盖率门禁**（`pnpm run test:coverage`）：门禁级运行，对 `packages/*/*/src` 按文件 100% 覆盖。未覆盖的行往往是门禁正确标记出的死代码（应删除），而非需要补写的测试。行覆盖率是必要条件，但永远不是充分条件：它证明行被执行过，不证明功能按交付预期工作。`packages/bash/pwsh-local/src` 的按文件 100% 覆盖需要真实的 `pwsh`：缺少它时其 executor 套件会自动跳过，`vitest.config.ts` 会豁免该文件以使无 pwsh 的主机保持绿色，而 CI runner 自带 pwsh，仍按完整标准执行门禁。
 - **真实 API e2e**（`pnpm run test:e2e`）：带密钥测试调用真实提供方 API，包括 DeepSeek 模型以及各提供方特有的冒烟测试；这些测试各自由自己的密钥控制（`EXA_API_KEY`、`PERPLEXITY_API_KEY` 等），缺少密钥时套件会自动跳过，使 keyless CI 保持绿色（[真实 API e2e Agent Note](../.agents/notes/implemented/testing/2026-06-19-real-api-e2e-ci.md)）。
-- **快照**（`pnpm run test:snapshot`）：无密钥预期输出覆盖对外行为（传输约定与呈现），持久化日志则固定组装后的后端行为。ACP 启动真实的自动化服务器示例、回放录制会话，并对归一化 JSON-RPC 与重新持久化的日志执行 diff（[ACP 快照 Agent Note](../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md)）；headless 后端场景通过未导出的 JSONL 测试 driver 启动各自显式的示例组装，而 `apps/cli` 则单独负责产品 CLI（命令行界面）`dsh run` 的验收。当模型 transcript（文本记录）发生变化时使用 `pnpm run test:snapshot:record`，回放输入仍然有效时使用 `pnpm run test:snapshot:refresh`；请审查每一处 JSONL 与预期输出差异。一个 ACP 场景（`text-turn`）固定完整的系统提示词与工具 schema 内容；其他 fixture（测试前置数据）将其 token 化，因此修改只会扰动一行（[pinned-header Agent Note](../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）。
+- **快照**（`pnpm run test:snapshot`）：无密钥预期输出覆盖对外行为（传输约定与呈现），持久化日志则固定组装后的后端行为。ACP 启动真实的自动化服务器示例、回放录制会话，并对归一化 JSON-RPC 与重新持久化的日志执行 diff（[ACP 快照 Agent Note](../.agents/notes/implemented/testing/2026-06-19-acp-snapshot-tests.md)）；headless 后端场景通过未导出的 JSONL 测试 driver 启动各自显式的示例组装，而 `apps/cli` 则单独负责产品 CLI（命令行界面）`dsh --profile headless` 的验收。当模型 transcript（文本记录）发生变化时使用 `pnpm run test:snapshot:record`，回放输入仍然有效时使用 `pnpm run test:snapshot:refresh`；请审查每一处 JSONL 与预期输出差异。一个 ACP 场景（`text-turn`）固定完整的系统提示词与工具 schema 内容；其他 fixture（测试前置数据）将其 token 化，因此修改只会扰动一行（[pinned-header Agent Note](../.agents/notes/archived/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)）。
 - **Web 浏览器快照**（`pnpm run test:web`；必需的 Linux PR（Pull Request）门禁）：Chromium 将回放后的浏览器输出与 `apps/web/tests/snapshots/` 比较。CI 强制只读的 `DSH_SNAPSHOT=replay`，绝不写入预期输出；record/refresh 留在本地，每处 diff 都须评审（[web e2e 车道](../.agents/notes/implemented/testing/2026-07-24-web-gui-browser-e2e-lane.md)、[CI 门禁决策](../.agents/notes/implemented/testing/2026-07-30-web-browser-snapshot-ci-gate.md)）。`test:web` 会[先构建](../.agents/notes/implemented/bug-fix/2026-07-28-themed-scrollbars-and-reserved-gutter.md)以交付插件 CSS。
 
 签入仓库的会话格式 JSONL 使用规范打包行布局，无密钥快照门禁会通过 `session` header 发现每一份此类 fixture；[临时迁移器](../scripts/migrate-packed-session-fixtures.ts)会改写旧版 fixture 布局。

docs/user/develop/basic/publish.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/develop/basic/publish.md
-publish.md: 7657654b1467c14b22e0eb6372c2bc4e77db2f38
-publish.zh.md: 7af2ae3a06cc74597d5cbd6fddd46fbab069e287
+publish.md: 8437c7ea5c4cb966f9f3d68977949c78986ec9a5
+publish.zh.md: 4409dbfda060a84b316029d87ec985209cfa286a

docs/user/develop/basic/publish.md

@@ -98,7 +98,8 @@ The effective configuration composes over an empty root by applying, in order:
 2. The profile's own `cordis.patch.yml`.
 3. The home-level `$DSH_HOME/cordis.patch.yml` — machine-local preferences shared by every profile.
 4. Each `--patch <path>` overlay, in argv order.
-5. Launcher flag patches (for example `dsh web --port`).
+
+App arguments are not another patch layer. A surface bundle can resolve them through an ordinary app-owned service, described below.
 
 Later layers win per row, and a patch replaces a row's entire `config` value rather than deep-merging keys. Two consequences for bundle authors:
 
@@ -107,6 +108,29 @@ Later layers win per row, and a patch replaces a row's entire `config` value rat
 
 In-box bundle names always resolve from the dsh installation itself; pnpm manages only out-of-tree packages, so your bundle can rely on `@deepseek-ai/dsh-base` being present and current.
 
+## Give a surface bundle its own command line
+
+A bundle that defines a runnable app mounts an ordinary provider plugin:
+
+```yaml
+- id: hello-startup
+  name: 'dsh-hello-plugin/startup'
+```
+
+The plugin exports `inject = ['cmdlineArgs']`, calls `parseCmdline` from [`@deepseek-ai/dsh-cmdline`](../../../../packages/boot/cmdline/README.md) with its own commander program, and provides the returned value as its app-owned service. The launcher hands every plugin the same immutable arguments after launcher flags, so app-specific flags need no launcher change and multiple plugins may parse the snapshot. The Loader row needs no launcher marker or special kind.
+
+Rows configured by those arguments inject the provider's service and read it from their own `!!js` options, with the deployment value beside it as the fallback:
+
+```yaml
+- id: my-app
+  name: '@example/my-app'
+  inject: [myAppStartup]
+  config:
+    port: !!js ctx.myAppStartup.port ?? 8080
+```
+
+On `--help`, the provider publishes no service, so those rows never activate. Loader mounts the composition once, waits for each row's ordinary injections, and only then evaluates that row's `!!js` config against its injected context.
+
 ## Installing from GitHub: the build-script catch
 
 Publishing to a registry is not required — users can install straight from a git host:

docs/user/develop/basic/publish.zh.md

@@ -2,14 +2,14 @@
 
 [English](publish.md) | 中文
 
-前几篇教程通过 `--patch` overlay 加载本地插件。本教程把它打包成可安装的**组合包**，用 `dsh plugin add` 安装进一个 **profile**，并解释决定组合后配置的层顺序。请先完成[插件配置](./config.md)。
+前几篇教程通过 `--patch` overlay 加载本地插件。本教程把它打包成可安装的**组合包**（bundle），用 `dsh plugin add` 安装进一个 **profile**，并解释决定组合后配置的层顺序。请先完成[插件配置](./config.md)。
 
-## 两个概念，两种 manifest（元数据清单）
+## 两个概念，两种 manifest
 
-安装机制建立在两个概念之上。二者都由一份 `package.json` 描述，但它们在 `dsh` 键下携带的 manifest 种类不同，回答的问题也不同：
+安装机制建立在两个概念之上。二者都由一份 `package.json` 描述，但它们在 `dsh` 键下携带的 manifest（元数据清单）种类不同，回答的问题也不同：
 
-- **组合包**是附带一个配置层的 npm 包。它的 manifest 声明 `dsh.bundle`，回答的是「这个包贡献什么？」：一个插入或覆盖插件行的 patch 文件。
-- **profile** 是位于 `$DSH_HOME/profiles/<name>` 下、描述一份可启动组合的目录。它的 manifest 声明 `dsh.profile`，回答的是「这套配置由哪些组合包按什么顺序组成？」。
+- **组合包**是附带一个配置层的 npm 包。它的 manifest 声明 `dsh.bundle`，回答的是"这个包贡献什么？"：一个插入或覆盖插件行的 patch 文件。
+- **profile** 是位于 `$DSH_HOME/profiles/<name>` 下、描述一份可启动组合的目录。它的 manifest 声明 `dsh.profile`，回答的是"这套配置由哪些组合包按什么顺序组成？"。
 
 组合包是你编写并分发的东西；profile 是用户用 `dsh --profile <name>` 启动的东西。没有东西同时是两者。
 
@@ -98,7 +98,8 @@ dsh --profile demo
 2. profile 自己的 `cordis.patch.yml`。
 3. home 级的 `$DSH_HOME/cordis.patch.yml`——各 profile 共享的机器本地偏好。
 4. 每个 `--patch <path>` overlay，按 argv 顺序。
-5. 启动器 flag patch（例如 `dsh web --port`）。
+
+应用参数不是另一层 patch。表层组合包可以通过下文所述的普通应用自有服务解析它们。
 
 后应用的层按行胜出，且 patch 会替换目标行的整个 `config` 值，而不是深度合并各键。这给组合包作者带来两个推论：
 
@@ -107,6 +108,29 @@ dsh --profile demo
 
 内置组合包名称始终从 dsh 安装目录本身解析；pnpm 只管理树外的包，所以你的组合包可以放心依赖 `@deepseek-ai/dsh-base` 存在且与安装保持一致。
 
+## 让表层组合包持有自己的命令行
+
+定义了可运行应用的组合包挂载一个普通提供方插件：
+
+```yaml
+- id: hello-startup
+  name: 'dsh-hello-plugin/startup'
+```
+
+该插件导出 `inject = ['cmdlineArgs']`，使用自己的 commander program 调用 [`@deepseek-ai/dsh-cmdline`](../../../../packages/boot/cmdline/README.md) 中的 `parseCmdline`，再把返回值作为应用自有服务提供出去。启动器把自身 flag 之后的同一份不可变参数交给每个插件，因此添加应用专属 flag 无需修改启动器，多个插件也可以解析该快照。Loader 行不需要启动器标记或特殊类型。
+
+受这些参数配置的行会注入提供方服务，并在自己的 `!!js` 选项中读取它，同时把部署取值写在旁边作为回退：
+
+```yaml
+- id: my-app
+  name: '@example/my-app'
+  inject: [myAppStartup]
+  config:
+    port: !!js ctx.myAppStartup.port ?? 8080
+```
+
+遇到 `--help` 时，提供方不会发布该服务，所以这些行不会激活。Loader 只挂载一次组合，等待每一行的普通注入，再基于其已注入的上下文求值该行的 `!!js` 配置。
+
 ## 从 GitHub 安装：构建脚本这道坎
 
 发布到注册表不是必须的——用户可以直接从 git 托管安装：
@@ -127,7 +151,7 @@ dsh plugin --profile demo add github:you/hello-plugin
 
   然后重新执行 `add`。
 
-请如实看待这项授权：**允许该包的代码在安装时于你的机器上执行**，且不在 agent（智能体）运行的任何沙箱之内。只对源码可信的包授权，并锁定 commit（`github:you/hello-plugin#<sha>`），让后续推送无法悄悄改变实际运行的内容。
+请如实看待这项授权：**允许该包的代码在安装时于你的机器上执行**，且不在 agent 运行的任何沙箱之内。只对源码可信的包授权，并锁定 commit（`github:you/hello-plugin#<sha>`），让后续推送无法悄悄改变实际运行的内容。
 
 如果不想让用户做这项授权，就改为分发构建产物——以下两种形式都不需要任何构建权限：
 

docs/user/guide/config.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/config.md
-config.md: cd778065801ae58a46703ae3447f835f80abf062
-config.zh.md: 6f6d37bfe8f7ad29c154d65c1763279655006435
+config.md: 1d3ad5ce36d4b360ba5156b6be28a6caae4a23d4
+config.zh.md: 7f8bfaa77066f2976a5667e3ac402814a7afdf96

docs/user/guide/config.md

@@ -18,6 +18,10 @@ A minimal configuration is a list of plugin entries:
 ```yaml
 - id: llm-deepseek
   name: '@deepseek-ai/dsh-llm-deepseek'
+  config:
+    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    models:
+      - deepseek-v4-flash
 
 - id: bash
   name: '@deepseek-ai/dsh-bash-local'
@@ -47,16 +51,17 @@ Cordis starts sibling entries concurrently. A plugin declares required services
 
 ## CLI patch layers
 
-`dsh --profile <name>` composes the profile's bundle patch layers (its manifest's `dsh.profile.bundles` list, in order) over an empty root, then the profile's own `~/.dsh/profiles/<name>/cordis.patch.yml`, then each `--patch <path>` overlay, then CLI-flag patches. Later layers win per row.
+`dsh --profile <name>` composes the profile's bundle patch layers (its manifest's `dsh.profile.bundles` list, in order) over an empty root, then the profile's own `~/.dsh/profiles/<name>/cordis.patch.yml`, the home-level `$DSH_HOME/cordis.patch.yml`, and each `--patch <path>` overlay. Later layers win per row. App flags are not another patch layer: an ordinary bundle plugin injects `cmdlineArgs` and provides parsed values as its own service, while rows that inject and retain a `!!js` read of that service give the invocation value precedence.
 
-A patch replaces a row's entire `config` value; it does not deep-merge keys. For example, patching `llm-deepseek` with only `config: { thinking: disabled }` also removes that row's configured `apiKeyEnv` and `baseURL`, so restate every key the row must retain.
+A patch replaces a row's entire `config` value; it does not deep-merge keys. For example, patching `llm-deepseek` with only `config: { thinking: disabled }` also removes that row's configured `apiKey` and `baseURL`, so restate every key the row must retain.
 
 ## JavaScript values and environment variables
 
-The Cordis loader evaluates runtime expressions tagged with `!!js` for non-secret runtime values. Bundled LLM adapters carry credential references such as `apiKeyEnv`; the value belongs in an environment layer or `$DSH_HOME/.credentials.yaml`, not Cordis configuration.
+The Cordis loader evaluates runtime expressions tagged with `!!js`. Keep API keys and other secrets in the gitignored `.env` file at the repository root, never in committed configuration.
 
 ```yaml
 config:
+  apiKey: !!js process.env.DEEPSEEK_API_KEY
   cwd: !!js process.cwd()
 ```
 

docs/user/guide/config.zh.md

@@ -18,6 +18,10 @@ Harness 使用 `cordis.yml` 描述 agent（智能体）加载哪些插件以及
 ```yaml
 - id: llm-deepseek
   name: '@deepseek-ai/dsh-llm-deepseek'
+  config:
+    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    models:
+      - deepseek-v4-flash
 
 - id: bash
   name: '@deepseek-ai/dsh-bash-local'
@@ -47,16 +51,17 @@ Cordis 会并发启动同级配置项。插件通过 `inject` 声明必需服务
 
 ## CLI 补丁层
 
-`dsh --profile <name>` 按该 profile 的 manifest（元数据清单）中 `dsh.profile.bundles` 列表的顺序，在空根之上组合各组合包补丁层，随后依次应用该 profile 自己的 `~/.dsh/profiles/<name>/cordis.patch.yml`、home 级 `$DSH_HOME/cordis.patch.yml`、每个 `--patch <path>` overlay，最后是 CLI（命令行界面）标志补丁。同一行以较后的层为准。
+`dsh --profile <name>` 按该 profile 的 manifest（元数据清单）中 `dsh.profile.bundles` 列表的顺序，在空根之上组合各组合包补丁层，随后依次应用该 profile 自己的 `~/.dsh/profiles/<name>/cordis.patch.yml`、home 级的 `$DSH_HOME/cordis.patch.yml` 与每个 `--patch <path>` overlay。同一行以较后的层为准。应用 flag 并不是另一层 patch：组合包中的普通插件注入 `cmdlineArgs`，再把解析值作为自身服务提供；注入该服务并保留其 `!!js` 读取的行会让本次调用的取值优先。
 
-补丁会替换目标行的整个 `config` 值，而不是深度合并各个键。例如，只用 `config: { thinking: disabled }` 修补 `llm-deepseek`，也会移除该行原有的 `apiKeyEnv` 与 `baseURL`；因此必须重新写出该行需要保留的全部键。
+补丁会替换目标行的整个 `config` 值，而不是深度合并各个键。例如，只用 `config: { thinking: disabled }` 修补 `llm-deepseek`，也会移除该行原有的 `apiKey` 与 `baseURL`；因此必须重新写出该行需要保留的全部键。
 
 ## JavaScript 值和环境变量
 
-Cordis loader 会求值以 `!!js` 标记的运行时表达式，用于非机密的运行时值。仓库内置的 LLM（大语言模型）适配器携带 `apiKeyEnv` 等凭据引用；对应的值应放在环境层或 `$DSH_HOME/.credentials.yaml`，而不是 Cordis 配置中。
+Cordis loader 使用 `!!js` 标签读取运行时表达式。API key 等凭据应放在仓库根目录、已被 Git 忽略的 `.env` 中，不能提交到配置文件。
 
 ```yaml
 config:
+  apiKey: !!js process.env.DEEPSEEK_API_KEY
   cwd: !!js process.cwd()
 ```
 
@@ -64,4 +69,4 @@ config:
 
 ## 精确配置参考
 
-每个插件当前支持的字段、类型和默认值见自动生成的[插件配置目录](../../config-catalog.md)。理解插件如何组合可继续阅读[架构说明](../../architecture.md)和[能力 seam](../../capability-seams.md)；要创建自己的配置，优先复制并修改[示例目录说明](../../../examples/README.md)中最接近的例子。
+每个插件当前支持的字段、类型和默认值见自动生成的[插件配置目录](../../config-catalog.md)。理解插件如何组合可继续阅读[架构说明](../../architecture.md)和[能力接口](../../capability-seams.md)；要创建自己的配置，优先复制并修改[示例目录说明](../../../examples/README.md)中最接近的例子。

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: 6a0b292ce12b32b7993b7de56b35f1df2e7a7153
-quickstart.zh.md: 008245f136e28630c7e8368eeec536e11112a885
+quickstart.md: 8e883efd470fef329a7308f1017cab0b7afcdd67
+quickstart.zh.md: e0e3f4e4754bca588831b6d204f77d1c97a140b3

docs/user/guide/quickstart.md

@@ -36,10 +36,10 @@ DEEPSEEK_API_KEY=sk-your-key-here
 Run a non-interactive task and print its final answer:
 
 ```sh
-pnpm run dsh run "summarize the architecture of this workspace"
+pnpm run dsh --profile headless "summarize the architecture of this workspace"
 ```
 
-`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.
+`dsh --profile headless` 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) 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`.
+`dsh --profile headless` 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

@@ -36,10 +36,10 @@ DEEPSEEK_API_KEY=sk-your-key-here
 运行一个非交互式任务并打印最终回答：
 
 ```sh
-pnpm run dsh run "summarize the architecture of this workspace"
+pnpm run dsh --profile headless "summarize the architecture of this workspace"
 ```
 
-`dsh run` 创建并持久化一个新会话，打印最终助手回答，然后退出。它不会启动 Web 服务器或监听端口；成功运行时 stderr 为空。
+`dsh --profile headless` 创建并持久化一个新会话，打印最终助手回答，然后退出。它不会启动 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-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 模型路由。
+`dsh --profile headless` 启动 `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/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 examples/headless-agent/README.md
-README.md: f12a56920c79f3a7e257c4e56163f323e4312d11
-README.zh.md: 9e409735f03afc62cd788fa2a5d1afdef0fa6c2a
+README.md: 08b36e9c8e558db3b30175b20bd6e0af160ccef5
+README.zh.md: 40d11ebeeb1631af1421b3c013a5e548fd3fd488

examples/headless-agent/README.md

@@ -10,10 +10,10 @@ This directory owns the replay and real-model test composition for a headless co
 # repo root .env (gitignored) or exported env:
 #   DEEPSEEK_API_KEY=sk-…
 #   DEEPSEEK_BASE_URL=https://…   # optional; defaults to the public API
-pnpm run dsh run "fix the failing test in this workspace"
+pnpm run dsh --profile headless "fix the failing test in this workspace"
 ```
 
-The product command is [`dsh run`](../../apps/cli/README.md): it accepts one nonblank task, creates and persists a fresh session, prints the final assistant text, and exits. The root `demo:headless` script is only an alias of that command.
+The product command is [`dsh --profile headless`](../../apps/cli/README.md): it accepts one nonblank task, creates and persists a fresh session, prints the final assistant text, and exits. The root `demo:headless` script is only an alias of that command.
 
 Snapshot suites run this directory's configuration through [`tests/fixtures/headless-driver.ts`](tests/fixtures/headless-driver.ts), an unexported test-only process that emits canonical session events as JSONL before its result record. That stream is test infrastructure, not a supported CLI output format. Child sessions surface only through parent tool events and results.
 

examples/headless-agent/README.zh.md

@@ -10,10 +10,10 @@
 # repo root .env (gitignored) or exported env:
 #   DEEPSEEK_API_KEY=sk-…
 #   DEEPSEEK_BASE_URL=https://…   # optional; defaults to the public API
-pnpm run dsh run "fix the failing test in this workspace"
+pnpm run dsh --profile headless "fix the failing test in this workspace"
 ```
 
-产品命令是 [`dsh run`](../../apps/cli/README.md)：它接受一项非空任务，创建并持久化新会话，打印最终 assistant 文本，然后退出。根目录的 `demo:headless` 脚本只是该命令的别名。
+产品命令是 [`dsh --profile headless`](../../apps/cli/README.md)：它接受一项非空任务，创建并持久化新会话，打印最终 assistant 文本，然后退出。根目录的 `demo:headless` 脚本只是该命令的别名。
 
 快照套件通过 [`tests/fixtures/headless-driver.ts`](tests/fixtures/headless-driver.ts) 运行本目录的配置。这个未导出且仅供测试使用的进程会在结果记录之前，以 JSONL 发出规范会话事件。该事件流属于测试基础设施，不是受支持的 CLI（命令行界面）输出格式。子会话只通过父会话的工具事件和结果对外显示。
 

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

@@ -52,9 +52,9 @@ const dshBinScript = fileURLToPath(new URL('../../../apps/cli/src/bin.ts', impor
 const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
 const reasoningConfigPath = fileURLToPath(new URL('./fixtures/cli.cordis.yml', import.meta.url))
 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 headlessOverlayPath = fileURLToPath(new URL('./fixtures/headless-profile.cordis.yml', import.meta.url))
+const headlessSessionExpected = join(snapshotsDir, 'headless-profile', 'session.expected.jsonl')
+const headlessFailureExpected = join(snapshotsDir, 'headless-profile', 'stderr.expected.txt')
 const cliMockLlmPluginPath = fileURLToPath(new URL('./fixtures/cli-mock-llm.ts', import.meta.url))
 const refreshing = process.env.DSH_SNAPSHOT === 'refresh'
 
@@ -217,14 +217,14 @@ async function prepareCliMockFixture(cwd: string): Promise<void> {
 }
 
 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.'
+  it('runs one task through the product headless profile command', async () => {
+    const task = 'Prove the product headless profile path with one real tool round trip.'
     const result = await runLoaderSmoke({
-      label: 'product dsh run snapshot',
-      tempDirPrefix: 'headless-snapshot-dsh-run-',
+      label: 'product headless profile snapshot',
+      tempDirPrefix: 'headless-snapshot-profile-',
       binScript: dshBinScript,
-      configPath: dshRunOverlayPath,
-      binArgs: ['run', '--patch', dshRunOverlayPath, task],
+      configPath: headlessOverlayPath,
+      binArgs: ['--profile', 'headless', '--patch', headlessOverlayPath, task],
       tsconfigPath,
       env: {
         DSH_PERMISSION_MODE: 'danger-full-access',
@@ -236,11 +236,11 @@ describe('headless stream-json snapshots', () => {
         const logs = await persistedLogs(cwd, join(cwd, '.dsh', 'sessions'))
         expect(logs).toHaveLength(1)
         const actual = logs[0]
-        if (actual === undefined) throw new Error('dsh run did not persist its session')
+        if (actual === undefined) throw new Error('the headless profile did not persist its session')
         const context = contextFromLogs([actual.content])
         const session = scrubRequestHeaders(normalizeSessionLog(actual.content, context))
-        if (refreshing) await writeFile(dshRunSessionExpected, session)
-        expect(session).toBe(await readFile(dshRunSessionExpected, 'utf8'))
+        if (refreshing) await writeFile(headlessSessionExpected, session)
+        expect(session).toBe(await readFile(headlessSessionExpected, 'utf8'))
         expect(session).toContain(task)
         expect(session).toContain('CLI tool round trip complete: CLI_TOOL_ROUND_TRIP')
       },
@@ -250,13 +250,13 @@ describe('headless stream-json snapshots', () => {
     expect(result.stderr).toBe('')
   }, LOADER_SMOKE_TEST_TIMEOUT_MS)
 
-  it('prints a terminal model failure through the product dsh run command', async () => {
+  it('prints a terminal model failure through the product headless profile command', async () => {
     const result = await runLoaderSmoke({
-      label: 'product dsh run model failure snapshot',
-      tempDirPrefix: 'headless-snapshot-dsh-run-failure-',
+      label: 'product headless profile model failure snapshot',
+      tempDirPrefix: 'headless-snapshot-profile-failure-',
       binScript: dshBinScript,
-      configPath: dshRunOverlayPath,
-      binArgs: ['run', '--patch', dshRunOverlayPath, 'Trigger the keyless model failure.'],
+      configPath: headlessOverlayPath,
+      binArgs: ['--profile', 'headless', '--patch', headlessOverlayPath, 'Trigger the keyless model failure.'],
       tsconfigPath,
       expectedExitCode: 1,
       env: {
@@ -268,7 +268,7 @@ describe('headless stream-json snapshots', () => {
     })
 
     expect(result.stdout).toBe('\n')
-    await expect(result.stderr).toMatchFileSnapshot(dshRunFailureExpected)
+    await expect(result.stderr).toMatchFileSnapshot(headlessFailureExpected)
   }, 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 → examples/headless-agent/tests/snapshots/headless-profile/session.expected.jsonl

@@ -2,16 +2,16 @@
 {"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"},"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 headless profile 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"},"role":"user","id":"{{sessionId}}"},"surfaceOp":"append"}
+{"type":"user/message","seq":7,"time":0,"data":{"content":[{"type":"text","text":"Prove the product headless profile 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":"session/title","seq":9,"time":0,"data":{"title":"Prove the product headless profile","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"}}
 {"type":"request/context","seq":11,"time":0,"data":{"provider":"cli-mock","model":"cli-mock"}}
-{"type":"session/title-llm-request","seq":12,"time":0,"data":{"titleProvider":"session-title-first-message-llm","messageSeqs":[7],"route":{"provider":"cli-mock","model":"cli-mock"},"system":"Create a concise title for an AI coding-assistant session from the supplied human messages.\nReturn only the title on one line, **in plain text of natural language**, with no quotes, prefix, explanation, Markdown, XML, or terminal control codes. No code is allowed.\nUse the language of the messages.\nAim for about 5 words in non-CJK languages or 10 CJK characters.","messages":[{"content":[{"type":"text","text":"Generate the session title from this JSON array of human messages:\n[{\"seq\":7,\"text\":\"Prove the product dsh run path with one real tool round trip.\"}]"}],"source":{"kind":"plugin","plugin":"dsh-session-title-llm"},"role":"user","id":"{{sessionId}}"}],"maxTokens":64}}
+{"type":"session/title-llm-request","seq":12,"time":0,"data":{"titleProvider":"session-title-first-message-llm","messageSeqs":[7],"route":{"provider":"cli-mock","model":"cli-mock"},"system":"Create a concise title for an AI coding-assistant session from the supplied human messages.\nReturn only the title on one line, **in plain text of natural language**, with no quotes, prefix, explanation, Markdown, XML, or terminal control codes. No code is allowed.\nUse the language of the messages.\nAim for about 5 words in non-CJK languages or 10 CJK characters.","messages":[{"content":[{"type":"text","text":"Generate the session title from this JSON array of human messages:\n[{\"seq\":7,\"text\":\"Prove the product headless profile path with one real tool round trip.\"}]"}],"source":{"kind":"plugin","plugin":"dsh-session-title-llm"},"role":"user","id":"{{sessionId}}"}],"maxTokens":64}}
 {"type":"assistant/chunk","seq":13,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
 {"type":"assistant/chunk","seq":14,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"cli-smoke-call","name":"bash","argumentsDelta":"{\"command\":\"printf CLI_TOOL_ROUND_TRIP\",\"description\":\"Prove the CLI tool round trip.\"}"}}}
 {"type":"assistant/chunk","seq":15,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"cli-smoke-call","name":"bash","arguments":"{\"command\":\"printf CLI_TOOL_ROUND_TRIP\",\"description\":\"Prove the CLI tool round trip.\"}"}}}}

package.json

@@ -122,7 +122,7 @@
     "hygiene": "pnpm run rescope-vendor:check && pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-package-invariants && pnpm run verify-built-package-invariants && pnpm run verify-cordis-config && pnpm run verify-node-next-types && pnpm run verify-runtime-closure && pnpm run verify-vendored-links",
     "publish:npm-baseline": "tsx scripts/publish-npm-baseline.ts",
     "dsh": "node --import tsx/esm apps/cli/src/bin.ts",
-    "demo:headless": "node --import tsx/esm apps/cli/src/bin.ts run",
+    "demo:headless": "node --import tsx/esm apps/cli/src/bin.ts --profile headless",
     "demo:code-mode": "node scripts/demo-code-mode.mjs",
     "demo:cordis": "node scripts/demo-cordis.mjs",
     "demo:acp": "node --import tsx packages/examples/acp-demo/src/bin.ts --config examples/acp-agent/cordis.yml",

packages/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/README.md
-README.md: 5e4e483b60adab0b22ddb5279f4cd8fb699b9c35
-README.zh.md: 95a3f98129a7d1fdfaffb3cac6fed77bab7cff56
+README.md: 79d653260ea4a9d9a4c71a593b41a6a7e17efa14
+README.zh.md: 839be164328ef168cd6ac18bf2f1dcb930dfce3e

packages/boot/README.md

@@ -7,5 +7,6 @@ The channel-neutral boot library the app bins share: `apps/cli`, the [`scaffold/
 | Package | Role | ctx key |
 |---|---|---|
 | `app-boot/` | Shared boot glue for the app bins: `.env` loading, fail-loud Loader guards, snapshot-aware config resolution, the settle-the-tree boot sequence | (library for the bins) |
+| `cmdline/` | Launcher-to-app command-line handoff and app-owned startup parsing | `cmdlineArgs`, `appExit` |
 
-The boot sequence and personal-config contract are documented in [`app-boot/README.md`](app-boot/README.md).
+The boot sequence and personal-config contract are documented in [`app-boot/README.md`](app-boot/README.md); app-owned command lines are documented in [`cmdline/README.md`](cmdline/README.md).

packages/boot/README.zh.md

@@ -7,5 +7,6 @@
 | 包 | 职责 | ctx 键 |
 |---|---|---|
 | `app-boot/` | app bin 的共享启动粘合层：加载 `.env`、会明确报错的 Loader 保护机制、感知快照的配置解析，以及等待整棵树停稳的启动序列 | （供各 bin 使用的库） |
+| `cmdline/` | 启动器到应用的命令行交接，以及由应用持有的启动解析 | `cmdlineArgs`、`appExit` |
 
-启动序列与个人配置约定见 [`app-boot/README.md`](app-boot/README.md)。
+启动序列与个人配置约定见 [`app-boot/README.md`](app-boot/README.md)；由应用持有的命令行见 [`cmdline/README.md`](cmdline/README.md)。

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: f3ffdae3846edba6f1a1a4821adade7b6c7fce76
-README.zh.md: 4f31fd743f1ddc57edc9c215a42e79a16afcdecb
+README.md: 1d56b2b6d22c08574f8e361955bee1dbe2aca601
+README.zh.md: 5429a1322d0311f03c7c43946753a290e28cd936

packages/boot/app-boot/README.md

@@ -42,7 +42,7 @@ User-level machine-local preferences also live in the Harness home:
 - **`.env`** — the product CLI's ordinary environment layers: the invoking directory's file outranks the Harness-home file, and both sit below the inherited environment. `loadLayeredEnv` snapshots each value's source, rejects [bootstrap-only file variables](../../../.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md#decision) case-insensitively, and materializes accepted values into `process.env` for Loader expressions and third-party libraries. Managed credentials live separately in [`.credentials.yaml`](../../credentials/credentials-local/README.md); a credential left in either `.env` remains a lower-priority fallback.
 - **`cordis.patch.yml`** (home level) and **`profiles/<name>/cordis.patch.yml`** — the user patch layers, applied after every bundle layer (per-profile first, then the home-level file, which therefore outranks it): an id-targeted patch replaces the named entry's whole `config` (restate unchanged fields), `insert` adds entries, and `!!js` expressions interpolate at mount. A patch naming an entry id absent from the composed tree is a stderr warning. An empty or comments-only file throws (it parses to nothing, not to a list); disable the layer with `[]`.
 
-Long-lived surfaces keep `cordis.patch.yml` live through `watchUserPatches`; one-shot runs read only the startup value. The watcher targets the exact path even when the file or immediate parent does not exist, serializes bursts, and recomposes the user patches inside the caller's layer order (bundle layers below, overlay/flag patches above). A rejected read, parse, or Loader candidate leaves the last good tree running and the HMR service broadcasts `hmr/config-update-failed(filename, Error)` after logging it; observer failures are contained. Disposing the context closes the watcher and drains an active refresh.
+Long-lived surfaces keep `cordis.patch.yml` live through `watchUserPatches`; one-shot runs read only the startup value. The watcher targets the exact path even when the file or immediate parent does not exist, serializes bursts, and recomposes the user patches inside the caller's layer order (bundle layers below, overlays above). A rejected read, parse, or Loader candidate leaves the last good tree running and the HMR service broadcasts `hmr/config-update-failed(filename, Error)` after logging it; observer failures are contained. Disposing the context closes the watcher and drains an active refresh.
 
 ## Model Experience
 

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

@@ -42,7 +42,7 @@ profile 是位于 `$DSH_HOME/profiles/<name>` 下的目录（Harness home 由 [`
 - **`.env`**：产品 CLI 的普通环境层；调用目录的文件优先于 Harness home 的文件，两者都低于继承环境。`loadLayeredEnv` 记录每个值的来源，按不区分大小写的方式拒绝 [bootstrap-only 文件变量](../../../.agents/notes/implemented/architecture/2026-08-04-configuration-source-ownership.md#decision)，并把其余值物化进 `process.env`，供 Loader 表达式和第三方库使用。受管凭据另存于 [`.credentials.yaml`](../../credentials/credentials-local/README.md)；留在任一 `.env` 中的凭据仍是低优先级后备值。
 - **`cordis.patch.yml`**（home 级）与 **`profiles/<name>/cordis.patch.yml`**：用户 patch 层，应用在所有组合包层之后（先应用逐 profile 的文件，再应用 home 级文件，因此后者优先级更高）：按 id 定位的 patch 会替换对应条目的整个 `config`（未改字段也要重述），`insert` 会添加条目，`!!js` 表达式则在挂载时插值。如果 patch 指定的条目 id 不在组合后的树中，则输出一条 stderr 警告。空文件或仅含注释的文件会抛出异常（其解析结果为空，而不是列表）；如需禁用该层，请使用 `[]`。
 
-长期运行的界面会持续应用 `cordis.patch.yml` 的变更，具体由 `watchUserPatches` 负责；一次性运行只读取启动时的值。即使该文件或其直接父目录不存在，监视器仍会监视确切路径；它会串行处理突发变更，并按调用方的层次顺序重新组合用户 patch（组合包层在下、overlay／标志 patch 在上）。读取失败、解析失败或 Loader 候选被拒时，最后一个可用树会继续运行；HMR 服务记录错误后广播 `hmr/config-update-failed(filename, Error)`，并隔离观察方的失败。上下文 dispose 时会关闭 watcher，并等待进行中的刷新结束。
+长期运行的界面会持续应用 `cordis.patch.yml` 的变更，具体由 `watchUserPatches` 负责；一次性运行只读取启动时的值。即使该文件或其直接父目录不存在，监视器仍会监视确切路径；它会串行处理突发变更，并按调用方的层次顺序重新组合用户 patch（组合包层在下、overlay 在上）。读取失败、解析失败或 Loader 候选被拒时，最后一个可用树会继续运行；HMR 服务记录错误后广播 `hmr/config-update-failed(filename, Error)`，并隔离观察方的失败。上下文 dispose 时会关闭 watcher，并等待进行中的刷新结束。
 
 ## 模型体验
 

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

@@ -199,7 +199,7 @@ export function loadLayeredEnv(
 const bootstrapIncludes = new WeakMap<Context, Entry>()
 
 // The include's YAML dialect (`!!js` scalars become expression nodes the
-// Loader interpolates against each entry's context at mount time), imported
+// Loader interpolates against each entry's injection-ready context), imported
 // from the include itself so patch parsing and config dumping can never drift
 // from what the include mounts. User patch layers share it so they may
 // reference `process.env`.
@@ -215,7 +215,7 @@ export interface UserPatchWatchOptions {
    * Compose the full patch list for a fresh user-layer generation —
    * the same composition the app booted with, so a reload can interleave the
    * new user patches between app-owned layers (bundle layers below,
-   * overlay/flag patches above). Identity when omitted: the user layer
+   * overlays above). Identity when omitted: the user layer
    * is the whole patch list.
    */
   compose?: (userPatches: PatchOptions[]) => PatchOptions[]

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

@@ -1,4 +1,4 @@
-import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs'
+import { mkdtempSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join, resolve, sep } from 'node:path'
 import { pathToFileURL } from 'node:url'
@@ -699,7 +699,18 @@ describe('boot', () => {
       '}',
       '',
     ].join('\n'))
-    writeFileSync(join(dir, 'cordis.yml'), '- id: exiting\n  name: ./exiting.mjs\n')
+    writeFileSync(join(dir, 'delayed.mjs'), [
+      'await new Promise(resolve => setTimeout(resolve, 10))',
+      'export function apply() {}',
+      '',
+    ].join('\n'))
+    writeFileSync(join(dir, 'cordis.yml'), [
+      '- id: exiting',
+      '  name: ./exiting.mjs',
+      '- id: delayed',
+      '  name: ./delayed.mjs',
+      '',
+    ].join('\n'))
     const ctx = await boot(NAME, join(dir, 'cordis.yml'))
     expect(ctx.get('loader')).toBeUndefined()
   })
@@ -712,6 +723,25 @@ describe('boot', () => {
     )
   })
 
+  it('labels a deferred config failure with its row and leaves the source file unchanged', async () => {
+    const dir = tmp()
+    const configPath = join(dir, 'cordis.yml')
+    const config = [
+      '- id: invalid-config',
+      '  name: ./noop.mjs',
+      '  config:',
+      '    value: !!js "JSON.parse(\'invalid\')"',
+      '',
+    ].join('\n')
+    writeFileSync(join(dir, 'noop.mjs'), 'export function apply() {}\n')
+    writeFileSync(configPath, config)
+
+    await expect(boot(NAME, configPath)).rejects.toThrow(
+      'failed to apply loader entry invalid-config (./noop.mjs)',
+    )
+    expect(readFileSync(configPath, 'utf8')).toBe(config)
+  })
+
   it('appends the deepest cause with its original stack to the load failure', async () => {
     const dir = tmp()
     writeFileSync(join(dir, 'failing.mjs'), [

packages/boot/app-boot/tests/user-patches.spec.ts

@@ -11,6 +11,7 @@ import { pathToFileURL } from 'node:url'
 import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import Hmr from '@deepseek-ai/cordis-plugin-hmr'
+import Include, { type PatchOptions } from '@deepseek-ai/cordis-plugin-include'
 import Loader from '@deepseek-ai/cordis-plugin-loader'
 import Timer from '@deepseek-ai/cordis-plugin-timer'
 import {
@@ -92,23 +93,101 @@ describe('loadOptionalPatches', () => {
   })
 })
 
-describe('boot with user patches', () => {
-  function writeTree(dir: string): string {
-    writeFileSync(join(dir, 'noop.mjs'), [
-      'export const name = "noop"',
-      'export function apply(_ctx, config = {}) {',
-      '  if (config.fail) throw new Error("candidate config failed")',
-      '}',
+function writeTree(dir: string): string {
+  writeFileSync(join(dir, 'noop.mjs'), [
+    'export const name = "noop"',
+    'export function apply(_ctx, config = {}) {',
+    '  if (config.fail) throw new Error("candidate config failed")',
+    '}',
+    '',
+  ].join('\n'))
+  writeFileSync(join(dir, 'cordis.yml'), '- id: noop\n  name: ./noop.mjs\n  config:\n    value: base\n')
+  return join(dir, 'cordis.yml')
+}
+
+function entryConfig(ctx: Context, id: string): unknown {
+  return [...ctx.loader.entries()].find(entry => entry.options.id === id)?.options.config
+}
+
+describe('Loader config interpolation', () => {
+  it("resolves Include's own !!js options", async () => {
+    const dir = tmp()
+    writeFileSync(join(dir, 'noop.mjs'), 'export function apply() {}\n')
+    writeFileSync(join(dir, 'cordis.yml'), '- id: noop\n  name: ./noop.mjs\n')
+    const ctx = new Context()
+    await ctx.plugin(Loader)
+    ctx.loader.builtins.include = Include
+    ctx.provide('includePath', pathToFileURL(join(dir, 'cordis.yml')).href)
+    try {
+      await ctx.loader.create({
+        name: 'cordis:include',
+        config: { path: { __jsExpr: "ctx.get('includePath')" } },
+      })
+      await ctx.loader.await()
+      expect([...ctx.loader.entries()].some(entry => entry.options.id === 'noop')).toBe(true)
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('waits for row injections before resolving !!js and resolves again after provider replacement', async () => {
+    const dir = tmp()
+    writeFileSync(join(dir, 'provider.mjs'), [
+      'export const name = "provider"',
+      'export function apply(ctx, config) { ctx.provide("phaseOne", config) }',
       '',
     ].join('\n'))
-    writeFileSync(join(dir, 'cordis.yml'), '- id: noop\n  name: ./noop.mjs\n  config:\n    value: base\n')
-    return join(dir, 'cordis.yml')
-  }
+    writeFileSync(join(dir, 'reader.mjs'), [
+      'export const name = "reader"',
+      'export const inject = ["phaseOne"]',
+      'export function apply(ctx, config) { ctx.provide("readerResult", config) }',
+      '',
+    ].join('\n'))
+    writeFileSync(join(dir, 'cordis.yml'), '[]\n')
+    const composition: PatchOptions[] = [{
+      insert: [
+        {
+          // Consumer-first order proves interpolation follows injection
+          // readiness rather than YAML position.
+          id: 'reader',
+          name: './reader.mjs',
+          inject: ['phaseOne'],
+          config: { value: { __jsExpr: 'ctx.phaseOne.fail ? (() => { throw new Error("rejected provider") })() : ctx.phaseOne.value' } },
+        },
+        { id: 'provider', name: './provider.mjs', config: { value: 'first' } },
+      ],
+    }]
+    const ctx = await boot(NAME, join(dir, 'cordis.yml'), composition)
+    try {
+      expect(ctx.get('readerResult')).toEqual({ value: 'first' })
+      const provider = [...ctx.loader.entries()].find(entry => entry.options.id === 'provider')
+      expect(provider).toBeDefined()
+      await provider?.update({ disabled: true })
+      await ctx.loader.await()
+      expect(ctx.get('readerResult')).toBeUndefined()
+      await provider?.update({ config: { value: 'second' } })
+      await provider?.update({ disabled: false })
+      await ctx.loader.await()
+      expect(ctx.get('readerResult')).toEqual({ value: 'second' })
 
-  function entryConfig(ctx: Context, id: string): unknown {
-    return [...ctx.loader.entries()].find(entry => entry.options.id === id)?.options.config
-  }
+      await provider?.update({ disabled: true })
+      await provider?.update({ config: { fail: true } })
+      await provider?.update({ disabled: false })
+      await expect(ctx.loader.await()).rejects.toThrow('rejected provider')
+      expect(ctx.get('readerResult')).toBeUndefined()
+
+      await provider?.update({ disabled: true })
+      await provider?.update({ config: { value: 'recovered' } })
+      await provider?.update({ disabled: false })
+      await ctx.loader.await()
+      expect(ctx.get('readerResult')).toEqual({ value: 'recovered' })
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+})
 
+describe('boot with user patches', () => {
   it('applies id-targeted overrides, inserts, and interpolates !!js from the environment', async () => {
     const dir = tmp()
     const userDir = tmp()

packages/boot/cmdline/README.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 packages/boot/cmdline/README.md
+README.md: 98335e901bdf8fe33e14c1ad4c1a320d77f30c96
+README.zh.md: 28ea749943c60089c6b4725cb61e121f82aa0114

packages/boot/cmdline/README.md

@@ -0,0 +1,74 @@
+# `@deepseek-ai/dsh-cmdline`
+
+English | [中文](README.zh.md)
+
+The command line a dsh launcher hands to the app it boots. The launcher parses only its own flags (`--profile`, `--patch`, the config dumps) and hands **everything after them** to the tree verbatim, so an app owns its flag family, its `--help` text, and its parse errors instead of the launcher knowing them.
+
+## The launcher values
+
+A launcher calls `provideCmdline(ctx, host)` before any tree entry mounts, which provides:
+
+- `ctx.cmdlineArgs` — the invocation's inner arguments. `get()` is the whole interface, and it returns a snapshot: `dsh --profile tui --resume abc` yields `['--resume', 'abc']`.
+- `ctx.appExit` — a bounded process-exit request, wired to the launcher's shutdown controller.
+
+An embedding host with no command line provides an empty list; that is the honest answer, not a missing value.
+
+## Ordinary providers and injected config
+
+Any app plugin may inject `cmdlineArgs`, parse it, and publish an ordinary app-owned service. `parseCmdline(ctx, program, plan)` is only a commander adapter; the caller owns the returned value and service:
+
+```ts ignore
+export const name = 'web-startup'
+export const inject = ['cmdlineArgs']
+
+export function apply(ctx: Context): void {
+  const values = parseCmdline(ctx, webCommand(), planWebStartup)
+  if (values !== undefined) ctx.provide('webStartup', values)
+}
+```
+
+Its Loader row carries no launcher marker or special kind:
+
+```yaml
+- id: web-startup
+  name: '@deepseek-ai/dsh-web-app/startup'
+```
+
+Every row configured from those values uses ordinary service injection and direct lazy config access:
+
+```yaml
+- id: webserver
+  name: '@deepseek-ai/dsh-host-webserver'
+  inject: [webStartup]
+  config:
+    host: !!js ctx.webStartup.host ?? '127.0.0.1'
+    port: !!js ctx.webStartup.port ?? 3080
+```
+
+`parseCmdline` parses the immutable arguments and asks `plan` for the app-owned value. On `--help`, `--version`, a parse error, or a `program.error(...)` from the plan, it writes commander's text, requests exit, and returns `undefined`; the provider publishes nothing, so dependent rows never activate.
+
+### How injection orders config
+
+Loader defers a row's `!!js` interpolation until that row's declared injections are active, then evaluates against the row's plugin context. The example above can therefore read `ctx.webStartup` directly: Cordis has already populated that injected service before Loader asks for `webserver`'s config. Include trees preserve nested expression nodes until each target row reaches this point. Provider replacement and live patch reload repeat interpolation against the current injected services, so a launch flag cannot be silently reset.
+
+`enableRow(ctx, id)` turns on a row a bundle ships disabled because only some invocations want it (`dsh web --dev` and its client-plugin reload chain). The activation is an in-memory override: it does not rewrite the row's configured `disabled` value and survives config reapplication for that mounted entry. Loader applies the enabled row's ordinary injection ordering.
+
+### Shared immutable arguments
+
+`get()` does not consume or mutate argv. Multiple plugins can parse the same snapshot and independently provide services. The launcher does not inspect the composition for a command-line owner; a profile with no reader simply ignores its app arguments.
+
+An out-of-tree plugin brings its own commander copy, so commander's control-flow errors are detected structurally rather than by class identity; an identity check would rethrow a printed help as a fatal load failure.
+
+## Model Experience
+
+None, as this package resolves the process's own command line before any session exists.
+
+#### KV Cache effect
+
+None; this package neither assembles nor sends a provider request.
+
+## Known Limitations and Deferred Work
+
+- **Launcher flags must precede app arguments.** The split is positional: the first token the launcher does not recognize starts the inner arguments, so `--patch` placed after an app flag belongs to the app. The launcher's parser consumes one `--`, so an app argument that must survive as a literal `--` needs `-- --`.
+- **An app-owned service has no statically declared provider.** Consumer rows name it through ordinary injection; a bundle that omits its provider fails at settlement with pending entries naming the service rather than at load.
+- **A user patch that replaces a row's whole `config` drops its expressions.** A flag beats the value written beside it, not a literal a user wrote in place of the expression; keeping the expression is what keeps the flag winning.

packages/boot/cmdline/README.zh.md

@@ -0,0 +1,74 @@
+# `@deepseek-ai/dsh-cmdline`
+
+[English](README.md) | 中文
+
+dsh 启动器交给它所引导应用的那条命令行。启动器只解析属于自己的 flag（`--profile`、`--patch`、配置 dump），并把**其后的一切**原样交给配置树，因此 flag 家族、`--help` 文本和解析错误都由应用自己持有，启动器不必知道它们。
+
+## 启动器提供的值
+
+启动器在任何配置树条目挂载之前调用 `provideCmdline(ctx, host)`，它提供：
+
+- `ctx.cmdlineArgs`：本次调用的内层参数。`get()` 就是它的全部接口，返回一份快照：`dsh --profile tui --resume abc` 得到 `['--resume', 'abc']`。
+- `ctx.appExit`：一个有边界的进程退出请求，接到启动器的关停控制器上。
+
+没有命令行的嵌入宿主提供空列表；这是诚实的答案，而不是缺失的值。
+
+## 普通提供方与注入配置
+
+任何应用插件都可以注入 `cmdlineArgs`、解析它，再发布一个普通的应用自有服务。`parseCmdline(ctx, program, plan)` 只适配 commander；返回值与服务都归调用方持有：
+
+```ts ignore
+export const name = 'web-startup'
+export const inject = ['cmdlineArgs']
+
+export function apply(ctx: Context): void {
+  const values = parseCmdline(ctx, webCommand(), planWebStartup)
+  if (values !== undefined) ctx.provide('webStartup', values)
+}
+```
+
+它的 Loader 行不携带启动器标记，也没有特殊类型：
+
+```yaml
+- id: web-startup
+  name: '@deepseek-ai/dsh-web-app/startup'
+```
+
+所有由这些取值配置的行都使用普通服务注入，并在惰性配置中直接访问该服务：
+
+```yaml
+- id: webserver
+  name: '@deepseek-ai/dsh-host-webserver'
+  inject: [webStartup]
+  config:
+    host: !!js ctx.webStartup.host ?? '127.0.0.1'
+    port: !!js ctx.webStartup.port ?? 3080
+```
+
+`parseCmdline` 解析不可变参数，再向 `plan` 索取应用自有取值。遇到 `--help`、`--version`、解析错误，或 `plan` 发出的 `program.error(...)` 时，它输出 commander 文本、请求退出并返回 `undefined`；提供方什么也不发布，因此依赖行不会激活。
+
+### 注入如何排列配置求值
+
+Loader 会把一行的 `!!js` 插值推迟到该行声明的注入全部激活之后，再基于该行的插件上下文求值。所以上例可以直接读取 `ctx.webStartup`：Loader 索取 `webserver` 的配置之前，Cordis 已经填入了这个注入服务。Include 树会保留嵌套表达式节点，直到各个目标行到达这一时点。提供方替换与活动 patch 重载都会针对当前注入服务重新插值，因此启动 flag 不会被悄悄重置。
+
+`enableRow(ctx, id)` 打开某个组合包以禁用状态交付、只有部分调用才需要的行（`dsh web --dev` 及其客户端插件重载链路）。该激活是内存中的覆盖：它不会改写行所配置的 `disabled` 值，并会在已挂载条目的配置重新应用后继续生效。Loader 会对启用后的行应用普通的注入顺序。
+
+### 共享不可变参数
+
+`get()` 不会消费或修改 argv。多个插件可以解析同一份快照，并分别提供服务。启动器不会检查组合中的命令行所有者；没有读取方的 profile 只会忽略自己的应用参数。
+
+树外插件会带来自己的一份 commander 副本，因此 commander 的控制流错误按结构识别，而不是按类身份识别；按身份判断会把已经打印出来的 help 重新抛成致命的加载失败。
+
+## 模型体验
+
+无。本包在任何会话存在之前解析进程自身的命令行。
+
+#### KV Cache 影响
+
+无；本包既不组装也不发送提供方请求。
+
+## 已知限制与延期工作
+
+- **启动器的 flag 必须写在应用参数之前**：切分按位置进行，启动器不认识的第一个 token 就是内层参数的起点，因此写在某个应用 flag 之后的 `--patch` 属于应用。启动器的解析器会消耗掉一个 `--`，因此必须以字面量 `--` 存活到应用的参数需要写成 `-- --`。
+- **应用自有服务没有静态声明的提供方**：消费行通过普通注入点名它；缺少提供方的组合包会在结算时失败，由待处理条目点名该服务，而不是在加载时失败。
+- **用户 patch 若整体替换某行的 `config`，会连同其中的表达式一起丢掉**：flag 胜过的是表达式旁写着的那个值，而不是用户用字面量替换掉表达式之后的结果；保留表达式才能保留 flag 的优先级。

packages/boot/cmdline/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@deepseek-ai/dsh-cmdline",
+  "description": "Immutable command-line handoff from a dsh launcher to any app plugin that injects cmdlineArgs",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./invariant": {
+      "types": "./lib/types/invariant.d.ts",
+      "default": "./lib/invariant.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/invariant.js",
+    "lib/types/**/*.d.ts"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.0-rc.5",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/cordis": "^4.0.0-rc.7"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis-plugin-include": "workspace:^",
+    "@deepseek-ai/cordis-plugin-loader": "workspace:^",
+    "commander": "^15.0.0",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/cordis": "^4.0.0-rc.7"
+  }
+}

packages/boot/cmdline/src/index.ts

@@ -0,0 +1,174 @@
+/**
+ * @deepseek-ai/dsh-cmdline — the command line a dsh launcher hands to the app
+ * it boots.
+ *
+ * The launcher parses only its own flags (`--profile`, `--patch`, the config
+ * dumps) and hands everything after them to the tree verbatim through the
+ * {@link CmdlineArgs} service, so an app owns its flag family, its `--help`
+ * text, and its parse errors instead of the launcher knowing them.
+ *
+ * Any app plugin can inject `cmdlineArgs` and call {@link parseCmdline}. A
+ * provider may publish the parsed values as its own service, and ordinary rows
+ * can inject that service and read it from lazily resolved config —
+ * `port: !!js ctx.webStartup.port ?? 3080` — so a flag beats the value written
+ * beside it. No row has launcher-level command-line status.
+ * @module @deepseek-ai/dsh-cmdline
+ */
+
+import type { Command } from 'commander'
+import type { Context } from '@deepseek-ai/cordis'
+// Empty type import carries the Loader Context merge used by enableRow.
+import type {} from '@deepseek-ai/cordis-plugin-loader'
+
+/**
+ * The invocation's inner arguments: everything after the launcher's own flags,
+ * verbatim and in argv order. `dsh --profile tui --resume abc` yields
+ * `['--resume', 'abc']`.
+ */
+export interface CmdlineArgs {
+  /**
+   * Read the inner arguments.
+   * @returns the arguments in argv order; empty when the invocation carried none.
+   */
+  get(): readonly string[]
+}
+
+/** Request bounded process exit; the launcher wires it to its shutdown controller. */
+export interface AppExit {
+  /**
+   * Request exit once the tree has been disposed.
+   * @param code - the process exit code.
+   */
+  (code: number): void
+}
+
+declare module '@deepseek-ai/cordis' {
+  interface Context {
+    /** The invocation's inner arguments; provided by a launcher before the tree mounts. */
+    cmdlineArgs?: CmdlineArgs
+    /** Bounded process-exit request; provided by a launcher before the tree mounts. */
+    appExit?: AppExit
+  }
+}
+
+/** The launcher facts an app needs. */
+export interface CmdlineHost {
+  /** The invocation's inner arguments, in argv order. */
+  args: readonly string[]
+  /** Bounded process-exit request. */
+  exit: AppExit
+}
+
+/**
+ * Provide the command line and the exit request on a host context before any
+ * tree entry mounts. Both are launcher facts, not config: an embedding host
+ * with no command line provides an empty argument list.
+ * @param ctx - the host context the tree will mount under.
+ * @param host - the invocation's arguments and its exit request.
+ */
+export function provideCmdline(ctx: Context, host: CmdlineHost): void {
+  const snapshot: readonly string[] = Object.freeze([...host.args])
+  ctx.provide('cmdlineArgs', { get: () => snapshot })
+  ctx.provide('appExit', host.exit)
+}
+
+/** The process streams commander output is written to; production writes to the process. */
+export const internals: { stdout: { write(chunk: string): unknown }; stderr: { write(chunk: string): unknown } } = {
+  stdout: process.stdout,
+  stderr: process.stderr,
+}
+
+/**
+ * Resolve parsed arguments into an app-owned value. Call
+ * `program.error(...)` to reject the invocation with a usage message instead
+ * of throwing.
+ * @param program - the parsed commander program.
+ * @param ctx - the plugin context that received the command line.
+ * @returns the value an ordinary provider plugin may publish.
+ */
+export type CmdlinePlan<T = unknown> = (program: Command, ctx: Context) => T
+
+/**
+ * Parse the launcher's immutable argument snapshot with an app's commander
+ * program. The caller decides whether and how to publish the returned value;
+ * this helper has no Loader-row or service ownership semantics.
+ *
+ * Help, version, and rejected arguments are terminal for the process: commander
+ * writes the text, the helper requests `ctx.appExit`, and it returns
+ * `undefined` so the caller publishes nothing.
+ * @param ctx - plugin context carrying `cmdlineArgs` and `appExit`.
+ * @param program - the app's commander program, with its flags and description already declared.
+ * @param plan - this invocation's resolved value; omitted returns an empty object.
+ * @returns the resolved value, or `undefined` when the app asked to exit.
+ * @throws when the launcher did not provide the command line and exit request.
+ */
+export function parseCmdline<T>(
+  ctx: Context,
+  program: Command,
+  plan: CmdlinePlan<T> = (() => ({}) as T),
+): T | undefined {
+  // Read through the global service store, not the property proxy: appExit is
+  // an optional host value and the plugin only needs to inject cmdlineArgs.
+  const args = ctx.get('cmdlineArgs')
+  const exit = ctx.get('appExit')
+  if (args === undefined || exit === undefined) {
+    throw new Error(`${program.name()}: the launcher must provide ctx.cmdlineArgs and ctx.appExit before the tree mounts`)
+  }
+  program
+    .exitOverride()
+    .configureOutput({
+      writeOut: text => void internals.stdout.write(text),
+      writeErr: text => void internals.stderr.write(text),
+    })
+  try {
+    program.parse(args.get(), { from: 'user' })
+    return plan(program, ctx)
+  } catch (error) {
+    // exitOverride turns help, version, a parse error, and a plan's own
+    // program.error() into a CommanderError; commander has already written the
+    // text through the output configured above.
+    if (!isCommanderError(error)) throw error
+    exit(error.exitCode)
+    return undefined
+  }
+}
+
+/**
+ * Turn on a row this composition ships disabled, because this invocation asked
+ * for it (`dsh web --dev` and its client-plugin reload chain).
+ *
+ * A row cannot be inserted from inside a mounting plugin — the Loader returns a
+ * prefixed id it then fails to resolve — so a conditional row ships disabled
+ * and a row mounted beside it enables it after startup resolves the invocation.
+ * The Loader keeps that activation in memory, separate from serialized options,
+ * so reapplying the composition cannot restore the invocation's row to disabled.
+ * @param ctx - plugin context whose Loader tree carries the row.
+ * @param id - the row id.
+ * @returns nothing once the row has started or is waiting for its dependencies.
+ * @throws when the Loader or named row is absent.
+ */
+export async function enableRow(ctx: Context, id: string): Promise<void> {
+  const loader = ctx.get('loader')
+  if (loader === undefined) throw new Error('dsh-cmdline: enabling a row requires the Loader service')
+  const entry = [...loader.entries()].find(candidate => candidate.options.id === id)
+  if (entry === undefined) throw new Error(`dsh-cmdline: the composition has no ${JSON.stringify(id)} row to enable`)
+  await entry.enableRuntime()
+}
+
+/**
+ * Whether a thrown value is commander's own control-flow error (help, version,
+ * a parse error, or `program.error`).
+ *
+ * Detected structurally, not with `instanceof`: an out-of-tree plugin brings
+ * its own commander copy, whose `CommanderError` class is a different identity
+ * from this package's, and an identity check there would rethrow a printed
+ * help as a fatal load failure.
+ * @param error - the thrown value.
+ * @returns true when the value carries commander's error code and exit code.
+ */
+function isCommanderError(error: unknown): error is { code: string; exitCode: number } {
+  if (typeof error !== 'object' || error === null) return false
+  const candidate = error as { code?: unknown; exitCode?: unknown }
+  return typeof candidate.code === 'string' && candidate.code.startsWith('commander.')
+    && typeof candidate.exitCode === 'number'
+}

packages/boot/cmdline/src/invariant.ts

@@ -0,0 +1,30 @@
+/**
+ * Package-owned invariant companion for `@deepseek-ai/dsh-cmdline`.
+ * @module @deepseek-ai/dsh-cmdline/invariant
+ */
+
+import type { Context } from '@deepseek-ai/cordis'
+import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
+
+const PACKAGE_NAME = '@deepseek-ai/dsh-cmdline'
+
+/** Cordis companion plugin name. */
+export const name = 'cmdline-invariant'
+/** Service required before the companion can register. */
+export const inject = ['invariants']
+
+/**
+ * No runtime invariant: `cmdlineArgs` is an immutable launcher fact that any
+ * number of ordinary plugins may read. App-owned providers and consumers use
+ * normal Cordis service injection, whose missing dependencies are already
+ * reported by Loader settlement.
+ */
+const install: InvariantInstaller = () => {}
+
+/**
+ * Register this package's invariant companion.
+ * @param ctx - Cordis context carrying the invariant service.
+ * @returns the installed registration's disposer after setup succeeds.
+ */
+export const apply = (ctx: Context): Promise<() => void> =>
+  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))

packages/boot/cmdline/tests/cmdline.spec.ts

@@ -0,0 +1,265 @@
+/**
+ * The launcher-to-app command line over a REAL Loader tree, mounted the way a
+ * profile boot mounts it: Loader holds each row until its injections are
+ * active, then resolves that row's config against its injection-ready context.
+ */
+
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { pathToFileURL } from 'node:url'
+import { Command } from 'commander'
+import { Context } from '@deepseek-ai/cordis'
+import Loader from '@deepseek-ai/cordis-plugin-loader'
+import Include from '@deepseek-ai/cordis-plugin-include'
+import type { PatchOptions } from '@deepseek-ai/cordis-plugin-include'
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+  enableRow, internals, parseCmdline, provideCmdline, type CmdlinePlan,
+} from '../src/index.ts'
+
+/** Every value one boot of the fixture tree observed. */
+interface Observed {
+  /** Config the reading row started with; absent means it never started. */
+  started?: Record<string, unknown>
+  exits: number[]
+  out: string
+}
+
+/** A booted fixture tree: what it observed, and its root for direct parser calls. */
+interface Fixture {
+  observed: Observed
+  ctx: Context
+}
+
+const disposers: (() => Promise<void>)[] = []
+
+afterEach(async () => {
+  for (const dispose of disposers.splice(0)) await dispose()
+  internals.stdout = process.stdout
+  internals.stderr = process.stderr
+})
+
+/** The fixture app's flag family: one `--port` its rows read from the service. */
+function demoCommand(): Command {
+  return new Command().name('demo').exitOverride().option('--port <port>', 'listen port')
+}
+
+/** The fixture app's plan: the resolved values its rows read. */
+const demoPlan: CmdlinePlan<{ port?: number }> = (program) => {
+  const port = program.opts<{ port?: string }>().port
+  if (port === undefined) return {}
+  if (!/^\d+$/.test(port)) program.error(`error: --port must be a number, got ${JSON.stringify(port)}`)
+  return { port: Number(port) }
+}
+
+/** A YAML `!!js` expression node, as the include parses one out of a patch file. */
+const expression = (source: string): unknown => ({ __jsExpr: source })
+
+/**
+ * Mount a two-row composition the way a profile boot does: both rows at once,
+ * with Loader ordering config resolution from their injections.
+ * @param args - the invocation's inner arguments.
+ * @param plan - the app's plan; defaults to the fixture's own.
+ * @returns the booted fixture.
+ */
+async function bootFixture(
+  args: string[],
+  plan: CmdlinePlan = demoPlan,
+  options: { objectInject?: boolean; withoutProvider?: boolean } = {},
+): Promise<Fixture> {
+  const dir = mkdtempSync(join(tmpdir(), 'dsh-cmdline-'))
+  const observed: Observed = { exits: [], out: '' }
+  writeFileSync(join(dir, 'reader.mjs'), `
+export const name = 'reader'
+export const inject = ['demoStartup']
+export function apply(ctx, config) { globalThis.__observed.started = config }
+`)
+  // The Loader imports a row through Node's own resolver, which cannot resolve
+  // this workspace's sources; the row delegates to the real function the test
+  // imported through the source-plane path mapping.
+  writeFileSync(join(dir, 'startup.mjs'), `
+export const name = 'demo-startup'
+export const inject = ['cmdlineArgs']
+export function apply(ctx) { return globalThis.__provideDemoArgs(ctx) }
+`)
+  writeFileSync(join(dir, 'cordis.yml'), '[]\n')
+  const observing = { write: (chunk: string) => { observed.out += chunk; return true } }
+  internals.stdout = observing
+  internals.stderr = observing
+  const globals = globalThis as unknown as { __observed: Observed; __provideDemoArgs: (ctx: Context) => void }
+  globals.__observed = observed
+  globals.__provideDemoArgs = (ctx: Context) => {
+    const values = parseCmdline(ctx, demoCommand(), plan)
+    if (values !== undefined) ctx.provide('demoStartup', values)
+  }
+
+  // The composition, exactly as a profile delivers one: include patches whose
+  // config carries `!!js` expressions.
+  const composition: PatchOptions[] = [{
+    insert: [
+      ...options.withoutProvider === true
+        ? []
+        : [{ id: 'demo-startup', name: pathToFileURL(join(dir, 'startup.mjs')).href }],
+      {
+        id: 'reader',
+        name: pathToFileURL(join(dir, 'reader.mjs')).href,
+        inject: options.objectInject === true ? { demoStartup: { required: true } } : ['demoStartup'],
+        config: { port: expression('ctx.demoStartup.port ?? 3080') },
+      },
+    ],
+  }]
+  const ctx = new Context()
+  await ctx.plugin(Loader)
+  ctx.loader.builtins.include = Include
+  provideCmdline(ctx, { args, exit: code => void observed.exits.push(code) })
+  await ctx.loader.create({
+    name: 'cordis:include',
+    config: { path: pathToFileURL(join(dir, 'cordis.yml')).href, patches: structuredClone(composition) },
+  })
+  await ctx.loader.await()
+  disposers.push(async () => { await ctx.fiber.dispose() })
+  return { observed, ctx }
+}
+
+describe('parseCmdline', () => {
+  it('lets a row read the flag value the app resolved', async () => {
+    const { observed } = await bootFixture(['--port', '8080'])
+    expect(observed.started).toEqual({ port: 8080 })
+    expect(observed.exits).toEqual([])
+  })
+
+  it('leaves a row on the value written beside the expression when no flag names one', async () => {
+    const { observed } = await bootFixture([])
+    expect(observed.started).toEqual({ port: 3080 })
+  })
+
+  it('recognizes the Loader object form of a provider-service injection', async () => {
+    const { observed } = await bootFixture(['--port', '8080'], demoPlan, { objectInject: true })
+    expect(observed.started).toEqual({ port: 8080 })
+  })
+
+  it('prints the app help, starts no reading row, and requests exit 0', async () => {
+    const { observed } = await bootFixture(['--help'])
+    expect(observed.out).toContain('Usage: demo')
+    expect(observed.started).toBeUndefined()
+    expect(observed.exits).toEqual([0])
+  })
+
+  it('rejects the invocation from the plan without starting the app', async () => {
+    const { observed } = await bootFixture(['--port', 'abc'])
+    expect(observed.out).toContain('--port must be a number')
+    expect(observed.started).toBeUndefined()
+    expect(observed.exits).toEqual([1])
+  })
+
+  it('rethrows a plan failure that is not commander asking to exit', async () => {
+    const { ctx } = await bootFixture([], demoPlan, { withoutProvider: true })
+    const plan: CmdlinePlan = () => { throw new Error('plan exploded') }
+    expect(() => { parseCmdline(ctx, demoCommand(), plan) }).toThrow('plan exploded')
+  })
+
+  it('rethrows a thrown value that is not an object at all', async () => {
+    const { ctx } = await bootFixture([], demoPlan, { withoutProvider: true })
+    const plan: CmdlinePlan = () => {
+      const thrown: unknown = 'plan threw a string'
+      throw thrown
+    }
+    expect(() => { parseCmdline(ctx, demoCommand(), plan) }).toThrow('plan threw a string')
+  })
+
+  it('returns values without inspecting Loader rows or owning a service', async () => {
+    const { ctx } = await bootFixture([], demoPlan, { withoutProvider: true })
+    expect(parseCmdline(ctx, demoCommand())).toEqual({})
+    expect(ctx.get('demoStartup')).toBeUndefined()
+  })
+})
+
+describe('enableRow', () => {
+  it('enables the named Loader row and fails loud when the Loader or row is absent', async () => {
+    const withoutLoader = new Context()
+    await expect(enableRow(withoutLoader, 'client-hmr')).rejects.toThrow('requires the Loader service')
+
+    const ctx = new Context()
+    let enabled = false
+    ctx.provide('loader', {
+      entries: () => [{
+        options: { id: 'client-hmr' },
+        enableRuntime: async () => { enabled = true },
+      }],
+    } as never)
+    await enableRow(ctx, 'client-hmr')
+    expect(enabled).toBe(true)
+    await expect(enableRow(ctx, 'absent')).rejects.toThrow('no "absent" row to enable')
+  })
+
+  it('keeps invocation-only activation through config reapplication', async () => {
+    const dir = mkdtempSync(join(tmpdir(), 'dsh-runtime-enable-'))
+    const observed = { starts: 0, stops: 0 }
+    ;(globalThis as unknown as { __runtimeEnableObserved: typeof observed }).__runtimeEnableObserved = observed
+    writeFileSync(join(dir, 'conditional.mjs'), `
+export function apply(ctx) {
+  globalThis.__runtimeEnableObserved.starts += 1
+  ctx.effect(() => () => { globalThis.__runtimeEnableObserved.stops += 1 })
+}
+`)
+    writeFileSync(join(dir, 'cordis.yml'), [
+      '- id: conditional',
+      `  name: ${pathToFileURL(join(dir, 'conditional.mjs')).href}`,
+      '  disabled: true',
+      '',
+    ].join('\n'))
+
+    const ctx = new Context()
+    await ctx.plugin(Loader)
+    ctx.loader.builtins.include = Include
+    await ctx.loader.create({
+      name: 'cordis:include',
+      config: { path: pathToFileURL(join(dir, 'cordis.yml')).href },
+    })
+    await ctx.loader.await()
+    const conditional = [...ctx.loader.entries()].find(entry => entry.options.id === 'conditional')
+    const include = [...ctx.loader.entries()].find(entry => entry.options.name === 'cordis:include')
+    expect(conditional).toBeDefined()
+    expect(include?.fiber).toBeDefined()
+    expect(conditional?.options.disabled).toBe(true)
+    expect(observed).toEqual({ starts: 0, stops: 0 })
+
+    await enableRow(ctx, 'conditional')
+    await ctx.loader.await()
+    expect(conditional?.disabled).toBe(false)
+    expect(conditional?.options.disabled).toBe(true)
+    expect(observed).toEqual({ starts: 1, stops: 0 })
+
+    await include!.fiber!.update(include!.options.config, true)
+    await ctx.loader.await()
+    expect(conditional?.disabled).toBe(false)
+    expect(conditional?.options.disabled).toBe(true)
+    expect(observed).toEqual({ starts: 1, stops: 0 })
+    disposers.push(async () => { await ctx.fiber.dispose() })
+  })
+})
+
+describe('provideCmdline', () => {
+  it('hands the app a snapshot the caller cannot mutate afterwards', () => {
+    const ctx = new Context()
+    const args = ['--resume', 'abc']
+    provideCmdline(ctx, { args, exit: () => {} })
+    args.push('--tampered')
+    expect(ctx.cmdlineArgs?.get()).toEqual(['--resume', 'abc'])
+  })
+
+  it('fails loud when a parser runs without the launcher values', () => {
+    const ctx = new Context()
+    expect(() => { parseCmdline(ctx, demoCommand()) })
+      .toThrow('the launcher must provide ctx.cmdlineArgs and ctx.appExit')
+  })
+
+  it('lets multiple parsers read the same immutable snapshot', () => {
+    const ctx = new Context()
+    provideCmdline(ctx, { args: ['--port', '8080'], exit: () => {} })
+    expect(parseCmdline(ctx, demoCommand(), demoPlan)).toEqual({ port: 8080 })
+    expect(parseCmdline(ctx, demoCommand(), demoPlan)).toEqual({ port: 8080 })
+    expect(Object.isFrozen(ctx.cmdlineArgs?.get())).toBe(true)
+  })
+})

packages/boot/cmdline/tsconfig.json

@@ -0,0 +1,24 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/include"
+    },
+    {
+      "path": "../../../vendor/loader"
+    },
+    {
+      "path": "../../support/invariants"
+    }
+  ]
+}

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: f8b76b77f2beb22f501a49f0fc4cf5cd72223765
-README.zh.md: aae8ab5bea663b8909de942f72615f5ef9b16c84
+README.md: 31a4894dbb191d2244371ca7272339e96e253053
+README.zh.md: 6e8d28f10071fbab175c4f14f1aaa9618b8f598a