Add files using upload-large-folder tool

apps/cli/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 apps/cli/README.md
+README.md: cfab7a4983c31a21b68157c9cefb38c1654571ff
+README.zh.md: 67d07fba1fc27bca9c2a696daddde88aac3aa39c

apps/cli/README.md

@@ -0,0 +1,58 @@
+# `@deepseek-ai/dsh`
+
+English | [中文](README.zh.md)
+
+The `dsh` command is the sole supported Node application launcher: profiles are ordered stacks of plugin-bundle patch layers under the user's own overrides. SDK and ACP are profiles, not separate public bins. The Python runtime wheel packages this same command; the SDK defaults to `sdk`, and the minimal example selects `sdk-minimal`. [`src/args.ts`](src/args.ts) owns the command grammar, and [`src/bin.ts`](src/bin.ts) loads only the selected runner. Invalid commands, options from another mode, and fatal configuration or boot failures exit nonzero.
+
+## Entry modes
+
+| Command | Purpose |
+|---|---|
+| `dsh --profile <name>` | Boot the named profile under `$DSH_HOME/profiles/<name>`. |
+| `dsh --profile <name> --from-default-profile <template>` | Create a new custom profile from a shipped template, then boot it. |
+| `dsh --profile acp` | Serve automation clients over ACP stdio until disconnect. |
+| `dsh --profile headless "job"` | Run one fresh persisted session, print the final answer, and exit. |
+| `dsh --profile sdk` | Serve SDK clients over JSON-RPC stdio until shutdown or disconnect. |
+| `dsh --profile sdk-minimal` | Serve SDK clients with the standalone minimal agent tree. |
+| `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. The `web`, `headless`, `sdk`, `sdk-minimal`, and `acp` profiles auto-initialize on first use from shipped templates. Create another profile at an unused, non-shipped name with `--from-default-profile`, or initialize a base-backed profile through `dsh plugin`. The `desktop` name is reserved for the Electron-owned profile, so the CLI rejects boot, config-dump, and plugin-management requests for it.
+
+## 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)). 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>     # example, assuming the tui profile is installed; --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
+```
+
+<a id="profiles"></a>
+## 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 `patchReload` lifecycle) and a `cordis.patch.yml` (the user's own patch layer). `patchReload: live` watches the profile and home-level patch files; `startup` applies them once.
+
+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`, `@deepseek-ai/dsh-sdk-app`, `@deepseek-ai/dsh-sdk-minimal`, `@deepseek-ai/dsh-acp-app`), 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 source execution. The [startup and reload failure table](../../packages/boot/app-boot/README.md#startup-and-reload-failures) compares optional and required plugin failures with configuration HMR.
+
+## Optional overlays
+
+`config/examples/` ships opt-in overlays for GitHub review webhooks, session-local Schedule, memory MCP servers, and runtime Cordis tools. They are never part of a default profile; the [user guides](../../docs/user/guide/index.md) and [developer practice guides](../../docs/user/develop/practice/index.md) own setup and safety instructions.
+
+## Development
+
+Production runs require built package and frontend artifacts. From the repository root, run `pnpm run build` separately, then use `pnpm dsh <args...>` to run the TypeScript entry and forward every argument; the [source-execution reference](reference/README.md#source-execution) owns the module-resolution contract.
+
+The [Web failure matrix](tests/profiles/web/tests/web-failure-matrix.expected.e2e.ts) runs the built CLI through startup failures and native configuration HMR with `awaitWriteFinish` enabled in `test:expected`. It verifies authenticated HTTP responses, diagnostics, recovery, process exits, and disposal without model API calls; the [startup acceptance](tests/profiles/web/tests/web-best-effort-startup.expected.e2e.ts) also covers the shipped required Web dependencies and port conflicts.

apps/cli/README.zh.md

@@ -0,0 +1,58 @@
+# `@deepseek-ai/dsh`
+
+[English](README.md) | 中文
+
+`dsh` 是唯一受支持的 Node 应用启动器；profile 由多个插件组合包 patch 层按顺序叠加而成，其上再应用用户自己的覆盖配置。SDK 与 ACP（Agent Client Protocol）都是 profile，而不是独立的公开可执行命令。Python 运行时 wheel 包中也包含同一个命令；SDK 默认使用 `sdk`，极简示例选择 `sdk-minimal`。[`src/args.ts`](src/args.ts) 负责命令语法，[`src/bin.ts`](src/bin.ts) 只加载选中的运行器。无效命令、来自其他模式的选项，以及致命的配置或启动错误都会以非零状态退出。
+
+## 入口模式
+
+| 命令 | 用途 |
+|---|---|
+| `dsh --profile <name>` | 启动位于 `$DSH_HOME/profiles/<name>` 的指定 profile。 |
+| `dsh --profile <name> --from-default-profile <template>` | 从随附模板创建新的自定义 profile，然后启动它。 |
+| `dsh --profile acp` | 通过 ACP stdio 为自动化客户端提供服务，直至断开连接。 |
+| `dsh --profile headless "job"` | 运行一个全新的持久化会话，打印最终答案并退出。 |
+| `dsh --profile sdk` | 通过 JSON-RPC stdio 为 SDK 客户端提供服务，直至关闭或断开连接。 |
+| `dsh --profile sdk-minimal` | 以独立极简 agent（智能体）配置树为 SDK 客户端提供服务。 |
+| `dsh web` | `--profile web` 的别名。 |
+| `dsh plugin --profile <name> <pnpm args>` | 通过在 profile 目录中转发给 pnpm 来管理该 profile 的插件。 |
+
+运行命令时所在的目录将作为默认 workspace 根目录。`web`、`headless`、`sdk`、`sdk-minimal` 和 `acp` profile 在首次使用时会从随附模板自动初始化。使用 `--from-default-profile` 可以基于这些模板之一，在尚未使用的非内置名称处创建其他 profile；通过 `dsh plugin` 则可以初始化一个以 base 为基础的 profile。`desktop` 名称保留给 Electron 持有的 profile，因此 CLI（命令行界面）会拒绝针对它的启动、配置 dump 和插件管理请求。
+
+## 应用参数
+
+启动器只解析自身的 flag，并将其后的所有内容交给已启动的 profile；注入该 profile 的任意应用插件都可以解析这份共享的不可变快照（[`dsh-cmdline`](../../packages/boot/cmdline/README.zh.md)）。启动器无法识别的第一个 token 标志着应用参数的开始：
+
+```sh
+dsh --profile web --port 8080       # --port belongs to the web app
+dsh --profile tui --resume <id>     # example, assuming the tui profile is installed; --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
+```
+
+<a id="profiles"></a>
+## Profile
+
+profile 目录包含一个 `package.json`，其中记录树外插件依赖，以及 profile manifest（元数据清单）`dsh.profile`、其中按顺序排列的 `bundles` 列表与 `patchReload` 生命周期；还包含一个 `cordis.patch.yml`，其中保存用户自己的 patch 层。`patchReload: live` 监视 profile 与 home 级 patch 文件，`startup` 则只应用一次。
+
+配置树以空根为起点，依次叠加以下配置层：
+- `dsh.profile.bundles` 中各组合包的 patch
+- profile 自身的 `cordis.patch.yml`，然后是 home 级的 `$DSH_HOME/cordis.patch.yml`
+- `--patch` 指定的覆盖层
+
+`dsh.profile.bundles` 中列出的组合包先从 dsh 安装目录解析（`@deepseek-ai/dsh-base`、`@deepseek-ai/dsh-web-app`、`@deepseek-ai/dsh-headless`、`@deepseek-ai/dsh-sdk-app`、`@deepseek-ai/dsh-sdk-minimal`、`@deepseek-ai/dsh-acp-app`），再从 profile 自身的 `node_modules` 解析；pnpm 会将树外插件安装到该目录。
+
+使用 `--dump-default-config` 和 `--dump-config` 可在不启动的情况下检查组合后的配置树。
+
+层的确切优先级、flag、关闭行为、部署默认值和源码执行方式，以 [CLI 行为参考](reference/README.zh.md)为准。[启动与重载失败表](../../packages/boot/app-boot/README.zh.md#startup-and-reload-failures)对比 optional、required 插件启动失败与配置 HMR 的行为。
+
+## 可选覆盖层
+
+`config/examples/` 交付 GitHub 评审 webhook、会话内 Schedule、记忆 MCP 服务器与运行时 Cordis 工具的可选覆盖层。它们绝不属于默认 profile；设置与安全说明由[用户指南](../../docs/user/guide/index.zh.md)和[开发实战指南](../../docs/user/develop/practice/index.zh.md)负责。
+
+## 开发
+
+生产运行需要已构建的包与前端产物。请在仓库根目录单独运行 `pnpm run build`，然后使用 `pnpm dsh <args...>` 运行 TypeScript 入口并转发所有参数；模块解析约定以[源码执行参考](reference/README.zh.md#source-execution)为准。
+
+[Web 失败矩阵](tests/profiles/web/tests/web-failure-matrix.expected.e2e.ts)在 `test:expected` 中通过构建后的 CLI 验证启动失败与启用 `awaitWriteFinish` 的原生配置 HMR。它不调用模型 API，��是检查经过认证的 HTTP 响应、诊断、恢复、进程退出与 dispose；[启动验收测试](tests/profiles/web/tests/web-best-effort-startup.expected.e2e.ts)还覆盖随附 Web 的必需依赖与端口冲突。

apps/cli/composition.md

@@ -0,0 +1,279 @@
+<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
+     Run `pnpm run gen-doc-graphs` to regenerate. -->
+
+# DSH Base Composition
+
+The dsh-base bundle patch shared by the web, headless, sdk, and acp profiles; their mode bundles and user layers patch over it, while sdk-minimal owns a separate standalone tree.
+
+```mermaid
+flowchart LR
+  cfg["packages/bundle/base/cordis.patch.yml<br/>cordis.yml"]
+  plugin_dsh_base_timer["timer<br/>@deepseek-ai/cordis-plugin-timer"]
+  cfg --> plugin_dsh_base_timer
+  plugin_dsh_base_hmr["hmr<br/>@deepseek-ai/cordis-plugin-hmr"]
+  cfg --> plugin_dsh_base_hmr
+  plugin_dsh_base_llm["llm<br/>@deepseek-ai/dsh-llm"]
+  cfg --> plugin_dsh_base_llm
+  plugin_dsh_base_deepseek_llm_api_extensions["deepseek-llm-api-extensions<br/>@deepseek-ai/dsh-deepseek-llm-api-extensions"]
+  cfg --> plugin_dsh_base_deepseek_llm_api_extensions
+  plugin_dsh_base_session["session<br/>@deepseek-ai/dsh-session"]
+  cfg --> plugin_dsh_base_session
+  plugin_dsh_base_session_log_deepseek["session-log-deepseek<br/>@deepseek-ai/dsh-session-log-deepseek"]
+  cfg --> plugin_dsh_base_session_log_deepseek
+  plugin_dsh_base_typert["typert<br/>@deepseek-ai/dsh-typert-registry"]
+  cfg --> plugin_dsh_base_typert
+  plugin_dsh_base_typert_loader["typert-loader<br/>@deepseek-ai/dsh-typert-loader"]
+  cfg --> plugin_dsh_base_typert_loader
+  plugin_dsh_base_typert_gateway["typert-gateway<br/>@deepseek-ai/dsh-api-gateway"]
+  cfg --> plugin_dsh_base_typert_gateway
+  plugin_dsh_base_session_title["session-title<br/>@deepseek-ai/dsh-session-title"]
+  cfg --> plugin_dsh_base_session_title
+  plugin_dsh_base_session_title_llm["session-title-llm<br/>@deepseek-ai/dsh-session-title-first-prompt-llm"]
+  cfg --> plugin_dsh_base_session_title_llm
+  plugin_dsh_base_user_questions["user-questions<br/>@deepseek-ai/dsh-user-questions"]
+  cfg --> plugin_dsh_base_user_questions
+  plugin_dsh_base_agent["agent<br/>@deepseek-ai/dsh-agent"]
+  cfg --> plugin_dsh_base_agent
+  plugin_dsh_base_plugin_package_inventory_deepseek["plugin-package-inventory-deepseek<br/>@deepseek-ai/dsh-plugin-package-inventory-deepseek"]
+  cfg --> plugin_dsh_base_plugin_package_inventory_deepseek
+  plugin_dsh_base_agent_default_model["agent-default-model<br/>@deepseek-ai/dsh-agent-default-model"]
+  cfg --> plugin_dsh_base_agent_default_model
+  plugin_dsh_base_jobs["jobs<br/>@deepseek-ai/dsh-jobs-local"]
+  cfg --> plugin_dsh_base_jobs
+  plugin_dsh_base_llm_retry["llm-retry<br/>@deepseek-ai/dsh-llm-retry"]
+  cfg --> plugin_dsh_base_llm_retry
+  plugin_dsh_base_settings["settings<br/>@deepseek-ai/dsh-settings-file"]
+  cfg --> plugin_dsh_base_settings
+  plugin_dsh_base_credentials["credentials<br/>@deepseek-ai/dsh-credentials-local"]
+  cfg --> plugin_dsh_base_credentials
+  plugin_dsh_base_llm_pi_ai["llm-pi-ai<br/>@deepseek-ai/dsh-llm-pi-ai"]
+  cfg --> plugin_dsh_base_llm_pi_ai
+  plugin_dsh_base_session_persistence_jsonl["session-persistence-jsonl<br/>@deepseek-ai/dsh-session-persistence-jsonl"]
+  cfg --> plugin_dsh_base_session_persistence_jsonl
+  plugin_dsh_base_attachment_local["attachment-local<br/>@deepseek-ai/dsh-attachment-local"]
+  cfg --> plugin_dsh_base_attachment_local
+  plugin_dsh_base_session_query_sqlite["session-query-sqlite<br/>@deepseek-ai/dsh-session-query-sqlite"]
+  cfg --> plugin_dsh_base_session_query_sqlite
+  plugin_dsh_base_session_projection["session-projection<br/>@deepseek-ai/dsh-session-projection"]
+  cfg --> plugin_dsh_base_session_projection
+  plugin_dsh_base_storage["storage<br/>@deepseek-ai/dsh-storage"]
+  cfg --> plugin_dsh_base_storage
+  plugin_dsh_base_storage_json["storage-json<br/>@deepseek-ai/dsh-storage-json"]
+  cfg --> plugin_dsh_base_storage_json
+  plugin_dsh_base_storage_domain["storage-domain<br/>@deepseek-ai/dsh-storage-domain"]
+  cfg --> plugin_dsh_base_storage_domain
+  plugin_dsh_base_session_projection_cache["session-projection-cache<br/>@deepseek-ai/dsh-session-projection-cache"]
+  cfg --> plugin_dsh_base_session_projection_cache
+  plugin_dsh_base_session_telemetry_otel["session-telemetry-otel<br/>@deepseek-ai/dsh-session-telemetry-otel"]
+  cfg --> plugin_dsh_base_session_telemetry_otel
+  plugin_dsh_base_subprocess["subprocess<br/>@deepseek-ai/dsh-subprocess-local"]
+  cfg --> plugin_dsh_base_subprocess
+  plugin_dsh_base_sandbox["sandbox<br/>@deepseek-ai/dsh-sandbox-local"]
+  cfg --> plugin_dsh_base_sandbox
+  plugin_dsh_base_sandbox_policy["sandbox-policy<br/>@deepseek-ai/dsh-sandbox-policy"]
+  cfg --> plugin_dsh_base_sandbox_policy
+  plugin_dsh_base_bash_sandbox["bash-sandbox<br/>@deepseek-ai/dsh-bash-sandbox"]
+  cfg --> plugin_dsh_base_bash_sandbox
+  plugin_dsh_base_pwsh_sandbox["pwsh-sandbox<br/>@deepseek-ai/dsh-pwsh-sandbox"]
+  cfg --> plugin_dsh_base_pwsh_sandbox
+  plugin_dsh_base_approval["approval<br/>@deepseek-ai/dsh-user-approval"]
+  cfg --> plugin_dsh_base_approval
+  plugin_dsh_base_permission["permission<br/>@deepseek-ai/dsh-permission-presets"]
+  cfg --> plugin_dsh_base_permission
+  plugin_dsh_base_shell_env["shell-env<br/>@deepseek-ai/dsh-shell-env"]
+  cfg --> plugin_dsh_base_shell_env
+  plugin_dsh_base_tool_bash["tool-bash<br/>@deepseek-ai/dsh-tool-bash"]
+  cfg --> plugin_dsh_base_tool_bash
+  plugin_dsh_base_tool_pwsh["tool-pwsh<br/>@deepseek-ai/dsh-tool-pwsh"]
+  cfg --> plugin_dsh_base_tool_pwsh
+  plugin_dsh_base_tool_jobs["tool-jobs<br/>@deepseek-ai/dsh-tool-jobs"]
+  cfg --> plugin_dsh_base_tool_jobs
+  plugin_dsh_base_fs_observation_policy["fs-observation-policy<br/>@deepseek-ai/dsh-fs-observation-policy"]
+  cfg --> plugin_dsh_base_fs_observation_policy
+  plugin_dsh_base_tool_fs["tool-fs<br/>@deepseek-ai/dsh-tool-fs"]
+  cfg --> plugin_dsh_base_tool_fs
+  plugin_dsh_base_tool_fs_search["tool-fs-search<br/>@deepseek-ai/dsh-tool-fs-search"]
+  cfg --> plugin_dsh_base_tool_fs_search
+  plugin_dsh_base_agent_instructions["agent-instructions<br/>@deepseek-ai/dsh-agent-instructions"]
+  cfg --> plugin_dsh_base_agent_instructions
+  plugin_dsh_base_skill["skill<br/>@deepseek-ai/dsh-skill"]
+  cfg --> plugin_dsh_base_skill
+  plugin_dsh_base_skill_filesystem["skill-filesystem<br/>@deepseek-ai/dsh-skill-filesystem"]
+  cfg --> plugin_dsh_base_skill_filesystem
+  plugin_dsh_base_skill_badge["skill-badge<br/>@deepseek-ai/dsh-skill-badge"]
+  cfg --> plugin_dsh_base_skill_badge
+  plugin_dsh_base_tool_skill["tool-skill<br/>@deepseek-ai/dsh-tool-skill"]
+  cfg --> plugin_dsh_base_tool_skill
+  plugin_dsh_base_commands["commands<br/>@deepseek-ai/dsh-commands"]
+  cfg --> plugin_dsh_base_commands
+  plugin_dsh_base_command_feedback["command-feedback<br/>@deepseek-ai/dsh-command-feedback"]
+  cfg --> plugin_dsh_base_command_feedback
+  plugin_dsh_base_goal["goal<br/>@deepseek-ai/dsh-goal"]
+  cfg --> plugin_dsh_base_goal
+  plugin_dsh_base_goal_round_driver["goal-round-driver<br/>@deepseek-ai/dsh-goal-round-driver"]
+  cfg --> plugin_dsh_base_goal_round_driver
+  plugin_dsh_base_command_goal["command-goal<br/>@deepseek-ai/dsh-command-goal"]
+  cfg --> plugin_dsh_base_command_goal
+  plugin_dsh_base_plan_mode["plan-mode<br/>@deepseek-ai/dsh-plan-mode"]
+  cfg --> plugin_dsh_base_plan_mode
+  plugin_dsh_base_token_meter["token-meter<br/>@deepseek-ai/dsh-token-meter"]
+  cfg --> plugin_dsh_base_token_meter
+  plugin_dsh_base_compaction_basic["compaction-basic<br/>@deepseek-ai/dsh-compaction-basic"]
+  cfg --> plugin_dsh_base_compaction_basic
+  plugin_dsh_base_command_compact["command-compact<br/>@deepseek-ai/dsh-command-compact"]
+  cfg --> plugin_dsh_base_command_compact
+  plugin_dsh_base_subagent["subagent<br/>@deepseek-ai/dsh-subagent"]
+  cfg --> plugin_dsh_base_subagent
+  plugin_dsh_base_subagent_spawn_in_process["subagent-spawn-in-process<br/>@deepseek-ai/dsh-subagent-spawn-in-process"]
+  cfg --> plugin_dsh_base_subagent_spawn_in_process
+  plugin_dsh_base_subagent_fork_in_process["subagent-fork-in-process<br/>@deepseek-ai/dsh-subagent-fork-in-process"]
+  cfg --> plugin_dsh_base_subagent_fork_in_process
+  plugin_dsh_base_tool_subagent_control["tool-subagent-control<br/>@deepseek-ai/dsh-tool-subagent-control"]
+  cfg --> plugin_dsh_base_tool_subagent_control
+  plugin_dsh_base_tool_subagent_list_agents["tool-subagent-list-agents<br/>@deepseek-ai/dsh-tool-subagent-control/list-agents"]
+  cfg --> plugin_dsh_base_tool_subagent_list_agents
+  plugin_dsh_base_tool_subagent["tool-subagent<br/>@deepseek-ai/dsh-tool-subagent"]
+  cfg --> plugin_dsh_base_tool_subagent
+  plugin_dsh_base_tool_subagent_fork["tool-subagent-fork<br/>@deepseek-ai/dsh-tool-subagent"]
+  cfg --> plugin_dsh_base_tool_subagent_fork
+  plugin_dsh_base_ptc_runtime["ptc-runtime<br/>@deepseek-ai/dsh-ptc-runtime-node"]
+  cfg --> plugin_dsh_base_ptc_runtime
+  plugin_dsh_base_workflow_ptc["workflow-ptc<br/>@deepseek-ai/dsh-workflow-ptc"]
+  cfg --> plugin_dsh_base_workflow_ptc
+  plugin_dsh_base_tool_workflow["tool-workflow<br/>@deepseek-ai/dsh-tool-workflow"]
+  cfg --> plugin_dsh_base_tool_workflow
+  plugin_dsh_base_timeout_policy["timeout-policy<br/>@deepseek-ai/dsh-tool-call-timeout-policy"]
+  cfg --> plugin_dsh_base_timeout_policy
+  plugin_dsh_base_spill_local["spill-local<br/>@deepseek-ai/dsh-spill-local"]
+  cfg --> plugin_dsh_base_spill_local
+  plugin_dsh_base_spill_policy["spill-policy<br/>@deepseek-ai/dsh-spill-policy"]
+  cfg --> plugin_dsh_base_spill_policy
+  plugin_dsh_base_session_checkpoint_policy["session-checkpoint-policy<br/>@deepseek-ai/dsh-session-checkpoint-policy"]
+  cfg --> plugin_dsh_base_session_checkpoint_policy
+  plugin_dsh_base_tool_result_pruner["tool-result-pruner<br/>@deepseek-ai/dsh-compaction-tool-result-pruner"]
+  cfg --> plugin_dsh_base_tool_result_pruner
+  plugin_dsh_base_image_offload["image-offload<br/>@deepseek-ai/dsh-compaction-image-offload"]
+  cfg --> plugin_dsh_base_image_offload
+  plugin_dsh_base_tool_todo["tool-todo<br/>@deepseek-ai/dsh-tool-todo"]
+  cfg --> plugin_dsh_base_tool_todo
+  plugin_dsh_base_tool_goal["tool-goal<br/>@deepseek-ai/dsh-tool-goal"]
+  cfg --> plugin_dsh_base_tool_goal
+  plugin_dsh_base_tool_ralph["tool-ralph<br/>@deepseek-ai/dsh-tool-ralph"]
+  cfg --> plugin_dsh_base_tool_ralph
+  plugin_dsh_base_repeat_tool_reminder["repeat-tool-reminder<br/>@deepseek-ai/dsh-repeat-tool-reminder"]
+  cfg --> plugin_dsh_base_repeat_tool_reminder
+  plugin_dsh_base_web["web<br/>@deepseek-ai/dsh-web"]
+  cfg --> plugin_dsh_base_web
+  plugin_dsh_base_web_search_deepseek["web-search-deepseek<br/>@deepseek-ai/dsh-web-search-deepseek"]
+  cfg --> plugin_dsh_base_web_search_deepseek
+  plugin_dsh_base_web_fetch_http["web-fetch-http<br/>@deepseek-ai/dsh-web-fetch-http"]
+  cfg --> plugin_dsh_base_web_fetch_http
+  plugin_dsh_base_tool_web["tool-web<br/>@deepseek-ai/dsh-tool-web"]
+  cfg --> plugin_dsh_base_tool_web
+  plugin_dsh_base_mcp_resources["mcp-resources<br/>@deepseek-ai/dsh-mcp-resources"]
+  cfg --> plugin_dsh_base_mcp_resources
+  plugin_dsh_base_tools["tools<br/>@deepseek-ai/dsh-tools"]
+  cfg --> plugin_dsh_base_tools
+  plugin_dsh_base_system_prompt["system-prompt<br/>@deepseek-ai/dsh-system-prompt"]
+  cfg --> plugin_dsh_base_system_prompt
+  plugin_dsh_base_agent_loop["agent-loop<br/>@deepseek-ai/dsh-agent-loop"]
+  cfg --> plugin_dsh_base_agent_loop
+  plugin_dsh_base_fs_sandbox["fs-sandbox<br/>@deepseek-ai/dsh-fs-sandbox"]
+  cfg --> plugin_dsh_base_fs_sandbox
+  plugin_dsh_base_llm_deepseek["llm-deepseek<br/>@deepseek-ai/dsh-llm-deepseek"]
+  cfg --> plugin_dsh_base_llm_deepseek
+```
+
+| Plugin id | Package / module |
+| --- | --- |
+| `timer` | `@deepseek-ai/cordis-plugin-timer` |
+| `hmr` | `@deepseek-ai/cordis-plugin-hmr` |
+| `llm` | `@deepseek-ai/dsh-llm` |
+| `deepseek-llm-api-extensions` | `@deepseek-ai/dsh-deepseek-llm-api-extensions` |
+| `session` | `@deepseek-ai/dsh-session` |
+| `session-log-deepseek` | `@deepseek-ai/dsh-session-log-deepseek` |
+| `typert` | `@deepseek-ai/dsh-typert-registry` |
+| `typert-loader` | `@deepseek-ai/dsh-typert-loader` |
+| `typert-gateway` | `@deepseek-ai/dsh-api-gateway` |
+| `session-title` | `@deepseek-ai/dsh-session-title` |
+| `session-title-llm` | `@deepseek-ai/dsh-session-title-first-prompt-llm` |
+| `user-questions` | `@deepseek-ai/dsh-user-questions` |
+| `agent` | `@deepseek-ai/dsh-agent` |
+| `plugin-package-inventory-deepseek` | `@deepseek-ai/dsh-plugin-package-inventory-deepseek` |
+| `agent-default-model` | `@deepseek-ai/dsh-agent-default-model` |
+| `jobs` | `@deepseek-ai/dsh-jobs-local` |
+| `llm-retry` | `@deepseek-ai/dsh-llm-retry` |
+| `settings` | `@deepseek-ai/dsh-settings-file` |
+| `credentials` | `@deepseek-ai/dsh-credentials-local` |
+| `llm-pi-ai` | `@deepseek-ai/dsh-llm-pi-ai` |
+| `session-persistence-jsonl` | `@deepseek-ai/dsh-session-persistence-jsonl` |
+| `attachment-local` | `@deepseek-ai/dsh-attachment-local` |
+| `session-query-sqlite` | `@deepseek-ai/dsh-session-query-sqlite` |
+| `session-projection` | `@deepseek-ai/dsh-session-projection` |
+| `storage` | `@deepseek-ai/dsh-storage` |
+| `storage-json` | `@deepseek-ai/dsh-storage-json` |
+| `storage-domain` | `@deepseek-ai/dsh-storage-domain` |
+| `session-projection-cache` | `@deepseek-ai/dsh-session-projection-cache` |
+| `session-telemetry-otel` | `@deepseek-ai/dsh-session-telemetry-otel` |
+| `subprocess` | `@deepseek-ai/dsh-subprocess-local` |
+| `sandbox` | `@deepseek-ai/dsh-sandbox-local` |
+| `sandbox-policy` | `@deepseek-ai/dsh-sandbox-policy` |
+| `bash-sandbox` | `@deepseek-ai/dsh-bash-sandbox` |
+| `pwsh-sandbox` | `@deepseek-ai/dsh-pwsh-sandbox` |
+| `approval` | `@deepseek-ai/dsh-user-approval` |
+| `permission` | `@deepseek-ai/dsh-permission-presets` |
+| `shell-env` | `@deepseek-ai/dsh-shell-env` |
+| `tool-bash` | `@deepseek-ai/dsh-tool-bash` |
+| `tool-pwsh` | `@deepseek-ai/dsh-tool-pwsh` |
+| `tool-jobs` | `@deepseek-ai/dsh-tool-jobs` |
+| `fs-observation-policy` | `@deepseek-ai/dsh-fs-observation-policy` |
+| `tool-fs` | `@deepseek-ai/dsh-tool-fs` |
+| `tool-fs-search` | `@deepseek-ai/dsh-tool-fs-search` |
+| `agent-instructions` | `@deepseek-ai/dsh-agent-instructions` |
+| `skill` | `@deepseek-ai/dsh-skill` |
+| `skill-filesystem` | `@deepseek-ai/dsh-skill-filesystem` |
+| `skill-badge` | `@deepseek-ai/dsh-skill-badge` |
+| `tool-skill` | `@deepseek-ai/dsh-tool-skill` |
+| `commands` | `@deepseek-ai/dsh-commands` |
+| `command-feedback` | `@deepseek-ai/dsh-command-feedback` |
+| `goal` | `@deepseek-ai/dsh-goal` |
+| `goal-round-driver` | `@deepseek-ai/dsh-goal-round-driver` |
+| `command-goal` | `@deepseek-ai/dsh-command-goal` |
+| `plan-mode` | `@deepseek-ai/dsh-plan-mode` |
+| `token-meter` | `@deepseek-ai/dsh-token-meter` |
+| `compaction-basic` | `@deepseek-ai/dsh-compaction-basic` |
+| `command-compact` | `@deepseek-ai/dsh-command-compact` |
+| `subagent` | `@deepseek-ai/dsh-subagent` |
+| `subagent-spawn-in-process` | `@deepseek-ai/dsh-subagent-spawn-in-process` |
+| `subagent-fork-in-process` | `@deepseek-ai/dsh-subagent-fork-in-process` |
+| `tool-subagent-control` | `@deepseek-ai/dsh-tool-subagent-control` |
+| `tool-subagent-list-agents` | `@deepseek-ai/dsh-tool-subagent-control/list-agents` |
+| `tool-subagent` | `@deepseek-ai/dsh-tool-subagent` |
+| `tool-subagent-fork` | `@deepseek-ai/dsh-tool-subagent` |
+| `ptc-runtime` | `@deepseek-ai/dsh-ptc-runtime-node` |
+| `workflow-ptc` | `@deepseek-ai/dsh-workflow-ptc` |
+| `tool-workflow` | `@deepseek-ai/dsh-tool-workflow` |
+| `timeout-policy` | `@deepseek-ai/dsh-tool-call-timeout-policy` |
+| `spill-local` | `@deepseek-ai/dsh-spill-local` |
+| `spill-policy` | `@deepseek-ai/dsh-spill-policy` |
+| `session-checkpoint-policy` | `@deepseek-ai/dsh-session-checkpoint-policy` |
+| `tool-result-pruner` | `@deepseek-ai/dsh-compaction-tool-result-pruner` |
+| `image-offload` | `@deepseek-ai/dsh-compaction-image-offload` |
+| `tool-todo` | `@deepseek-ai/dsh-tool-todo` |
+| `tool-goal` | `@deepseek-ai/dsh-tool-goal` |
+| `tool-ralph` | `@deepseek-ai/dsh-tool-ralph` |
+| `repeat-tool-reminder` | `@deepseek-ai/dsh-repeat-tool-reminder` |
+| `web` | `@deepseek-ai/dsh-web` |
+| `web-search-deepseek` | `@deepseek-ai/dsh-web-search-deepseek` |
+| `web-fetch-http` | `@deepseek-ai/dsh-web-fetch-http` |
+| `tool-web` | `@deepseek-ai/dsh-tool-web` |
+| `mcp-resources` | `@deepseek-ai/dsh-mcp-resources` |
+| `tools` | `@deepseek-ai/dsh-tools` |
+| `system-prompt` | `@deepseek-ai/dsh-system-prompt` |
+| `agent-loop` | `@deepseek-ai/dsh-agent-loop` |
+| `fs-sandbox` | `@deepseek-ai/dsh-fs-sandbox` |
+| `llm-deepseek` | `@deepseek-ai/dsh-llm-deepseek` |
+
+Source config: [`packages/bundle/base/cordis.patch.yml`](../../packages/bundle/base/cordis.patch.yml).
+
+Maintenance mode: hybrid: the patch row list is parsed from its `cordis.yml`; app package expansion is curated from package source.

apps/cli/package.json

@@ -0,0 +1,152 @@
+{
+  "name": "@deepseek-ai/dsh",
+  "description": "dsh CLI: profile boot, plugin management, and the browser UI alias",
+  "version": "0.1.6-alpha.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "apps/cli"
+  },
+  "type": "module",
+  "bin": {
+    "dsh": "lib/bin.js"
+  },
+  "files": [
+    "lib/*.js"
+  ],
+  "dsh": {
+    "configTrees": [
+      {
+        "mount": "config/agent-presets",
+        "path": "../../packages/preset/agent-presets/presets",
+        "scanRoster": true
+      }
+    ]
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@deepseek-ai/cordis": "workspace:^",
+    "@deepseek-ai/cordis-plugin-hmr": "workspace:^",
+    "@deepseek-ai/cordis-plugin-include": "workspace:^",
+    "@deepseek-ai/cordis-plugin-loader": "workspace:^",
+    "@deepseek-ai/cordis-plugin-timer": "workspace:^",
+    "@deepseek-ai/dsh-acp-app": "workspace:^",
+    "@deepseek-ai/dsh-agent-instructions": "workspace:^",
+    "@deepseek-ai/dsh-agent-tool-presentation": "workspace:^",
+    "@deepseek-ai/dsh-app-boot": "workspace:^",
+    "@deepseek-ai/dsh-base": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-agent-preset": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-cordis": "workspace:^",
+    "@deepseek-ai/dsh-cmdline": "workspace:^",
+    "@deepseek-ai/dsh-command-compact": "workspace:^",
+    "@deepseek-ai/dsh-command-goal": "workspace:^",
+    "@deepseek-ai/dsh-compaction-basic": "workspace:^",
+    "@deepseek-ai/dsh-compaction-tool-result-pruner": "workspace:^",
+    "@deepseek-ai/dsh-cordis-client-runner": "workspace:^",
+    "@deepseek-ai/dsh-fs-local": "workspace:^",
+    "@deepseek-ai/dsh-goal": "workspace:^",
+    "@deepseek-ai/dsh-goal-round-driver": "workspace:^",
+    "@deepseek-ai/dsh-headless": "workspace:^",
+    "@deepseek-ai/dsh-home-paths": "workspace:^",
+    "@deepseek-ai/dsh-hooks-claude-code": "workspace:^",
+    "@deepseek-ai/dsh-hooks-codex": "workspace:^",
+    "@deepseek-ai/dsh-jobs-local": "workspace:^",
+    "@deepseek-ai/dsh-launch-environment": "workspace:^",
+    "@deepseek-ai/dsh-mcp-client": "workspace:^",
+    "@deepseek-ai/dsh-persona": "workspace:^",
+    "@deepseek-ai/dsh-plan-mode": "workspace:^",
+    "@deepseek-ai/dsh-pwsh-local": "workspace:^",
+    "@deepseek-ai/dsh-pwsh-sandbox": "workspace:^",
+    "@deepseek-ai/dsh-schedule": "workspace:^",
+    "@deepseek-ai/dsh-sdk-app": "workspace:^",
+    "@deepseek-ai/dsh-sdk-minimal": "workspace:^",
+    "@deepseek-ai/dsh-session-projection": "workspace:^",
+    "@deepseek-ai/dsh-session-reference": "workspace:^",
+    "@deepseek-ai/dsh-skill": "workspace:^",
+    "@deepseek-ai/dsh-skill-filesystem": "workspace:^",
+    "@deepseek-ai/dsh-terminal": "workspace:^",
+    "@deepseek-ai/dsh-terminal-bash": "workspace:^",
+    "@deepseek-ai/dsh-time-context": "workspace:^",
+    "@deepseek-ai/dsh-tmux-context": "workspace:^",
+    "@deepseek-ai/dsh-token-meter": "workspace:^",
+    "@deepseek-ai/dsh-tool-ask-user": "workspace:^",
+    "@deepseek-ai/dsh-tool-bash": "workspace:^",
+    "@deepseek-ai/dsh-tool-bash-persistent": "workspace:^",
+    "@deepseek-ai/dsh-tool-cordis": "workspace:^",
+    "@deepseek-ai/dsh-tool-present": "workspace:^",
+    "@deepseek-ai/dsh-tool-fs": "workspace:^",
+    "@deepseek-ai/dsh-tool-fs-search": "workspace:^",
+    "@deepseek-ai/dsh-tool-goal": "workspace:^",
+    "@deepseek-ai/dsh-tool-jobs": "workspace:^",
+    "@deepseek-ai/dsh-tool-pwsh": "workspace:^",
+    "@deepseek-ai/dsh-tool-pwsh-persistent": "workspace:^",
+    "@deepseek-ai/dsh-tool-ralph": "workspace:^",
+    "@deepseek-ai/dsh-tool-skill": "workspace:^",
+    "@deepseek-ai/dsh-tool-str-replace-editor": "workspace:^",
+    "@deepseek-ai/dsh-tool-subagent": "workspace:^",
+    "@deepseek-ai/dsh-tool-subagent-control": "workspace:^",
+    "@deepseek-ai/dsh-tool-todo": "workspace:^",
+    "@deepseek-ai/dsh-tool-web": "workspace:^",
+    "@deepseek-ai/dsh-tool-workflow": "workspace:^",
+    "@deepseek-ai/dsh-web-app": "workspace:^",
+    "@deepseek-ai/dsh-webhook": "workspace:^",
+    "@deepseek-ai/dsh-webhook-github": "workspace:^",
+    "@deepseek-ai/dsh-workflow-ptc": "workspace:^",
+    "@deepseek-ai/schemastery": "workspace:^",
+    "commander": "^15.0.0",
+    "js-yaml": "^4.2.0",
+    "node-addon-require-builtin": "^0.1.6",
+    "@deepseek-ai/dsh-http-proxy": "workspace:^",
+    "@deepseek-ai/dsh-mcp-resources": "workspace:^"
+  },
+  "devDependencies": {
+    "@agentclientprotocol/sdk": "1.4.0",
+    "@deepseek-ai/dsh-acp": "workspace:^",
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-agent-loop-testkit": "workspace:^",
+    "@deepseek-ai/dsh-attachment-local": "workspace:^",
+    "@deepseek-ai/dsh-bash-local": "workspace:^",
+    "@deepseek-ai/dsh-credentials-local": "workspace:^",
+    "@deepseek-ai/dsh-deepseek-llm-api-extensions": "workspace:^",
+    "@deepseek-ai/dsh-experimental-agent-team": "workspace:^",
+    "@deepseek-ai/dsh-experimental-agent-team-profile": "workspace:^",
+    "@deepseek-ai/dsh-experimental-ptc-runtime-python": "workspace:^",
+    "@deepseek-ai/dsh-experimental-tool-agent-team": "workspace:^",
+    "@deepseek-ai/dsh-fs-observation-policy": "workspace:^",
+    "@deepseek-ai/dsh-fs-sandbox": "workspace:^",
+    "@deepseek-ai/dsh-host-frontend-static": "workspace:^",
+    "@deepseek-ai/dsh-host-webserver": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-llm-deepseek": "workspace:^",
+    "@deepseek-ai/dsh-llm-mock-server": "workspace:^",
+    "@deepseek-ai/dsh-llm-pi-ai": "workspace:^",
+    "@deepseek-ai/dsh-llm-replay": "workspace:^",
+    "@deepseek-ai/dsh-loader-smoke": "workspace:^",
+    "@deepseek-ai/dsh-plugin-package-inventory-deepseek": "workspace:^",
+    "@deepseek-ai/dsh-sandbox-local": "workspace:^",
+    "@deepseek-ai/dsh-sandbox-policy": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-session-checkpoint-policy": "workspace:^",
+    "@deepseek-ai/dsh-session-log-deepseek": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
+    "@deepseek-ai/dsh-session-query": "workspace:^",
+    "@deepseek-ai/dsh-shell-env": "workspace:^",
+    "@deepseek-ai/dsh-settings": "workspace:^",
+    "@deepseek-ai/dsh-settings-file": "workspace:^",
+    "@deepseek-ai/dsh-subagent": "workspace:^",
+    "@deepseek-ai/dsh-subagent-fork-in-process": "workspace:^",
+    "@deepseek-ai/dsh-subagent-spawn-in-process": "workspace:^",
+    "@deepseek-ai/dsh-subprocess-local": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-user-approval": "workspace:^",
+    "@types/js-yaml": "^4.0.9",
+    "@types/ws": "8.18.1",
+    "execa": "^10.0.0",
+    "ws": "8.21.0"
+  }
+}

apps/cli/reference/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 apps/cli/reference/README.md
+README.md: b2931e05c1c10c6de13427b2cdaf38a0e78db904
+README.zh.md: 2a9014a5d338c3d81d9976d8cb47474a95c45cb5

apps/cli/reference/README.md

@@ -0,0 +1,110 @@
+# `dsh` CLI behavior reference
+
+English | [中文](README.zh.md)
+
+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), 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. `dsh.profile.patchReload` selects `live` patch-file watching or `startup` one-time loading; omission defaults a custom profile to `live`. 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`, `@deepseek-ai/dsh-sdk-app`, `@deepseek-ai/dsh-sdk-minimal`, `@deepseek-ai/dsh-acp-app`) therefore always come from the same installation as the running `dsh`; out-of-tree bundles come from the profile's pnpm-managed `node_modules`. Before mounting rows, the launcher traverses the installation and selected bundles in that order and materializes the resulting fallback links. The internal runtime and dual modes consume the same immutable generation in tests without changing the CLI's link-mode behavior. Profile-installed packages keep native priority in every mode.
+
+The `web`, `headless`, `sdk`, `sdk-minimal`, and `acp` profiles auto-initialize from shipped templates on first use (`web`: base + web-app with live patches; `headless`: base + headless with startup-only patches; `sdk`: base + sdk-app with startup-only patches; `sdk-minimal`: its standalone bundle with startup-only patches; `acp`: base + acp-app with startup-only patches). Any other missing profile fails loudly with a hint to run `dsh plugin --profile <name> add <package>`.
+
+`dsh --profile <name> --from-default-profile <template>` initializes a new custom target from one of those five shipped templates before boot. The target name cannot be a shipped profile name, and its complete profile directory must not exist. The launcher claims that directory exclusively, so residual files and another concurrent creator are rejected without modification. It copies the template's current bundle list and `patchReload` value into a new manifest with empty dependencies and an empty user patch. It does not read the local profile named by `<template>`, copy its dependencies or patch, or persist an inheritance field; later template-list changes do not rewrite the new profile. The in-box bundles named by that copied list still resolve from the current dsh installation. A successful initialization adds no launcher output.
+
+An existing profile rejects `--from-default-profile` without changing or booting it; omit the option to use it. A residual target directory is also preserved and requires a different profile name. An unknown template or a shipped target name fails before creating the target. Unknown-template diagnostics name the valid templates. Initialization is committed before bundle resolution and application boot, so a later failure leaves the new profile on disk and the retry omits the creation option. `--dump-config` and `--dump-default-config` accept the option, initialize the target, print the requested tree, and do not boot it.
+
+```sh
+dsh --profile rescue --from-default-profile web
+dsh --profile rescue
+```
+
+### 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 rescue --from-default-profile web --no-open` therefore initializes before handing `--no-open` to Web, `dsh --profile web --port 8080` 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. In a `patchReload: live` profile, a patch-file 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`, repeatable `--trusted-host`, `--no-open` |
+| `headless` | the task text, as the positional argument |
+| `sdk` | no options; stdio carries the JSON-RPC protocol |
+| `sdk-minimal` | no options; stdio carries the same JSON-RPC protocol |
+| `acp` | no options; stdio carries ACP (Agent Client Protocol) |
+
+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 streams non-empty provider reasoning deltas to stderr under a `dsh: reasoning:` heading, prints only the final text on stdout, and exits 0 for `completed`, else 1; a successful response with no reasoning leaves stderr empty. An invocation with no task is a usage error from that app. The shipped headless profile mounts no browser Connection, HTTP server, Web runtime, or browser client, and opens no listening port.
+
+Inspect the composed tree without booting it:
+
+```sh
+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, relative plugin names in inserted rows resolve beside their patch file, and unmatched patch targets are reported on stderr. A dump initializes missing profile files but does not prepare the runtime module fallback under `$DSH_HOME/profiles/node_modules`. It 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
+
+`dsh plugin --profile <name> <args...>` initializes the profile when missing (shipped template, or `@deepseek-ai/dsh-base` alone for other names), then forwards `<args...>` to `pnpm` with the profile directory as working directory — `add`, `remove`, `why`, `update`, and every other pnpm verb work unchanged; pnpm must be on PATH. Relative path specs (`.`, `../plugin`, and their `file:`/`link:` forms) are anchored to the invoking directory first, so `add .` from a plugin checkout installs that checkout, not the profile. After every successful run, `dsh.profile.bundles` is reconciled against the installed state: each dependency resolving to a package whose manifest declares `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }` joins the layer stack (so an `update` that gains the declaration activates it), a bundle-less dependency stays plain with a one-time warning, and a removed dependency leaves the stack.
+
+The Codex and Claude Code subagent providers are separate optional Bundles. Add either package, both in one command, or remove either package independently:
+
+```sh
+dsh plugin --profile <name> add @deepseek-ai/dsh-subagent-codex
+dsh plugin --profile <name> add @deepseek-ai/dsh-subagent-claude-code
+dsh plugin --profile <name> add @deepseek-ai/dsh-subagent-codex @deepseek-ai/dsh-subagent-claude-code
+dsh plugin --profile <name> remove @deepseek-ai/dsh-subagent-codex
+dsh plugin --profile <name> remove @deepseek-ai/dsh-subagent-claude-code
+```
+
+The successful pnpm operation changes the Profile manifest and Bundle list on disk; a running Profile keeps the Bundle set from its current start. Restart that Profile after adding, removing, or updating a Bundle. This startup boundary applies to Bundle membership, while ordinary edits to the Profile or home `cordis.patch.yml` take effect through hot reload. On the next start, each installed Bundle registers only its dormant Host provider; a copied Preset must separately enable the matching tool row for new Agents. The [Codex provider README](../../../packages/subagent/subagent-codex/README.md) and [Claude Code provider README](../../../packages/subagent/subagent-claude-code/README.md) own executable, authentication, payload, and failure details; the [base Bundle reference](../../../packages/bundle/base/README.md) owns the default dependency closure.
+
+```sh
+dsh plugin --profile tui add github:deepseek-harness/turtle-ui
+dsh plugin --profile tui remove turtle-ui
+dsh --profile tui
+```
+
+Git-hosted plugins that ship sources build during install through their `prepare` script, which pnpm ≥10 blocks until the consumer allows it: the first `add` fails with pnpm's `allowBuilds` hint (and a dsh pointer at the profile's `pnpm-workspace.yaml`); copy the printed key there and re-run. Installing a built tarball or a local checkout needs no allowance.
+
+## Web alias
+
+`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 `--no-open` disables the default-browser handoff for this invocation. The client-plugin HMR receiver is always mounted and stays idle until a separate `pnpm run dev:web` watcher rebuilds client bundles.
+
+```sh
+dsh web
+dsh web --no-open
+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 and, for a local launch, opens that canonical host URL only after the complete Loader tree settles. A non-empty inherited `SSH_CONNECTION` or `SSH_TTY` suppresses the browser handoff because the SSH client or editor owns the local forwarded address; the host URL is still printed. The CLI intentionally does not support `--host 0.0.0.0` and exits with a usage error. Immediately before a local handoff it prints `dsh web: opening the default browser; pass --no-open to disable`; if the operating-system handoff fails, a diagnostic on stderr states the reason, leaves the server running, and names the URL for manual use. `--trusted-host` adds named authorities accepted by the `/api` browser-trust fence.
+
+Process shutdown gives the plugin tree up to five seconds to dispose. The first `SIGINT`/`SIGTERM` starts that graceful drain — `SIGTERM` is a supervisor's ordinary stop request and exits 0 on every surface, `SIGINT` reports 130; a second signal forces immediate exit. If one-shot normal completion is already stuck in disposal, the first `Ctrl+C` is the escalation and exits immediately instead of being swallowed.
+
+The base-backed modes treat the invoking directory as the default workspace root, load applicable `AGENTS.md` or `CLAUDE.md` instructions with a 65,536-byte render budget, and use an in-memory SQLite session content index. The standalone `sdk-minimal` profile uses the invoking directory as its sandbox-policy root but intentionally omits filesystem tools, instruction discovery, and SQLite. A `patchReload: live` profile watches valid edits of both `cordis.patch.yml` layers (profile and home) and reapplies them transactionally; a `startup` profile applies them once. A one-shot surface exits through its bounded shutdown, which disposes any live watchers.
+
+New sessions in base-backed profiles default to the `workspace-write` permission preset. Bash and filesystem mutations are restricted to the session workspace and platform temporary roots; reads and network access are not confined, while process visibility depends on the selected sandbox backend — bwrap runs commands in a private PID namespace that hides host processes, and Landlock and Seatbelt leave host process visibility unchanged. `DSH_PERMISSION_MODE` changes the process fallback. Stored General-settings permissions affect later Web sessions, not an already-open one. The standalone `sdk-minimal` tree instead pins `danger-full-access` and mounts no approval or permission-settings service.
+
+`DSH_TOOLS_MODE` selects `native`, `ptc`, or `both` for the process; another value fails at boot. The shipped `minimal` agent preset keeps that deployment presentation, fixes the complete system prompt to `You are a helpful software engineer assistant.`, and composes only the platform-selected persistent shell. Select 极简模式 when creating a Web session; every other prompt section and model-facing plugin remains absent from that agent while the shared browser, workspace, persistence, sandbox, and permission host stays in place.
+
+## Shared deployment behavior
+
+The base bundle mounts the native DeepSeek adapter, settings and credential providers, stable `web_search` and `web_fetch`, the public-only HTTP fetch provider, default-on DeepSeek session-log upload, and feedback-gated OTel upload for all users. Provider credentials resolve from the inherited environment, `$DSH_HOME/.credentials.yaml`, the invoking directory's `.env`, then `$DSH_HOME/.env`; the managed document is never materialized into `process.env`, while both `.env` files are ordinary launch environment layers. Search uses `DEEPSEEK_API_KEY` and accepts `DEEPSEEK_SEARCH_BASE_URL`. Enabled fetch calls run in every sandbox and approval mode without per-call confirmation; the provider rejects non-public destinations before connecting. The Web app disables the base tool row and exposes the same tools through its `cordis`, `ptc`, and `standard` agent presets.
+
+Feedback is recorded in the Session log without starting model work. The [DeepSeek session-log contributor](../../../packages/session/session-log-deepseek/README.md) sends complete unaccepted log suffixes with subsequent DeepSeek requests by default, including requests sent through configured gateways; set its `enabled` configuration to `false` to opt out. [OTel session upload](../../../packages/session/session-telemetry-otel/README.md) applies to all users and providers, including `deepseek-official`, without requiring a request header. The base defaults to `FEEDBACK_ONLY`: new own text feedback, message ratings, edits, and withdrawals release the complete canonical prefix through that event, including stored context; later records wait for the next explicit feedback. Inherited parent feedback does not authorize a fork. Requests, restoration, mount, and HMR do not trigger capture. SDK batching may finish an authorized upload without further interaction or model work. `DSH_TELEMETRY_MODE=DISABLED` disables OTel delivery; `FULL` is rejected, and any non-empty `DSH_TELEMETRY_DISABLED` disables its row. `DSH_TELEMETRY_OTLP_URL` selects the collector. Handoff is best-effort, not collector acceptance; no durable outbox or retry guarantee is provided. These OTel settings do not enable or disable the DeepSeek contribution. Neither path changes model input, but exports can include message text, tool arguments and results, and workspace paths.
+
+Install external plugin bundles through `dsh plugin --profile <name> add <package-or-git-spec>`. The installed package owns its dependencies and contributes its declared `cordis.patch.yml` layer. The CLI also ships `@deepseek-ai/dsh-mcp-client` as a dependency for patch layers, but no MCP server is enabled by default because each server command is trusted executable code outside the agent sandbox.
+
+<a id="source-execution"></a>
+## Source execution
+
+From the repository root, run `pnpm run build` separately after a fresh checkout and whenever artifacts need updating, then use `pnpm dsh <args...>`. The `package.json` script launches `apps/cli/src/bin.ts` with `node --import tsx/esm` without building and forwards every argument. Missing Typert host artifacts fail profile boot through module-resolution errors without a build instruction. Once those host artifacts exist, missing frontend or client-plugin bundles fail at startup with an instruction to run `pnpm run build`. The launcher does not check freshness, so existing stale bundles can run older browser code until rebuilt. The process inherits the launch environment, and `runProfile` resolves the outbound proxy from that snapshot before any entry mounts, so `HTTP_PROXY`/`HTTPS_PROXY` (and a proxy declared in a `.env` layer) apply without any further flag. The installed form launches the built `apps/cli/lib/bin.js` without rebuilding the repository.

apps/cli/reference/README.zh.md

@@ -0,0 +1,112 @@
+# `dsh` CLI（命令行界面）行为参考
+
+[English](README.md) | 中文
+
+本参考定义 profile 启动、web 别名、插件管理和配置 dump 等命令模式。argv 由 [`src/args.ts`](../src/args.ts) 统一解析一次，[`src/bin.ts`](../src/bin.ts) 只会动态导入选中的运行器。
+
+<a id="profile-boot"></a>
+
+## 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>` 覆盖层。对同一配置行，后应用的层优先。patch 会替换目标行的整个 `config` 值，而不是深度合并其中的键；patch 也可以插入新行。`dsh.profile.patchReload` 可选择 `live` patch 文件监视或 `startup` 单次加载；自定义 profile 省略该值时默认使用 `live`。配置解析、schema 校验、模块解析或插件启动失败时，系统会报告错误并以非零状态退出。收到 SIGINT 或 SIGTERM 时，挂载的根节点会先 dispose（资源释放）再退出。
+
+组合包名称先从 dsh 安装目录解析，再从 profile 目录解析。因此，内置组合包（`@deepseek-ai/dsh-base`、`@deepseek-ai/dsh-web-app`、`@deepseek-ai/dsh-headless`、`@deepseek-ai/dsh-sdk-app`、`@deepseek-ai/dsh-sdk-minimal`、`@deepseek-ai/dsh-acp-app`）始终来自当前运行的 `dsh` 所属的安装；树外组合包来自 profile 中由 pnpm 管理的 `node_modules`。挂载配置行前，launcher 会按此顺序遍历安装与所选 bundle，并物化计算出的 fallback 链接。内部 runtime 与 dual 模式会在测试中消费同一份不可变 generation，但不改变 CLI 的 link 模式行为。所有模式都保留 profile 已安装包的原生优先级。
+
+`web`、`headless`、`sdk`、`sdk-minimal` 和 `acp` profile 首次使用时会从随附模板自动初始化（`web`：base + web-app，实时应用 patch；`headless`：base + headless，只在启动时应用 patch；`sdk`：base + sdk-app，只在启动时应用 patch；`sdk-minimal`：独立组合包，只在启动时应用 patch；`acp`：base + acp-app，只在启动时应用 patch）。其他缺失的 profile 会显式报错，并提示运行 `dsh plugin --profile <name> add <package>`。
+
+`dsh --profile <name> --from-default-profile <template>` 会在启动前，从上述五个随附模板之一初始化新的自定义目标。目标名称不能是随附 profile 名称，并且完整的目标 profile 目录必须不存在。launcher 会以独占方式领取该目录，因此残留文件和另一个并发创建者都会在不作修改的情况下被拒绝。它把模板当前的组合包列表和 `patchReload` 值复制进一份依赖为空、用户 patch 为空的新 manifest。它不会读取 `<template>` 指定的本地同名 profile，不会复制其依赖或 patch，也不会持久化继承字段；模板列表之后的变化不会改写新 profile。复制列表中指名的内置组合包仍从当前 dsh 安装目录解析。初始化成功不会增加 launcher 输出。
+
+profile 已经存在时，`--from-default-profile` 会被拒绝，且不会修改或启动它；去掉该选项即可使用它。残留的目标目录同样会被原样保留，此时必须改用另一个 profile 名称。未知模板或随附目标名称会在创建目标之前失败；未知模板的诊断会列出有效模板。初始化在组合包解析和应用启动之前提交，因此后续失败仍会把新 profile 留在磁盘上，重试时需要去掉创建选项。`--dump-config` 和 `--dump-default-config` 接受该选项：它们初始化目标并打印所请求的配置树，但不启动应用。
+
+```sh
+dsh --profile rescue --from-default-profile web
+dsh --profile rescue
+```
+
+### 应用参数
+
+启动器自身的 flag 必须写在最前面，并在遇到第一个无法识别的 token 时结束；从该 token 开始的所有内容都会通过 `ctx.cmdlineArgs` 原样交给已启动的 profile，注入该 profile 的任意应用插件都可以解析这些内容（[`dsh-cmdline`](../../../packages/boot/cmdline/README.zh.md)）。因此，`dsh --profile rescue --from-default-profile web --no-open` 会先初始化，再把 `--no-open` 交给 Web；`dsh --profile web --port 8080` 会将 `--port` 交给 web 应用；`dsh --profile web --help` 只打印该应用的帮助信息，不启动应用；`dsh --help` 没有可供交付参数的 profile，因此会打印启动器自身的帮助信息。`-V`/`--version` 位于应用参数边界之前时，会打印启动器的版本。
+
+每套组合只会挂载一次。普通插件注入 `cmdlineArgs`，解析所属应用的参数，并将解析结果作为服务提供。每个从 flag 取值的配置行都会注入该服务；Loader 会等到���务激活后，再对该行的配置求值（`port: !!js ctx.webStartup.port ?? 3080`），因此 flag 的优先级高于配置行中写明的值。要维持这一优先级，配置行必须保留该表达式；如果用户 patch 用字面量替换整个 `config`，也会随之移除运行时读取。帮助参数和被拒绝的参数都会请求退出：参数被拒绝时以非零状态退出，显示帮助时以 0 退出；依赖该提供方服务的配置行不会激活。在 `patchReload: live` profile 中，编辑 patch 文件会根据仍在运行的服务重新计算表达式，因此不会重置当前正在使用的端口。
+
+启动器的 flag 必须写在应用参数之前，且启动器的解析器会消耗掉一个 `--`：必须以字面量 `--` 送达应用的参数需要写成 `-- --`。如果应用的第一个参数恰好等于 `web` 或 `plugin`，会选择对应的子命令。`ctx.cmdlineArgs.get()` 是共享的不可变读取：多个插件可以解析同一份快照，没有读取方的 profile 则会忽略自己的应用参数。
+
+随附的应用接受以下命令行参数：
+
+| Profile | 参数 |
+|---|---|
+| `web` | `--host`、`--port`、可重复的 `--trusted-host`、`--no-open` |
+| `headless` | 任务文本，作为位置参数 |
+| `sdk` | 无选项；stdio 携带 JSON-RPC 协议 |
+| `sdk-minimal` | 无选项；stdio 携带相同的 JSON-RPC 协议 |
+| `acp` | 无选项；stdio 携带 ACP（Agent Client Protocol） |
+
+一次性任务（`dsh --profile headless "run the tests"`）通过核心注册表创建一个全新的持久化 Agent（智能体），提交任务、等待完全停稳并对会话执行 flush，再从其持久化事件区间中推导最后一个非空 assistant 文本与最终 `turn/end` 原因。它在 `dsh: reasoning:` 标题下将非空的提供方推理（reasoning）增量流式写入 stderr，只在 stdout 打印最终文本，并在原因为 `completed` 时以 0 退出，否则以 1 退出；没有推理内容的成功响应会保持 stderr 为空。没有任务的调用是该应用的用法错误。随附 headless profile 不挂载浏览器 Connection、HTTP 服务器、Web 运行时或浏览器客户端，也不会打开监听端口。
+
+可在不启动的情况下检查组合出的配置树：
+
+```sh
+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 文件所在目录解析，找不到目标的 patch 会报告到 stderr。dump 操作会初始化缺失的 profile 文件，但不会准备 `$DSH_HOME/profiles/node_modules` 下的运行时模块 fallback。它不会运行应用的命令行参数提供方，因此展示的是解析任何应用参数之前的组合配置树；如果调用中包含应用参数，dump 会拒绝该调用。
+
+## 插件管理
+
+`dsh plugin --profile <name> <args...>` 在 profile 缺失时先初始化它（有随附模板的用模板，其他名称只装 `@deepseek-ai/dsh-base`），然后以 profile 目录为工作目录，把 `<args...>` 转发给 `pnpm`：`add`、`remove`、`why`、`update` 及其他所有 pnpm 子命令都照常可用；pnpm 必须在 PATH 上。相对路径 spec（`.`、`../plugin` 及其 `file:`/`link:` 形式）会先锚定到调用目录，因此在插件 checkout 中执行 `add .` 安装的是该 checkout，而不是 profile。每次成功运行后，系统都会根据当前安装状态更新 `dsh.profile.bundles`：如果某项依赖解析到的包在 manifest 中声明了 `"dsh": { "bundle": { "patch": "./cordis.patch.yml" } }`，该依赖就会加入配置层栈；如果某项依赖在 `update` 后获得该声明，也会随即激活。没有组合包声明的依赖仍作为普通依赖保留，并显示一次性警告；已移除的依赖则从配置层栈中删除。
+
+Codex 与 Claude Code subagent 提供方是两个彼此独立的可选组合包。可以只添加一个包、在同一命令中添加两个包，或独立移除任一包：
+
+```sh
+dsh plugin --profile <name> add @deepseek-ai/dsh-subagent-codex
+dsh plugin --profile <name> add @deepseek-ai/dsh-subagent-claude-code
+dsh plugin --profile <name> add @deepseek-ai/dsh-subagent-codex @deepseek-ai/dsh-subagent-claude-code
+dsh plugin --profile <name> remove @deepseek-ai/dsh-subagent-codex
+dsh plugin --profile <name> remove @deepseek-ai/dsh-subagent-claude-code
+```
+
+pnpm 操作成功后会改变磁盘上的 Profile manifest 与组合包列表；正在运行的 Profile 会保留本次启动时的组合包集合。添加、移除或更新组合包后须重启该 Profile。这个启动边界只适用于组合包成员变化，Profile 或 home 中普通 `cordis.patch.yml` 的编辑通过热重载生效。下一次启动时，每个已安装组���包只注册自己的休眠 Host 提供方；还须在复制出的 Preset 中单独启用对应工具行，新 Agent 才能看到该工具。[Codex provider README](../../../packages/subagent/subagent-codex/README.zh.md) 与 [Claude Code provider README](../../../packages/subagent/subagent-claude-code/README.zh.md) 负责可执行文件、身份验证、载荷与失败细节；[base 组合包参考](../../../packages/bundle/base/README.zh.md) 负责默认依赖闭包。
+
+```sh
+dsh plugin --profile tui add github:deepseek-harness/turtle-ui
+dsh plugin --profile tui remove turtle-ui
+dsh --profile tui
+```
+
+随源码发布的 Git 托管插件会在安装期间通过 `prepare` 脚本构建，而 pnpm ≥10 默认会阻止该脚本，直到使用方明确允许。首次运行 `add` 会失败，并显示 pnpm 的 `allowBuilds` 提示；dsh 还会提示应修改该 profile 的 `pnpm-workspace.yaml`。将输出的键复制到该文件后，重新运行命令即可。安装已经构建好的 tarball 或本地 checkout 时，无需加入 `allowBuilds`。
+
+## Web 别名
+
+`dsh web` 是 `--profile web` 的硬编码别名；写在它之后的 flag 属于 web 应用，由组合包中的普通提供方解析。`--host` 和 `--port` 覆盖承载它们的那些行的组合取值，可重复的 `--trusted-host` 通过 `ctx.webRuntime.trustedHosts` 提供本次调用的 authority（部署表达式会拼接自己的 authority），`--no-open` 则只对本次调用关闭默认浏览器交接。客户端插件 HMR（热模块替换）接收器始终挂载，在单独运行的 `pnpm run dev:web` watcher 重建客户端 bundle 之前保持空闲。
+
+```sh
+dsh web
+dsh web --no-open
+dsh web --patch ./extra.cordis.yml
+dsh web --dump-config
+dsh web --help
+```
+
+生产 Web 运行器需要已构建的包和前端产物（`pnpm run build`）。默认服务地址是 `http://127.0.0.1:3080`；本机启动时，只在完整 Loader 配置树结算后才用默认浏览器打开该规范宿主机 URL。继承的 `SSH_CONNECTION` 或 `SSH_TTY` 非空时会跳过浏览器交接，因为本地转发地址由 SSH 客户端或编辑器持有；宿主机 URL 仍会打印。CLI 有意不支持 `--host 0.0.0.0`，并会以用法错误退出。本机交接前会打印英文提示 `dsh web: opening the default browser; pass --no-open to disable`；若操作系统交接失败，stderr 诊断会说明原因、给出 URL 供手动访问，服务器仍继续运行。`--trusted-host` 可添加 `/api` 浏览器信任围栏接受的具名 authority。
+
+进程关闭时，插件树最多有 5 秒完成 dispose。首次收到 `SIGINT` 或 `SIGTERM` 时会开始优雅排空：`SIGTERM` 是监督进程发出的常规停止请求，在所有运行模式下都以 0 退出；`SIGINT` 则报告 130。第二次收到信号时会立即强制退出。如果一次性运行在正常结束时已经卡在 dispose 阶段，第一次按下 `Ctrl+C` 就会直接升级为强制退出，而不会被忽略。
+
+基于 base 的模式都将运行命令时所在的目录作为默认 workspace 根目录，以 65,536 字节渲染预算加载适用的 `AGENTS.md` 或 `CLAUDE.md` 指令，并使用内存 SQLite 会话内容索引。独立的 `sdk-minimal` profile 把运行命令时所在的目录作为沙箱策略根目录，但刻意省略文件系统工具、指令发现与 SQLite。`patchReload: live` profile 会监视 profile 与 home 两个 `cordis.patch.yml` 配置层的有效变更，并以事务方式重新应用；`startup` profile 则只应用一次。一次性运行模式通过有界关闭流程退出，该流程会 dispose 所有实时监视器。
+
+基于 base 的 profile 中，新会话默认使用 `workspace-write` 权限预设。Bash 和文件系统修改仅限于会话 workspace 与平台临时根目录；读取和网络访问不受限制，进程可见性则取决于所选沙箱后端——bwrap 在私有 PID 命名空间中运行命令并隐藏宿主进程，Landlock 与 Seatbelt 保持宿主进程可见性不变。`DSH_PERMISSION_MODE` 更改进程后备值。General settings 中存储的权限影响后续 Web 会话，不改变已打开的会话。独立的 `sdk-minimal` 配置树则固定为 `danger-full-access`，且不挂载 approval 或权限 settings 服务。
+
+`DSH_TOOLS_MODE` 为进程选择 `native`、`ptc` 或 `both`；其他值会导致启动失败。随附的 `minimal` agent preset 会保留该部署的呈现方式，将完整系统提示词固定为 `You are a helpful software engineer assistant.`，并且仅组合按平台选择的持久 shell。创建 Web 会话时请选择极简模式；该 agent 不包含任何其他提示词段落或面向模型的插件，而共享的浏览器、workspace、持久化、沙箱与权限宿主保持不变。
+
+## 共享部署行为
+
+基础组合包挂载原生 DeepSeek 适配器、settings 与凭据提供方、稳定的 `web_search` 和 `web_fetch`、仅限公网的 HTTP fetch 提供方，默认开启的 DeepSeek 会话日志上传，以及面向所有用户的反馈门控 OTel 上传。提供方凭据依次���继承环境、`$DSH_HOME/.credentials.yaml`、调用目录的 `.env` 和 `$DSH_HOME/.env` 解析；受管文档从不物化进 `process.env`，而两个 `.env` 文件都是普通启动环境层。搜索使用 `DEEPSEEK_API_KEY` 并接受 `DEEPSEEK_SEARCH_BASE_URL`。已启用的抓取调用会在所有 sandbox 与审批模式下执行，无需逐次确认；提供方会在连接前拒绝非公开目的地址。Web app 会禁用 base 工具配置项，再通过 `cordis`、`ptc` 与 `standard` agent preset 暴露相同工具。
+
+反馈记录在会话日志中，不会启动模型工作。[DeepSeek 会话日志贡献器](../../../packages/session/session-log-deepseek/README.zh.md)默认随后续 DeepSeek 请求发送尚未确认接收的完整日志后缀，包括经已配置网关发送的请求；将其 `enabled` 配置设为 `false` 可关闭上传。[OTel 会话上传](../../../packages/session/session-telemetry-otel/README.zh.md)适用于所有用户和提供方，包括 `deepseek-official`，无需请求头。基础配置默认使用 `FEEDBACK_ONLY`：新的自身文本反馈、消息评分、编辑与撤回会释放截至该事件的完整规范日志前缀，包含存储的上下文；后续记录等待下一次显式反馈。继承的父级反馈不构成 fork 的授权。请求、恢复、挂载和 HMR 不触发捕获。SDK 批处理可完成已授权上传，无需进一步交互或模型工作。`DSH_TELEMETRY_MODE=DISABLED` 禁止 OTel 投递；`FULL` 被拒绝，任何非空的 `DSH_TELEMETRY_DISABLED` 都会禁用其配置行。`DSH_TELEMETRY_OTLP_URL` 选择采集端。交接尽力而为，不代表采集端接受；不提供持久化 outbox 或重试保证。这些 OTel 设置不会开启或关闭 DeepSeek 贡献。两条路径都不改变模型输入，但导出可能包含消息文本、工具参数和结果，以及工作区路径。
+
+通过 `dsh plugin --profile <name> add <package-or-git-spec>` 安装外部插件组合包。安装的包拥有其依赖，并贡献其声明的 `cordis.patch.yml` 层。CLI 还随附 `@deepseek-ai/dsh-mcp-client` 作为供 patch 层使用的依赖，但默认不启用 MCP 服务器，因为每条服务器命令都是 agent 沙箱之外的受信任可执行代码。
+
+<a id="source-execution"></a>
+## 源码执行
+
+请在仓库根目录中，于全新 checkout 之后及产物需要更新时单独运行 `pnpm run build`，然后使用 `pnpm dsh <args...>`。`package.json` 中的脚本不会构建，而是通过 `node --import tsx/esm` 启动 `apps/cli/src/bin.ts`，并转发所有参数。Typert Host 产物缺失时，profile 启动会因不含构建指引的模块解析错误而失败。这些 Host 产物存在后，如果前端或 Client plugin 组合包缺失，启动会失败并提示运行 `pnpm run build`。启动器不会检查产物是否为最新，因此已有的陈旧组合包可能继续运行旧版浏览器代码，直至重新构建。该进程会继承启动环境，且 `runProfile` 会在任何 entry 挂载之前从该快照解析出站代理，因此 `HTTP_PROXY`／`HTTPS_PROXY`（以及写在 `.env` 层中的代理）无需任何额外开关即可生效。安装形式会直接启动构建后的 `apps/cli/lib/bin.js`，不会重新构建仓库。

apps/cli/tests/agent-team-headless.e2e.ts

@@ -0,0 +1,125 @@
+import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { execa } from 'execa'
+import { describe, expect, it } from 'vitest'
+import { resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke'
+
+const dshBinScript = fileURLToPath(new URL('../src/bin.ts', import.meta.url))
+const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
+const fixturePlugin = pathToFileURL(fileURLToPath(
+  new URL('./profiles/headless/tests/fixtures/team-llm.mjs', import.meta.url),
+)).href
+
+function records(content: string): Record<string, unknown>[] {
+  return content.split('\n').filter(Boolean).map(line => JSON.parse(line) as Record<string, unknown>)
+}
+
+describe('dsh run with Agent Teams enabled', () => {
+  it('runs two teammates, durable peer mail, dependent tasks, waiting, and final aggregation', async () => {
+    const cwd = await mkdtemp(join(tmpdir(), 'dsh-agent-team-headless-'))
+    try {
+      const home = join(cwd, '.dsh')
+      const sessions = join(home, 'sessions')
+      const profileDir = join(home, 'profiles', 'headless')
+      await mkdir(profileDir, { recursive: true })
+      await writeFile(join(profileDir, 'package.json'), JSON.stringify({
+        name: 'dsh-profile-headless',
+        private: true,
+        dependencies: {
+          '@deepseek-ai/dsh-experimental-agent-team-profile': 'workspace:^',
+        },
+        dsh: {
+          profile: {
+            bundles: [
+              '@deepseek-ai/dsh-base',
+              '@deepseek-ai/dsh-headless',
+              '@deepseek-ai/dsh-experimental-agent-team-profile',
+            ],
+          },
+        },
+      }, undefined, 2) + '\n')
+      await writeFile(join(profileDir, 'cordis.patch.yml'), [
+        '- id: llm-deepseek',
+        '  disabled: true',
+        '- id: session-persistence-jsonl',
+        '  config:',
+        `    root: '${sessions}'`,
+        '    compression: none',
+        '- insert:',
+        '    - id: team-fixture-llm',
+        `      name: '${fixturePlugin}'`,
+        '',
+      ].join('\n'))
+      const launch = resolveExampleLaunch({
+        srcBin: dshBinScript,
+        configArgs: ['--profile', 'headless', '请先运行 workflow 检查，再使用 Agent Teams 把调研和实现拆给两个 teammate，等待完成后汇总。'],
+        tsconfigPath,
+        env: {
+          DSH_HOME: home,
+          DSH_AGENTS_HOME: join(cwd, '.agents'),
+          DSH_TELEMETRY_DISABLED: '1',
+          DEEPSEEK_API_KEY: '',
+          NODE_OPTIONS: [
+            process.env.NODE_OPTIONS,
+            '--disable-warning=ExperimentalWarning',
+            '--disable-warning=MODULE_TYPELESS_PACKAGE_JSON',
+          ].filter(Boolean).join(' '),
+        },
+      })
+      const result = await execa(launch.command, launch.args, {
+        cwd,
+        env: launch.env,
+        input: '',
+        timeout: 90_000,
+        killSignal: 'SIGKILL',
+        reject: false,
+      })
+      expect(
+        result.exitCode,
+        `dsh headless profile exited unexpectedly.\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`,
+      ).toBe(0)
+      expect(result.stderr).toBe('')
+      expect(result.stdout).toContain('TEAM_WORKFLOW_OK')
+
+      const files = (await readdir(sessions, { recursive: true }))
+        .filter(file => file.endsWith('.jsonl'))
+      expect(files).toHaveLength(4)
+      const logs = await Promise.all(files.map(file => readFile(join(sessions, file), 'utf8')))
+      const parsed = logs.map(records)
+      const workflowChild = parsed.find(log => log.some(record => record.type === 'subagent/descriptor'
+        && (record.data as { mode: string }).mode === 'one-shot'))
+      expect(workflowChild).toBeDefined()
+      expect(workflowChild!.find(record => record.type === 'subagent/descriptor')?.data)
+        .toMatchObject({ mode: 'one-shot', provider: 'spawn' })
+      expect(workflowChild!.filter(record => record.type === 'user/message'
+        && (record.data as { source: { kind: string } }).source.kind === 'user').map(record => record.data))
+        .toEqual([expect.objectContaining({ content: [{ type: 'text', text: 'TEAM_WORKFLOW_CHILD' }] })])
+      const root = parsed.find((log) => {
+        const header = log[0]
+        return header?.type === 'session' && typeof header.parentSession !== 'string'
+      })
+      expect(root).toBeDefined()
+      const eventTypes = root!.map(record => record.type)
+      expect(eventTypes.filter(type => type === 'team/member')).toHaveLength(4)
+      expect(eventTypes).toContain('team/message/queued')
+      expect(eventTypes).toContain('team/message/delivered')
+      const taskEvents = root!.filter(record => record.type === 'team/task')
+      expect(taskEvents.filter((record) => {
+        const data = record.data as { task?: { status?: string } } | undefined
+        return data?.task?.status === 'completed'
+      })).toHaveLength(2)
+      const toolNames = root!.filter(record => record.type === 'tool/call')
+        .map(record => (record.data as { name?: string } | undefined)?.name)
+      expect(toolNames).toContain('wait_agent')
+      expect(toolNames).toContain('team_task_list')
+      expect(toolNames).toContain('list_agents')
+      expect(toolNames).toContain('workflow')
+      expect(root!.find(record => record.type === 'tool-workflow/run-end')?.data)
+        .toMatchObject({ stopReason: 'completed' })
+    } finally {
+      await rm(cwd, { recursive: true, force: true })
+    }
+  }, 105_000)
+})

apps/cli/tests/args.spec.ts

@@ -0,0 +1,134 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { parseDshArgs } from '../src/args.ts'
+
+const parse = (argv: string[]) => parseDshArgs(argv, '1.2.3')
+
+/** Capture the process exit code while muting Commander's output. */
+function exitCode(argv: string[]): number {
+  const exit = vi.spyOn(process, 'exit').mockImplementation(() => { throw new Error('exit') })
+  vi.spyOn(process.stdout, 'write').mockReturnValue(true)
+  vi.spyOn(process.stderr, 'write').mockReturnValue(true)
+  try {
+    parse(argv)
+    throw new Error(`expected ${JSON.stringify(argv)} to exit`)
+  } catch {
+    return exit.mock.calls.at(-1)?.[0] as number
+  } finally {
+    vi.restoreAllMocks()
+  }
+}
+
+afterEach(() => { vi.restoreAllMocks() })
+
+describe('parseDshArgs', () => {
+  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'], args: [] })
+    expect(parse(['--profile', 'rescue', '--from-default-profile', 'web']))
+      .toEqual({ mode: 'profile', profile: 'rescue', fromDefaultProfile: 'web', patches: [], 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', '127.0.0.1', '--port', '8080', '--no-open', '--future-web-flag']))
+      .toEqual({ mode: 'profile', profile: 'web', patches: [], args: ['--host', '127.0.0.1', '--port', '8080', '--no-open', '--future-web-flag'] })
+    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'] })
+    expect(parse(['--profile', 'rescue', '--resume', 'abc', '--from-default-profile', 'web']))
+      .toEqual({
+        mode: 'profile',
+        profile: 'rescue',
+        patches: [],
+        args: ['--resume', 'abc', '--from-default-profile', 'web'],
+      })
+    expect(parse(['web', '--from-default-profile', 'web']))
+      .toEqual({ mode: 'profile', profile: 'web', patches: [], args: ['--from-default-profile', 'web'] })
+  })
+
+  it('routes the plugin pnpm forwarder', () => {
+    expect(parse(['plugin', '--profile', 'tui', 'add', 'turtle-ui']))
+      .toEqual({ mode: 'plugin', profile: 'tui', args: ['add', 'turtle-ui'] })
+    expect(parse(['plugin', '--profile', 'tui', 'remove', 'turtle-ui']))
+      .toEqual({ mode: 'plugin', profile: 'tui', args: ['remove', 'turtle-ui'] })
+    expect(parse(['plugin', '--profile', 'tui', 'why', '@deepseek-ai/cordis']))
+      .toEqual({ mode: 'plugin', profile: 'tui', args: ['why', '@deepseek-ai/cordis'] })
+    // Unknown pnpm flags forward verbatim.
+    expect(parse(['plugin', '--profile', 'tui', 'add', '--save-dev', 'x']))
+      .toEqual({ mode: 'plugin', profile: 'tui', args: ['add', '--save-dev', 'x'] })
+  })
+
+  it('routes profile and web config dumps', () => {
+    expect(parse(['--profile', 'web', '--dump-config']))
+      .toEqual({ mode: 'dump-config', profile: 'web', defaultOnly: false, patches: [] })
+    expect(parse(['--profile', 'web', '--dump-default-config']))
+      .toEqual({ mode: 'dump-config', profile: 'web', defaultOnly: true, patches: [] })
+    expect(parse(['--profile', 'rescue', '--from-default-profile', 'web', '--dump-config']))
+      .toEqual({
+        mode: 'dump-config',
+        profile: 'rescue',
+        fromDefaultProfile: 'web',
+        defaultOnly: false,
+        patches: [],
+      })
+    expect(parse(['--profile', 'tui', '--dump-config', '--patch', 'x.yml']))
+      .toEqual({ mode: 'dump-config', profile: 'tui', defaultOnly: false, patches: ['x.yml'] })
+    expect(parse(['web', '--dump-config']))
+      .toEqual({ mode: 'dump-config', profile: 'web', defaultOnly: false, patches: [] })
+    expect(parse(['web', '--dump-default-config']))
+      .toEqual({ mode: 'dump-config', profile: 'web', defaultOnly: true, patches: [] })
+  })
+
+  it('rejects missing profile, removed flags, and contradictory inputs', () => {
+    expect(exitCode([])).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', '--from-default-profile='])).toBe(1)
+    expect(exitCode(['--profile', 'x', '--from-default-profile'])).toBe(1)
+    expect(exitCode(['--profile', 'x', '--patch='])).toBe(1)
+    expect(exitCode(['--dump-config'])).toBe(1)
+    expect(exitCode(['--profile', 'x', '--dump-config', '--dump-default-config'])).toBe(1)
+    expect(exitCode(['--profile', 'x', '--dump-default-config', '--patch', 'p.yml'])).toBe(1)
+    expect(exitCode(['--profile', 'x', '--dump-config', 'task'])).toBe(1)
+    expect(exitCode(['--bogus'])).toBe(1)
+    expect(exitCode(['--profile', 'x', 'web'])).toBe(1)
+    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)
+    // 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(['--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', 'desktop'])).toBe(1)
+    expect(exitCode(['--profile', 'Desktop'])).toBe(1)
+    expect(exitCode(['--profile', 'DESKTOP'])).toBe(1)
+    expect(exitCode(['--profile', 'desktop', '--dump-config'])).toBe(1)
+    expect(exitCode(['plugin', '--profile', 'desktop', 'add', 'x'])).toBe(1)
+    expect(exitCode(['plugin', '--profile', 'Desktop', 'add', 'x'])).toBe(1)
+    expect(exitCode(['--profile', 'x', 'plugin', 'add', 'y'])).toBe(1)
+    expect(exitCode(['--from-default-profile', 'web', 'plugin', '--profile', 'x', 'add', 'y'])).toBe(1)
+  })
+
+  it('keeps its own help for an invocation with no app to hand it to', () => {
+    expect(exitCode(['--help'])).toBe(0)
+    expect(exitCode(['-h'])).toBe(0)
+    expect(exitCode(['--version'])).toBe(0)
+  })
+})

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

@@ -0,0 +1,1151 @@
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, symlinkSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { createInterface } from 'node:readline'
+import { Readable, Writable } from 'node:stream'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import {
+  client as createAcpClientApp,
+  methods,
+  ndJsonStream,
+  PROTOCOL_VERSION,
+  type SessionNotification,
+} from '@agentclientprotocol/sdk'
+import { startMockLlmServer } from '@deepseek-ai/dsh-llm-mock-server'
+import { entryListSchema } from '@deepseek-ai/cordis-plugin-include'
+import { execa } from 'execa'
+import * as yaml from 'js-yaml'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+/** Published-entry acceptance for argument errors, profile lifecycle, and boot-free config dumps. */
+const repoRoot = fileURLToPath(new URL('../../../', import.meta.url))
+// The dsh built bin cold-starts slowly on the contended self-hosted Windows pool; the
+// execa deadline, its error text, the outer vitest case budget, and waitForFile all
+// share this value so a widening cannot leave a stale 25s diagnostic behind.
+const SPAWN_TIMEOUT_MS = 60_000
+// The release version, including a prerelease such as 0.0.1-rc.1: `--version`
+// prints what this manifest carries, so no test may pin it to a literal.
+const cliVersion = (JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')) as { version: string }).version
+const dshBin = join(repoRoot, 'apps/cli/lib/bin.js')
+const invalidProvider = fileURLToPath(new URL('./fixtures/invalid-provider.cordis.yml', import.meta.url))
+const webReadyExitHook = new URL('./fixtures/web-browser-open/register.mjs', import.meta.url).href
+
+async function runBuiltBin(
+  args: readonly string[] = [],
+  env: Readonly<Record<string, string | undefined>> = {},
+  cwd?: string,
+): Promise<{ stdout: string; code: number; stderr: string }> {
+  const childEnv = Object.fromEntries(
+    Object.entries({ ...process.env, ...env })
+      .filter((entry): entry is [string, string] => entry[1] !== undefined),
+  )
+  const result = await execa(process.execPath, [dshBin, ...args], {
+    input: '',
+    timeout: SPAWN_TIMEOUT_MS,
+    killSignal: 'SIGKILL',
+    reject: false,
+    env: childEnv,
+    extendEnv: false,
+    ...cwd === undefined ? {} : { cwd },
+  })
+  if (result.timedOut) {
+    throw new Error(`dsh built bin did not exit within ${SPAWN_TIMEOUT_MS / 1_000}s. stdout:\n${result.stdout}\nstderr:\n${result.stderr}`)
+  }
+  return { stdout: result.stdout, code: result.exitCode ?? -1, stderr: result.stderr }
+}
+
+async function waitForFile(file: string): Promise<void> {
+  const deadline = Date.now() + SPAWN_TIMEOUT_MS
+  while (!existsSync(file)) {
+    if (Date.now() >= deadline) throw new Error(`dsh profile lifecycle marker did not appear: ${file}`)
+    await new Promise(resolve => setTimeout(resolve, 20))
+  }
+}
+
+interface ProfileLifecycleFixture {
+  home: string
+  ready: string
+  settled: string
+  disposed: string
+  interrupt: string
+}
+
+/**
+ * A minimal custom profile: one lifecycle-marker plugin bundle listed in
+ * dsh.profile.bundles, no dsh-base — proving out-of-box composition machinery without
+ * booting the entire product tree.
+ */
+function createProfileLifecycleFixture(): ProfileLifecycleFixture {
+  const home = mkdtempSync(join(tmpdir(), 'dsh-profile-lifecycle-'))
+  const ready = join(home, 'ready')
+  const settled = join(home, 'settled')
+  const disposed = join(home, 'disposed')
+  const interrupt = join(home, 'interrupt')
+  const bundleDir = join(home, 'lifecycle-bundle')
+  mkdirSync(bundleDir, { recursive: true })
+  writeFileSync(join(bundleDir, 'plugin.mjs'), [
+    "import { existsSync, writeFileSync } from 'node:fs'",
+    "import { join } from 'node:path'",
+    "export const name = 'profile-lifecycle-fixture'",
+    'export function apply(ctx, config = {}) {',
+    '  let active = true',
+    '  // Keep the event loop alive so process lifetime is signal-owned, like a real surface.',
+    '  // Windows has no deliverable SIGTERM; the marker emits the same process event there.',
+    '  let interrupted = false',
+    '  const heartbeat = setInterval(() => {',
+    '    if (interrupted || !existsSync(process.env.RAW_INTERRUPT_FILE)) return',
+    '    interrupted = true',
+    "    process.emit('SIGTERM')",
+    '  }, 20)',
+    '  // Echo the mounted generation so the hot-reload e2e can assert both an',
+    '  // applied override and its removal reverting to this bundle default.',
+    "  writeFileSync(join(process.env.DSH_HOME, 'config-echo'), String(config.generation ?? 'bundle-default'))",
+    "  writeFileSync(process.env.RAW_READY_FILE, 'ready')",
+    '  void ctx.loader.await().then(() => {',
+    "    if (active) writeFileSync(process.env.RAW_SETTLED_FILE, 'settled')",
+    '  })',
+    '  ctx.effect(() => () => {',
+    '    active = false',
+    '    clearInterval(heartbeat)',
+    "    writeFileSync(process.env.RAW_DISPOSED_FILE, 'disposed')",
+    '  })',
+    '}',
+    '',
+  ].join('\n'))
+  writeFileSync(join(bundleDir, 'cordis.patch.yml'), [
+    '- insert:',
+    '    - id: profile-lifecycle-fixture',
+    `      name: ${pathToFileURL(join(bundleDir, 'plugin.mjs')).href}`,
+    '',
+  ].join('\n'))
+  writeFileSync(join(bundleDir, 'package.json'), JSON.stringify({
+    name: 'dsh-lifecycle-bundle',
+    version: '0.0.0',
+    type: 'module',
+    dsh: { bundle: { patch: './cordis.patch.yml' } },
+  }, undefined, 2))
+  const profileDir = join(home, 'profiles', 'lifecycle')
+  mkdirSync(join(profileDir, 'node_modules'), { recursive: true })
+  writeFileSync(join(profileDir, 'package.json'), JSON.stringify({
+    name: 'dsh-profile-lifecycle',
+    private: true,
+    dependencies: {},
+    dsh: { profile: { bundles: ['dsh-lifecycle-bundle'] } },
+  }, undefined, 2))
+  // Hand-place the "installed" bundle where profile resolution finds it.
+  writeFileSync(join(profileDir, 'cordis.patch.yml'), '[]\n')
+  const linkTarget = join(profileDir, 'node_modules', 'dsh-lifecycle-bundle')
+  mkdirSync(join(profileDir, 'node_modules'), { recursive: true })
+  try {
+    rmSync(linkTarget, { recursive: true, force: true })
+  } catch { /* fresh dir */ }
+  // Copy-free: a package.json redirecting via a relative main is enough for require.resolve.
+  mkdirSync(linkTarget, { recursive: true })
+  for (const file of ['package.json', 'cordis.patch.yml', 'plugin.mjs']) {
+    writeFileSync(join(linkTarget, file), readFileSync(join(bundleDir, file)))
+  }
+  return { home, ready, settled, disposed, interrupt }
+}
+
+function startProfileLifecycle(fixture: ProfileLifecycleFixture, args: readonly string[] = []) {
+  return execa(process.execPath, [dshBin, '--profile', 'lifecycle', ...args], {
+    cwd: fixture.home,
+    input: '',
+    timeout: SPAWN_TIMEOUT_MS,
+    killSignal: 'SIGKILL',
+    reject: false,
+    env: {
+      DSH_HOME: fixture.home,
+      RAW_READY_FILE: fixture.ready,
+      RAW_SETTLED_FILE: fixture.settled,
+      RAW_DISPOSED_FILE: fixture.disposed,
+      RAW_INTERRUPT_FILE: fixture.interrupt,
+    },
+  })
+}
+
+function requestProfileShutdown(
+  child: Pick<ReturnType<typeof startProfileLifecycle>, 'kill'>,
+  fixture: Pick<ProfileLifecycleFixture, 'interrupt'>,
+): void {
+  if (process.platform === 'win32') {
+    writeFileSync(fixture.interrupt, 'interrupt')
+    return
+  }
+  child.kill('SIGTERM')
+}
+
+function createEnvironmentProbeProfile(home: string, project: string): void {
+  const pluginFile = join(project, 'environment-probe.mjs')
+  writeFileSync(pluginFile, [
+    "export const name = 'environment-probe'",
+    "export const inject = ['llm']",
+    'export function apply(ctx) {',
+    '  void ctx.loader.await().then(async () => {',
+    "    let text = ''",
+    '    for await (const chunk of ctx.llm.stream({',
+    "      provider: 'deepseek-official',",
+    "      model: 'deepseek-v4-flash',",
+    '      messages: [],',
+    '      maxTokens: 32,',
+    '    })) {',
+    "      if (chunk.type === 'text-delta') text += chunk.text",
+    '    }',
+    '    process.stdout.write(`${text}\\n`)',
+    "    if (process.platform === 'win32') process.emit('SIGTERM')",
+    "    else process.kill(process.pid, 'SIGTERM')",
+    '  })',
+    '}',
+    '',
+  ].join('\n'))
+  const profileDir = join(home, 'profiles', 'environment-probe')
+  mkdirSync(profileDir, { recursive: true })
+  writeFileSync(join(profileDir, 'package.json'), JSON.stringify({
+    name: 'dsh-profile-environment-probe',
+    private: true,
+    dependencies: {},
+    dsh: { profile: { bundles: ['@deepseek-ai/dsh-base'] } },
+  }, undefined, 2))
+  writeFileSync(join(profileDir, 'cordis.patch.yml'), [
+    '- insert:',
+    '    - id: environment-probe',
+    `      name: ${pathToFileURL(pluginFile).href}`,
+    '',
+  ].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')",
+    "  program.action(() => ctx.provide('fixtureStartup', { generation: program.opts().generation }))",
+    '  parseCmdline(ctx, program)',
+    '}',
+    '',
+  ].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: SPAWN_TIMEOUT_MS,
+    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 removed commands', async () => {
+    const bare = await runBuiltBin()
+    expect(bare.code).toBe(1)
+    expect(bare.stdout).toBe('')
+    expect(bare.stderr).toContain('--profile <name> is required')
+    const help = await runBuiltBin(['--help'])
+    expect(help.code).toBe(0)
+    expect(help.stdout).toContain('dsh --profile web')
+    expect(help.stdout).toContain('dsh plugin --profile')
+    expect(help.stdout).not.toMatch(/^\s+(?:tui|meta|upgrade)\b/mu)
+    for (const removed of [['tui'], ['--config', 'x.yml'], ['-p', 'task'], ['run', 'task']]) {
+      const result = await runBuiltBin(removed)
+      expect(result.code).toBe(1)
+    }
+  }, SPAWN_TIMEOUT_MS * 3 + 30_000)
+
+  it('routes help and usage errors without activating startup-dependent rows', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'dsh-app-help-'))
+    try {
+      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 wildcardHost = await runBuiltBin(['web', '--host', '0.0.0.0'], {
+        DSH_HOME: home,
+        DSH_TELEMETRY_DISABLED: '1',
+      })
+      expect(wildcardHost.code).toBe(1)
+      expect(wildcardHost.stdout).toBe('')
+      expect(wildcardHost.stderr).toContain('--host 0.0.0.0 is intentionally not supported yet for safety: it would expose remote code execution to the network; use 127.0.0.1 instead')
+      expect(wildcardHost.stderr).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 sdkHelp = await runBuiltBin(['--profile', 'sdk', '--help'], {
+        DSH_HOME: home,
+        DSH_TELEMETRY_DISABLED: '1',
+      })
+      expect(sdkHelp.code).toBe(0)
+      expect(sdkHelp.stderr).toBe('')
+      expect(sdkHelp.stdout).toContain('Usage: dsh --profile sdk')
+
+      const acpHelp = await runBuiltBin(['--profile', 'acp', '--help'], {
+        DSH_HOME: home,
+        DSH_TELEMETRY_DISABLED: '1',
+      })
+      expect(acpHelp.code).toBe(0)
+      expect(acpHelp.stderr).toBe('')
+      expect(acpHelp.stdout).toContain('Usage: dsh --profile acp')
+
+      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(home, { recursive: true, force: true })
+    }
+  }, SPAWN_TIMEOUT_MS * 3 + 30_000)
+
+  it('ignores an optional SDK plugin import failure before stdin reaches EOF', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'dsh-built-sdk-startup-failure-'))
+    const patch = join(home, 'broken-sdk.cordis.yml')
+    writeFileSync(patch, [
+      '- insert:',
+      '    - id: missing-sdk-startup-plugin',
+      '      name: "@deepseek-ai/dsh-missing-sdk-startup-plugin"',
+      '',
+    ].join('\n'))
+    try {
+      const result = await runBuiltBin(['--profile', 'sdk', '--patch', patch], {
+        DSH_HOME: home,
+        DSH_TELEMETRY_DISABLED: '1',
+        DEEPSEEK_API_KEY: 'built-sdk-startup-failure-no-call',
+      }, home)
+      expect(result.code).toBe(0)
+      expect(result.stdout).toBe('')
+      expect(result.stderr).toContain('warning: 1 entry did not activate')
+      expect(result.stderr).toContain('@deepseek-ai/dsh-missing-sdk-startup-plugin')
+    } finally {
+      rmSync(home, { recursive: true, force: true })
+    }
+  }, SPAWN_TIMEOUT_MS + 30_000)
+
+  it('serves the SDK protocol with an absolute-path overlay plugin and exits after shutdown', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'dsh-built-sdk-'))
+    const pluginPath = join(home, 'plugin #100%.mjs')
+    const marker = join(home, 'plugin-loaded')
+    writeFileSync(pluginPath, [
+      "import { writeFileSync } from 'node:fs'",
+      'export function apply(ctx, config) { writeFileSync(config.marker, "loaded") }',
+      '',
+    ].join('\n'))
+    const patch = join(home, 'absolute.patch.yml')
+    writeFileSync(patch, JSON.stringify([{ insert: [
+      { id: 'absolute-plugin', name: pluginPath, config: { marker } },
+    ] }]))
+    const child = execa(process.execPath, [dshBin, '--profile', 'sdk', '--patch', patch], {
+      cwd: home,
+      reject: false,
+      timeout: SPAWN_TIMEOUT_MS,
+      killSignal: 'SIGKILL',
+      env: {
+        ...process.env,
+        DSH_HOME: home,
+        DSH_TELEMETRY_DISABLED: '1',
+        DEEPSEEK_API_KEY: 'built-sdk-profile-no-call',
+      },
+      extendEnv: false,
+    })
+    const stdoutLines = createInterface({ input: child.stdout, crlfDelay: Infinity })[Symbol.asyncIterator]()
+    let stderr = ''
+    child.stderr.on('data', (chunk: Buffer) => { stderr += chunk.toString('utf8') })
+    const response = async (id: number): Promise<Record<string, unknown>> => {
+      for (;;) {
+        const line = await stdoutLines.next()
+        if (line.done) throw new Error(`SDK profile stdout closed before response ${String(id)}; stderr=${stderr}`)
+        let value: Record<string, unknown>
+        try {
+          value = JSON.parse(line.value) as Record<string, unknown>
+        } catch {
+          throw new Error(`SDK profile wrote non-JSON stdout: ${line.value}`)
+        }
+        if (value.id === id) return value
+      }
+    }
+    try {
+      child.stdin.write(`${JSON.stringify({
+        jsonrpc: '2.0',
+        id: 1,
+        method: 'initialize',
+        params: { cwd: home, provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      })}\n`)
+      const initialized = await response(1)
+      expect(initialized, `${JSON.stringify(initialized)}\n${stderr}`).toMatchObject({
+        jsonrpc: '2.0',
+        id: 1,
+        result: { serverInfo: { name: 'deepseek-harness-sdk-runtime' } },
+      })
+      child.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id: 2, method: 'shutdown' })}\n`)
+      expect(await response(2)).toEqual({ jsonrpc: '2.0', id: 2, result: {} })
+      const result = await child
+      expect(result.timedOut, stderr).toBe(false)
+      expect(result.signal, stderr).toBeUndefined()
+      expect(result.exitCode, stderr).toBe(0)
+      expect(stderr).toBe('')
+      expect(readFileSync(marker, 'utf8')).toBe('loaded')
+    } finally {
+      child.kill('SIGKILL')
+      await child
+      rmSync(home, { recursive: true, force: true })
+    }
+  }, SPAWN_TIMEOUT_MS + 30_000)
+
+  it('runs a mock-backed ACP turn through the acp profile and exits on disconnect', async () => {
+    const apiKey = 'built-acp-profile-key'
+    const server = await startMockLlmServer({
+      sequence: ['success'],
+      apiKey,
+      successText: 'ACP BUILT PROFILE OK',
+    })
+    const home = mkdtempSync(join(tmpdir(), 'dsh-built-acp-'))
+    writeFileSync(join(home, 'settings.yaml'), 'llm-deepseek:\n  protocol: chat-completions\n')
+    const child = execa(process.execPath, [dshBin, '--profile', 'acp'], {
+      cwd: home,
+      reject: false,
+      timeout: SPAWN_TIMEOUT_MS,
+      killSignal: 'SIGKILL',
+      env: {
+        ...process.env,
+        DSH_HOME: home,
+        DSH_TELEMETRY_DISABLED: '1',
+        DEEPSEEK_API_KEY: apiKey,
+        DEEPSEEK_BASE_URL: server.baseURL,
+        DSH_PERMISSION_MODE: 'danger-full-access',
+      },
+      extendEnv: false,
+    })
+    const rawOut: string[] = []
+    const passthrough = new Readable({ read() {} })
+    child.stdout.on('data', (chunk: Buffer) => {
+      rawOut.push(chunk.toString('utf8'))
+      passthrough.push(chunk)
+    })
+    child.stdout.on('end', () => { passthrough.push(null) })
+    const stream = ndJsonStream(
+      Writable.toWeb(child.stdin) as WritableStream<Uint8Array>,
+      Readable.toWeb(passthrough) as ReadableStream<Uint8Array>,
+    )
+    const updates: SessionNotification['update'][] = []
+    const clientApp = createAcpClientApp({ name: 'dsh-built-acp-profile' })
+      .onNotification(methods.client.session.update, ({ params }) => {
+        updates.push(params.update)
+        return Promise.resolve()
+      })
+      .onRequest(methods.client.session.requestPermission, () => {
+        return Promise.resolve({ outcome: { outcome: 'cancelled' } })
+      })
+    const client = clientApp.connect(stream).agent
+    try {
+      const initialized = await client.request(methods.agent.initialize, {
+        protocolVersion: PROTOCOL_VERSION,
+        clientCapabilities: {},
+      })
+      expect(initialized.agentInfo).toMatchObject({ name: 'deepseek-harness-acp' })
+      expect(initialized.agentCapabilities).toEqual({
+        mcpCapabilities: { http: true },
+        promptCapabilities: { image: false, audio: false, embeddedContext: false },
+        sessionCapabilities: { close: {}, list: {}, resume: {} },
+      })
+      expect('_meta' in initialized).toBe(false)
+      const session = await client.request(methods.agent.session.new, { cwd: home, mcpServers: [] })
+      expect(session.sessionId).toBeTruthy()
+      expect(await client.request(methods.agent.session.prompt, {
+        sessionId: session.sessionId,
+        prompt: [{ type: 'text', text: 'reply from the built ACP profile' }],
+      })).toEqual({ stopReason: 'end_turn' })
+      expect(updates).toContainEqual(expect.objectContaining({
+        sessionUpdate: 'agent_message_chunk',
+        content: { type: 'text', text: 'ACP BUILT PROFILE OK' },
+      }))
+      const message = updates.find(update => update.sessionUpdate === 'agent_message_chunk')
+      expect(message !== undefined && 'messageId' in message && typeof message.messageId === 'string').toBe(true)
+      expect(server.requests).toHaveLength(1)
+      child.stdin.end()
+      const result = await child
+      expect(result.exitCode, `signal=${String(result.signal)}; stderr=${result.stderr}`).toBe(0)
+      expect(result.stderr).toBe('')
+      for (const line of rawOut.join('').split('\n').filter(value => value.trim() !== '')) {
+        expect(() => JSON.parse(line) as unknown).not.toThrow()
+      }
+    } finally {
+      child.kill('SIGKILL')
+      await child
+      await server.close()
+      rmSync(home, { recursive: true, force: true })
+    }
+  }, SPAWN_TIMEOUT_MS + 30_000)
+
+  it('runs the headless profile through its app-owned task positional', async () => {
+    const apiKey = 'built-dsh-headless-key'
+    const server = await startMockLlmServer({
+      sequence: ['reasoning_success'],
+      apiKey,
+      reasoningText: 'Inspecting the published entry.',
+      successText: 'published headless profile reached the mock',
+    })
+    const home = mkdtempSync(join(tmpdir(), 'dsh-built-headless-'))
+    writeFileSync(join(home, 'settings.yaml'), 'llm-deepseek:\n  protocol: chat-completions\n')
+    try {
+      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 headless profile reached the mock')
+      expect(result.stderr).toBe('dsh: reasoning:\nInspecting the published entry.')
+      expect(server.requests.length).toBeGreaterThan(0)
+      expect(server.requests.every(request => request.path === '/chat/completions')).toBe(true)
+      expect(JSON.stringify(server.requests.map(request => request.body))).toContain('answer from the published entry')
+    } finally {
+      await server.close()
+      rmSync(home, { recursive: true, force: true })
+    }
+  }, SPAWN_TIMEOUT_MS + 30_000)
+
+  it('does not load a project environment for --version', async () => {
+    const project = mkdtempSync(join(tmpdir(), 'dsh-version-project-'))
+    writeFileSync(join(project, '.env'), 'PATH=/project-only-path\n')
+    try {
+      const result = await runBuiltBin(['--version'], {}, project)
+      expect(result).toEqual({ code: 0, stdout: cliVersion, stderr: '' })
+    } finally {
+      rmSync(project, { recursive: true, force: true })
+    }
+  })
+
+  it.skipIf(process.platform === 'win32')('runs through an installed-style symlink', async () => {
+    const installation = mkdtempSync(join(tmpdir(), 'dsh-bin-link-'))
+    const installedBin = join(installation, 'dsh')
+    symlinkSync(dshBin, installedBin)
+    try {
+      const result = await execa(process.execPath, [installedBin, '--version'], {
+        input: '',
+        timeout: SPAWN_TIMEOUT_MS,
+        killSignal: 'SIGKILL',
+        reject: false,
+      })
+      expect(result.exitCode).toBe(0)
+      expect(result.stdout).toBe(cliVersion)
+      expect(result.stderr).toBe('')
+    } finally {
+      rmSync(installation, { recursive: true, force: true })
+    }
+  })
+
+  it('fails loud on a nonexistent profile with the plugin-command hint', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'dsh-missing-profile-'))
+    try {
+      const result = await runBuiltBin(['--profile', 'nope'], { DSH_HOME: home })
+      expect(result.code).toBe(1)
+      expect(result.stderr).toContain('profile "nope" does not exist')
+      expect(result.stderr).toContain('dsh plugin --profile nope add')
+    } finally {
+      rmSync(home, { recursive: true, force: true })
+    }
+  }, SPAWN_TIMEOUT_MS + 30_000)
+
+  it('creates a custom profile from the shipped web template before booting it', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'dsh-from-default-profile-'))
+    try {
+      const created = await runBuiltBin(
+        ['--profile', 'rescue', '--from-default-profile', 'web', '--help'],
+        { DSH_HOME: home, DSH_TELEMETRY_DISABLED: '1' },
+      )
+      expect(created.code).toBe(0)
+      expect(created.stderr).toBe('')
+      expect(created.stdout).toContain('Usage: dsh --profile web')
+
+      const dir = join(home, 'profiles', 'rescue')
+      const manifest = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')) as {
+        dependencies: Record<string, string>
+        dsh: { profile: { bundles: string[]; patchReload: string } }
+      }
+      expect(manifest.dependencies).toEqual({})
+      expect(manifest.dsh.profile).toEqual({
+        bundles: ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app'],
+        patchReload: 'live',
+      })
+      expect(readFileSync(join(dir, 'cordis.patch.yml'), 'utf8')).toContain('[]')
+      expect(readFileSync(join(dir, 'pnpm-workspace.yaml'), 'utf8')).toContain('nodeLinker: hoisted')
+
+      const repeated = await runBuiltBin(
+        ['--profile', 'rescue', '--from-default-profile', 'web', '--help'],
+        { DSH_HOME: home, DSH_TELEMETRY_DISABLED: '1' },
+      )
+      expect(repeated.code).toBe(1)
+      expect(repeated.stdout).toBe('')
+      expect(repeated.stderr).toContain('profile "rescue" already exists')
+      expect(repeated.stderr).toContain('omit --from-default-profile to use it')
+
+      const reopened = await runBuiltBin(
+        ['--profile', 'rescue', '--help'],
+        { DSH_HOME: home, DSH_TELEMETRY_DISABLED: '1' },
+      )
+      expect(reopened.code).toBe(0)
+      expect(reopened.stderr).toBe('')
+      expect(reopened.stdout).toContain('Usage: dsh --profile web')
+    } finally {
+      rmSync(home, { recursive: true, force: true })
+    }
+  }, SPAWN_TIMEOUT_MS * 3 + 30_000)
+
+  it('keeps a newly created profile when application boot rejects its arguments', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'dsh-from-default-profile-failed-boot-'))
+    try {
+      const failed = await runBuiltBin(
+        ['--profile', 'rescue', '--from-default-profile', 'web', '--port', 'not-a-number'],
+        { DSH_HOME: home, DSH_TELEMETRY_DISABLED: '1' },
+      )
+      expect(failed.code).toBe(1)
+      expect(failed.stderr).toContain('--port must be a number')
+      expect(existsSync(join(home, 'profiles', 'rescue', 'package.json'))).toBe(true)
+
+      const retried = await runBuiltBin(
+        ['--profile', 'rescue', '--help'],
+        { DSH_HOME: home, DSH_TELEMETRY_DISABLED: '1' },
+      )
+      expect(retried.code).toBe(0)
+      expect(retried.stderr).toBe('')
+      expect(retried.stdout).toContain('Usage: dsh --profile web')
+    } finally {
+      rmSync(home, { recursive: true, force: true })
+    }
+  }, SPAWN_TIMEOUT_MS * 2 + 30_000)
+
+  it('uses the launching endpoint and managed credential through the published entry', async () => {
+    const apiKey = 'built-home-layer-key'
+    const server = await startMockLlmServer({
+      sequence: ['success'],
+      apiKey,
+      successText: 'launching endpoint reached the mock',
+    })
+    const home = mkdtempSync(join(tmpdir(), 'dsh-home-environment-'))
+    writeFileSync(join(home, 'settings.yaml'), 'llm-deepseek:\n  protocol: chat-completions\n')
+    const project = mkdtempSync(join(tmpdir(), 'dsh-home-project-'))
+    writeFileSync(join(home, '.credentials.yaml'), `version: 1\nrefs:\n  DEEPSEEK_API_KEY: ${apiKey}\n`, { mode: 0o600 })
+    createEnvironmentProbeProfile(home, project)
+    try {
+      const result = await runBuiltBin(
+        ['--profile', 'environment-probe'],
+        {
+          DSH_HOME: home,
+          DSH_TELEMETRY_DISABLED: '1',
+          DEEPSEEK_API_KEY: undefined,
+          DEEPSEEK_BASE_URL: server.baseURL,
+        },
+        project,
+      )
+      expect(
+        result.code,
+        `${result.stderr}\nstdout:\n${result.stdout}\nmock requests: ${String(server.requests.length)}`,
+      ).toBe(0)
+      expect(result.stdout).toBe('launching endpoint reached the mock')
+      expect(result.stdout).not.toContain(apiKey)
+      expect(result.stderr).not.toContain(apiKey)
+      expect(server.requests).toHaveLength(1)
+      expect(server.requests[0]?.path).toBe('/chat/completions')
+      expect(server.requests[0]?.headers.authorization).toBe(`Bearer ${apiKey}`)
+      expect(JSON.stringify(server.requests[0]?.body)).not.toContain(apiKey)
+    } finally {
+      await server.close()
+      rmSync(home, { recursive: true, force: true })
+      rmSync(project, { recursive: true, force: true })
+    }
+  }, SPAWN_TIMEOUT_MS + 30_000)
+
+  it('keeps serving when an optional patch-overlay plugin fails', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'dsh-invalid-patch-'))
+    try {
+      const result = await runBuiltBin(['--profile', 'web', '--patch', invalidProvider, '--port', '0', '--no-open'], {
+        DSH_HOME: home,
+        DSH_BROWSER_OPEN_TEST_EXIT_ON_READY: '1',
+        DEEPSEEK_API_KEY: 'keyless-invalid-config',
+        DSH_TELEMETRY_DISABLED: '1',
+        NODE_OPTIONS: `--import=${webReadyExitHook}`,
+      })
+      expect(result.code, result.stderr).toBe(0)
+      expect(result.stdout).toMatch(/^dsh web: http:\/\/127\.0\.0\.1:\d+\/\?token=[A-Za-z0-9_-]+$/u)
+      expect(result.stderr).toContain('llm-pi-ai')
+    } finally {
+      rmSync(home, { recursive: true, force: true })
+    }
+  }, SPAWN_TIMEOUT_MS + 30_000)
+
+  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, ['--unclaimed'])
+    try {
+      await waitForFile(fixture.ready)
+      requestProfileShutdown(child, fixture)
+      const result = await child
+      expect(result.exitCode, `${result.stderr}\nstdout:\n${result.stdout}\nsignal: ${String(result.signal)}`).toBe(0)
+      expect(result.signal).toBeUndefined()
+      expect(existsSync(fixture.disposed)).toBe(true)
+    } finally {
+      child.kill('SIGKILL')
+      rmSync(fixture.home, { recursive: true, force: true })
+    }
+  }, SPAWN_TIMEOUT_MS + 30_000)
+
+  it('fully settles a custom profile, hot-reloads its patch layer with removal reverting, and disposes on a signal', async () => {
+    const fixture = createProfileLifecycleFixture()
+    const child = startProfileLifecycle(fixture)
+    const profilePatch = join(fixture.home, 'profiles', 'lifecycle', 'cordis.patch.yml')
+    const configFile = join(fixture.home, 'config-echo')
+    try {
+      await waitForFile(fixture.settled)
+      // The live profile layer: even without an hmr row in the composition,
+      // the launcher mounts a config-only watcher, so an edited
+      // cordis.patch.yml lands in the running tree (the reload disposes the
+      // patched row's old fiber — observable as the disposed marker — and
+      // mounts the new config, which echoes its generation and re-writes the
+      // ready marker).
+      rmSync(fixture.ready)
+      writeFileSync(profilePatch, [
+        '- id: profile-lifecycle-fixture',
+        '  config:',
+        '    generation: 2',
+        '',
+      ].join('\n'))
+      await waitForFile(fixture.ready)
+      expect(readFileSync(configFile, 'utf8')).toBe('2')
+      // Unlink exercises layer removal without racing Chokidar's change-event
+      // suppression window after the preceding edit. The bundle default must return.
+      rmSync(fixture.ready)
+      rmSync(profilePatch)
+      await waitForFile(fixture.ready)
+      expect(existsSync(profilePatch)).toBe(false)
+      expect(readFileSync(configFile, 'utf8')).toBe('bundle-default')
+      // The home-level user layer ($DSH_HOME/cordis.patch.yml) is live too
+      // and outranks the per-profile layer.
+      rmSync(fixture.ready)
+      writeFileSync(join(fixture.home, 'cordis.patch.yml'), [
+        '- id: profile-lifecycle-fixture',
+        '  config:',
+        '    generation: home',
+        '',
+      ].join('\n'))
+      await waitForFile(fixture.ready)
+      expect(readFileSync(configFile, 'utf8')).toBe('home')
+      requestProfileShutdown(child, fixture)
+      const result = await child
+      expect(result.exitCode, `${result.stderr}\nstdout:\n${result.stdout}\nsignal: ${String(result.signal)}`).toBe(0)
+      expect(result.signal).toBeUndefined()
+      expect(existsSync(fixture.disposed)).toBe(true)
+    } finally {
+      child.kill('SIGKILL')
+      await child
+      rmSync(fixture.home, { recursive: true, force: true })
+    }
+  }, SPAWN_TIMEOUT_MS + 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 })
+    }
+  }, SPAWN_TIMEOUT_MS + 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')
+      expect(existsSync(join(fixture.home, 'profiles', 'node_modules'))).toBe(true)
+      requestProfileShutdown(child, fixture)
+      expect((await child).exitCode).toBe(0)
+    } finally {
+      child.kill('SIGKILL')
+      rmSync(fixture.home, { recursive: true, force: true })
+    }
+  }, SPAWN_TIMEOUT_MS + 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 })
+    }
+  }, SPAWN_TIMEOUT_MS + 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 })
+    }
+  }, SPAWN_TIMEOUT_MS + 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 `.`
+    // would self-link the profile.
+    const home = mkdtempSync(join(tmpdir(), 'dsh-plugin-anchor-'))
+    const checkout = mkdtempSync(join(tmpdir(), 'dsh-plugin-checkout-'))
+    try {
+      writeFileSync(join(checkout, 'package.json'), JSON.stringify({
+        name: 'anchored-bundle',
+        version: '1.0.0',
+        dsh: { bundle: { patch: './cordis.patch.yml' } },
+      }))
+      writeFileSync(join(checkout, 'cordis.patch.yml'), '[]\n')
+      const result = await execa(process.execPath, [dshBin, 'plugin', '--profile', 'anchor', 'add', '.'], {
+        cwd: checkout,
+        input: '',
+        timeout: SPAWN_TIMEOUT_MS,
+        killSignal: 'SIGKILL',
+        reject: false,
+        env: { DSH_HOME: home },
+      })
+      expect(result.exitCode).toBe(0)
+      const manifest = JSON.parse(readFileSync(join(home, 'profiles', 'anchor', 'package.json'), 'utf8')) as {
+        dependencies: Record<string, string>
+        dsh: { profile: { bundles: string[] } }
+      }
+      expect(Object.keys(manifest.dependencies)).toEqual(['anchored-bundle'])
+      expect(manifest.dsh.profile.bundles).toContain('anchored-bundle')
+
+      const removed = await runBuiltBin(
+        ['plugin', '--profile', 'anchor', 'remove', 'anchored-bundle'],
+        { DSH_HOME: home },
+        checkout,
+      )
+      expect(removed.code).toBe(0)
+      const afterRemove = JSON.parse(
+        readFileSync(join(home, 'profiles', 'anchor', 'package.json'), 'utf8'),
+      ) as {
+        dependencies?: Record<string, string>
+        dsh: { profile: { bundles: string[] } }
+      }
+      expect(Object.keys(afterRemove.dependencies ?? {})).toEqual([])
+      expect(afterRemove.dsh.profile.bundles).not.toContain('anchored-bundle')
+    } finally {
+      rmSync(home, { recursive: true, force: true })
+      rmSync(checkout, { recursive: true, force: true })
+    }
+  }, SPAWN_TIMEOUT_MS * 2 + 30_000)
+
+  it('activates a dependency that gained dsh.bundle in a later update', async () => {
+    // Reconcile runs against the INSTALLED state on every successful pnpm
+    // run, so `update` (not only `add`) activates a package whose newer
+    // version declares dsh.bundle. Simulated without a registry: hand-place
+    // the installed package, flip its manifest, and run a benign pnpm verb.
+    const home = mkdtempSync(join(tmpdir(), 'dsh-plugin-update-'))
+    try {
+      const profileDir = join(home, 'profiles', 'up')
+      const installed = join(profileDir, 'node_modules', 'late-bundle')
+      mkdirSync(installed, { recursive: true })
+      writeFileSync(join(profileDir, 'package.json'), JSON.stringify({
+        name: 'dsh-profile-up',
+        private: true,
+        dependencies: { 'late-bundle': 'file:./late-bundle' },
+        dsh: { profile: { bundles: ['@deepseek-ai/dsh-base'] } },
+      }))
+      writeFileSync(join(profileDir, 'cordis.patch.yml'), '[]\n')
+      // v1: no dsh manifest — a plain dependency.
+      writeFileSync(join(installed, 'package.json'), JSON.stringify({ name: 'late-bundle', version: '1.0.0' }))
+      const first = await runBuiltBin(['plugin', '--profile', 'up', 'root'], { DSH_HOME: home })
+      expect(first.code).toBe(0)
+      let manifest = JSON.parse(readFileSync(join(profileDir, 'package.json'), 'utf8')) as { dsh: { profile: { bundles: string[] } } }
+      expect(manifest.dsh.profile.bundles).toEqual(['@deepseek-ai/dsh-base'])
+      // v2: the installed package now declares dsh.bundle (an update landed).
+      writeFileSync(join(installed, 'package.json'), JSON.stringify({
+        name: 'late-bundle', version: '2.0.0', dsh: { bundle: { patch: './cordis.patch.yml' } },
+      }))
+      writeFileSync(join(installed, 'cordis.patch.yml'), '[]\n')
+      const second = await runBuiltBin(['plugin', '--profile', 'up', 'root'], { DSH_HOME: home })
+      expect(second.code).toBe(0)
+      manifest = JSON.parse(readFileSync(join(profileDir, 'package.json'), 'utf8')) as { dsh: { profile: { bundles: string[] } } }
+      expect(manifest.dsh.profile.bundles).toEqual(['@deepseek-ai/dsh-base', 'late-bundle'])
+    } finally {
+      rmSync(home, { recursive: true, force: true })
+    }
+  }, SPAWN_TIMEOUT_MS * 2 + 30_000)
+
+  describe('config dump', () => {
+    let home: string
+    beforeEach(() => { home = mkdtempSync(join(tmpdir(), 'dsh-dump-bin-')) })
+    afterEach(() => { rmSync(home, { recursive: true, force: true }) })
+
+    it('prints the web profile bundle layers without a user layer', async () => {
+      const { stdout, code, stderr } = await runBuiltBin(['--profile', 'web', '--dump-default-config'], { DSH_HOME: home })
+      expect(code).toBe(0)
+      expect(stderr).toBe('')
+      expect(stdout).toContain("name: '@deepseek-ai/dsh-agent-loop'")
+      expect(stdout).toContain('agents: []')
+      expect(stdout).toContain('# == @deepseek-ai/dsh-base')
+      expect(stdout).toContain("name: '@deepseek-ai/dsh-host-webserver'")
+      expect(existsSync(join(home, 'profiles', 'node_modules'))).toBe(false)
+    }, SPAWN_TIMEOUT_MS + 30_000)
+
+    it('creates a custom profile from a shipped template before printing it', async () => {
+      const { stdout, code, stderr } = await runBuiltBin(
+        ['--profile', 'rescue', '--from-default-profile', 'web', '--dump-default-config'],
+        { DSH_HOME: home },
+      )
+      expect(code).toBe(0)
+      expect(stderr).toBe('')
+      expect(stdout).toContain('# == @deepseek-ai/dsh-web-app')
+      expect(existsSync(join(home, 'profiles', 'rescue', 'package.json'))).toBe(true)
+    }, SPAWN_TIMEOUT_MS + 30_000)
+
+    it('rejects an unknown source before creating the target profile', async () => {
+      const { stdout, code, stderr } = await runBuiltBin(
+        ['--profile', 'rescue', '--from-default-profile', 'unknown', '--dump-default-config'],
+        { DSH_HOME: home },
+      )
+      expect(code).toBe(1)
+      expect(stdout).toBe('')
+      expect(stderr).toContain('unknown default profile "unknown"')
+      expect(stderr).toContain('"web"')
+      expect(existsSync(join(home, 'profiles', 'rescue'))).toBe(false)
+    }, SPAWN_TIMEOUT_MS + 30_000)
+
+    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-headless'")
+      expect(stdout).not.toMatch(/name: '@deepseek-ai\/dsh-host-/)
+      expect(stdout).not.toContain("name: '@deepseek-ai/dsh-web-app'")
+      expect(stdout).not.toMatch(/name: '@deepseek-ai\/dsh-client-/)
+    }, SPAWN_TIMEOUT_MS + 30_000)
+
+    it('prints the exact standalone sdk-minimal tree without dsh-base', async () => {
+      const { stdout, code, stderr } = await runBuiltBin(
+        ['--profile', 'sdk-minimal', '--dump-default-config'],
+        { DSH_HOME: home },
+      )
+      expect(code).toBe(0)
+      expect(stderr).toBe('')
+      const rows = yaml.load(stdout, { schema: entryListSchema }) as Array<{ id?: string; name?: string }>
+      expect(rows.map(row => [row.id, row.name])).toEqual([
+        ['sdk-app-startup', '@deepseek-ai/dsh-sdk-app'],
+        ['sdk-jsonrpc-server', '@deepseek-ai/dsh-sdk-jsonrpc-server'],
+        ['deepseek-llm-api-extensions', '@deepseek-ai/dsh-deepseek-llm-api-extensions'],
+        ['session-log-deepseek', '@deepseek-ai/dsh-session-log-deepseek'],
+        ['plugin-package-inventory-deepseek', '@deepseek-ai/dsh-plugin-package-inventory-deepseek'],
+        ['llm-deepseek', '@deepseek-ai/dsh-llm-deepseek'],
+        ['sandbox', '@deepseek-ai/dsh-sandbox-local'],
+        ['session-projection', '@deepseek-ai/dsh-session-projection'],
+        ['sandbox-policy', '@deepseek-ai/dsh-sandbox-policy'],
+        ['subprocess', '@deepseek-ai/dsh-subprocess-local'],
+        ['pty', '@deepseek-ai/dsh-terminal'],
+        ['terminal-bash', '@deepseek-ai/dsh-terminal-bash'],
+        ['terminal-pwsh', '@deepseek-ai/dsh-terminal-bash'],
+        ['timer', '@deepseek-ai/cordis-plugin-timer'],
+        ['llm', '@deepseek-ai/dsh-llm'],
+        ['session', '@deepseek-ai/dsh-session'],
+        ['session-title', '@deepseek-ai/dsh-session-title'],
+        ['system-prompt', '@deepseek-ai/dsh-system-prompt'],
+        ['tools', '@deepseek-ai/dsh-tools'],
+        ['mcp-resources', '@deepseek-ai/dsh-mcp-resources'],
+        ['agent', '@deepseek-ai/dsh-agent'],
+        ['llm-retry', '@deepseek-ai/dsh-llm-retry'],
+        ['jobs', '@deepseek-ai/dsh-jobs-local'],
+        ['invariants', '@deepseek-ai/dsh-invariants'],
+        ['session-invariant', '@deepseek-ai/dsh-session/invariant'],
+        ['agent-invariant', '@deepseek-ai/dsh-agent/invariant'],
+        ['scope-invariant', '@deepseek-ai/dsh-scope/invariant'],
+        ['agent-loop-invariant', '@deepseek-ai/dsh-agent-loop/invariant'],
+        ['agent-loop', '@deepseek-ai/dsh-agent-loop'],
+        ['persistent-bash', '@deepseek-ai/dsh-tool-bash-persistent'],
+        ['persistent-pwsh', '@deepseek-ai/dsh-tool-pwsh-persistent'],
+        ['sessions', '@deepseek-ai/dsh-session-persistence-jsonl'],
+      ])
+      expect(stdout).toContain('# == @deepseek-ai/dsh-sdk-minimal')
+      expect(stdout).not.toContain('@deepseek-ai/dsh-base')
+      expect(stdout).not.toContain('@deepseek-ai/dsh-web-app')
+    }, SPAWN_TIMEOUT_MS * 2 + 30_000)
+
+    it('composes the profile user layer and a --patch overlay in order', async () => {
+      // Auto-init the web profile first, then write its user layer.
+      const init = await runBuiltBin(['--profile', 'web', '--dump-default-config'], { DSH_HOME: home })
+      expect(init.code).toBe(0)
+      const profilePatch = join(home, 'profiles', 'web', 'cordis.patch.yml')
+      writeFileSync(profilePatch, [
+        '- id: agent-loop',
+        '  config:',
+        '    agents:',
+        '      - id: personal',
+        '        provider: personal-provider',
+        '        model: personal-model',
+        '- id: absent-row',
+        '  config:',
+        '    x: 1',
+        '',
+      ].join('\n'))
+      const overlay = join(home, 'overlay.cordis.yml')
+      writeFileSync(overlay, [
+        '- id: agent-loop',
+        '  config:',
+        '    agents:',
+        '      - id: configured',
+        '        provider: configured-provider',
+        '        model: configured-model',
+        '',
+      ].join('\n'))
+      const { stdout, code, stderr } = await runBuiltBin(
+        ['--profile', 'web', '--patch', overlay, '--dump-config'],
+        { DSH_HOME: home },
+      )
+      expect(code).toBe(0)
+      expect(stdout).toContain('provider: configured-provider')
+      expect(stdout).not.toContain('personal-provider')
+      // Both layers patched the row; the comment lists them in application order.
+      expect(stdout).toContain(`patched by ${profilePatch}, ${overlay}`)
+      expect(stderr).toContain('patch: entry "absent-row" not found')
+    }, SPAWN_TIMEOUT_MS * 2 + 30_000)
+  })
+})

apps/cli/tests/dsh-badge.expected.e2e.ts

@@ -0,0 +1,176 @@
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
+const binScript = fileURLToPath(new URL('./fixtures/dsh-badge/snapshot.ts', import.meta.url))
+const configPath = fileURLToPath(new URL('./fixtures/dsh-badge/cordis.yml', import.meta.url))
+const defaultConfigPath = fileURLToPath(new URL('./fixtures/dsh-badge/default.cordis.yml', import.meta.url))
+const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
+const badgeAssetsPath = fileURLToPath(new URL('../../../packages/skill/skill-badge/assets/', import.meta.url))
+
+describe('dsh badge assembled snapshot', () => {
+  it('advertises and loads the opt-in bundled skill through the shipped app', async () => {
+    const disabled = await runLoaderSmoke({
+      label: 'disabled dsh badge skill snapshot',
+      tempDirPrefix: 'headless-snapshot-dsh-badge-disabled-',
+      binScript,
+      libBinScript: binScript,
+      configPath: defaultConfigPath,
+      tsconfigPath,
+    })
+    const enabled = await runLoaderSmoke({
+      label: 'dsh badge skill snapshot',
+      tempDirPrefix: 'headless-snapshot-dsh-badge-',
+      binScript,
+      libBinScript: binScript,
+      configPath,
+      tsconfigPath,
+    })
+    const disabledSnapshot = JSON.parse(disabled.stdout) as unknown
+    const enabledSnapshot = JSON.parse(
+      enabled.stdout.replaceAll(badgeAssetsPath, '{{badgeAssetsPath}}'),
+    ) as unknown
+
+    expect(disabled.stderr).toBe('')
+    expect(enabled.stderr).toBe('')
+    expect(disabledSnapshot).toMatchInlineSnapshot(`
+      {
+        "catalog": null,
+        "result": {
+          "content": [
+            {
+              "text": "Error: skill "dsh-badge" is unknown or no longer available",
+              "type": "text",
+            },
+          ],
+          "error": {
+            "message": "skill "dsh-badge" is unknown or no longer available",
+          },
+          "isError": true,
+        },
+        "summary": null,
+      }
+    `)
+    expect(enabledSnapshot).toMatchInlineSnapshot(`
+      {
+        "catalog": [
+          {
+            "text": "<system-reminder>
+      A skill is a reusable set of task-specific instructions. The following skills are available in this session:
+
+      <available_skills>
+      - \`dsh-badge\`: Add the official “powered by dsh” badge to documents, pull requests, merge requests, and other content produced with DeepSeek Harness. Use whenever creating a pull request or merge request. Also use when the user asks for a dsh badge, powered-by-dsh attribution, or a reusable dsh badge asset or snippet.
+      </available_skills>
+
+      If the user names a skill, or the task clearly matches a skill's description, call the \`skill\` tool with the exact skill name before taking task actions. Load all applicable skills, then follow their full instructions. This catalog contains summaries only; do not infer or follow a skill's instructions until it has been loaded.
+      A user may also invoke a skill directly; its <skill_content> block then appears in this conversation. Follow it, and do not call the \`skill\` tool again for that skill.
+      </system-reminder>",
+            "type": "text",
+          },
+        ],
+        "result": {
+          "content": [
+            {
+              "text": "<skill_content name="dsh-badge">
+      <skill_resources>
+      Base directory for this skill: {{badgeAssetsPath}}
+      Resolve relative paths mentioned by this skill against the base directory before using them. Load referenced resources only as needed.
+      </skill_resources>
+
+      <skill_instructions>
+      # dsh Badge
+
+      Add the official “powered by dsh” badge without recreating or restyling it.
+
+      ## Assets
+
+      - Local PNG: [\`dsh-badge.png\`](dsh-badge.png), 726×120 source image; render at 121×20
+      - Shields.io image URL: \`https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white\`
+      - Project URL: \`https://github.com/deepseek-ai/deepseek-harness\`
+
+      ## Markdown
+
+      Use this linked badge in Markdown:
+
+      \`\`\`markdown
+      [![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)
+      \`\`\`
+
+      If attribution should not be linked, use:
+
+      \`\`\`markdown
+      ![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)
+      \`\`\`
+
+      ## Usage rules
+
+      - For GitHub or GitLab Markdown, use the Shields.io URL and link it to the project URL unless the user asks for an unlinked image.
+      - For Feishu and other systems that import remote images unreliably, upload \`dsh-badge.png\` from this skill directory instead of generating another badge.
+      - Preserve the badge's 121×20 dimensions and aspect ratio.
+      - Place the badge at the end of the attributed document or section unless the user specifies another position.
+      - Do not substitute another color, logo, label, or project URL.
+
+      </skill_instructions>
+      </skill_content>",
+              "type": "text",
+            },
+          ],
+          "isError": false,
+          "value": {
+            "content": "# dsh Badge
+
+      Add the official “powered by dsh” badge without recreating or restyling it.
+
+      ## Assets
+
+      - Local PNG: [\`dsh-badge.png\`](dsh-badge.png), 726×120 source image; render at 121×20
+      - Shields.io image URL: \`https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white\`
+      - Project URL: \`https://github.com/deepseek-ai/deepseek-harness\`
+
+      ## Markdown
+
+      Use this linked badge in Markdown:
+
+      \`\`\`markdown
+      [![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)](https://github.com/deepseek-ai/deepseek-harness)
+      \`\`\`
+
+      If attribution should not be linked, use:
+
+      \`\`\`markdown
+      ![](https://img.shields.io/badge/powered_by-dsh-4D6BFE?style=flat-square&logo=deepseek&logoColor=white)
+      \`\`\`
+
+      ## Usage rules
+
+      - For GitHub or GitLab Markdown, use the Shields.io URL and link it to the project URL unless the user asks for an unlinked image.
+      - For Feishu and other systems that import remote images unreliably, upload \`dsh-badge.png\` from this skill directory instead of generating another badge.
+      - Preserve the badge's 121×20 dimensions and aspect ratio.
+      - Place the badge at the end of the attributed document or section unless the user specifies another position.
+      - Do not substitute another color, logo, label, or project URL.
+      ",
+            "name": "dsh-badge",
+            "provider": "dsh-badge",
+            "resourceBase": {
+              "kind": "directory",
+              "path": "{{badgeAssetsPath}}",
+            },
+          },
+        },
+        "summary": {
+          "description": "Add the official “powered by dsh” badge to documents, pull requests, merge requests, and other content produced with DeepSeek Harness. Use whenever creating a pull request or merge request. Also use when the user asks for a dsh badge, powered-by-dsh attribution, or a reusable dsh badge asset or snippet.",
+          "invocation": {
+            "modelInvocable": true,
+            "userInvocable": true,
+          },
+          "name": "dsh-badge",
+          "provider": "dsh-badge",
+          "resourceBase": {
+            "kind": "directory",
+            "path": "{{badgeAssetsPath}}",
+          },
+          "source": "bundled",
+        },
+      }
+    `)
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS * 2)
+})

apps/cli/tests/github-webhook-real.e2e.ts

@@ -0,0 +1,467 @@
+/** Real CLI and DeepSeek evidence for a GitHub webhook-created Session. */
+
+import type { ChildProcess } from 'node:child_process'
+import { spawn } from 'node:child_process'
+import { createHmac, randomUUID } from 'node:crypto'
+import { existsSync } from 'node:fs'
+import { mkdir, mkdtemp, realpath, rm } from 'node:fs/promises'
+import { createServer } from 'node:net'
+import type { AddressInfo } from 'node:net'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { setTimeout as delay } from 'node:timers/promises'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import WebSocket from 'ws'
+
+const REPO_ROOT = fileURLToPath(new URL('../../..', import.meta.url))
+const BUILT_BIN = join(REPO_ROOT, 'apps/cli/lib/bin.js')
+const OVERLAY = fileURLToPath(new URL(
+  './fixtures/github-webhook/cordis.yml',
+  import.meta.url,
+))
+const SECRET = 'github-webhook-real-e2e-secret'
+const DELIVERY = 'github-webhook-real-e2e-delivery'
+const MARKER = 'DSH_GITHUB_WEBHOOK_REAL_E2E_OK'
+const TITLE = 'GitHub webhook real e2e'
+const authenticatedCookies = new Map<string, Promise<{ origin: string; cookie: string }>>()
+
+/** Exchange the printed process token once for Node-side API probes. */
+function authenticatedWeb(launchUrl: string): Promise<{ origin: string; cookie: string }> {
+  const existing = authenticatedCookies.get(launchUrl)
+  if (existing !== undefined) return existing
+  const exchange = (async () => {
+    const response = await fetch(launchUrl, { redirect: 'manual' })
+    const setCookie = response.headers.get('set-cookie')
+    if (response.status !== 303 || setCookie === null) {
+      throw new Error(`dsh web authentication returned HTTP ${String(response.status)}`)
+    }
+    return { origin: new URL(launchUrl).origin, cookie: setCookie.split(';', 1)[0]! }
+  })()
+  authenticatedCookies.set(launchUrl, exchange)
+  return exchange
+}
+
+interface SessionList {
+  items: Array<{
+    sessionId: string
+    cwd?: string
+    blank: boolean
+    projections?: { values: { agentPreset?: string | null } }
+  }>
+}
+
+interface WorkspaceBaseline {
+  items: Array<{
+    path: string
+    sessionIds: string[]
+  }>
+}
+
+interface HistoryPage {
+  records: Array<{ type: 'event'; event: HistoryEvent }>
+  hasMore: boolean
+}
+
+interface HistoryEvent {
+  type: string
+  data: unknown
+}
+
+interface ProcessObservation {
+  readonly ready: Promise<string>
+  readonly text: () => string
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+/** Capture bounded process output and resolve the public Web URL after settled boot. */
+function observeProcess(child: ChildProcess): ProcessObservation {
+  let output = ''
+  let settled = false
+  let resolveReady!: (url: string) => void
+  let rejectReady!: (error: Error) => void
+  const ready = new Promise<string>((resolve, reject) => {
+    resolveReady = resolve
+    rejectReady = reject
+  })
+  const timer = setTimeout(() => {
+    if (!settled) rejectReady(new Error(`dsh web did not become ready within 90s:\n${output}`))
+  }, 90_000)
+  timer.unref()
+  const append = (chunk: Buffer | string): void => {
+    output = `${output}${String(chunk)}`.slice(-100_000)
+    const match = /dsh web: (http:\/\/[^\s]+)/u.exec(output)
+    if (settled || match?.[1] === undefined) return
+    settled = true
+    clearTimeout(timer)
+    resolveReady(match[1].replace('0.0.0.0', '127.0.0.1'))
+  }
+  child.stdout?.on('data', append)
+  child.stderr?.on('data', append)
+  child.once('error', (error) => {
+    if (!settled) rejectReady(error)
+  })
+  child.once('exit', (code) => {
+    if (!settled) rejectReady(new Error(`dsh web exited before readiness (code ${String(code)}):\n${output}`))
+  })
+  return { ready, text: () => output }
+}
+
+/** Reserve and release one loopback port for the isolated webhook listener. */
+async function freePort(): Promise<number> {
+  const server = createServer()
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', resolve)
+  })
+  const port = (server.address() as AddressInfo).port
+  await new Promise<void>((resolve, reject) => {
+    server.close((error) => {
+      if (error === undefined) resolve()
+      else reject(error)
+    })
+  })
+  return port
+}
+
+/** Invoke one public Remote method over its HTTP carrier. */
+async function remoteRpc<T>(baseUrl: string, endpoint: string, args: object): Promise<T> {
+  const authenticated = await authenticatedWeb(baseUrl)
+  const response = await fetch(`${authenticated.origin}/api/${endpoint}`, {
+    method: 'POST',
+    headers: { 'content-type': 'application/json', cookie: authenticated.cookie },
+    body: JSON.stringify({
+      type: 'client-request',
+      rpcId: `github-webhook-real-${endpoint}-${randomUUID()}`,
+      method: endpoint,
+      payload: { args },
+    }),
+  })
+  if (!response.ok) {
+    throw new Error(`${endpoint} returned HTTP ${String(response.status)}: ${await response.text()}`)
+  }
+  const envelope = await response.json() as {
+    result: { ok: true; value: T } | { ok: false; error: { code: string; message: string } }
+  }
+  if (!envelope.result.ok) {
+    throw new Error(`${endpoint} failed: ${envelope.result.error.code}: ${envelope.result.error.message}`)
+  }
+  return envelope.result.value
+}
+
+/** Read one opening item from a public Remote stream. */
+async function openingStreamItem(
+  baseUrl: string,
+  endpoint: string,
+  args: object,
+  accepts: (value: unknown) => boolean,
+): Promise<Record<string, unknown>> {
+  const authenticated = await authenticatedWeb(baseUrl)
+  const socket = new WebSocket(`${authenticated.origin.replace(/^http/u, 'ws')}/api/remote.mux`, {
+    headers: { cookie: authenticated.cookie },
+  })
+  const streamId = `github-webhook-real-${endpoint}-${randomUUID()}`
+  try {
+    await new Promise<void>((resolve, reject) => {
+      const cleanup = (): void => {
+        socket.removeEventListener('open', opened)
+        socket.removeEventListener('error', failed)
+        socket.removeEventListener('close', closed)
+      }
+      const opened = (): void => {
+        cleanup()
+        resolve()
+      }
+      const failed = (): void => {
+        cleanup()
+        reject(new Error(`${endpoint} carrier failed before opening`))
+      }
+      const closed = (): void => {
+        cleanup()
+        reject(new Error(`${endpoint} carrier closed before opening`))
+      }
+      socket.addEventListener('open', opened)
+      socket.addEventListener('error', failed)
+      socket.addEventListener('close', closed)
+    })
+    return await new Promise<Record<string, unknown>>((resolve, reject) => {
+      const timer = setTimeout(() => { finish(new Error(`${endpoint} did not publish its opening item`)) }, 10_000)
+      const cleanup = (): void => {
+        clearTimeout(timer)
+        socket.removeEventListener('message', message)
+        socket.removeEventListener('error', failed)
+        socket.removeEventListener('close', closed)
+      }
+      const finish = (error: Error | undefined, value?: Record<string, unknown>): void => {
+        cleanup()
+        if (error !== undefined) reject(error)
+        else if (value === undefined) reject(new Error(`${endpoint} opening item was absent`))
+        else resolve(value)
+      }
+      const message = (event: WebSocket.MessageEvent): void => {
+        try {
+          const text = typeof event.data === 'string'
+            ? event.data
+            : Buffer.isBuffer(event.data) ? event.data.toString('utf8') : undefined
+          if (text === undefined) throw new Error(`${endpoint} published a non-text frame`)
+          const frame: unknown = JSON.parse(text)
+          if (!isRecord(frame) || frame.streamId !== streamId) return
+          if (frame.type === 'error') {
+            finish(new Error(`${endpoint} failed: ${JSON.stringify(frame.error)}`))
+            return
+          }
+          if (frame.type === 'end') {
+            finish(new Error(`${endpoint} ended before its opening item`))
+            return
+          }
+          if (frame.type === 'item' && isRecord(frame.value) && accepts(frame.value)) {
+            finish(undefined, frame.value)
+          }
+        } catch (error) {
+          finish(error instanceof Error ? error : new Error(String(error)))
+        }
+      }
+      const failed = (): void => { finish(new Error(`${endpoint} carrier failed before its opening item`)) }
+      const closed = (): void => { finish(new Error(`${endpoint} carrier closed before its opening item`)) }
+      socket.addEventListener('message', message)
+      socket.addEventListener('error', failed)
+      socket.addEventListener('close', closed)
+      socket.send(JSON.stringify({ type: 'open', streamId, endpoint, payload: { args } }))
+    })
+  } finally {
+    socket.close()
+  }
+}
+
+/** Read the current Workspace baseline from a fresh follow generation. */
+async function workspaceBaseline(baseUrl: string): Promise<WorkspaceBaseline> {
+  const frame = await openingStreamItem(
+    baseUrl,
+    'workspace/follow',
+    {},
+    value => isRecord(value) && value.type === 'baseline' && isRecord(value.value),
+  )
+  return frame.value as WorkspaceBaseline
+}
+
+/** Read the complete opening page from a fresh Session follow generation. */
+async function history(baseUrl: string, sessionId: string): Promise<HistoryPage> {
+  const frame = await openingStreamItem(
+    baseUrl,
+    'session/follow',
+    { request: { address: { kind: 'session', sessionId }, maxMessages: 100 } },
+    value => isRecord(value)
+      && value.type === 'snapshot'
+      && Array.isArray(value.records)
+      && typeof value.hasMore === 'boolean',
+  )
+  return { records: frame.records as HistoryPage['records'], hasMore: frame.hasMore as boolean }
+}
+
+/** Poll a public observation until it satisfies the test's behavior predicate. */
+async function eventually<T>(
+  child: ChildProcess,
+  processOutput: () => string,
+  label: string,
+  probe: () => Promise<T>,
+  accepts: (value: T) => boolean,
+  timeoutMs: number,
+): Promise<T> {
+  const deadline = Date.now() + timeoutMs
+  let lastValue: T | undefined
+  let lastError: unknown
+  while (Date.now() < deadline) {
+    if (child.exitCode !== null) {
+      throw new Error(`dsh web exited while waiting for ${label} (code ${String(child.exitCode)}):\n${processOutput()}`)
+    }
+    try {
+      lastValue = await probe()
+      if (accepts(lastValue)) return lastValue
+    } catch (error) {
+      lastError = error
+    }
+    await delay(300)
+  }
+  throw new Error(
+    `timed out waiting for ${label}; last value=${JSON.stringify(lastValue)}; `
+    + `last error=${String(lastError)}; process output:\n${processOutput()}`,
+  )
+}
+
+/** Return every text block from durable assistant messages. */
+function assistantText(page: HistoryPage): string {
+  const text: string[] = []
+  for (const event of historyEvents(page)) {
+    if (event.type !== 'assistant/message' || !isRecord(event.data) || !isRecord(event.data.message)) continue
+    const content = event.data.message.content
+    if (!Array.isArray(content)) continue
+    for (const block of content) {
+      if (isRecord(block) && block.type === 'text' && typeof block.text === 'string') text.push(block.text)
+    }
+  }
+  return text.join('\n')
+}
+
+/** Read scalar v2 history records for assertions over the public event stream. */
+function historyEvents(page: HistoryPage): HistoryEvent[] {
+  return page.records.map(record => record.event)
+}
+
+/** Stop the spawned CLI through its normal signal path, escalating only on a stuck teardown. */
+async function stop(child: ChildProcess): Promise<void> {
+  if (child.exitCode !== null) return
+  let resolveClosed!: () => void
+  const closed = new Promise<void>((resolve) => { resolveClosed = resolve })
+  child.once('close', resolveClosed)
+  child.kill('SIGTERM')
+  if (await Promise.race([closed.then(() => true), delay(10_000, false, { ref: false })])) return
+  if (child.exitCode === null) child.kill('SIGKILL')
+  await Promise.race([closed, delay(5_000, undefined, { ref: false })])
+}
+
+/** Send the sole synthetic external interaction: one signed GitHub delivery. */
+async function sendGitHubDelivery(origin: string): Promise<Response> {
+  const body = JSON.stringify({
+    action: 'ready_for_review',
+    number: 4242,
+    repository: { full_name: 'deepseek-ai/deepseek-harness' },
+    pull_request: {
+      title: 'Real CLI webhook e2e',
+      html_url: 'https://github.com/deepseek-ai/deepseek-harness/pull/4242',
+      draft: false,
+      user: { login: 'octocat' },
+      base: { ref: 'master', sha: 'aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa' },
+      head: { ref: 'webhook-e2e', sha: 'bbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb' },
+    },
+  })
+  const signature = `sha256=${createHmac('sha256', SECRET).update(body).digest('hex')}`
+  return await fetch(`${origin}/github`, {
+    method: 'POST',
+    headers: {
+      'content-type': 'application/json',
+      'x-github-delivery': DELIVERY,
+      'x-github-event': 'pull_request',
+      'x-hub-signature-256': signature,
+    },
+    body,
+  })
+}
+
+describe.skipIf(!process.env.DEEPSEEK_API_KEY)('GitHub webhook through the real dsh CLI and model', () => {
+  it('creates, attaches, prompts, and completes a Workspace Session', async () => {
+    expect(existsSync(BUILT_BIN), `missing built CLI ${BUILT_BIN}; run pnpm run build:official`).toBe(true)
+    const root = await mkdtemp(join(tmpdir(), 'dsh-github-webhook-real-'))
+    const workspacePath = join(root, 'workspace')
+    await mkdir(workspacePath)
+    const canonicalWorkspacePath = await realpath(workspacePath)
+    const webhookPort = await freePort()
+    const child = spawn(process.execPath, [
+      BUILT_BIN,
+      'web',
+      '--patch', OVERLAY,
+      '--no-open',
+      '--host', '127.0.0.1',
+      '--port', '0',
+    ], {
+      cwd: root,
+      env: {
+        ...process.env,
+        DSH_AGENTS_HOME: join(root, '.agents'),
+        DSH_GITHUB_E2E_MARKER: MARKER,
+        DSH_GITHUB_E2E_WORKSPACE: workspacePath,
+        DSH_GITHUB_WEBHOOK_PORT: String(webhookPort),
+        DSH_GITHUB_WEBHOOK_SECRET: SECRET,
+        DSH_HOME: join(root, '.dsh'),
+        DSH_TELEMETRY_DISABLED: '1',
+      },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    const observation = observeProcess(child)
+
+    try {
+      const baseUrl = await observation.ready
+      const webhookOrigin = `http://127.0.0.1:${String(webhookPort)}`
+
+      expect((await fetch(`${webhookOrigin}/api`)).status).toBe(404)
+      expect((await sendGitHubDelivery(new URL(baseUrl).origin)).status).not.toBe(202)
+      expect((await sendGitHubDelivery(webhookOrigin)).status).toBe(202)
+
+      const workspaces = await eventually(
+        child,
+        observation.text,
+        'one Workspace-attached Session',
+        async () => await workspaceBaseline(baseUrl),
+        value => value.items.some(workspace =>
+          workspace.path === canonicalWorkspacePath && workspace.sessionIds.length === 1),
+        30_000,
+      )
+      const workspace = workspaces.items.find(item => item.path === canonicalWorkspacePath)
+      const sessionId = workspace?.sessionIds[0]
+      if (sessionId === undefined) throw new Error('workspace/follow did not expose the webhook Session')
+
+      const sessions = await remoteRpc<SessionList>(baseUrl, 'session/list', { _request: {} })
+      expect(sessions.items.find(session => session.sessionId === sessionId)).toMatchObject({
+        blank: false,
+        cwd: canonicalWorkspacePath,
+        projections: { values: { agentPreset: 'minimal' } },
+      })
+
+      const admitted = await eventually(
+        child,
+        observation.text,
+        'webhook source, title, and permission events',
+        async () => await history(baseUrl, sessionId),
+        (page) => {
+          const events = historyEvents(page)
+          const title = events.find(event => event.type === 'session/title')
+          const permission = events.find(event =>
+            event.type === 'permission/preset'
+            && isRecord(event.data)
+            && event.data.preset === 'read-only')
+          const message = events.find(event =>
+            event.type === 'user/message'
+            && isRecord(event.data)
+            && isRecord(event.data.source)
+            && event.data.source.kind === 'webhook')
+          return isRecord(title?.data) && title.data.title === TITLE
+            && permission !== undefined
+            && isRecord(message?.data) && isRecord(message.data.source)
+            && message.data.source.provider === 'github'
+            && message.data.source.deliveryId === DELIVERY
+        },
+        30_000,
+      )
+      const webhookMessage = historyEvents(admitted)
+        .find(event => event.type === 'user/message'
+          && isRecord(event.data)
+          && isRecord(event.data.source)
+          && event.data.source.kind === 'webhook')
+      expect(webhookMessage?.data).toMatchObject({
+        content: [{ type: 'text', text: `Reply with exactly ${MARKER} and no other text. Do not call tools.` }],
+        source: {
+          kind: 'webhook',
+          provider: 'github',
+          deliveryId: DELIVERY,
+          ruleId: 'github-real-e2e',
+          source: 'github-real-e2e',
+        },
+      })
+
+      const completed = await eventually(
+        child,
+        observation.text,
+        'a real DeepSeek assistant response',
+        async () => await history(baseUrl, sessionId),
+        page => assistantText(page).includes(MARKER),
+        150_000,
+      )
+      expect(assistantText(completed)).toContain(MARKER)
+    } finally {
+      await stop(child)
+      await rm(root, { recursive: true, force: true })
+    }
+  }, 330_000)
+})

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

@@ -0,0 +1,131 @@
+import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { execa } from 'execa'
+import { describe, expect, it } from 'vitest'
+import { LOADER_SMOKE_TEST_TIMEOUT_MS, resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke'
+
+const dshBinScript = fileURLToPath(new URL('../src/bin.ts', import.meta.url))
+const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
+const neverDisposePlugin = pathToFileURL(
+  fileURLToPath(new URL('./fixtures/never-dispose.mjs', import.meta.url)),
+).href
+
+const POSIX_HEADLESS_PTY_DRIVER = String.raw`
+import errno, json, os, pty, select, signal, sys, time
+node, launch_args_json, launch_env_json, cwd, timeout_seconds = sys.argv[1:]
+env = os.environ.copy()
+env.update(json.loads(launch_env_json))
+pid, fd = pty.fork()
+if pid == 0:
+    os.chdir(cwd)
+    os.execvpe(node, [node, *json.loads(launch_args_json)], env)
+
+markers = [b"dsh-test: never-dispose ready", b"dsh-test: never-dispose started"]
+output = bytearray()
+marker_index = 0
+deadline = time.monotonic() + float(timeout_seconds)
+status = None
+while time.monotonic() < deadline:
+    ready, _, _ = select.select([fd], [], [], 0.05)
+    if ready:
+        try:
+            chunk = os.read(fd, 65536)
+        except OSError as error:
+            if error.errno != errno.EIO:
+                raise
+            chunk = b""
+        if chunk:
+            output.extend(chunk)
+    while marker_index < len(markers) and markers[marker_index] in output:
+        if marker_index == 0:
+            open(os.path.join(cwd, "shutdown-armed"), "w").close()
+        os.write(fd, b"\x03")
+        marker_index += 1
+    waited, candidate = os.waitpid(pid, os.WNOHANG)
+    if waited == pid:
+        status = candidate
+        break
+
+if status is None:
+    os.kill(pid, signal.SIGKILL)
+    _, status = os.waitpid(pid, 0)
+sys.stdout.buffer.write(output)
+if marker_index != len(markers):
+    sys.stderr.write(f"completed {marker_index}/{len(markers)} PTY actions before timeout\n")
+    sys.exit(124)
+actual_exit = os.waitstatus_to_exitcode(status)
+if actual_exit != 130:
+    sys.stderr.write(f"expected exit 130, got {actual_exit}\n")
+    sys.exit(125)
+`
+
+async function runHeadlessPtySmoke(): Promise<string> {
+  const cwd = await mkdtemp(join(tmpdir(), 'dsh-headless-shutdown-'))
+  try {
+    const home = join(cwd, '.dsh')
+    // Pre-initialize the headless profile with the never-dispose row in its
+    // user patch layer (the same file a long-lived profile boot hot-reloads).
+    const profileDir = join(home, 'profiles', 'headless')
+    await mkdir(profileDir, { recursive: true })
+    await writeFile(join(profileDir, 'package.json'), JSON.stringify({
+      name: 'dsh-profile-headless',
+      private: true,
+      dependencies: {},
+      dsh: { profile: { bundles: ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-headless'] } },
+    }, undefined, 2))
+    await writeFile(join(profileDir, 'cordis.patch.yml'), [
+      '- insert:',
+      '    - id: never-dispose',
+      `      name: '${neverDisposePlugin}'`,
+      '',
+    ].join('\n'))
+    const launch = resolveExampleLaunch({
+      srcBin: dshBinScript,
+      configArgs: ['--profile', 'headless', 'never complete'],
+      tsconfigPath,
+      env: {
+        DSH_HOME: home,
+        DSH_AGENTS_HOME: join(cwd, '.agents'),
+        DEEPSEEK_API_KEY: 'keyless-shutdown-no-call',
+        DSH_TELEMETRY_DISABLED: '1',
+        DSH_TEST_SHUTDOWN_ARM_FILE: join(cwd, 'shutdown-armed'),
+      },
+    })
+    const timeoutMs = 15_000
+    const result = await execa('python3', [
+      '-c',
+      POSIX_HEADLESS_PTY_DRIVER,
+      launch.command,
+      JSON.stringify(launch.args),
+      JSON.stringify(launch.env),
+      cwd,
+      String(timeoutMs / 1_000),
+    ], {
+      stdin: 'ignore',
+      timeout: timeoutMs + 5_000,
+      killSignal: 'SIGKILL',
+      reject: false,
+      stripFinalNewline: false,
+    })
+    if (result.timedOut) {
+      throw new Error(`dsh headless PTY driver did not exit. stdout:\n${result.stdout}\nstderr:\n${result.stderr}`)
+    }
+    if (result.failed) {
+      throw new Error(`dsh headless PTY driver exited ${String(result.exitCode)}. stdout:\n${result.stdout}\nstderr:\n${result.stderr}`)
+    }
+    return result.stdout
+  } finally {
+    await rm(cwd, { recursive: true, force: true })
+  }
+}
+
+describe.skipIf(process.platform === 'win32')('headless process shutdown (real Loader tree in a PTY)', () => {
+  it('lets a second Ctrl+C force exit while the first signal is draining', async () => {
+    const output = await runHeadlessPtySmoke()
+    expect(output).not.toContain('dsh: observing at ')
+    expect(output).toContain('dsh-test: never-dispose ready')
+    expect(output).toContain('dsh-test: never-dispose started')
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+})

apps/cli/tests/lazy-search-startup.compat.spec.ts

@@ -0,0 +1,128 @@
+/**
+ * Node 22 startup-output smoke for the shipped Web CLI composition.
+ *
+ * Only the dedicated Node compatibility gate opts this test in after building
+ * both artifacts; ordinary Vitest inventory deterministically skips it.
+ * The child runs built artifacts under plain Node with the real shipped
+ * web profile (dsh-base + dsh-web-app bundle patches, auto-initialized).
+ * Its URL line follows the settled profile boot; SIGTERM then exercises the
+ * shipped quiescent disposer.
+ */
+
+import { spawn } from 'node:child_process'
+import { existsSync } from 'node:fs'
+import { mkdtemp, readFile, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import yaml from 'js-yaml'
+import { describe, expect, it } from 'vitest'
+
+const repoRoot = fileURLToPath(new URL('../../../', import.meta.url))
+const builtBin = join(repoRoot, 'apps/cli/lib/bin.js')
+const webDist = join(repoRoot, 'apps/web/dist/index.html')
+// Full-text session search ships off (`openAt: never` on both layers): the
+// base patch carries the default, and the web restatement must not re-enable it.
+const baseConfigPath = join(repoRoot, 'packages/bundle/base/cordis.patch.yml')
+const webConfigPath = join(repoRoot, 'packages/bundle/web-app/cordis.patch.yml')
+const requireBuiltArtifacts = process.env.DSH_REQUIRE_BUILT_CLI_SMOKE === '1'
+
+interface ConfigRow {
+  id?: string
+  disabled?: unknown
+  config?: { openAt?: unknown }
+}
+
+interface PatchEntry extends ConfigRow {
+  insert?: ConfigRow[]
+}
+
+const jsExprType = new yaml.Type('tag:yaml.org,2002:js', {
+  kind: 'scalar',
+  construct: value => String(value),
+})
+const configSchema = yaml.JSON_SCHEMA.extend(jsExprType)
+
+/** Boot the built Web CLI, wait for its settled URL, then dispose through SIGTERM. */
+function runBuiltWeb(cwd: string): Promise<{ stdout: string; stderr: string; code: number }> {
+  return new Promise((resolveRun, rejectRun) => {
+    const env: NodeJS.ProcessEnv = {
+      ...process.env,
+      DEEPSEEK_API_KEY: 'dsh-cli-smoke-dummy-key',
+      DSH_HOME: join(cwd, '.dsh'),
+    }
+    delete env.DEEPSEEK_BASE_URL
+    delete env.NODE_OPTIONS
+    delete env.NODE_NO_WARNINGS
+    const child = spawn(process.execPath, [
+      builtBin,
+      'web',
+      '--no-open',
+      '--host',
+      '127.0.0.1',
+      '--port',
+      '0',
+    ], {
+      cwd,
+      env,
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    let stdout = ''
+    let stderr = ''
+    let settled = false
+    child.stdout.setEncoding('utf8')
+    child.stderr.setEncoding('utf8')
+    child.stdout.on('data', (chunk: string) => {
+      stdout += chunk
+      if (!settled && /dsh web: http:\/\/127\.0\.0\.1:\d+/u.test(stdout)) {
+        settled = true
+        child.kill('SIGTERM')
+      }
+    })
+    child.stderr.on('data', (chunk: string) => { stderr += chunk })
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL')
+      rejectRun(new Error(`built Web CLI did not settle and dispose within 60s\nstdout:\n${stdout}\nstderr:\n${stderr}`))
+    }, 60_000)
+    child.on('error', (error) => {
+      clearTimeout(timer)
+      rejectRun(error)
+    })
+    child.on('close', (code) => {
+      clearTimeout(timer)
+      if (!settled) {
+        rejectRun(new Error(`built Web CLI exited before settled startup (code ${String(code)})\nstdout:\n${stdout}\nstderr:\n${stderr}`))
+        return
+      }
+      resolveRun({ stdout, stderr, code: code ?? -1 })
+    })
+  })
+}
+
+describe.skipIf(!requireBuiltArtifacts)('built CLI lazy-search startup', () => {
+  it('boots and disposes the shipped composition with full-text search off by default', async () => {
+    expect(existsSync(builtBin), `missing built CLI ${resolve(builtBin)}; run pnpm build`).toBe(true)
+    expect(existsSync(webDist), `missing Web dist ${resolve(webDist)}; run pnpm run build:web`).toBe(true)
+    const baseRows = (yaml.load(await readFile(baseConfigPath, 'utf8'), { schema: configSchema }) as PatchEntry[])
+      .flatMap(entry => entry.insert ?? [entry])
+    const webRows = (yaml.load(await readFile(webConfigPath, 'utf8'), { schema: configSchema }) as PatchEntry[])
+      .flatMap(entry => entry.insert ?? [entry])
+    const baseRow = baseRows.find(row => row.id === 'session-query-sqlite')
+    const webRow = webRows.find(row => row.id === 'session-query-sqlite')
+    expect(baseRow?.config?.openAt).toBe('never')
+    expect(baseRow?.disabled).toBeUndefined()
+    // The web restatement keeps the shipped default; opting in is a later layer's override.
+    expect(webRow?.config?.openAt).toBe('never')
+    expect(webRow?.disabled).toBeUndefined()
+
+    const cwd = await mkdtemp(join(tmpdir(), 'dsh-cli-lazy-search-'))
+    try {
+      const result = await runBuiltWeb(cwd)
+      expect(result.stdout).toMatch(/dsh web: http:\/\/127\.0\.0\.1:\d+/u)
+      expect(result.code).toBe(0)
+      expect(result.stderr).not.toMatch(/ExperimentalWarning: SQLite/u)
+    } finally {
+      await rm(cwd, { recursive: true, force: true })
+    }
+  }, 70_000)
+})

apps/cli/tests/memory-mcp-configs.spec.ts

@@ -0,0 +1,132 @@
+/**
+ * The third-party memory examples stay config-only. This suite parses every
+ * checked-in overlay, verifies its package pin, transport, and secret handling, then replaces
+ * only the upstream endpoint with the package-owned keyless MCP fixture and
+ * proves the real Cordis Loader discovers a tool through the generic bridge.
+ */
+
+import { readFileSync } from 'node:fs'
+import { resolve } from 'node:path'
+import { afterEach, describe, expect, it } from 'vitest'
+import type { Context } from '@deepseek-ai/cordis'
+import type { PatchOptions } from '@deepseek-ai/cordis-plugin-include'
+import { boot, loadOverlayPatches } from '@deepseek-ai/dsh-app-boot'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRuntime from '@deepseek-ai/dsh-tools'
+import * as McpClient from '@deepseek-ai/dsh-mcp-client/src/index.ts'
+
+interface ExampleContract {
+  file: string
+  id: string
+  serverName: string
+  transport: 'stdio' | 'streamable-http'
+  pin: string
+}
+
+interface InsertedRow {
+  id?: string
+  name?: string
+  config?: Record<string, unknown>
+}
+
+const root = resolve(import.meta.dirname, '../../..')
+const exampleDir = resolve(root, 'apps/cli/config/examples/mcp-memory')
+const baseConfig = resolve(import.meta.dirname, 'fixtures/memory-mcp-base.cordis.yml')
+const fixtureServer = resolve(root, 'packages/mcp/mcp-client/tests/fixture-server.ts')
+
+const examples: ExampleContract[] = [
+  {
+    file: 'memorix.cordis.yml',
+    id: 'memory-memorix',
+    serverName: 'memorix',
+    transport: 'stdio',
+    pin: '1.3.0',
+  },
+  {
+    file: 'mcp-reference-memory.cordis.yml',
+    id: 'memory-mcp-reference',
+    serverName: 'reference_memory',
+    transport: 'stdio',
+    pin: '2026.7.4',
+  },
+  {
+    file: 'engram.cordis.yml',
+    id: 'memory-engram',
+    serverName: 'engram',
+    transport: 'stdio',
+    pin: '1.20.0',
+  },
+]
+
+const liveContexts = new Set<Context>()
+
+afterEach(async () => {
+  await Promise.all([...liveContexts].map(async ctx => ctx.fiber.dispose()))
+  liveContexts.clear()
+})
+
+function insertedRow(patches: PatchOptions[]): InsertedRow {
+  expect(patches).toHaveLength(1)
+  const insert = patches[0]?.insert
+  expect(insert).toHaveLength(1)
+  return insert?.[0] as InsertedRow
+}
+
+async function waitForTool(ctx: Context, name: string): Promise<void> {
+  const deadline = Date.now() + 10_000
+  while (!ctx.tools.schemas().some(schema => schema.name === name)) {
+    if (Date.now() >= deadline) throw new Error(`timed out waiting for ${name}`)
+    await new Promise(resolveWait => setTimeout(resolveWait, 25))
+  }
+}
+
+describe('third-party memory MCP example overlays', () => {
+  it.each(examples)('parses $file with the documented generic plugin fields', (contract) => {
+    const file = resolve(exampleDir, contract.file)
+    const source = readFileSync(file, 'utf8')
+    const row = insertedRow(loadOverlayPatches('memory-mcp-config-test', file))
+
+    expect(row.id).toBe(contract.id)
+    expect(row.name).toBe('@deepseek-ai/dsh-mcp-client')
+    expect(row.config?.serverName).toBe(contract.serverName)
+    expect(row.config?.transport).toBe(contract.transport)
+    expect(source.split('\n', 1)[0]).toContain(contract.pin)
+    expect(source).not.toMatch(/\bsk-[A-Za-z0-9_-]{8,}\b/)
+    expect(source).not.toContain('DEEPSEEK_API_KEY')
+  })
+
+  it.each(examples)('loads $file and discovers a keyless fixture tool', async (contract) => {
+    const patches = loadOverlayPatches(
+      'memory-mcp-config-test',
+      resolve(exampleDir, contract.file),
+    )
+    // The static config gate verifies the checked-in bare package specifier.
+    // The unit test maps it to the source module so a clean checkout needs no
+    // prebuilt `lib/` artifacts before proving the Loader/MCP behavior.
+    insertedRow(patches).name = 'cordis:memory-test-mcp-client'
+    const fixturePatch: PatchOptions = {
+      id: contract.id,
+      config: {
+        serverName: contract.serverName,
+        transport: 'stdio',
+        command: process.execPath,
+        args: [fixtureServer],
+        env: {},
+        cwd: root,
+        toolCallTimeoutMs: 5_000,
+      },
+    }
+    const ctx = await boot(
+      'memory-mcp-config-test',
+      baseConfig,
+      [...patches, fixturePatch],
+      (ctx) => {
+        liveContexts.add(ctx)
+        ctx.loader.builtins['memory-test-system-prompt'] = SystemPrompt
+        ctx.loader.builtins['memory-test-tools'] = ToolRuntime
+        ctx.loader.builtins['memory-test-mcp-client'] = McpClient
+      },
+    )
+    await waitForTool(ctx, `mcp__${contract.serverName}__greet`)
+  }, 15_000)
+})

apps/cli/tests/process-shutdown.spec.ts

@@ -0,0 +1,179 @@
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import {
+  createProcessShutdown,
+  PROCESS_SHUTDOWN_TIMEOUT_MS,
+} from '../src/process-shutdown.ts'
+
+function deferred(): { promise: Promise<void>; resolve: () => void; reject: (error: Error) => void } {
+  let resolve!: () => void
+  let reject!: (error: Error) => void
+  const promise = new Promise<void>((accept, fail) => {
+    resolve = accept
+    reject = fail
+  })
+  return { promise, resolve, reject }
+}
+
+afterEach(() => {
+  vi.useRealTimers()
+  vi.restoreAllMocks()
+})
+
+describe('process shutdown', () => {
+  it('completes naturally after disposal resolves and forces exit when it rejects', async () => {
+    const resolvedExit = vi.fn()
+    const resolvedComplete = vi.fn()
+    const resolved = createProcessShutdown(() => Promise.resolve(), resolvedExit, resolvedComplete)
+    await resolved.shutdown(0)
+    expect(resolvedComplete).toHaveBeenCalledOnce()
+    expect(resolvedComplete).toHaveBeenCalledWith(0)
+    expect(resolvedExit).not.toHaveBeenCalled()
+
+    const rejectedExit = vi.fn()
+    const rejectedComplete = vi.fn()
+    const rejected = createProcessShutdown(
+      () => Promise.reject(new Error('dispose failed')),
+      rejectedExit,
+      rejectedComplete,
+    )
+    await rejected.shutdown(1)
+    expect(rejectedExit).toHaveBeenCalledOnce()
+    expect(rejectedExit).toHaveBeenCalledWith(1)
+    expect(rejectedComplete).not.toHaveBeenCalled()
+  })
+
+  it('uses process.exitCode for default normal completion', async () => {
+    const exit = vi.spyOn(process, 'exit').mockImplementation(_code => undefined as never)
+    const originalExitCode = process.exitCode
+    process.exitCode = undefined
+    const shutdown = createProcessShutdown(() => Promise.resolve())
+
+    try {
+      await shutdown.shutdown(7)
+
+      expect(process.exitCode).toBe(7)
+      expect(exit).not.toHaveBeenCalled()
+    } finally {
+      process.exitCode = originalExitCode
+    }
+  })
+
+  it('forces exit when graceful disposal reaches its bound', async () => {
+    vi.useFakeTimers()
+    const disposal = deferred()
+    const exit = vi.fn()
+    const complete = vi.fn()
+    const shutdown = createProcessShutdown(() => disposal.promise, exit, complete)
+    const pending = shutdown.shutdown(0)
+
+    await vi.advanceTimersByTimeAsync(PROCESS_SHUTDOWN_TIMEOUT_MS - 1)
+    expect(exit).not.toHaveBeenCalled()
+    await vi.advanceTimersByTimeAsync(1)
+    expect(exit).toHaveBeenCalledOnce()
+    expect(exit).toHaveBeenCalledWith(0)
+
+    disposal.resolve()
+    await pending
+    expect(exit).toHaveBeenCalledOnce()
+    expect(complete).not.toHaveBeenCalled()
+  })
+
+  it('honors a caller-supplied grace period', async () => {
+    vi.useFakeTimers()
+    const disposal = deferred()
+    const exit = vi.fn()
+    const shutdown = createProcessShutdown(() => disposal.promise, exit, vi.fn(), 25)
+    const pending = shutdown.shutdown(0)
+
+    await vi.advanceTimersByTimeAsync(24)
+    expect(exit).not.toHaveBeenCalled()
+    await vi.advanceTimersByTimeAsync(1)
+    expect(exit).toHaveBeenCalledOnce()
+
+    disposal.resolve()
+    await pending
+  })
+
+  it('lets Ctrl+C force a normal shutdown already stuck in disposal', async () => {
+    const disposal = deferred()
+    const exit = vi.fn()
+    const complete = vi.fn()
+    const shutdown = createProcessShutdown(() => disposal.promise, exit, complete)
+    const pending = shutdown.shutdown(0)
+
+    shutdown.interrupt(130)
+    expect(exit).toHaveBeenCalledOnce()
+    expect(exit).toHaveBeenCalledWith(130)
+
+    disposal.resolve()
+    await pending
+    expect(exit).toHaveBeenCalledOnce()
+    expect(complete).not.toHaveBeenCalled()
+  })
+
+  it('forces exit after disposal started by a signal', async () => {
+    const disposal = deferred()
+    const exit = vi.fn()
+    const complete = vi.fn()
+    const shutdown = createProcessShutdown(() => disposal.promise, exit, complete)
+
+    shutdown.interrupt(143)
+    disposal.resolve()
+    await shutdown.shutdown(0)
+
+    expect(exit).toHaveBeenCalledOnce()
+    expect(exit).toHaveBeenCalledWith(143)
+    expect(complete).not.toHaveBeenCalled()
+  })
+
+  it('drains on the first signal and forces on the second signal', async () => {
+    const disposal = deferred()
+    const dispose = vi.fn(() => disposal.promise)
+    const exit = vi.fn()
+    const shutdown = createProcessShutdown(dispose, exit, vi.fn())
+
+    shutdown.interrupt(143)
+    await Promise.resolve()
+    expect(dispose).toHaveBeenCalledOnce()
+    expect(exit).not.toHaveBeenCalled()
+
+    shutdown.interrupt(130)
+    expect(exit).toHaveBeenCalledOnce()
+    expect(exit).toHaveBeenCalledWith(130)
+
+    disposal.resolve()
+    await shutdown.shutdown(0)
+    expect(exit).toHaveBeenCalledOnce()
+  })
+
+  it('coalesces normal shutdown calls without treating them as escalation', async () => {
+    const disposal = deferred()
+    const exit = vi.fn()
+    const complete = vi.fn()
+    const shutdown = createProcessShutdown(() => disposal.promise, exit, complete)
+
+    const first = shutdown.shutdown(0)
+    const second = shutdown.shutdown(1)
+    expect(second).toBe(first)
+    expect(exit).not.toHaveBeenCalled()
+
+    disposal.resolve()
+    await first
+    expect(complete).toHaveBeenCalledOnce()
+    expect(complete).toHaveBeenCalledWith(0)
+    expect(exit).not.toHaveBeenCalled()
+  })
+
+  it('lets a signal force exit while natural completion drains remaining handles', async () => {
+    const exit = vi.fn()
+    const complete = vi.fn()
+    const shutdown = createProcessShutdown(() => Promise.resolve(), exit, complete)
+
+    await shutdown.shutdown(0)
+    shutdown.interrupt(130)
+
+    expect(complete).toHaveBeenCalledOnce()
+    expect(exit).toHaveBeenCalledOnce()
+    expect(exit).toHaveBeenCalledWith(130)
+  })
+})

apps/cli/tests/profile-hmr.spec.ts

@@ -0,0 +1,46 @@
+/** Module-HMR ownership across the real shipped profile bundle layers. */
+
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { composeEntries, loadOverlayPatches } from '@deepseek-ai/dsh-app-boot'
+import type { PatchOptions } from '@deepseek-ai/cordis-plugin-include'
+
+const REPOSITORY_ROOT = fileURLToPath(new URL('../../../', import.meta.url))
+
+/** Load one shipped bundle patch through the same parser as profile boot. */
+function bundle(name: 'acp-app' | 'base' | 'headless' | 'sdk-app' | 'sdk-minimal' | 'web-app'): PatchOptions[] {
+  return loadOverlayPatches('profile-hmr test', join(REPOSITORY_ROOT, 'packages', 'bundle', name, 'cordis.patch.yml'))
+}
+
+/** Resolve the effective HMR row after the supplied layers. */
+function hmr(layers: PatchOptions[][]) {
+  const row = composeEntries(layers).find(entry => entry.id === 'hmr')
+  if (row === undefined) throw new Error('the base bundle must insert the hmr row')
+  return row
+}
+
+describe('profile module-HMR policy', () => {
+  it.each(['web-app', 'headless', 'sdk-app', 'acp-app'] as const)(
+    '%s inherits the disabled base row without a mode override',
+    (mode) => {
+      const modePatches = bundle(mode)
+      expect(modePatches.some(patch => patch.id === 'hmr')).toBe(false)
+      expect(hmr([bundle('base'), modePatches])).toMatchObject({
+        disabled: true,
+        config: { root: ['.'] },
+      })
+    },
+  )
+
+  it('requires an explicit later layer to enable source-module reload', () => {
+    expect(hmr([bundle('base'), [{ id: 'hmr', disabled: false }]])).toMatchObject({
+      disabled: false,
+      config: { root: ['.'] },
+    })
+  })
+
+  it('keeps the standalone sdk-minimal tree free of module HMR', () => {
+    expect(composeEntries([bundle('sdk-minimal')]).find(entry => entry.id === 'hmr')).toBeUndefined()
+  })
+})

apps/cli/tests/profile-initialization.spec.ts

@@ -0,0 +1,158 @@
+/** One-time custom-profile initialization from shipped templates. */
+
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  initProfile,
+  PROFILE_PATCH_FILENAME,
+  PROFILE_TEMPLATES,
+  readProfileManifest,
+  resolveProfileDir,
+  writeProfileManifest,
+} from '@deepseek-ai/dsh-app-boot'
+import { describe, expect, it } from 'vitest'
+import { execa } from 'execa'
+import { initializeProfileFromDefault } from '../src/profile-boot.ts'
+
+const childEntry = fileURLToPath(new URL('./fixtures/initialize-profile-from-default.ts', import.meta.url))
+const tsxLoader = import.meta.resolve('tsx/esm')
+const CHILD_TIMEOUT_MS = 30_000
+
+/** Wait until a child has reached the shared creation barrier. */
+async function waitForFile(file: string): Promise<void> {
+  const deadline = Date.now() + CHILD_TIMEOUT_MS
+  while (!existsSync(file)) {
+    if (Date.now() >= deadline) throw new Error(`profile initialization marker did not appear: ${file}`)
+    await new Promise(resolve => setTimeout(resolve, 20))
+  }
+}
+
+/** Run one assertion against a private Harness home and remove it afterwards. */
+function withHome(assertion: (home: string) => void): void {
+  const home = mkdtempSync(join(tmpdir(), 'dsh-profile-from-default-'))
+  try {
+    assertion(home)
+  } finally {
+    rmSync(home, { recursive: true, force: true })
+  }
+}
+
+describe('initializeProfileFromDefault', () => {
+  it.each(Object.entries(PROFILE_TEMPLATES))(
+    'copies the %s template metadata into an independent profile',
+    (source, template) => {
+      withHome((home) => {
+        initializeProfileFromDefault('custom', source, home)
+        const dir = resolveProfileDir('custom', home)
+        const manifest = readProfileManifest('test', dir)
+        expect(manifest).toEqual({
+          name: 'dsh-profile-custom',
+          private: true,
+          dependencies: {},
+          dsh: { profile: { bundles: [...template.bundles], patchReload: template.patchReload } },
+        })
+        expect(readFileSync(join(dir, PROFILE_PATCH_FILENAME), 'utf8')).toContain('[]')
+        expect(readFileSync(join(dir, 'pnpm-workspace.yaml'), 'utf8')).toContain('nodeLinker: hoisted')
+      })
+    },
+  )
+
+  it('does not copy the local source profile dependencies or user patch', () => {
+    withHome((home) => {
+      const sourceDir = resolveProfileDir('web', home)
+      initProfile(sourceDir, ['local-bundle'], 'startup')
+      const sourceManifest = readProfileManifest('test', sourceDir)
+      sourceManifest.dependencies = { 'local-bundle': '1.0.0' }
+      writeProfileManifest(sourceDir, sourceManifest)
+      writeFileSync(join(sourceDir, PROFILE_PATCH_FILENAME), '- id: local-only\n  disabled: true\n')
+
+      initializeProfileFromDefault('rescue', 'web', home)
+
+      const targetDir = resolveProfileDir('rescue', home)
+      const target = readProfileManifest('test', targetDir)
+      expect(target.dependencies).toEqual({})
+      expect(target.dsh?.profile).toEqual({
+        bundles: [...PROFILE_TEMPLATES.web!.bundles],
+        patchReload: PROFILE_TEMPLATES.web!.patchReload,
+      })
+      expect(readFileSync(join(targetDir, PROFILE_PATCH_FILENAME), 'utf8')).not.toContain('local-only')
+    })
+  })
+
+  it('rejects an existing target without changing its files', () => {
+    withHome((home) => {
+      const dir = resolveProfileDir('rescue', home)
+      initProfile(dir, ['existing-bundle'], 'startup')
+      writeFileSync(join(dir, PROFILE_PATCH_FILENAME), '- id: existing\n  disabled: true\n')
+      const paths = ['package.json', PROFILE_PATCH_FILENAME, 'pnpm-workspace.yaml'].map(file => join(dir, file))
+      const before = paths.map(path => readFileSync(path))
+
+      expect(() => {
+        initializeProfileFromDefault('rescue', 'web', home)
+      })
+        .toThrow('profile "rescue" already exists')
+      expect(paths.map(path => readFileSync(path))).toEqual(before)
+    })
+  })
+
+  it('rejects a residual target directory without changing its contents', () => {
+    withHome((home) => {
+      const dir = resolveProfileDir('rescue', home)
+      mkdirSync(dir, { recursive: true })
+      const residual = join(dir, PROFILE_PATCH_FILENAME)
+      writeFileSync(residual, '- id: residual\n  disabled: true\n')
+      const before = readFileSync(residual)
+
+      expect(() => {
+        initializeProfileFromDefault('rescue', 'web', home)
+      })
+        .toThrow('profile directory')
+      expect(readFileSync(residual)).toEqual(before)
+      expect(existsSync(join(dir, 'package.json'))).toBe(false)
+    })
+  })
+
+  it.each(Object.keys(PROFILE_TEMPLATES))('rejects shipped target name %s without creating it', (name) => {
+    withHome((home) => {
+      expect(() => {
+        initializeProfileFromDefault(name, 'web', home)
+      })
+        .toThrow(`profile ${JSON.stringify(name)} is shipped`)
+      expect(existsSync(resolveProfileDir(name, home))).toBe(false)
+    })
+  })
+
+  it.each(['unknown', 'toString'])('rejects unknown template %s without creating the target', (source) => {
+    withHome((home) => {
+      expect(() => {
+        initializeProfileFromDefault('rescue', source, home)
+      })
+        .toThrow(`unknown default profile ${JSON.stringify(source)}`)
+      expect(existsSync(resolveProfileDir('rescue', home))).toBe(false)
+    })
+  })
+
+  it('allows only one of two synchronized processes to create the target', async () => {
+    const home = mkdtempSync(join(tmpdir(), 'dsh-profile-from-default-race-'))
+    const gate = join(home, 'start')
+    const ready = [join(home, 'ready-1'), join(home, 'ready-2')]
+    const children = ready.map(marker => execa(
+      process.execPath,
+      ['--import', tsxLoader, childEntry, home, 'rescue', 'web', marker, gate],
+      { reject: false, timeout: CHILD_TIMEOUT_MS },
+    ))
+    try {
+      await Promise.all(ready.map(waitForFile))
+      writeFileSync(gate, '')
+      const results = await Promise.all(children)
+      expect(results.map(result => result.exitCode).sort()).toEqual([0, 1])
+      expect(readProfileManifest('test', resolveProfileDir('rescue', home)).dsh?.profile)
+        .toEqual(PROFILE_TEMPLATES.web)
+    } finally {
+      for (const child of children) child.kill('SIGKILL')
+      rmSync(home, { recursive: true, force: true })
+    }
+  }, CHILD_TIMEOUT_MS + 10_000)
+})

apps/cli/tests/profile-mcp.spec.ts

@@ -0,0 +1,43 @@
+/** MCP resource ownership across the resolved shipped profile templates. */
+
+import { mkdtempSync, readFileSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { composeEntries, loadProfile, PROFILE_TEMPLATES } from '@deepseek-ai/dsh-app-boot'
+
+const installAnchor = fileURLToPath(new URL('../package.json', import.meta.url))
+const resourcePackage = '@deepseek-ai/dsh-mcp-resources'
+
+describe('shipped MCP resource composition', () => {
+  it.each(Object.keys(PROFILE_TEMPLATES))('%s carries one shared resource consumer without a server', (name) => {
+    const home = mkdtempSync(join(tmpdir(), 'dsh-profile-mcp-'))
+    try {
+      const profile = loadProfile('dsh', name, installAnchor, home)
+      const warnings: string[] = []
+      const rows = composeEntries([
+        ...profile.layers.map(layer => layer.patches),
+        profile.patches,
+      ], message => warnings.push(message))
+
+      expect(rows.filter(row => row.name === resourcePackage)).toEqual([
+        { id: 'mcp-resources', name: resourcePackage },
+      ])
+      expect(rows.filter(row => row.name === '@deepseek-ai/dsh-mcp-client')).toEqual([])
+      expect(warnings).toEqual([])
+
+      const owners = profile.layers.filter((layer) => {
+        const manifest = JSON.parse(readFileSync(join(layer.packageDir, 'package.json'), 'utf8')) as {
+          dependencies?: Record<string, string>
+        }
+        return manifest.dependencies?.[resourcePackage] !== undefined
+      })
+      expect(owners.map(owner => owner.packageName)).toEqual([
+        name === 'sdk-minimal' ? '@deepseek-ai/dsh-sdk-minimal' : '@deepseek-ai/dsh-base',
+      ])
+    } finally {
+      rmSync(home, { recursive: true, force: true })
+    }
+  })
+})

apps/cli/tests/source-launch.compat.spec.ts

@@ -0,0 +1,42 @@
+import { readFile } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { execa } from 'execa'
+import { describe, expect, it } from 'vitest'
+
+/**
+ * Keyless smoke for SOURCE `dsh` execution: run `apps/cli/src/bin.ts`
+ * with the exact production runtime vector (`node --import tsx/esm`, the
+ * vector the root `dsh` script invokes directly) and assert the
+ * required-config diagnostic. The Node compatibility matrix runs this
+ * WHOLE file, so a Node release changing module hooks or TypeScript handling
+ * breaks this gate instead of every developer's `pnpm dsh`; the built-bin
+ * suite covers the published `lib/` entry, not this source chain.
+ */
+
+const repoRoot = fileURLToPath(new URL('../../../', import.meta.url))
+const dshSourceBin = 'apps/cli/src/bin.ts'
+
+describe('dsh SOURCE launcher (node --import tsx/esm)', () => {
+  it('launches the source CLI without building', async () => {
+    const rootPackage = JSON.parse(await readFile(new URL('../../../package.json', import.meta.url), 'utf8')) as {
+      readonly scripts?: Record<string, string>
+    }
+    expect(rootPackage.scripts?.dsh).toBe('node --import tsx/esm apps/cli/src/bin.ts')
+  })
+
+  it('boots the source entry and requires a profile', async () => {
+    const result = await execa(process.execPath, ['--import', 'tsx/esm', dshSourceBin], {
+      cwd: repoRoot,
+      input: '',
+      timeout: 25_000,
+      killSignal: 'SIGKILL',
+      reject: false,
+    })
+    if (result.timedOut) {
+      throw new Error(`dsh source launch did not exit within 25s. stdout:\n${result.stdout}\nstderr:\n${result.stderr}`)
+    }
+    expect(result.exitCode).not.toBe(0)
+    expect(result.stderr).toContain('--profile <name> is required')
+    expect(result.stdout).toBe('')
+  }, 30_000)
+})

apps/cli/tests/telemetry-switch.spec.ts

@@ -0,0 +1,22 @@
+import { describe, expect, it } from 'vitest'
+import { resolveTelemetryPatch } from '../src/profile-boot.ts'
+
+describe('resolveTelemetryPatch', () => {
+  it('preserves the configured telemetry mode when the hard-disable switch is unset or empty', () => {
+    expect(resolveTelemetryPatch(undefined, true)).toBeUndefined()
+    expect(resolveTelemetryPatch('', true)).toBeUndefined()
+  })
+
+  it('disables on ANY non-empty value, including falsy-looking ones', () => {
+    for (const value of ['1', '0', 'false', 'no']) {
+      expect(resolveTelemetryPatch(value, true)).toEqual({ id: 'session-telemetry-otel', disabled: true })
+    }
+  })
+
+  it('is trivially satisfied by a composition without the telemetry row', () => {
+    // A custom profile need not mount telemetry: nothing exports, so the
+    // privacy switch has nothing to disable and generates no patch.
+    expect(resolveTelemetryPatch('1', false)).toBeUndefined()
+    expect(resolveTelemetryPatch(undefined, false)).toBeUndefined()
+  })
+})

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

@@ -0,0 +1,995 @@
+import { randomUUID } from 'node:crypto'
+import { mkdir, mkdtemp, readFile, stat, symlink, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { fileURLToPath } from 'node:url'
+import { dirname, join } from 'node:path'
+import { Context } from '@deepseek-ai/cordis'
+import {
+  boot,
+  createProfileResolutionGeneration,
+  loadOverlayPatches,
+  loadProfile,
+  PluginPackages,
+  type Profile,
+} from '@deepseek-ai/dsh-app-boot'
+import { provideCmdline } from '@deepseek-ai/dsh-cmdline'
+import { SessionId, SessionLogOffset } from '@deepseek-ai/dsh-session'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import type { PatchOptions } from '@deepseek-ai/cordis-plugin-include'
+import { afterAll, beforeAll, describe, expect, it, vi } from 'vitest'
+import { SUBAGENT_MODEL_SELECTION_SETTINGS_NAMESPACE } from '@deepseek-ai/dsh-tool-subagent/model-selection-settings'
+import { SETTINGS_NAMESPACE, SHIPPED_PRESET_ROOT } from '@deepseek-ai/dsh-agent-presets'
+import { applyChildComposition, childSessionMeta } from '@deepseek-ai/dsh-subagent'
+import { ToolCallId } from '@deepseek-ai/dsh-llm'
+import type {} from '@deepseek-ai/dsh-compaction-basic'
+import type {} from '@deepseek-ai/dsh-skill'
+import type {} from '@deepseek-ai/dsh-tools'
+// Type-only: resolves `ctx.get('sessionProjections')` and `ctx.get('tokenMeter')`.
+import type {} from '@deepseek-ai/dsh-session-projection'
+import type {} from '@deepseek-ai/dsh-token-meter'
+
+const REPO_ROOT = fileURLToPath(new URL('../../..', import.meta.url))
+/** The shipped Web surface: the dsh-base and dsh-web-app bundle patches over an empty preset root. */
+const BASE_PATCH = join(REPO_ROOT, 'packages/bundle/base/cordis.patch.yml')
+const WEB_PATCH = join(REPO_ROOT, 'packages/bundle/web-app/cordis.patch.yml')
+const CODEX_PACKAGE_DIR = join(REPO_ROOT, 'packages/subagent/subagent-codex')
+const CLAUDE_CODE_PACKAGE_DIR = join(REPO_ROOT, 'packages/subagent/subagent-claude-code')
+/** The installation anchor whose dependency surface the preset module fallback mirrors. */
+const INSTALL_ANCHOR = join(REPO_ROOT, 'apps/cli/package.json')
+const MINIMAL_PROMPT = 'You are a helpful software engineer assistant.'
+const MINIMAL_BASH_DESCRIPTION = `Run commands in a bash shell
+* When invoking this tool, the contents of the "command" parameter does NOT need to be XML-escaped.
+* Network access depends on the task environment. Prefer configured mirrors/proxies when they are available.
+* State is persistent across command calls and discussions with the user.
+* To inspect a particular line range of a file, e.g. lines 10-25, try 'sed -n 10,25p /path/to/the/file'.
+* Please avoid commands that may produce a very large amount of output.
+* Please run long lived commands in the background, e.g. 'sleep 10 &' or start a server in the background.`
+
+/**
+ * Boot the shipped Web composition, minus the rows that would bind a port,
+ * touch the network, or write outside the test. Everything that decides an
+ * agent's capabilities is the real thing, including both shipped presets.
+ */
+async function bootWeb(
+  settingsFile: string,
+  extra: PatchOptions[] = [],
+  profilePackages: readonly string[] = [],
+  profileBundles?: readonly string[],
+): Promise<Context> {
+  const storageRoot = join(dirname(settingsFile), 'storages')
+  const overrides: PatchOptions[] = [
+    // The settings row defaults to `$DSH_HOME/settings.yaml`. Left alone it
+    // reads the developer's own document — and since the default preset is a
+    // setting, a stored `agent-presets.default` would decide this file's
+    // outcome. Point it at a temp file for the same reason the roster row
+    // below pins `includeUserRoot` off.
+    { id: 'settings', config: { path: settingsFile, watch: false } },
+    // storage-json's root is anchored to the real $DSH_HOME. Unpinned, this
+    // file writes the developer's own `~/.dsh/storages/` — and then reads it
+    // back on the next run, so a stored document from any other build decides
+    // this test's boot. Same reason the settings row above is pinned.
+    { id: 'storage-json', config: { root: storageRoot } },
+    // Fixed Session IDs must stay inside this boot's temporary profile root.
+    { id: 'session-persistence-jsonl', config: { root: join(dirname(settingsFile), 'sessions') } },
+    // Host rows with side effects outside this process: a bound port, a served
+    // asset tree, a telemetry exporter. `api-gateway` and `directory-picker`
+    // stay ENABLED on purpose — the api-proxy is the host row that injects
+    // `subagents`, `workspace`, and the rest of the agent plane, so disabling
+    // it would hide exactly the breakage this file exists to catch: a service
+    // moved into the presets that a host row still waits for. The boot audit
+    // is that assertion.
+    { id: 'webserver', disabled: true },
+    // The web bundle's runtime row injects `webServer`, so it cannot
+    // activate without the bound port disabled above. It owns dist serving
+    // and the URL prompt line — surface glue, not anything that decides an
+    // agent's capabilities, which is all this file asserts.
+    { id: 'web-runtime', disabled: true },
+    { id: 'session-telemetry-otel', disabled: true },
+    // A deployment-level skill on the host registry's GLOBAL layer — the same
+    // registration shape a repository plugin's skill root uses. The layered
+    // skills test below proves it reaches preset-composed agents.
+    { id: 'skill-badge', disabled: false },
+    { id: 'modules', disabled: true },
+    // The physical Connection row owns the disabled HTTP server. bootWeb
+    // supplies only its in-process registries so Host services still prove
+    // their shipped dependency graph without binding a port.
+    { id: 'connection', disabled: true },
+    // Export owns a Connection Fetch route, so this Host-only composition
+    // disables it with the transport service above.
+    { id: 'session-log-download', disabled: true },
+    // The open-in-app host routes wait for the webserver and connection
+    // rows disabled above (connection's trust fence guards every route).
+    { id: 'open-in-app', disabled: true },
+    // The always-on reload chain waits for the browser roster and bound port
+    // disabled above.
+    { id: 'client-hmr', disabled: true },
+    // The shipped `-auto` chooser resolves its interaction from a running
+    // host and so waits for the webserver disabled above; the browse variant
+    // supplies `directoryPicker` without one.
+    { id: 'directory-picker', disabled: true },
+    { insert: [
+      { id: 'directory-picker-browse', name: '@deepseek-ai/dsh-host-directory-picker-browse' },
+      { id: 'ui-directory-picker-browse', name: '@deepseek-ai/dsh-client-ui-directory-picker-browse' },
+    ] },
+    // Pin the roster away from the developer's machine: `includeUserRoot`
+    // false keeps `~/.dsh/.agent-presets` from changing a test's outcome.
+    // `default` here is the COMPOSITION default — the base layer the settings
+    // document overrides. No `roots` entry: the plugin bundles the shipped
+    // presets itself and prepends their root.
+    { id: 'agent-presets', config: { default: 'standard', includeUserRoot: false } },
+    ...extra,
+  ]
+  const home = dirname(settingsFile)
+  const profileDir = join(home, 'profiles', 'spec')
+  await mkdir(profileDir, { recursive: true })
+  // Product Bundles are installed into the Profile, not the dsh app. Model
+  // pnpm's package link for only the selected products; their own production
+  // dependencies resolve from the linked workspace packages, while shared
+  // peers still resolve through the installation fallback above.
+  for (const packageDir of profilePackages) {
+    const manifest = JSON.parse(await readFile(join(packageDir, 'package.json'), 'utf8')) as { name: string }
+    const link = join(profileDir, 'node_modules', manifest.name)
+    await mkdir(dirname(link), { recursive: true })
+    await symlink(packageDir, link, 'junction')
+  }
+  let profile: Profile = {
+    name: 'spec',
+    dir: profileDir,
+    layers: [],
+    patchPath: join(profileDir, 'cordis.patch.yml'),
+    patches: [],
+    patchReload: 'startup',
+  }
+  let bundlePatches: PatchOptions[] = [
+    ...loadOverlayPatches('dsh-test', BASE_PATCH),
+    ...loadOverlayPatches('dsh-test', WEB_PATCH),
+  ]
+  if (profileBundles !== undefined) {
+    await writeFile(join(profileDir, 'package.json'), JSON.stringify({
+      private: true,
+      dependencies: Object.fromEntries(profileBundles.map(name => [name, 'workspace:*'])),
+      dsh: { profile: { bundles: profileBundles } },
+    }, null, 2) + '\n')
+    profile = loadProfile('dsh-test', 'spec', INSTALL_ANCHOR, home, { userLayer: false })
+    bundlePatches = profile.layers.flatMap(layer => layer.patches)
+  }
+  const resolution = await createProfileResolutionGeneration({ installAnchor: INSTALL_ANCHOR, home, profile })
+  const rootConfig = join(profileDir, 'cordis.yml')
+  await writeFile(rootConfig, '[]\n')
+  return await boot('dsh-test', rootConfig, [...bundlePatches, ...overrides], async (bootCtx) => {
+    await bootCtx.plugin(PluginPackages, { generation: resolution })
+    bootCtx.provide('connection', {
+      fetch: { register: () => () => {} },
+      rpc: { intercept: () => () => {} },
+    } as never)
+    provideCmdline(bootCtx, { args: [], exit: () => {} })
+  })
+}
+
+const toolNames = (ctx: Context, agent?: Agent): string[] =>
+  ctx.tools.schemas(agent).map(schema => schema.name).sort()
+
+function toolParameterNames(ctx: Context, agent: Agent, toolName: string): string[] {
+  const schema = ctx.tools.schemas(agent).find(tool => tool.name === toolName)
+  if (schema === undefined) throw new Error(`missing tool schema ${toolName}`)
+  const properties = schema.parameters.properties
+  if (typeof properties !== 'object' || properties === null || Array.isArray(properties)) {
+    throw new Error(`${toolName} has invalid parameter properties`)
+  }
+  return Object.keys(properties).sort()
+}
+
+function enablePresetTool(composition: string, id: string): string {
+  const row = `    - id: ${id}\n`
+  const start = composition.indexOf(row)
+  if (start < 0) throw new Error(`missing preset row ${id}`)
+  const end = composition.indexOf('\n    - id:', start + row.length)
+  const disabled = composition.indexOf('      disabled: true\n', start)
+  if (disabled < 0 || (end >= 0 && disabled > end)) {
+    throw new Error(`preset row ${id} is not disabled`)
+  }
+  return composition.slice(0, disabled) + composition.slice(disabled + '      disabled: true\n'.length)
+}
+
+let ctx: Context
+beforeAll(async () => {
+  const settingsFile = join(await mkdtemp(join(tmpdir(), 'dsh-web-presets-')), 'settings.yaml')
+  await writeFile(settingsFile, '{}\n')
+  ctx = await bootWeb(settingsFile)
+}, 120_000)
+
+describe('the shipped Web composition', () => {
+  it('leaves the global tool layer empty', () => {
+    // Every model-facing tool belongs to a preset, `ask_user_question`
+    // included: a tool in the global layer reaches EVERY agent regardless of
+    // which preset composed it, expanding that preset's tool list.
+    expect(toolNames(ctx)).toEqual([])
+  })
+
+  it('keeps the token meter and its context-meter projections on the host plane', async () => {
+    // Read before any preset in this file mounts, which is what makes this an
+    // ownership assertion rather than a mount-order coincidence: a preset-side
+    // meter sits behind an `isolate` realm and is invisible to `ctx.get`.
+    //
+    // The projection registry is process-wide rather than scope-layered, so a
+    // preset-side meter would also make the browser's context meter appear for
+    // a `minimal` session the moment some OTHER session mounted a preset that
+    // carries one, and vanish entirely in a process that only ever ran
+    // `minimal`. Host ownership is what makes the meter a per-session fact.
+    expect(ctx.get('tokenMeter')).toBeDefined()
+    const projections = ctx.get('sessionProjections')
+    if (projections === undefined) throw new Error('the Web composition must compose a projection registry')
+    const handle = await ctx.agents.create({
+      sessionId: SessionId('preset-minimal-meter'),
+      setup: agentCtx => ctx.agentPresets.mount(agentCtx, 'minimal').then(() => undefined),
+    })
+    try {
+      // A subset assertion: `tasks`, `goal`, and the rest register into the
+      // same process-wide table, and this is about the meter's three units.
+      expect(Object.keys(projections.snapshot(handle.agent.session).values))
+        .toEqual(expect.arrayContaining(['contextBreakdown', 'contextPressure', 'tokenUsage']))
+    } finally {
+      await handle.dispose()
+    }
+  })
+
+  it('supplies both shipped presets, and only those, from the system root', async () => {
+    const listed = await ctx.agentPresets.list()
+
+    expect(listed.map(preset => preset.id).sort()).toEqual(['cordis', 'minimal', 'ptc', 'standard'])
+    expect(listed.every(preset => preset.trust === 'system')).toBe(true)
+    expect(ctx.agentPresets.defaultId).toBe('standard')
+  })
+
+  it('composes the full agent from `standard`', async () => {
+    const handle = await ctx.agents.create({
+      sessionId: SessionId('preset-standard'),
+      setup: agentCtx => ctx.agentPresets.mount(agentCtx, 'standard').then(() => undefined),
+    })
+    try {
+      // The EXACT catalog, not a spot-check: an omission is this design's
+      // quietest failure mode, because a row that registers into the wrong
+      // layer mounts cleanly and simply contributes nothing. `glob`/`grep` are
+      // excluded for the reason the TUI composition e2e excludes them — they
+      // depend on ripgrep being present on the machine.
+      expect(toolNames(ctx, handle.agent).filter(name => name !== 'glob' && name !== 'grep')).toEqual([
+        'ask_user_question', 'bash', 'create_goal', 'edit', 'exit_plan_mode',
+        'get_goal', 'interrupt_agent', 'job_kill', 'job_list', 'job_output', 'list_agents', 'present', 'read', 'read_image', 'send_message', 'skill',
+        'subagent', 'subagent_fork', 'todo_write', 'update_goal', 'web_fetch', 'web_search',
+        'workflow', 'write',
+      ])
+      expect(ctx.commands.find(handle.agent, 'goal')).toBeDefined()
+    } finally {
+      await handle.dispose()
+    }
+  })
+
+  it('applies the default-off subagent model allowlist only to new sessions', async () => {
+    await ctx.settings.update(SUBAGENT_MODEL_SELECTION_SETTINGS_NAMESPACE, {
+      enabled: false,
+      allowedModels: [],
+    })
+    const disabled = await ctx.agents.create({
+      sessionId: SessionId('preset-model-selection-disabled'),
+      setup: agentCtx => ctx.agentPresets.mount(agentCtx, 'standard').then(() => undefined),
+    })
+    await ctx.settings.update(SUBAGENT_MODEL_SELECTION_SETTINGS_NAMESPACE, {
+      enabled: true,
+      allowedModels: [{ provider: 'deepseek-official', model: 'deepseek-v4-flash' }],
+    })
+    const enabled = await ctx.agents.create({
+      sessionId: SessionId('preset-model-selection-enabled'),
+      setup: agentCtx => ctx.agentPresets.mount(agentCtx, 'standard').then(() => undefined),
+    })
+    try {
+      expect(toolNames(ctx, disabled.agent)).not.toContain('list_subagent_models')
+      expect(toolParameterNames(ctx, disabled.agent, 'subagent')).not.toEqual(expect.arrayContaining([
+        'model', 'provider', 'reasoning_effort',
+      ]))
+      expect(toolNames(ctx, enabled.agent)).toContain('list_subagent_models')
+      expect(toolParameterNames(ctx, enabled.agent, 'subagent')).toEqual(expect.arrayContaining([
+        'model', 'provider', 'reasoning_effort',
+      ]))
+      expect(toolNames(ctx, disabled.agent)).not.toContain('list_subagent_models')
+    } finally {
+      await ctx.settings.update(SUBAGENT_MODEL_SELECTION_SETTINGS_NAMESPACE, { enabled: false })
+      await enabled.dispose()
+      await disabled.dispose()
+    }
+  })
+
+  it('composes the exact RL prompt and persistent shell from `minimal`', async () => {
+    const handle = await ctx.agents.create({
+      sessionId: SessionId('preset-minimal'),
+      setup: agentCtx => ctx.agentPresets.mount(agentCtx, 'minimal').then(() => undefined),
+    })
+    try {
+      const assembly = await ctx.systemPrompt.assemble({ scope: handle.agent })
+      expect(assembly.sections).toEqual([
+        { name: 'deployment:persona-prefix', text: MINIMAL_PROMPT },
+      ])
+      expect(assembly.tools.map(tool => tool.name)).toEqual(['bash'])
+      expect(assembly.tools.find(tool => tool.name === 'bash')?.description).toBe(MINIMAL_BASH_DESCRIPTION)
+      expect(ctx.commands.find(handle.agent, 'goal')).toBeUndefined()
+      // serviceFor reports preset-owned providers; unisolated consumers inherit the host fs.
+      expect(ctx.agentPresets.serviceFor(handle.agent, 'fs')).toBeUndefined()
+      expect(ctx.get('fs')?.sandboxMode).toBeDefined()
+      expect(handle.agent.ctx.get('fs')?.sandboxMode).toBe(ctx.get('fs')?.sandboxMode)
+      expect(ctx.agentPresets.serviceFor(handle.agent, 'compaction')).toBeUndefined()
+      expect(handle.agent.ctx.get('compaction')).toBeUndefined()
+    } finally {
+      await handle.dispose()
+    }
+  })
+
+  it('keeps two differently composed sessions independent', async () => {
+    const full = await ctx.agents.create({
+      sessionId: SessionId('preset-both-full'),
+      setup: agentCtx => ctx.agentPresets.mount(agentCtx, 'standard').then(() => undefined),
+    })
+    const minimal = await ctx.agents.create({
+      sessionId: SessionId('preset-both-minimal'),
+      setup: agentCtx => ctx.agentPresets.mount(agentCtx, 'minimal').then(() => undefined),
+    })
+    try {
+      expect(toolNames(ctx, minimal.agent)).toEqual(['bash'])
+      expect(toolNames(ctx, full.agent).length).toBeGreaterThan(10)
+
+      await minimal.dispose()
+
+      // Tearing the minimal session down leaves the full one whole.
+      expect(toolNames(ctx, full.agent).length).toBeGreaterThan(10)
+      expect(toolNames(ctx)).toEqual([])
+    } finally {
+      await full.dispose()
+    }
+  })
+
+  it('composes the cordis agent with its own toolset', async () => {
+    const handle = await ctx.agents.create({
+      sessionId: SessionId('preset-cordis'),
+      setup: agentCtx => ctx.agentPresets.mount(agentCtx, 'cordis').then(() => undefined),
+    })
+    try {
+      const tools = toolNames(ctx, handle.agent)
+      // The self-referential toolset is what distinguishes this preset.
+      expect(tools).toEqual(expect.arrayContaining([
+        'cordis_inspect_list', 'cordis_inspect_query', 'cordis_inspect_self',
+        'cordis_define', 'cordis_run', 'cordis_stop', 'cordis_undefine',
+      ]))
+      // And it keeps the standard agent's own tools rather than replacing them.
+      expect(tools).toEqual(expect.arrayContaining(['bash', 'read', 'edit', 'skill']))
+      expect(tools).not.toContain('str_replace_editor')
+      expect(ctx.commands.find(handle.agent, 'goal')).toBeDefined()
+
+      // The preset's own authoring skill registers into ITS layer of the host
+      // registry: the cordis agent's view carries it, the global view does not.
+      const scoped = (await ctx.skills.list({ scope: handle.agent })).map(skill => skill.name)
+      expect(scoped).toContain('editing-cordis-compositions')
+      expect((await ctx.skills.list()).map(skill => skill.name)).not.toContain('editing-cordis-compositions')
+    } finally {
+      await handle.dispose()
+    }
+  })
+
+  it('presents `ptc` as PTC mode without disturbing a native session beside it', async () => {
+    const coded = await ctx.agents.create({
+      sessionId: SessionId('preset-ptc'),
+      setup: agentCtx => ctx.agentPresets.mount(agentCtx, 'ptc').then(() => undefined),
+    })
+    const native = await ctx.agents.create({
+      sessionId: SessionId('preset-ptc-native'),
+      setup: agentCtx => ctx.agentPresets.mount(agentCtx, 'standard').then(() => undefined),
+    })
+    try {
+      // One tool reaches the MODEL: the transport. The registry's catalog for
+      // this agent is unchanged — PTC mode collapses the presentation, not
+      // the capabilities — so the assembly is what carries the claim.
+      const assembly = await ctx.systemPrompt.assemble({ scope: coded.agent })
+      expect(assembly.tools.map(tool => tool.name)).toEqual(['run_code'])
+      expect(toolNames(ctx, coded.agent)).not.toContain('str_replace_editor')
+      expect(ctx.commands.find(coded.agent, 'goal')).toBeDefined()
+      const sdk = assembly.sections.find(section => section.name === 'tools:sdk')?.text ?? ''
+      expect(sdk).not.toContain('str_replace_editor')
+      expect(sdk).toContain('web_search')
+
+      // The presentation is this agent's alone: the deployment default is
+      // native, and the session composed from `standard` still sees it.
+      const nativeAssembly = await ctx.systemPrompt.assemble({ scope: native.agent })
+      expect(nativeAssembly.tools.map(tool => tool.name)).toContain('bash')
+      expect(nativeAssembly.tools.map(tool => tool.name)).not.toContain('run_code')
+      expect(nativeAssembly.sections.some(section => section.name === 'tools:sdk')).toBe(false)
+    } finally {
+      await native.dispose()
+      await coded.dispose()
+    }
+  })
+
+  it('keeps the self-referential toolset out of every other preset', async () => {
+    const handle = await ctx.agents.create({
+      sessionId: SessionId('preset-no-cordis'),
+      setup: agentCtx => ctx.agentPresets.mount(agentCtx, 'standard').then(() => undefined),
+    })
+    try {
+      // Editing the live runtime is opt-in per session, not ambient.
+      expect(toolNames(ctx, handle.agent)).not.toContain('cordis_define')
+    } finally {
+      await handle.dispose()
+    }
+  })
+
+  it('ships the composition-authoring skill inside the preset directory', async () => {
+    // The preset's skill root is derived from its own `baseUrl`, so the skill
+    // travels with the directory wherever the preset is installed.
+    const skill = join(
+      SHIPPED_PRESET_ROOT, 'cordis', 'skills', 'editing-cordis-compositions', 'SKILL.md',
+    )
+
+    expect((await readFile(skill, 'utf8')).startsWith('---\nname: editing-cordis-compositions')).toBe(true)
+  })
+
+  it('merges the global skill layer into a preset agent\'s catalog, keeping local discovery preset-side', async () => {
+    const proj = await mkdtemp(join(tmpdir(), 'dsh-preset-skill-proj-'))
+    await mkdir(join(proj, '.dsh', 'skills', 'project-proof'), { recursive: true })
+    await writeFile(join(proj, '.dsh', 'skills', 'project-proof', 'SKILL.md'), [
+      '---',
+      'name: project-proof',
+      'description: Proves the preset layer discovers project skills beside global ones.',
+      '---',
+      '',
+      'Project proof body.',
+      '',
+    ].join('\n'))
+
+    const handle = await ctx.agents.create({
+      // Unique per run: the composition persists into the ambient DSH home,
+      // and a fixed id would collide with a log an earlier run left there.
+      sessionId: SessionId(`preset-skills-standard-${randomUUID()}`),
+      setup: agentCtx => ctx.agentPresets.mount(agentCtx, 'standard').then(() => undefined),
+    })
+    try {
+      // The host (global) view carries the deployment-level provider alone:
+      // local discovery moved behind the presets with `skill-filesystem`.
+      expect((await ctx.skills.list({ cwd: proj })).map(skill => skill.name)).toEqual(['dsh-badge'])
+
+      // The standard agent's view merges the global layer with its preset's
+      // own local discovery over the session cwd.
+      const scoped = (await ctx.skills.list({ cwd: proj, scope: handle.agent })).map(skill => skill.name)
+      expect(scoped).toContain('dsh-badge')
+      expect(scoped).toContain('project-proof')
+
+      // The preset's own loader tool resolves the global-layer skill.
+      const loaded = await ctx.tools.execute({
+        callId: ToolCallId('preset-skills-load'),
+        name: 'skill',
+        arguments: { name: 'dsh-badge' },
+        signal: new AbortController().signal,
+        agent: handle.agent,
+      })
+      expect(loaded.isError).toBe(false)
+      expect(JSON.stringify(loaded.content)).toContain('powered by dsh')
+    } finally {
+      await handle.dispose()
+    }
+  })
+
+  it('shows a minimal agent the global layer but no loader tool', async () => {
+    const handle = await ctx.agents.create({
+      sessionId: SessionId(`preset-skills-minimal-${randomUUID()}`),
+      setup: agentCtx => ctx.agentPresets.mount(agentCtx, 'minimal').then(() => undefined),
+    })
+    try {
+      // Layer visibility is the registry's; whether an agent can USE skills
+      // stays the preset's choice — minimal mounts no `tool-skill`, so its
+      // tool table has no loader even though the global layer is readable.
+      expect((await ctx.skills.list({ scope: handle.agent })).map(skill => skill.name)).toContain('dsh-badge')
+      expect(toolNames(ctx, handle.agent)).toEqual(['bash'])
+    } finally {
+      await handle.dispose()
+    }
+  })
+
+  it('never rewrites the preset file it composed from', async () => {
+    // The Loader persists a tree whose plugin self-disposed, and tearing an
+    // agent down disposes its whole subtree. Inherited, that rewrote the
+    // shipped composition — truncating it to `[]` the first time a session
+    // ended — so `PresetTree` refuses to write at all.
+    const path = join(SHIPPED_PRESET_ROOT, 'standard', 'agent.cordis.yml')
+    const before = await readFile(path, 'utf8')
+
+    const handle = await ctx.agents.create({
+      sessionId: SessionId('preset-readonly'),
+      setup: agentCtx => ctx.agentPresets.mount(agentCtx, 'standard').then(() => undefined),
+    })
+    await handle.dispose()
+    // Slack, not a race the number has to win. The write is driven by the
+    // Loader's fiber-unload listener, which fires as the subtree's fibers
+    // settle rather than when `dispose()` resolves, and the Loader exposes no
+    // flush to await. A regression writes synchronously inside that listener,
+    // so any wait past settlement fails; a longer one only slows the test.
+    await new Promise(resolve => setTimeout(resolve, 50))
+
+    expect(await readFile(path, 'utf8')).toBe(before)
+  })
+})
+
+describe('product Bundle and user-preset intersection', () => {
+  const presetIds = ['products-none', 'products-codex', 'products-claude', 'products-both'] as const
+  type Product = 'codex' | 'claude-code'
+  type PresetId = typeof presetIds[number]
+
+  async function bootProducts(installed: readonly Product[]): Promise<Context> {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-product-presets-'))
+    const userRoot = join(root, 'presets')
+    const settingsFile = join(root, 'settings.yaml')
+    const standard = await readFile(join(SHIPPED_PRESET_ROOT, 'standard', 'agent.cordis.yml'), 'utf8')
+    await writeFile(settingsFile, '{}\n')
+    for (const id of presetIds) {
+      let composition = standard
+      if (id === 'products-codex' || id === 'products-both') {
+        composition = enablePresetTool(composition, 'tool-subagent-codex')
+      }
+      if (id === 'products-claude' || id === 'products-both') {
+        composition = enablePresetTool(composition, 'tool-subagent-claude-code')
+      }
+      const directory = join(userRoot, id)
+      await mkdir(directory, { recursive: true })
+      await writeFile(join(directory, 'agent.cordis.yml'), composition)
+    }
+    const packageDir = (product: Product): string => (
+      product === 'codex' ? CODEX_PACKAGE_DIR : CLAUDE_CODE_PACKAGE_DIR
+    )
+    const packageName = (product: Product): string => (
+      product === 'codex'
+        ? '@deepseek-ai/dsh-subagent-codex'
+        : '@deepseek-ai/dsh-subagent-claude-code'
+    )
+    return await bootWeb(settingsFile, [
+      {
+        id: 'agent-presets',
+        config: {
+          default: 'standard',
+          // The shipped root is the plugin's own, prepended before this.
+          roots: [{ path: userRoot, trust: 'user' }],
+          includeUserRoot: false,
+        },
+      },
+    ], installed.map(packageDir), [
+      '@deepseek-ai/dsh-base',
+      '@deepseek-ai/dsh-web-app',
+      ...installed.map(packageName),
+    ])
+  }
+
+  it('composes the intersection of installed Bundles and enabled preset rows', async () => {
+    const enabledByPreset: Record<PresetId, Product[]> = {
+      'products-none': [],
+      'products-codex': ['codex'],
+      'products-claude': ['claude-code'],
+      'products-both': ['codex', 'claude-code'],
+    }
+    const scenarios: Array<{ installed: Product[]; presets: readonly PresetId[] }> = [
+      { installed: [], presets: ['products-both'] },
+      { installed: ['codex'], presets: ['products-both'] },
+      { installed: ['claude-code'], presets: ['products-both'] },
+      { installed: ['codex', 'claude-code'], presets: presetIds },
+    ]
+
+    for (const { installed, presets } of scenarios) {
+      const productCtx = await bootProducts(installed)
+      const spawn = vi.spyOn(productCtx.subprocess, 'spawn')
+      try {
+        expect(productCtx.subagents.list()
+          .filter(name => name === 'codex' || name === 'claude-code')
+          .sort())
+          .toEqual([...installed].sort())
+        for (const id of presets) {
+          const handle = await productCtx.agents.create({
+            sessionId: SessionId(`preset-${id}-${installed.join('-') || 'none'}-${randomUUID()}`),
+            setup: agentCtx => productCtx.agentPresets.mount(agentCtx, id).then(() => undefined),
+          })
+          try {
+            const productTools = enabledByPreset[id]
+              .filter(product => installed.includes(product))
+              .map(product => product === 'codex' ? 'subagent_codex' : 'subagent_claude_code')
+              .sort()
+            const tools = toolNames(productCtx, handle.agent)
+            expect(tools.filter(name => name === 'subagent_codex' || name === 'subagent_claude_code'))
+              .toEqual(productTools)
+            expect(tools).toEqual(expect.arrayContaining(['job_kill', 'job_list', 'job_output']))
+            for (const productTool of productTools) {
+              expect(toolParameterNames(productCtx, handle.agent, productTool)).toEqual([
+                'description', 'prompt', 'run_in_background',
+              ])
+            }
+          } finally {
+            await handle.dispose()
+          }
+        }
+        expect(spawn).not.toHaveBeenCalled()
+      } finally {
+        spawn.mockRestore()
+        await productCtx.fiber.dispose()
+      }
+    }
+  }, 120_000)
+
+  it('applies a product-row edit only to later sessions on the preset', async () => {
+    const productCtx = await bootProducts(['codex'])
+    const preset = await productCtx.agentPresets.resolve('products-none')
+    const original = await readFile(preset.path, 'utf8')
+    const existing = await productCtx.agents.create({
+      sessionId: SessionId('preset-product-generation-existing'),
+      setup: agentCtx => productCtx.agentPresets.mount(agentCtx, 'products-none').then(() => undefined),
+    })
+    try {
+      expect(toolNames(productCtx, existing.agent)).not.toContain('subagent_codex')
+      await writeFile(preset.path, enablePresetTool(original, 'tool-subagent-codex'))
+
+      const later = await productCtx.agents.create({
+        sessionId: SessionId('preset-product-generation-later'),
+        setup: agentCtx => productCtx.agentPresets.mount(agentCtx, 'products-none').then(() => undefined),
+      })
+      try {
+        expect(toolNames(productCtx, existing.agent)).not.toContain('subagent_codex')
+        expect(toolNames(productCtx, later.agent)).toContain('subagent_codex')
+      } finally {
+        await later.dispose()
+      }
+    } finally {
+      await existing.dispose()
+      await writeFile(preset.path, original)
+      await productCtx.fiber.dispose()
+    }
+  }, 120_000)
+})
+
+describe('a switch survives the session', () => {
+  it('records the choice so the log states what the agent runs', async () => {
+    const handle = await ctx.agents.create({
+      sessionId: SessionId('preset-switch-logged'),
+      meta: { agentPreset: 'standard' },
+      setup: agentCtx => ctx.agentPresets.mount(agentCtx, 'standard').then(() => undefined),
+    })
+    try {
+      // The api-proxy's select does exactly this pair while the session is blank.
+      expect(ctx.commands.find(handle.agent, 'goal')).toBeDefined()
+      await ctx.agentPresets.recompose(handle.agent.ctx, 'minimal')
+      handle.agent.session.append('agent-preset/selected', { agentPreset: 'minimal' })
+      expect(ctx.commands.find(handle.agent, 'goal')).toBeUndefined()
+
+      // The header keeps the creation fact; the log carries what it runs.
+      expect(handle.agent.session.header.agentPreset).toBe('standard')
+      expect(ctx.sessionProjections.stateOf(handle.agent.session, 'agentPreset')).toBe('minimal')
+    } finally {
+      await handle.dispose()
+    }
+  })
+
+})
+
+describe('a forked session', () => {
+  it('inherits the composition its seeded history was produced under', async () => {
+    const parent = await ctx.agents.create({
+      sessionId: SessionId('preset-fork-parent'),
+      meta: { agentPreset: 'minimal' },
+      setup: agentCtx => ctx.agentPresets.mount(agentCtx, 'minimal').then(() => undefined),
+    })
+    const inherited = ctx.sessionProjections.stateOf(parent.agent.session, 'agentPreset') ?? undefined
+    const child = await ctx.agents.create({
+      sessionId: SessionId('preset-fork-child'),
+      seed: [],
+      inheritedEventCount: SessionLogOffset(0),
+      meta: {
+        parentSession: SessionId('preset-fork-parent'),
+        isSeeded: true,
+        ...inherited === undefined ? {} : { agentPreset: inherited },
+      },
+      setup: agentCtx => ctx.agentPresets.mount(agentCtx, inherited).then(() => undefined),
+    })
+    try {
+      // Composing nothing would leave the child empty: this layer moved every
+      // model-facing row out of the host plane, so there is nothing to inherit
+      // for free any more.
+      expect(toolNames(ctx, child.agent)).toEqual(toolNames(ctx, parent.agent))
+      expect(toolNames(ctx, child.agent).length).toBeGreaterThan(0)
+    } finally {
+      await child.dispose()
+      await parent.dispose()
+    }
+  })
+})
+
+describe('a delegated child', () => {
+  it('runs on the composition its parent runs on', async () => {
+    const parent = await ctx.agents.create({
+      sessionId: SessionId('preset-child-parent'),
+      meta: { agentPreset: 'standard' },
+      setup: agentCtx => ctx.agentPresets.mount(agentCtx, 'standard').then(() => undefined),
+    })
+    // Exactly what an in-process subagent driver's creation window does.
+    const child = await parent.agent.ctx.agents.create({
+      sessionId: SessionId('preset-child'),
+      meta: childSessionMeta(parent.agent, 1, false),
+      setup: (agentCtx) => {
+        applyChildComposition(agentCtx, parent.agent, {})
+      },
+    })
+    try {
+      expect(toolNames(ctx, child.agent)).toEqual(toolNames(ctx, parent.agent))
+      // The shipped `standard` preset is the whole coding agent; an empty
+      // child here is the defect, and equality alone would not catch it.
+      expect(toolNames(ctx, child.agent)).toContain('bash')
+      expect(child.agent.session.header.agentPreset).toBe('standard')
+    } finally {
+      await child.dispose()
+      await parent.dispose()
+    }
+  })
+
+  it('follows a parent that switched preset while blank', async () => {
+    const parent = await ctx.agents.create({
+      sessionId: SessionId('preset-child-switch-parent'),
+      meta: { agentPreset: 'standard' },
+      setup: agentCtx => ctx.agentPresets.mount(agentCtx, 'standard').then(() => undefined),
+    })
+    await ctx.agentPresets.recompose(parent.agent.ctx, 'minimal')
+    const child = await parent.agent.ctx.agents.create({
+      sessionId: SessionId('preset-child-switch'),
+      meta: childSessionMeta(parent.agent, 1, false),
+      setup: (agentCtx) => {
+        applyChildComposition(agentCtx, parent.agent, {})
+      },
+    })
+    try {
+      // The live scope chain is the authority, not the parent's creation
+      // header — which still names `standard`.
+      expect(toolNames(ctx, child.agent)).toEqual(toolNames(ctx, parent.agent))
+      expect(child.agent.session.header.agentPreset).toBe('minimal')
+    } finally {
+      await child.dispose()
+      await parent.dispose()
+    }
+  })
+})
+
+describe('a launcher that configures no writable root', () => {
+  // The claim this default exists for, asserted through the real shipped
+  // bundles rather than a hand-built context: `apps/cli` patches in only the
+  // system root, and a person's own presets are found anyway because the
+  // roster derives `<dshHome>/.agent-presets` itself. `$DSH_HOME` is pointed
+  // at a temp home BEFORE boot — the derived root is resolved when the plugin
+  // is constructed, and an unpinned run would read the developer's own.
+  let derivedCtx: Context
+  let previousHome: string | undefined
+
+  beforeAll(async () => {
+    const home = await mkdtemp(join(tmpdir(), 'dsh-preset-derived-'))
+    previousHome = process.env.DSH_HOME
+    process.env.DSH_HOME = home
+    await mkdir(join(home, '.agent-presets', 'derived-mine'), { recursive: true })
+    await writeFile(
+      join(home, '.agent-presets', 'derived-mine', 'agent.cordis.yml'),
+      '- id: tool-todo\n  name: \'@deepseek-ai/dsh-tool-todo\'\n  config:\n    allowParallelInProgress: true\n',
+    )
+    const settingsFile = join(await mkdtemp(join(tmpdir(), 'dsh-preset-derived-settings-')), 'settings.yaml')
+    await writeFile(settingsFile, '{}\n')
+    // No configured roots: the shipped one is the plugin's own, and the
+    // writable one is the roster's own default rather than this patch's job.
+    derivedCtx = await bootWeb(settingsFile, [{
+      id: 'agent-presets',
+      config: { default: 'standard', includeUserRoot: true },
+    }])
+  }, 120_000)
+
+  afterAll(async () => {
+    if (previousHome === undefined) delete process.env.DSH_HOME
+    else process.env.DSH_HOME = previousHome
+    await derivedCtx.fiber.dispose()
+  })
+
+  it('discovers and mounts a preset the person authored under the harness home', async () => {
+    const listed = await derivedCtx.agentPresets.list()
+
+    const mine = listed.find(preset => preset.id === 'derived-mine')
+    expect(mine).toMatchObject({ trust: 'user' })
+    // Omitted rather than undefined: a healthy row carries no `broken` key.
+    expect(mine?.broken).toBeUndefined()
+    expect(derivedCtx.agentPresets.authorable).toBe(true)
+
+    const handle = await derivedCtx.agents.create({
+      sessionId: SessionId('preset-derived-root'),
+      setup: agentCtx => derivedCtx.agentPresets.mount(agentCtx, 'derived-mine').then(() => undefined),
+    })
+    try {
+      expect(toolNames(derivedCtx, handle.agent)).toContain('todo_write')
+    } finally {
+      await handle.dispose()
+    }
+  })
+})
+
+describe('authoring a preset on the shipped composition', () => {
+  let authorCtx: Context
+  let userRoot: string
+
+  beforeAll(async () => {
+    userRoot = join(await mkdtemp(join(tmpdir(), 'dsh-preset-authoring-')), 'profiles')
+    const settingsFile = join(await mkdtemp(join(tmpdir(), 'dsh-preset-authoring-settings-')), 'settings.yaml')
+    await writeFile(settingsFile, '{}\n')
+    authorCtx = await bootWeb(settingsFile, [{
+      id: 'agent-presets',
+      config: {
+        default: 'standard',
+        // The root does not exist yet: a deployment whose user has authored
+        // nothing is the normal first-run state. The shipped root is the
+        // plugin's own, prepended before this.
+        roots: [{ path: userRoot, trust: 'user' }],
+        includeUserRoot: false,
+      },
+    }])
+  })
+
+  it('refuses to copy over or delete a shipped preset', async () => {
+    await expect(authorCtx.agentPresets.copy('minimal', 'standard')).rejects.toThrow(/already exists/)
+    await expect(authorCtx.agentPresets.remove('standard')).rejects.toThrow(/ships with the deployment/)
+  })
+
+  it.each(['../escape', 'a/b', '/abs', 'Upper'])('refuses the uncontainable id %j', async (id) => {
+    // The id becomes a directory name under the user root, so containment is
+    // checked on the id rather than on the joined path afterwards.
+    await expect(authorCtx.agentPresets.copy('minimal', id)).rejects.toThrow()
+  })
+
+  it('copies a shipped preset a session then really composes from', async () => {
+    await authorCtx.agentPresets.copy('minimal', 'my-agent', '我的模式')
+
+    // Round-trips through the roster as a `user` row carrying the given name
+    // and the source's description, over the source's own composition text.
+    const preset = await authorCtx.agentPresets.resolve('my-agent')
+    const source = await authorCtx.agentPresets.resolve('minimal')
+    expect(preset.trust).toBe('user')
+    expect(preset.name).toBe('我的模式')
+    expect(preset.description).toBe(source.description)
+    expect(await authorCtx.agentPresets.read('my-agent')).toBe(await authorCtx.agentPresets.read('minimal'))
+    // Owner-only, in an owner-only directory: a composition is executable
+    // configuration on a machine that may have other users.
+    expect((await stat(preset.path)).mode & 0o777).toBe(0o600)
+    const handle = await authorCtx.agents.create({
+      sessionId: SessionId('preset-authored'),
+      setup: agentCtx => authorCtx.agentPresets.mount(agentCtx, 'my-agent').then(() => undefined),
+    })
+    try {
+      // The same tools the shipped `minimal` composes, from a directory copied
+      // through the service into a root outside the installed harness.
+      expect(toolNames(authorCtx, handle.agent)).toEqual(['bash'])
+    } finally {
+      await handle.dispose()
+    }
+  })
+
+  it('deletes what it copied', async () => {
+    await authorCtx.agentPresets.copy('minimal', 'doomed')
+
+    await authorCtx.agentPresets.remove('doomed')
+
+    expect((await authorCtx.agentPresets.list()).map(preset => preset.id)).not.toContain('doomed')
+  })
+})
+
+/**
+ * Which preset an unnamed session gets is a user setting layered over the
+ * composition's own default. The package suite proves the layering against a
+ * hand-built context; this proves it through the shipped `cordis.yml` — that
+ * the roster and the settings provider are actually wired to each other, and
+ * that the id the setting names is the one a session composes from.
+ */
+describe('the default preset as a user setting', () => {
+  it('composes an unnamed session from the stored default, not the composed one', async () => {
+    expect((await ctx.agentPresets.remoteExportList()).modeSelectionEnabled).toBe(true)
+    expect(ctx.agentPresets.defaultId).toBe('standard')
+
+    await ctx.settings.update(SETTINGS_NAMESPACE, { default: 'minimal' })
+    try {
+      expect(ctx.agentPresets.defaultId).toBe('minimal')
+
+      const handle = await ctx.agents.create({
+        sessionId: SessionId('preset-user-default'),
+        setup: agentCtx => ctx.agentPresets.mount(agentCtx).then(() => undefined),
+      })
+      try {
+        // `mount()` with no id resolves the effective default. One tool, not
+        // `standard`'s catalog: the setting decided the composition.
+        expect(toolNames(ctx, handle.agent)).toEqual(['bash'])
+      } finally {
+        await handle.dispose()
+      }
+    } finally {
+      // The context is shared with the rest of the file. `replace({})` drops
+      // the user section wholesale so the field re-inherits the composition
+      // base; `update` merges, and would leave the override standing.
+      await ctx.settings.replace(SETTINGS_NAMESPACE, {})
+    }
+
+    expect(ctx.agentPresets.defaultId).toBe('standard')
+  })
+})
+
+describe('a session keeps the preset it was created with', () => {
+  it('refuses to adopt a live session under a different preset', async () => {
+    const handle = await ctx.agents.create({
+      sessionId: SessionId('preset-locked'),
+      meta: { agentPreset: 'minimal' },
+      setup: agentCtx => ctx.agentPresets.mount(agentCtx, 'minimal').then(() => undefined),
+    })
+    try {
+      // The api-proxy guard reads exactly this: the header records what the
+      // session runs, so naming anything else is a caller error rather than a
+      // switch. Its history was produced under `minimal`'s single tool.
+      expect(handle.agent.session.header.agentPreset).toBe('minimal')
+    } finally {
+      await handle.dispose()
+    }
+  })
+})
+
+describe('a composition that configures its own preset roots', () => {
+  let rootsCtx: Context
+  let teamRoot: string
+
+  beforeAll(async () => {
+    const home = await mkdtemp(join(tmpdir(), 'dsh-preset-roots-'))
+    const settingsFile = join(home, 'settings.yaml')
+    await writeFile(settingsFile, '{}\n')
+    // A workspace-shared root beside the deployment: one preset of its own,
+    // plus a directory that claims a shipped id.
+    teamRoot = join(home, 'team-presets')
+    const minimalComposition = await readFile(join(SHIPPED_PRESET_ROOT, 'minimal', 'agent.cordis.yml'), 'utf8')
+    for (const id of ['team-spec', 'minimal']) {
+      await mkdir(join(teamRoot, id), { recursive: true })
+      await writeFile(join(teamRoot, id, 'agent.cordis.yml'), minimalComposition)
+    }
+    // The user layer of the reported regression: a profile's cordis.patch.yml
+    // configuring a shared preset root. The plugin must EXTEND it with its
+    // own shipped root, never lose it.
+    rootsCtx = await bootWeb(settingsFile, [{
+      id: 'agent-presets',
+      config: {
+        default: 'standard',
+        roots: [{ path: teamRoot, trust: 'user' }],
+        includeUserRoot: false,
+      },
+    }])
+  }, 120_000)
+
+  afterAll(async () => {
+    await rootsCtx.fiber.dispose()
+  })
+
+  it('keeps configured roots alongside the always-prepended shipped root', async () => {
+    expect(rootsCtx.agentPresets.roots.map(root => root.path)).toEqual([
+      SHIPPED_PRESET_ROOT,
+      teamRoot,
+    ])
+
+    const listed = await rootsCtx.agentPresets.list()
+    expect(listed.map(preset => preset.id).sort()).toEqual(['cordis', 'minimal', 'ptc', 'standard', 'team-spec'])
+    expect(listed.every(preset => preset.broken === undefined)).toBe(true)
+    // The shipped root comes first: a configured directory claiming a shipped
+    // id is shadowed, never the other way around.
+    expect(listed.find(preset => preset.id === 'minimal')?.trust).toBe('system')
+    expect(listed.find(preset => preset.id === 'team-spec')?.trust).toBe('user')
+  })
+
+  it('composes an agent from a configured-root preset', async () => {
+    const handle = await rootsCtx.agents.create({
+      sessionId: SessionId('preset-team-spec'),
+      setup: agentCtx => rootsCtx.agentPresets.mount(agentCtx, 'team-spec').then(() => undefined),
+    })
+    try {
+      expect(toolNames(rootsCtx, handle.agent)).toEqual(['bash'])
+    } finally {
+      await handle.dispose()
+    }
+  })
+})

apps/cli/tests/web-auth.e2e.ts

@@ -0,0 +1,210 @@
+/** Real `dsh web` authentication against a temporary Harness home. */
+
+import type { ChildProcess } from 'node:child_process'
+import { spawn } from 'node:child_process'
+import { stat } from 'node:fs/promises'
+import { request as httpRequest } from 'node:http'
+import { createRequire } from 'node:module'
+import { createServer } from 'node:net'
+import type { AddressInfo } from 'node:net'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { describe, expect, it } from 'vitest'
+
+const REPO_ROOT = fileURLToPath(new URL('../../..', import.meta.url))
+const DSH_SOURCE_BIN = join(REPO_ROOT, 'apps/cli/src/bin.ts')
+const TSX_LOADER = pathToFileURL(createRequire(join(REPO_ROOT, 'package.json')).resolve('tsx')).href
+
+interface RunningWeb {
+  readonly child: ChildProcess
+  readonly launchUrl: string
+  readonly output: () => string
+}
+
+interface HttpResult {
+  readonly status: number
+  readonly body: string
+}
+
+function redact(output: string): string {
+  return output.replace(/([?&]token=)[^\s)]+/gu, '$1<redacted>')
+}
+
+/** Reserve one concrete loopback port, then release it for the CLI process. */
+async function freePort(): Promise<number> {
+  const server = createServer()
+  await new Promise<void>((resolve, reject) => {
+    server.once('error', reject)
+    server.listen(0, '127.0.0.1', resolve)
+  })
+  const port = (server.address() as AddressInfo).port
+  await new Promise<void>((resolve, reject) => {
+    server.close((error) => {
+      if (error === undefined) resolve()
+      else reject(error)
+    })
+  })
+  return port
+}
+
+function cleanEnvironment(root: string, dshHome: string): NodeJS.ProcessEnv {
+  const env = Object.fromEntries(Object.entries(process.env).filter(([name]) =>
+    !/(?:KEY|SECRET|TOKEN|PASSWORD)/iu.test(name)))
+  return {
+    ...env,
+    DSH_AGENTS_HOME: join(root, '.agents'),
+    DSH_HOME: dshHome,
+    DSH_TELEMETRY_DISABLED: '1',
+    NODE_NO_WARNINGS: '1',
+    SSH_CONNECTION: '',
+    SSH_TTY: '',
+    TSX_TSCONFIG_PATH: join(REPO_ROOT, 'tsconfig.json'),
+  }
+}
+
+/** Start the public source CLI and wait for its authenticated readiness URL. */
+async function startWeb(root: string, dshHome: string, port: number): Promise<RunningWeb> {
+  const child = spawn(process.execPath, [
+    '--import', TSX_LOADER,
+    DSH_SOURCE_BIN,
+    'web',
+    '--no-open',
+    '--port', String(port),
+  ], {
+    cwd: root,
+    env: cleanEnvironment(root, dshHome),
+    stdio: ['ignore', 'pipe', 'pipe'],
+  })
+  let output = ''
+  const launchUrl = await new Promise<string>((resolve, reject) => {
+    let settled = false
+    const fail = (error: Error): void => {
+      if (settled) return
+      settled = true
+      clearTimeout(timer)
+      reject(error)
+    }
+    const timer = setTimeout(() => {
+      fail(new Error(`dsh web did not become ready:\n${redact(output)}`))
+    }, 90_000)
+    const append = (chunk: Buffer | string): void => {
+      output = `${output}${String(chunk)}`.slice(-100_000)
+      const match = /dsh web: (http:\/\/[^\s]+)/u.exec(output)
+      if (settled || match?.[1] === undefined) return
+      settled = true
+      clearTimeout(timer)
+      resolve(match[1])
+    }
+    child.stdout?.on('data', append)
+    child.stderr?.on('data', append)
+    child.once('error', (error) => {
+      fail(error)
+    })
+    child.once('exit', (code) => {
+      fail(new Error(`dsh web exited before readiness (${String(code)}):\n${redact(output)}`))
+    })
+  })
+  return { child, launchUrl, output: () => output }
+}
+
+async function stopWeb(running: RunningWeb): Promise<void> {
+  if (running.child.exitCode !== null) return
+  const exited = new Promise<void>((resolve) => { running.child.once('exit', () => { resolve() }) })
+  running.child.kill('SIGTERM')
+  const forced = setTimeout(() => { running.child.kill('SIGKILL') }, 10_000)
+  forced.unref()
+  await exited
+  clearTimeout(forced)
+}
+
+/** POST one real Remote envelope while controlling the wire Host header. */
+function describeSettings(port: number, host: string, cookie?: string): Promise<HttpResult> {
+  const body = JSON.stringify({
+    type: 'client-request',
+    rpcId: 'web-auth-real-cli',
+    method: 'settings/describe',
+    payload: { args: {} },
+  })
+  return new Promise((resolve, reject) => {
+    const req = httpRequest({
+      hostname: '127.0.0.1',
+      port,
+      path: '/api/settings/describe',
+      method: 'POST',
+      headers: {
+        host,
+        'content-type': 'application/json',
+        'content-length': Buffer.byteLength(body),
+        ...cookie === undefined ? {} : { cookie },
+      },
+    }, (res) => {
+      const chunks: Uint8Array[] = []
+      res.on('data', (chunk: Buffer) => { chunks.push(chunk) })
+      res.on('end', () => {
+        resolve({ status: res.statusCode ?? 0, body: Buffer.concat(chunks).toString('utf8') })
+      })
+    })
+    req.once('error', reject)
+    req.end(body)
+  })
+}
+
+describe('dsh web authentication through the real CLI', () => {
+  it('rejects a forged loopback Host and preserves the browser cookie across restart', { timeout: 180_000 }, async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-web-auth-real-cli-'))
+    const dshHome = join(root, '.dsh')
+    const port = await freePort()
+    let first: RunningWeb | undefined
+    let second: RunningWeb | undefined
+    try {
+      first = await startWeb(root, dshHome, port)
+      const firstUrl = new URL(first.launchUrl)
+      expect(firstUrl.origin).toBe(`http://127.0.0.1:${String(port)}`)
+      expect(firstUrl.pathname).toBe('/')
+      expect(firstUrl.searchParams.get('token')).toMatch(/^[A-Za-z0-9_-]{43}$/u)
+
+      expect(await describeSettings(port, `localhost:${String(port)}`)).toEqual({
+        status: 401,
+        body: 'unauthorized',
+      })
+
+      const exchange = await fetch(first.launchUrl, { redirect: 'manual' })
+      expect(exchange.status).toBe(303)
+      expect(exchange.headers.get('location')).toBe('/')
+      const setCookie = exchange.headers.get('set-cookie')
+      if (setCookie === null) throw new Error('real CLI token exchange omitted Set-Cookie')
+      expect(setCookie).toContain('HttpOnly')
+      expect(setCookie).toContain('SameSite=Strict')
+      expect(setCookie).not.toContain('Secure')
+      const cookie = setCookie.split(';', 1)[0]!
+
+      const authenticated = await describeSettings(port, firstUrl.host, cookie)
+      expect(authenticated.status).toBe(200)
+      const authenticatedBody = JSON.parse(authenticated.body) as unknown
+      expect(authenticatedBody).toMatchObject({
+        type: 'server-response',
+        rpcId: 'web-auth-real-cli',
+        result: { ok: true, value: { namespaces: expect.any(Array) as unknown } },
+      })
+
+      await stopWeb(first)
+      first = undefined
+      second = await startWeb(root, dshHome, port)
+      const secondUrl = new URL(second.launchUrl)
+      expect(secondUrl.searchParams.get('token')).not.toBe(firstUrl.searchParams.get('token'))
+      expect((await describeSettings(port, secondUrl.host, cookie)).status).toBe(200)
+
+      const credentialMode = (await stat(join(dshHome, '.credentials.yaml'))).mode & 0o777
+      expect(credentialMode).toBe(0o600)
+    } catch (error) {
+      const evidence = [first?.output(), second?.output()].filter(value => value !== undefined).join('\n')
+      throw new Error(`${error instanceof Error ? error.message : String(error)}\n${redact(evidence)}`, { cause: error })
+    } finally {
+      if (second !== undefined) await stopWeb(second)
+      if (first !== undefined) await stopWeb(first)
+      await rm(root, { recursive: true, force: true })
+    }
+  })
+})

apps/cli/tests/web-browser-open.expected.e2e.ts

@@ -0,0 +1,240 @@
+/** Assembled keyless snapshot for the default `dsh web` browser handoff. */
+
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { execa } from 'execa'
+import { afterEach, describe, expect, it } from 'vitest'
+
+const repoRoot = fileURLToPath(new URL('../../../', import.meta.url))
+const builtBin = join(repoRoot, 'apps/cli/lib/bin.js')
+const frontendIndex = join(repoRoot, 'apps/web/dist/index.html')
+const openerHook = new URL('./fixtures/web-browser-open/register.mjs', import.meta.url).href
+const openingMessage = 'dsh web: opening the default browser; pass --no-open to disable'
+const tempRoots: string[] = []
+const builtArtifactsExist = existsSync(builtBin) && existsSync(frontendIndex)
+
+if (process.env.DSH_EXAMPLE_MODE === 'lib' && !builtArtifactsExist) {
+  throw new Error('dsh web browser-open snapshot requires built CLI and Web artifacts in lib mode')
+}
+
+afterEach(() => {
+  for (const root of tempRoots.splice(0)) rmSync(root, { recursive: true, force: true })
+})
+
+interface BrowserOpenRecord {
+  url: string
+  status: number
+  bootManifest: boolean
+  apiKeyPresent: boolean
+  dshHomePresent: boolean
+}
+
+function normalizeLocalUrl(url: string): string {
+  return url
+    .replace(/:\d+/u, ':{{port}}')
+    .replace(/token=[^&]+/u, 'token={{token}}')
+}
+
+describe.skipIf(!builtArtifactsExist)('dsh web browser-open assembled snapshot', () => {
+  it('hands the reachable page to the default browser after the shipped tree settles', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'dsh-web-browser-open-snapshot-'))
+    tempRoots.push(root)
+    const result = await execa(process.execPath, [
+      '--import', openerHook,
+      builtBin,
+      'web',
+      '--port', '0',
+    ], {
+      cwd: root,
+      env: {
+        ...process.env,
+        DEEPSEEK_API_KEY: 'keyless-browser-open-no-call',
+        DSH_AGENTS_HOME: join(root, '.agents'),
+        DSH_HOME: join(root, '.dsh'),
+        DSH_TELEMETRY_DISABLED: '1',
+        NODE_NO_WARNINGS: '1',
+        SSH_CONNECTION: '',
+        SSH_TTY: '',
+      },
+      input: '',
+      timeout: 30_000,
+      killSignal: 'SIGKILL',
+      reject: false,
+    })
+    const readyUrl = /dsh web: (http:\/\/[^\s]+)/u.exec(result.stdout)?.[1]
+    const openLine = result.stdout.split('\n').find(line => line.startsWith('dsh browser-open: '))
+    const opening = result.stdout.includes(openingMessage)
+    if (readyUrl === undefined || openLine === undefined || !opening) {
+      throw new Error(`dsh web browser-open evidence missing\nstdout:\n${result.stdout}\nstderr:\n${result.stderr}`)
+    }
+    const opened = JSON.parse(openLine.slice('dsh browser-open: '.length)) as BrowserOpenRecord
+
+    expect({
+      exitCode: result.exitCode,
+      opening,
+      readyUrl: normalizeLocalUrl(readyUrl),
+      openedUrl: normalizeLocalUrl(opened.url),
+      status: opened.status,
+      bootManifest: opened.bootManifest,
+      apiKeyPresent: opened.apiKeyPresent,
+      dshHomePresent: opened.dshHomePresent,
+      stderr: result.stderr,
+    }).toMatchInlineSnapshot(`
+      {
+        "apiKeyPresent": false,
+        "bootManifest": true,
+        "dshHomePresent": false,
+        "exitCode": 0,
+        "openedUrl": "http://127.0.0.1:{{port}}/?token={{token}}",
+        "opening": true,
+        "readyUrl": "http://127.0.0.1:{{port}}/?token={{token}}",
+        "status": 200,
+        "stderr": "",
+      }
+    `)
+  })
+
+  it('prints the launcher reason and manual URL after the Web app is ready', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'dsh-web-browser-open-failure-snapshot-'))
+    tempRoots.push(root)
+    const result = await execa(process.execPath, [
+      '--import', openerHook,
+      builtBin,
+      'web',
+      '--port', '0',
+    ], {
+      cwd: root,
+      env: {
+        ...process.env,
+        BROWSER_OPEN_TEST_FAILURE: 'fixture desktop unavailable',
+        DEEPSEEK_API_KEY: 'keyless-browser-open-no-call',
+        DSH_AGENTS_HOME: join(root, '.agents'),
+        DSH_BROWSER_OPEN_TEST_EXIT_ON_FAILURE: '1',
+        DSH_HOME: join(root, '.dsh'),
+        DSH_TELEMETRY_DISABLED: '1',
+        NODE_NO_WARNINGS: '1',
+        SSH_CONNECTION: '',
+        SSH_TTY: '',
+      },
+      input: '',
+      timeout: 30_000,
+      killSignal: 'SIGKILL',
+      reject: false,
+    })
+    const readyUrl = /dsh web: (http:\/\/[^\s]+)/u.exec(result.stdout)?.[1]
+    const diagnostic = result.stderr.split(/\r?\n/u)
+      .find(line => line.startsWith('web-app: could not open the default browser because '))
+
+    expect({
+      diagnostic,
+      exitCode: result.exitCode,
+      opened: result.stdout.includes('dsh browser-open: '),
+      opening: result.stdout.includes(openingMessage),
+      readyUrl: readyUrl === undefined ? undefined : normalizeLocalUrl(readyUrl),
+    }).toMatchInlineSnapshot(`
+      {
+        "diagnostic": "web-app: could not open the default browser because fixture desktop unavailable; use the dsh web URL printed at startup",
+        "exitCode": 0,
+        "opened": false,
+        "opening": true,
+        "readyUrl": "http://127.0.0.1:{{port}}/?token={{token}}",
+      }
+    `)
+  })
+
+  it('prints the host URL without launching a browser in a VS Code Remote SSH session', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'dsh-web-browser-open-ssh-snapshot-'))
+    tempRoots.push(root)
+    const result = await execa(process.execPath, [
+      '--import', openerHook,
+      builtBin,
+      'web',
+      '--port', '0',
+    ], {
+      cwd: root,
+      env: {
+        ...process.env,
+        DEEPSEEK_API_KEY: 'keyless-browser-open-no-call',
+        DSH_AGENTS_HOME: join(root, '.agents'),
+        DSH_BROWSER_OPEN_TEST_EXIT_ON_READY: '1',
+        DSH_HOME: join(root, '.dsh'),
+        DSH_TELEMETRY_DISABLED: '1',
+        NODE_NO_WARNINGS: '1',
+        SSH_CONNECTION: '10.0.0.2 55000 10.0.0.9 22',
+        SSH_TTY: '',
+        VSCODE_IPC_HOOK_CLI: '/tmp/vscode-ipc',
+      },
+      input: '',
+      timeout: 30_000,
+      killSignal: 'SIGKILL',
+      reject: false,
+    })
+    const readyUrl = /dsh web: (http:\/\/[^\s]+)/u.exec(result.stdout)?.[1]
+
+    expect({
+      exitCode: result.exitCode,
+      opening: result.stdout.includes(openingMessage),
+      readyUrl: readyUrl === undefined ? undefined : normalizeLocalUrl(readyUrl),
+      opened: result.stdout.includes('dsh browser-open: '),
+      stderr: result.stderr,
+    }).toMatchInlineSnapshot(`
+      {
+        "exitCode": 0,
+        "opened": false,
+        "opening": false,
+        "readyUrl": "http://127.0.0.1:{{port}}/?token={{token}}",
+        "stderr": "",
+      }
+    `)
+  })
+
+  it('rejects a project browser command before starting the Web app', async () => {
+    const root = mkdtempSync(join(tmpdir(), 'dsh-web-browser-open-env-snapshot-'))
+    tempRoots.push(root)
+    writeFileSync(join(root, '.env'), 'BROWSER=./project-browser\n')
+    const result = await execa(process.execPath, [
+      '--import', openerHook,
+      builtBin,
+      'web',
+      '--port', '0',
+    ], {
+      cwd: root,
+      env: {
+        ...process.env,
+        DEEPSEEK_API_KEY: 'keyless-browser-open-no-call',
+        DSH_AGENTS_HOME: join(root, '.agents'),
+        DSH_HOME: join(root, '.dsh'),
+        DSH_TELEMETRY_DISABLED: '1',
+        NODE_NO_WARNINGS: '1',
+        SSH_CONNECTION: '',
+        SSH_TTY: '',
+      },
+      input: '',
+      timeout: 30_000,
+      killSignal: 'SIGKILL',
+      reject: false,
+    })
+
+    const diagnostic = result.stderr.split(/\r?\n/u)
+      .find(line => line.startsWith('Error: dsh: '))
+      ?.replace(/^Error: dsh: .*[/\\]\.env/u, 'dsh: {{root}}/.env')
+
+    expect({
+      diagnostic,
+      exitCode: result.exitCode,
+      opening: result.stdout.includes(openingMessage),
+      opened: result.stdout.includes('dsh browser-open: '),
+      ready: result.stdout.includes('dsh web: '),
+    }).toMatchInlineSnapshot(`
+      {
+        "diagnostic": "dsh: {{root}}/.env sets "BROWSER", which only the launching environment may set (it decides how this process starts, where its code and instructions load from, or how it reaches the network); export BROWSER instead of putting it in a .env file",
+        "exitCode": 1,
+        "opened": false,
+        "opening": false,
+        "ready": false,
+      }
+    `)
+  })
+})

apps/cli/tests/windows-shell.spec.ts

@@ -0,0 +1,159 @@
+/**
+ * The shipped shell composition: the base bundle gates both shell stacks by
+ * platform on its own rows (`disabled: !!js process.platform`), so exactly
+ * one shell stack mounts per host and no separate platform layer exists —
+ * the launcher applies nothing beyond the bundle layers. The spec composes
+ * the REAL shipped bundle layers (dsh-base + dsh-web-app resolved from the
+ * app installation anchor) through the boot's patch algorithm and pins the
+ * effective per-platform roster, the preset-level gates that keep tool-bash
+ * out of win32 sessions and tool-pwsh out of POSIX sessions, and the
+ * cold-start resolution closure for the pwsh rows' bare plugin names.
+ */
+
+import { afterEach, describe, expect, it } from 'vitest'
+import { mkdtempSync, rmSync, readFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import yaml from 'js-yaml'
+import { entryListSchema } from '@deepseek-ai/cordis-plugin-include'
+import { evaluate } from '@deepseek-ai/cordis-plugin-loader'
+import { SHIPPED_PRESET_ROOT } from '@deepseek-ai/dsh-agent-presets'
+import { composeEntries, initProfile, loadProfile, PROFILES_DIR } from '@deepseek-ai/dsh-app-boot'
+
+/**
+ * The effective disabled state of one row on one platform: a `!!js` expression
+ * evaluates with a platform-scoped `process` so both outcomes pin on any host.
+ */
+function disabledOn(row: { disabled?: unknown }, platform: 'win32' | 'linux'): boolean {
+  const value = row.disabled
+  if (value !== null && typeof value === 'object' && '__jsExpr' in value) {
+    return Boolean(evaluate({ process: { platform } }, (value as { __jsExpr: string }).__jsExpr))
+  }
+  return value === true
+}
+
+describe('the shipped shell composition (real bundle layers)', () => {
+  let home: string
+  afterEach(() => { if (home !== undefined) rmSync(home, { recursive: true, force: true }) })
+  // The app installation anchor, mirroring profile-boot.ts: the bundle layers
+  // resolve from the REAL dsh-base/dsh-web-app packages through it, so this
+  // suite composes the shipped patch files, not test fixtures.
+  const anchor = fileURLToPath(new URL('../package.json', import.meta.url))
+
+  it('composes the confined pwsh roster on win32 and the bash roster on POSIX from the same rows', () => {
+    home = mkdtempSync(join(tmpdir(), 'dsh-windows-home-'))
+    initProfile(join(home, PROFILES_DIR, 'web'), ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app'])
+    const profile = loadProfile('dsh', 'web', anchor, home)
+    const warnings: string[] = []
+    const rows = composeEntries(
+      profile.layers.map(layer => layer.patches),
+      message => warnings.push(message),
+    )
+    const byId = new Map(rows.map(row => [row.id, row]))
+    // One shared patch set, two rosters: the shell stacks gate themselves.
+    for (const id of ['bash-sandbox', 'pwsh-sandbox', 'tool-bash', 'tool-pwsh']) {
+      expect(byId.has(id), `row ${id}`).toBe(true)
+    }
+    expect(disabledOn(byId.get('bash-sandbox')!, 'win32'), 'bash-sandbox on win32').toBe(true)
+    expect(disabledOn(byId.get('bash-sandbox')!, 'linux'), 'bash-sandbox on linux').toBe(false)
+    expect(disabledOn(byId.get('pwsh-sandbox')!, 'win32'), 'pwsh-sandbox on win32').toBe(false)
+    expect(disabledOn(byId.get('pwsh-sandbox')!, 'linux'), 'pwsh-sandbox on linux').toBe(true)
+    // Host shell-tool rows are disabled on every platform; sessions mount
+    // their own rows instead.
+    expect(byId.get('tool-bash')?.disabled).toBe(true)
+    expect(byId.get('tool-pwsh')?.disabled).toBe(true)
+    // The permission surface never moves: the sandbox/policy rows, the
+    // permission switcher, fs-sandbox, and the approval service stay enabled
+    // exactly as on POSIX — the confined pwsh executor is what changes.
+    for (const id of ['permission', 'ui-permission', 'sandbox', 'sandbox-policy', 'fs-sandbox', 'approval']) {
+      expect(byId.get(id)?.disabled, `row ${id}`).not.toBe(true)
+    }
+    // The launcher's cold-start module fallback BFS-links the apps/cli
+    // dependency closure into the profile's node_modules, so every bare
+    // plugin name in the base patch must resolve from there.
+    const cliManifest = JSON.parse(readFileSync(anchor, 'utf8')) as { dependencies?: Record<string, string> }
+    for (const name of ['@deepseek-ai/dsh-pwsh-sandbox', '@deepseek-ai/dsh-tool-pwsh']) {
+      expect(cliManifest.dependencies?.[name], `cold-start closure must reach ${name}`).toBeDefined()
+    }
+    expect(warnings).toEqual([])
+  })
+
+  it('base-only profiles carry both stacks with the same platform gating', () => {
+    home = mkdtempSync(join(tmpdir(), 'dsh-windows-home-'))
+    initProfile(join(home, PROFILES_DIR, 'base-only'), ['@deepseek-ai/dsh-base'])
+    const profile = loadProfile('dsh', 'base-only', anchor, home)
+    const warnings: string[] = []
+    const rows = composeEntries(
+      profile.layers.map(layer => layer.patches),
+      message => warnings.push(message),
+    )
+    const byId = new Map(rows.map(row => [row.id, row]))
+    for (const id of ['bash-sandbox', 'tool-bash', 'pwsh-sandbox', 'tool-pwsh']) {
+      expect(byId.has(id), `row ${id}`).toBe(true)
+    }
+    // No web overlay: the tool rows keep their own gating too.
+    expect(disabledOn(byId.get('tool-bash')!, 'win32'), 'tool-bash on win32').toBe(true)
+    expect(disabledOn(byId.get('tool-bash')!, 'linux'), 'tool-bash on linux').toBe(false)
+    expect(disabledOn(byId.get('tool-pwsh')!, 'win32'), 'tool-pwsh on win32').toBe(false)
+    expect(disabledOn(byId.get('tool-pwsh')!, 'linux'), 'tool-pwsh on linux').toBe(true)
+    expect(warnings).toEqual([])
+  })
+})
+
+describe('shipped agent presets gate both shell tools by platform', () => {
+  const presetRoot = SHIPPED_PRESET_ROOT
+
+  it.each(['standard', 'ptc', 'cordis'])('preset %s gates its shell tool rows by platform', (preset) => {
+    const entries: unknown = yaml.load(
+      readFileSync(join(presetRoot, preset, 'agent.cordis.yml'), 'utf8'),
+      { schema: entryListSchema },
+    )
+    if (!Array.isArray(entries)) throw new TypeError(`preset ${preset} must parse to an entry array`)
+    for (const [id, win32] of [['tool-bash', true], ['tool-pwsh', false]] as const) {
+      const row = entries.find((entry): entry is Record<string, unknown> => (
+        typeof entry === 'object' && entry !== null && (entry as Record<string, unknown>).id === id
+      ))
+      if (row === undefined) throw new TypeError(`preset ${preset} must mount ${id}`)
+      expect(row.disabled).toMatchObject({ __jsExpr: expect.any(String) as string })
+      // A platform-scoped context pins both outcomes on every host.
+      const expression = (row.disabled as { __jsExpr: string }).__jsExpr
+      expect(Boolean(evaluate({ process: { platform: 'win32' } }, expression)), `${id} on win32`).toBe(win32)
+      expect(Boolean(evaluate({ process: { platform: 'linux' } }, expression)), `${id} on linux`).toBe(!win32)
+    }
+  })
+
+  it('minimal mounts no shell tool row and gates its persistent shell stack by platform', () => {
+    const entries: unknown = yaml.load(
+      readFileSync(join(presetRoot, 'minimal', 'agent.cordis.yml'), 'utf8'),
+      { schema: entryListSchema },
+    )
+    if (!Array.isArray(entries)) throw new TypeError('minimal preset must parse to an entry array')
+    for (const id of ['tool-bash', 'tool-pwsh']) {
+      expect(entries.some(entry => (
+        typeof entry === 'object' && entry !== null && (entry as Record<string, unknown>).id === id
+      )), `${id} must be absent from minimal`).toBe(false)
+    }
+    const group = entries.find((entry): entry is Record<string, unknown> => (
+      typeof entry === 'object' && entry !== null && (entry as Record<string, unknown>).id === 'persistent-shell'
+    ))
+    if (group === undefined) throw new TypeError('minimal preset must mount persistent-shell')
+    const rows = group.config as unknown[]
+    if (!Array.isArray(rows)) throw new TypeError('persistent-shell must carry a row list')
+    const byId = new Map(rows
+      .filter((entry): entry is Record<string, unknown> => typeof entry === 'object' && entry !== null)
+      .map(entry => [entry.id, entry]))
+    // The bash stack (terminal-bash + persistent-bash) mounts on POSIX only; the
+    // pwsh twin (terminal-bash with shellDialect pwsh + persistent-pwsh) mounts on
+    // win32 only — exactly one persistent shell per host.
+    for (const id of ['terminal-bash', 'persistent-bash']) {
+      expect(disabledOn(byId.get(id)!, 'win32'), `${id} on win32`).toBe(true)
+      expect(disabledOn(byId.get(id)!, 'linux'), `${id} on linux`).toBe(false)
+    }
+    for (const id of ['terminal-pwsh', 'persistent-pwsh']) {
+      expect(disabledOn(byId.get(id)!, 'win32'), `${id} on win32`).toBe(false)
+      expect(disabledOn(byId.get(id)!, 'linux'), `${id} on linux`).toBe(true)
+    }
+    expect(byId.get('terminal-pwsh')?.config).toMatchObject({ shellDialect: 'pwsh' })
+  })
+})

apps/cli/tsconfig.json

@@ -0,0 +1,75 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../vendor/cordis"
+    },
+    {
+      "path": "../../vendor/loader"
+    },
+    {
+      "path": "../../vendor/include"
+    },
+    {
+      "path": "../../packages/boot/app-boot"
+    },
+    {
+      "path": "../../packages/boot/cmdline"
+    },
+    {
+      "path": "../../packages/bundle/base"
+    },
+    {
+      "path": "../../packages/bundle/headless"
+    },
+    {
+      "path": "../../packages/bundle/web-app"
+    },
+    {
+      "path": "../../packages/host/webserver"
+    },
+    {
+      "path": "../../packages/host/frontend-static"
+    },
+    {
+      "path": "../../packages/core/session"
+    },
+    {
+      "path": "../../packages/core/system-prompt"
+    },
+    {
+      "path": "../../packages/core/tools"
+    },
+    {
+      "path": "../../packages/util/launch-environment"
+    },
+    {
+      "path": "../../packages/util/home-paths"
+    },
+    {
+      "path": "../../packages/mcp/mcp-client"
+    },
+    {
+      "path": "../../packages/test-support/loader-smoke"
+    },
+    {
+      "path": "../../packages/session-query/session-query-sqlite"
+    },
+    {
+      "path": "../../packages/session-query/session-query"
+    },
+    {
+      "path": "../../packages/shell/shell-env"
+    },
+    {
+      "path": "../../packages/shell/tool-bash"
+    }
+  ]
+}

apps/cli/tsdown.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from 'tsdown'
+
+/**
+ * The dsh CLI ships one entry: the `bin` referenced by package.json `bin`.
+ * The root tsdown builds only `lib/types/index.js`, so this override points at
+ * `lib/types/bin.js` instead; its reachable mode modules bundle with it.
+ * Declarations come from `tsc -b` (dts: false), matching every package.
+ */
+export default defineConfig({
+  entry: ['lib/types/bin.js'],
+  outDir: 'lib',
+  format: ['esm'],
+  platform: 'node',
+  target: 'es2024',
+  fixedExtension: false,
+  dts: false,
+  clean: ['lib/*.js'],
+})

apps/desktop-host/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@deepseek-ai/dsh-desktop-host",
+  "description": "Private Node-mode host process for the Electron desktop application",
+  "version": "0.1.6-alpha.1",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "main": "lib/index.js",
+  "files": [
+    "lib/index.js",
+    "config/desktop.cordis.patch.yml"
+  ],
+  "dependencies": {
+    "@deepseek-ai/cordis": "workspace:^",
+    "@deepseek-ai/cordis-plugin-include": "workspace:^",
+    "@deepseek-ai/dsh": "workspace:^",
+    "@deepseek-ai/dsh-api-gateway": "workspace:^",
+    "@deepseek-ai/dsh-app-boot": "workspace:^",
+    "@deepseek-ai/dsh-client-connection": "workspace:^",
+    "@deepseek-ai/dsh-client-modules": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-directory-picker-native": "workspace:^",
+    "@deepseek-ai/dsh-cmdline": "workspace:^",
+    "@deepseek-ai/dsh-host-directory-picker-native": "workspace:^",
+    "@deepseek-ai/dsh-host-webserver": "workspace:^",
+    "@deepseek-ai/dsh-launch-environment": "workspace:^",
+    "@deepseek-ai/dsh-web-frontend": "workspace:^"
+  }
+}

apps/desktop-host/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../../vendor/cordis" },
+    { "path": "../../vendor/include" },
+    { "path": "../../packages/api/gateway/tsconfig.host.json" },
+    { "path": "../../packages/boot/app-boot" },
+    { "path": "../../packages/boot/cmdline" },
+    { "path": "../../packages/client/connection/tsconfig.host.json" },
+    { "path": "../../packages/client/modules" },
+    { "path": "../../packages/host/webserver" },
+    { "path": "../../packages/util/launch-environment" }
+  ]
+}

apps/desktop-host/tsdown.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'tsdown'
+
+export default defineConfig({
+  entry: ['lib/types/index.js'],
+  outDir: 'lib',
+  format: ['esm'],
+  platform: 'node',
+  target: 'es2024',
+  fixedExtension: false,
+  dts: false,
+  clean: false,
+})

apps/desktop/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 apps/desktop/README.md
+README.md: c053e4894714d10cba2a9d9c1ebed71b53457c37
+README.zh.md: e27554fe8a91ee8a918380ef5a860b0838351aa5

apps/desktop/README.md

@@ -0,0 +1,202 @@
+# DeepSeek Harness Desktop
+
+English | [中文](README.zh.md)
+
+The desktop application is an Electron shell around the dsh Web UI. It opens no listening port: a bundled upstream Node.js child boots the installed dsh project, versioned framed byte pipes carry Fetch requests and streaming responses without an outer Base64 envelope, Node IPC carries lifecycle control, and `dsh-app://` serves the matching client assets.
+
+## Key technical decisions
+
+| Decision | Why | Direct consequence |
+|---|---|---|
+| Release identity | The shell API, Web client, backend, and plugin graph are qualified as one combination; independent versions would create untested combinations and ambiguous update availability. | Electron and `@deepseek-ai/dsh` always have the same exact version. A dsh upgrade is a Desktop release, even when the shell code is unchanged. |
+| Runtime | Electron's Node.js carries Electron patches, fuses, ABI, and lifecycle constraints, while system runtimes and package-manager state are uncontrolled. | dsh runs under the bundled upstream Node.js and every package operation uses the bundled pnpm. Electron's Node.js, system Node.js, system pnpm, and user package-manager configuration are outside the execution path. |
+| Package sources | Core installation at startup adds work even when offline. | `extraResources/dsh` carries a complete production dependency tree; the profile installs only external plugins. |
+| Shared modules | Host APIs can depend on module identity. | Desktop links every bundled first-party package into the profile using directory symlinks, or Windows junctions; ordinary plugin dependencies remain local. |
+| State ownership | Sharing executable dependency graphs would let CLI and Desktop change each other's dsh, Cordis, plugin, or native-module versions, while two desktop processes could race on the same profile. | Electron acquires its process-lifetime single-instance lock before any profile access and exclusively owns `$DSH_HOME/profiles/desktop` plus its package-manager state. CLI and Desktop share supported product data under `$DSH_HOME`, but never executable packages, plugin activation, lockfiles, or `node_modules`. |
+| Transport | A listening Web service adds port ownership, authentication, CORS, and exposure concerns; Electron and upstream Node.js also need an explicit cross-process protocol. | The application opens no Web port. `dsh-app://` carries Web assets and Fetch traffic; framed byte pipes carry bounded request and response chunks with backpressure, while Node IPC carries only child lifecycle control. |
+| Plugin changes | Package installation and Host startup can fail. | Desktop stops the Host and modifies the current profile directly. Failures retain partial changes for explicit repair; there is no automatic profile rollback. |
+| Updates | Independent shell and dsh updates would recreate version splits, while unchanged shell blocks should not require a complete transfer. | The Electron shell, matching dsh runtime, Node.js, and pnpm form one signed update unit. Platform update artifacts may reuse unchanged blocks, but runtime version selection never splits from the Desktop release. |
+
+The [Electron packaging and update Agent Note](../../.agents/notes/implemented/architecture/2026-08-25-electron-desktop-packaging-and-updates.md) owns the rationale, alternatives, security constraints, and release qualification requirements behind these decisions.
+
+## Installation ownership
+
+Electron owns `$DSH_HOME/profiles/desktop`. Its `dependencies` contains only installed external plugins at exact versions; `dsh.profile.bundles` contains the built-in bundles followed by enabled plugins. The signed application supplies dsh, the private Desktop Host, and their production packages from `resources/dsh`. Shared package links resolve to those actual directories. Both host and plugins execute in the same bundled upstream Node process, with normal realpath resolution; Desktop does not enable `--preserve-symlinks`. The CLI cannot boot or mutate this profile.
+
+The local startup page exposes startup status and available recovery actions; the loaded dsh renderer receives only the desktop protocol marker. The separate plugin window receives structured list, install, remove, update, and update-check operations; neither renderer receives filesystem access, raw Electron IPC, a shell, or arbitrary pnpm arguments.
+
+Electron chooses typed English or Chinese shell copy from its application locale and falls back to English. Menus, native dialogs, the startup page, and the plugin-management renderer use the same locale payload; the repository Client UI i18n gate checks these desktop sources.
+
+### Runtime and plugin activation
+
+The signed `resources/dsh/desktop-runtime.json` binds the shell version, bundled Node version, platform, architecture, shared package versions, and final file inventory. Startup reads the metadata and checks shared package records. Release schema, shell version, target compatibility, and file integrity are verified during packaging. Core packages are never copied into profile storage or installed by pnpm at first launch.
+
+1. The main window displays a local loading page before profile preparation or backend startup. A fresh profile creates its manifest and shared package links while preserving unrelated files, then starts the actual backend once. Unchanged startups reuse the profile without scanning installed plugin manifests.
+2. A compatible application upgrade refreshes shared links in the current profile and checks enabled plugins’ peer requirements. Plugin files, configuration, versions, and lockfile remain in place; pnpm does not run.
+3. A changed bundled Node version, platform, or architecture reinstalls the locked plugin graph with scripts disabled, validates and links host packages, then runs approved pending builds and validates again.
+4. Plugin add, update, and remove operations use bundled pnpm and Desktop-owned package-manager state. Reserved host packages must be peers; nested copies and aliases of shared packages fail validation. Ordinary plugin dependencies must resolve inside the profile.
+5. Plugin changes stop the backend before modifying the current profile. Successful preparation starts the Host. Package or Host startup failures retain modified files and report the error. Unfinished package operations retain a marker so the next launch retries the locked installation and pending builds. Desktop creates no staging directories, activation journals, or rollback copies.
+
+The loading page does not depend on the Host. Errors offer restart and reinstallation guidance. Disabling plugins and resetting Desktop are offered only when packaged application resources support profile recovery; development and early initialization failures expose restart alone. The plugin manager remains available through the application menu. Runtime identity is checked before any backend starts; plugin changes have no automatic rollback.
+
+Reset deletes every entry in `$DSH_HOME/profiles/desktop` except the held transaction lock, then initializes the built-in profile. It removes Desktop configuration and installed third-party packages without a backup. Shared tasks, settings, and the Harness-home `.env` are untouched. Shell resource and preload failures use a self-contained document with the available recovery actions and diagnostics; its controls do not require preload.
+
+Package transactions hold `$DSH_HOME/profiles/desktop/lock` exclusively through pnpm process exit. Reset preserves the directory and its lock until initialization and Host startup finish. Shared links use directory symlinks on macOS/Linux and junctions on Windows; cleanup removes links without deleting their targets. Canonical filesystem paths identify shared packages, so Windows path casing alone does not trigger profile activation. Native builds follow the profile’s reviewed `allowBuilds` list; installing a new build-requiring package without approval in that list fails the transaction.
+
+## Develop
+
+`dev:desktop` builds the current Host, client bundles, Web frontend, and Electron shell, projects the built CLI and private Desktop Host packages with their workspace dependencies into a disposable desktop npm project, and launches Electron without downloading the packaged Node.js runtime or resolving dsh from npm:
+
+```sh
+pnpm run dev:desktop
+```
+
+Development Harness state defaults to `apps/desktop/.desktop-build/development/home`, the disposable npm project lives at `apps/desktop/.desktop-build/development/project`, and Electron browser data lives at `apps/desktop/.desktop-build/development/electron-user-data`. Sessions, settings, credentials, package links, and browser data therefore stay out of the user's normal Harness home. An explicit `DSH_HOME` replaces only the development Harness home. Renderer DevTools opens automatically; Main, Renderer, and dsh Host debugging listen on ports 9229, 9222, and 9230. `DSH_DESKTOP_MAIN_INSPECT_PORT`, `DSH_DESKTOP_RENDERER_DEBUG_PORT`, and `DSH_DESKTOP_HOST_INSPECT_PORT` replace those ports, while `DSH_DESKTOP_OPEN_DEVTOOLS=0` keeps the detached Renderer tools closed.
+
+After an explicit build, `start:desktop` reconstructs the disposable project and launches the existing artifacts without building again:
+
+```sh
+pnpm run start:desktop
+```
+
+Workspace development runs the current CLI and private Desktop Host packages under the invoking Node.js and disables desktop package mutations. Its explicitly linked disposable profile is the only mode allowed to resolve bundles outside its own directory. Use an unpacked application to exercise the bundled Node.js, bundled pnpm, bundled dsh resources, plugin installation and repair paths.
+
+## Package
+
+The normal packaging path is one complete command. It performs release preparation before creating the host platform's installers and update metadata. Every target requires a reverse-DNS `DSH_DESKTOP_APP_ID`. macOS targets additionally require the electron-builder certificate qualifier in `DSH_DESKTOP_MACOS_SIGNING_IDENTITY`, its 10-character Apple Team ID in `DSH_DESKTOP_MACOS_TEAM_ID`, and one complete notarytool credential strategy. The App Store Connect API-key strategy uses these variables:
+
+```sh
+export DSH_DESKTOP_APP_ID='<reverse-DNS application ID>'
+export DSH_DESKTOP_MACOS_SIGNING_IDENTITY='<certificate name without the Developer ID Application prefix>'
+export DSH_DESKTOP_MACOS_TEAM_ID='<10-character Apple Team ID>'
+export APPLE_API_KEY='<absolute path to the .p8 file>'
+export APPLE_API_KEY_ID='<App Store Connect API Key ID>'
+export APPLE_API_ISSUER='<App Store Connect issuer UUID>'
+```
+
+`prepare:desktop` is not a prerequisite:
+
+```sh
+pnpm run package:desktop
+```
+
+Release automation uses fixed target commands so runtime preparation, dsh preparation, and electron-builder receive the same platform and architecture:
+
+```sh
+pnpm run package:desktop:mac:arm64
+pnpm run package:desktop:mac:x64
+pnpm run package:desktop:win:x64
+```
+
+The macOS arm64 command requires Apple Silicon. The macOS x64 command runs on Intel macOS or Apple Silicon with Rosetta. The Windows x64 command requires Windows x64. Linux is not a supported Desktop release target.
+
+Each target owns its packed package inputs, prepared runtime, package set, dsh tree, pnpm preparation state, unpacked application, update metadata, and final artifacts under `apps/desktop/.desktop-build/targets/<target>/`. The Node.js archive cache remains shared under `.desktop-build/downloads` because every archive name includes its version, platform, and architecture and is verified before extraction. A target build never consumes another target's mutable preparation state.
+
+### Runtime file selection
+
+Production packages first pass through npm's publication rules and dependency installation. [Desktop's file policy](scripts/runtime-file-policy.ts) then filters the immutable `resources/dsh/node_modules` copy before signing and integrity sealing. It omits TypeScript declarations, recognized JavaScript/CSS/TypeScript source maps, TypeScript build caches, Domino's test directory, selected native compiler outputs, and node-pty prebuilds for other platforms. It preserves runtime JavaScript, native modules and their DLL/EXE helpers, WASM, unknown assets, licenses, and notices. The policy does not alter npm tarballs, the bundled package manager, or user-installed plugin files.
+
+The packaged application runs compiled JavaScript and pre-generated Typert metadata; it does not compile TypeScript plugins. Source-level debugger navigation and editor declarations remain available in development packages. [Copy-policy tests](tests/runtime-file-policy.spec.ts) cover exclusions and retained assets; `prepare:dsh` runs the [payload smoke](tests/fixtures/runtime-payload-smoke.mjs) under the bundled Node before the Host smoke and final inventory verification.
+
+Windows release qualification also runs [native cleanup and replacement checks](scripts/smoke-windows.ps1) manually after the Desktop build. Set `$Electron` to the prepared Electron executable and `$Makensis`, `$SevenZip`, and `$PluginDir` to the pinned builder’s NSIS compiler, 7-Zip executable, and x86-unicode NSIS plugin directory. From the repository root, run the command below. It verifies Electron junction cleanup, installer scratch cleanup, and both locked-file replacement modes; it is not part of the unit-test lane.
+
+```powershell
+pwsh -NoProfile -File apps/desktop/scripts/smoke-windows.ps1 -Electron $Electron -Makensis $Makensis -SevenZip $SevenZip -PluginDir $PluginDir
+```
+
+### Upload updates
+
+`DSH_DESKTOP_AUTO_UPDATE_ENV` selects `test` or `production` for both the URL embedded during packaging and the later COS upload; an absent value selects `test`. Test packaging requires its HTTPS origin in `DOWNLOAD_TEST_ORIGIN`, while the production origin remains `https://download.deepseek.com`. Upload additionally requires the selected deployment's COS bucket in `DOWNLOAD_TEST_COS_BUCKET` or `DOWNLOAD_PROD_COS_BUCKET`. The target path is `_/harness/desktop/stable/<target>/`, where `target` is `mac-arm64`, `mac-x64`, or `win-x64`.
+
+The update destination and upload credentials follow the selected deployment:
+
+| Environment | Public origin | COS bucket | COS credentials |
+|---|---|---|---|
+| `test` or unset | `DOWNLOAD_TEST_ORIGIN` | `DOWNLOAD_TEST_COS_BUCKET` | `DOWNLOAD_TEST_COS_SECRET_ID`, `DOWNLOAD_TEST_COS_SECRET_KEY` |
+| `production` | `https://download.deepseek.com` | `DOWNLOAD_PROD_COS_BUCKET` | `DOWNLOAD_PROD_COS_SECRET_ID`, `DOWNLOAD_PROD_COS_SECRET_KEY` |
+
+Package and upload one target under the same environment. For example, the default test deployment uses:
+
+```sh
+export DOWNLOAD_TEST_ORIGIN='https://desktop-updates.example.com'
+pnpm run package:desktop:mac:arm64
+
+export DOWNLOAD_TEST_COS_BUCKET='<test COS bucket>'
+export DOWNLOAD_TEST_COS_SECRET_ID='<test COS SecretId>'
+export DOWNLOAD_TEST_COS_SECRET_KEY='<test COS SecretKey>'
+pnpm run upload:mac:arm64
+```
+
+Set `DSH_DESKTOP_AUTO_UPDATE_ENV=production` before packaging, then provide `DOWNLOAD_PROD_COS_BUCKET` and the production credential pair before running `upload:mac:arm64`, `upload:mac:x64`, or `upload:win:x64`. Packaging does not require a COS bucket or credentials. It explicitly disables electron-builder publishing, strips all four COS credential fields from its subprocesses, and writes a target completion record only after electron-builder and every signing or notarization hook succeeds. Upload requires that record to match the selected environment, target, public URL, and current dsh version; it also requires the root dsh version, Desktop version, channel metadata version, artifact names, sizes, and SHA-512 values to agree before it reads the selected COS credential pair. It uploads only that target's immutable versioned artifacts, uploads the version-derived channel metadata last with `no-cache`, and never deletes historical objects. Stable releases use `latest-mac.yml` or `latest.yml`; a prerelease such as `alpha` uses `alpha-mac.yml` or `alpha.yml`, matching electron-builder's emitted filename.
+
+The macOS configuration uses the required release environment instead of accepting whichever certificate appears first in a keychain. It rejects empty values, a malformed Team ID, a signing identity that includes electron-builder's unsupported `Developer ID Application:` prefix, and incomplete notarization credentials. macOS packaging requires the configured identity and its private key. Runtime preparation applies that identity, a secure timestamp, and hardened runtime to every embedded Mach-O file; after signing the application, a deep strict check rejects any other leaf authority or Team ID before artifact creation. The fixed-target macOS installer commands create separate copies of the signed application and run two artifact lanes concurrently. One lane notarizes and staples the App before generating the ZIP and its update metadata. The other encloses its signed App copy in a signed DMG, then notarizes, staples, and verifies the DMG; its inner App has no individually stapled ticket. Both lanes must finish successfully before their artifacts reach the final directory and the release completion record is written. Directory-only commands also require notarization credentials and wait for Apple notarization and App stapling. The [parallel notarization decision](../../.agents/notes/implemented/process/2026-09-09-parallel-macos-notarization.md) owns copy isolation and container ticket semantics. The private key can come from the login keychain or electron-builder's standard `CSC_LINK` input; ambient `CSC_NAME` and certificate discovery order do not select the release owner. Notary credentials may instead use electron-builder's complete Apple ID or keychain-profile strategy. The two macOS identity variables are also required when repeating the application check manually with `pnpm --dir apps/desktop run verify:mac-signature -- <path-to-app>`.
+
+macOS signing visits real files without following Framework symlink aliases. PAK resources retain all shipped languages and are sealed by the enclosing Framework or application signature instead of receiving individual signatures. The [release policy](../../.agents/notes/implemented/architecture/2026-08-25-electron-desktop-packaging-and-updates.md) owns the dependency patch and verification requirements.
+
+Company proxies can accelerate uploads to Apple's notarization service. See the company internal documentation for configuration.
+
+### Unsigned Windows test installer
+
+On Windows x64, use the complete unsigned packaging command for local installation testing:
+
+```sh
+pnpm run package:desktop:win:x64:unsigned
+```
+
+The command requires `DSH_DESKTOP_APP_ID` and the normal build dependencies, including Python and Visual C++ build tools for native modules. Set `PYTHON` to the Python executable when it is absent from `PATH`. It writes the installer to `.desktop-build/targets/win-x64/unsigned-artifacts/`, omits automatic-update configuration, strips signing credentials, and creates no release completion record. It does not require EV credentials or an update origin. The signed packaging and upload commands retain their release requirements.
+
+### Windows EV signing
+
+Windows packaging fixes the 7-Zip filter to `BCJ` for compatibility with the bundled NSIS decoder. This preserves ARM64 binaries carried by dependencies in x64 installers; automatic ARM64 filtering produces entries that this decoder cannot extract.
+
+NSIS removes its temporary extraction tree during installation, before the completion page or an automatic launch. The installed production packages remain ordinary files; startup does not extract them again. Installation still writes the complete application tree.
+
+Windows release packaging requires `DSH_DESKTOP_WINDOWS_CER_FILE` to identify the public GlobalSign EV leaf certificate, `DSH_DESKTOP_WINDOWS_SIGNTOOL` to identify the SafeNet-compatible SignTool executable, `DSH_DESKTOP_WINDOWS_KEY_CONTAINER` to identify the matching private-key container, and `DSH_DESKTOP_WINDOWS_TOKEN_PIN` to contain the SafeNet Token Password. The certificate file remains outside source control, and the matching private key stays on the USB token. Set the four inputs before running the fixed Windows target:
+
+```powershell
+$env:DSH_DESKTOP_WINDOWS_CER_FILE = 'C:\path\to\server.cer'
+$env:DSH_DESKTOP_WINDOWS_SIGNTOOL = 'C:\path\to\the\validated\signtool.exe'
+$env:DSH_DESKTOP_WINDOWS_KEY_CONTAINER = '<SafeNet private-key container name>'
+$env:DSH_DESKTOP_WINDOWS_TOKEN_PIN = '<SafeNet Token Password>'
+pnpm run package:desktop:win:x64
+```
+
+Insert and unlock the token before packaging. The electron-builder hook passes each artifact to the CRLF `scripts/windows-sign.cmd`, which invokes the configured SignTool once with `/f`, SafeNet `/kc "[{{PIN}}]=container"`, `/csp "eToken Base Cryptographic Provider"`, a SHA-256 file digest, and a DigiCert SHA-256 RFC 3161 timestamp. The hook never substitutes electron-builder's bundled SignTool and never retries a failed signing request. Windows release packaging fails instead of emitting unsigned artifacts when the SignTool, certificate, container, PIN, token, or signature is unavailable.
+
+The PIN cannot contain `]`, a quote, or a line break because those characters delimit the SafeNet `/kc` value or its CMD argument. The CMD disables delayed expansion so a PIN containing `!` reaches SafeNet unchanged. Packaging withholds every `DSH_DESKTOP_WINDOWS_*` field from build and runtime-preparation subprocesses, gives electron-builder only the four configured inputs, gives the signing CMD only the validated signing fields in an otherwise scrubbed environment, clears those fields before SignTool starts, and redacts SignTool diagnostics. SafeNet still requires the PIN in the SignTool process command line. Inject it as an ephemeral secret only on a controlled self-hosted Windows runner with the physical token attached; never commit it, put it in `.env`, or persist it as a Windows user or system environment variable.
+
+Create a runnable application directory instead of an installer by using the matching `:dir` command, such as:
+
+```sh
+pnpm run package:desktop:dir
+pnpm run package:desktop:mac:arm64:dir
+```
+
+To inspect or troubleshoot the prepared host-target resources without invoking electron-builder, stop the same pipeline after preparation:
+
+```sh
+pnpm run prepare:desktop
+```
+
+This diagnostic command is an alternative stopping point, not the first half of a two-command build. A later `package:desktop*` command repeats the official build and preparation so it cannot consume stale dsh packages, runtime files, or dsh content.
+
+Every package command builds the repository, packs the first-party production closures rooted at dsh and the private Desktop Host, and prepares target-specific Node and pnpm executables. `prepare:dsh` installs the production graph once at build time, copies materialized packages into `extraResources/dsh`, removes package-manager metadata, and writes `desktop-runtime.json` with shared package versions and final file hashes. On macOS it signs and verifies native files before inventory generation; electron-builder excludes this already-signed tree from nested re-signing. Resource mappings explicitly include `dsh/node_modules`, which the default root-directory filter omits; the copied inventory is checked before signing and again after signing. Signed installer, notarization, installed upgrade, and target-specific native-module qualification require the release environment.
+
+An unpacked artifact contains Electron, the materialized dsh production tree, upstream Node.js and pnpm, and the shell application. Installer size and filesystem size differ; release qualification measures both, plus the profile’s plugin storage and first-launch latency. The runtime trades more application files for eliminating core package installation on the user’s machine.
+
+## Updates
+
+A packaged application checks its target-specific release stream ten seconds after the main window opens; the localized **Check for Updates…** menu item triggers the same check manually. An available release opens one native confirmation dialog. Accepting it waits for an in-flight check, downloads and verifies the signed Desktop release, stops the dsh child, and hands installation plus restart to electron-updater. The next launch displays the local loading page while reconciling the version-bound runtime.
+
+Signed packaging emits generic-provider channel metadata for the deployment selected by `DSH_DESKTOP_AUTO_UPDATE_ENV`. NSIS differential packages and the macOS ZIP target allow electron-updater to reuse unchanged blocks; the manually installed DMG is notarized without a blockmap because it is not a macOS updater payload. The runtime and shell still form one signed Desktop release. macOS signing and notarization credentials use electron-builder's standard environment; Windows EV signing uses the public certificate, validated SignTool, SafeNet container, and runner PIN described above. The required Desktop release environment selects the application and platform signature identities that the build verifies.
+
+## Low-level development overrides
+
+An unpackaged Electron process uses `.desktop-build/development/project` under its application directory as its development project. `DSH_DESKTOP_NODE_BINARY`, `DSH_DESKTOP_PNPM_ENTRY`, and `DSH_DESKTOP_DSH_DIR` select explicit runtime resources. Packaged applications ignore these variables, resolve signed resources from `process.resourcesPath`, and use the managed Desktop profile.
+
+## Known limitations
+
+- The Web "Open In..." action is disabled in Desktop because its host plugin requires HTTP routes; Desktop does not provide a `webServer`.
+- Release signing, notarization, update hosting, and previous-version installed-artifact qualification require the production release environment.
+- Desktop plugins with dependency lifecycle scripts are rejected unless their package appears in the desktop project's reviewed `allowBuilds` policy.
+- The desktop shell shares sessions, settings, credentials, workspaces, and storage under `$DSH_HOME` with CLI dsh, while executable packages, plugin activation, lockfiles, and package-manager state remain separate.

apps/desktop/README.zh.md

@@ -0,0 +1,202 @@
+# DeepSeek Harness 桌面端
+
+[English](README.md) | 中文
+
+桌面应用是包裹 dsh Web UI 的 Electron 壳。它不打开监听端口：内置的上游 Node.js 子进程启动已安装的 dsh 项目，带版本的分帧字节管道在没有外层 Base64 信封的情况下承载 Fetch 请求与流式响应，Node IPC 承载生命周期控制，`dsh-app://` 则提供与后端版本匹配的客户端资源。
+
+## 关键技术决策
+
+| 决策 | 原因 | 直接结果 |
+|---|---|---|
+| 发布身份 | 桌面壳 API、Web 客户端、后端与插件依赖图作为一个组合完成验证；独立版本会产生未经验证的组合，并让更新可用性含糊不清。 | Electron 与 `@deepseek-ai/dsh` 始终使用同一精确版本。即使桌面壳代码不变，升级 dsh 也必须发布新 Desktop 版本。 |
+| 运行时 | Electron 的 Node.js 带有 Electron 补丁、fuse、ABI 与生命周期约束，而系统运行时和包管理器状态不可控。 | dsh 通过内置的上游 Node.js 运行，所有包操作都使用内置 pnpm。Electron 的 Node.js、系统 Node.js、系统 pnpm 与用户的包管理器配置都不进入执行路径。 |
+| 包来源 | 即使离线，启动时安装核心依赖也会增加开销。 | `extraResources/dsh` 携带完整生产依赖树；profile 只安装外部插件。 |
+| 共享模块 | 宿主 API 可能依赖模块实例身份。 | Desktop 用目录软链接或 Windows junction 把每个内置第一方包连接到 profile；普通插件依赖保留在本地。 |
+| 状态归属 | 共享可执行依赖图会让 CLI（命令行界面）与 Desktop 相互改变 dsh、Cordis、插件或原生模块版本，而两个桌面进程还可能争用同一个 profile。 | Electron 在访问任何 profile 前获取进程生命周期单实例锁，并独占 `$DSH_HOME/profiles/desktop` 及其包管理器状态。CLI 与 Desktop 共享 `$DSH_HOME` 下受支持的产品数据，但绝不共享可执行包、插件激活、锁文件或 `node_modules`。 |
+| 通信 | 监听 Web 服务会引入端口归属、认证、CORS 与暴露风险；Electron 与上游 Node.js 之间也需要明确的跨进程协议。 | 应用不打开 Web 端口。`dsh-app://` 承载 Web 资源和 Fetch 流量；分帧字节管道以背压传输有界请求与响应分块，Node IPC 只承载子进程生命周期控制。 |
+| 插件变更 | 包安装和 Host 启动可能失败。 | Desktop 停止 Host 后直接修改当前 profile。失败保留部分修改供用户修复，不自动回滚 profile。 |
+| 更新 | 桌面壳与 dsh 独立更新会重新产生版本分裂，而桌面壳未变化的数据块不应强制完整传输。 | Electron 壳、匹配的 dsh 运行时、Node.js 与 pnpm 组成一个已签名更新单元。平台更新产物可以复用未变化的数据块，但运行时版本选择绝不脱离 Desktop 发布。 |
+
+[Electron 打包与更新 Agent Note](../../.agents/notes/implemented/architecture/2026-08-25-electron-desktop-packaging-and-updates.zh.md) 记录了这些决策背后的理由、替代方案、安全约束和发布验证要求。
+
+## 安装归属
+
+Electron 拥有 `$DSH_HOME/profiles/desktop`。其 `dependencies` 只包含已安装外部插件的精确版本；`dsh.profile.bundles` 包含内置 bundle，后接已启用插件。签名应用从 `resources/dsh` 提供 dsh、私有 Desktop Host 及其生产依赖。共享包链接解析到这些实际目录。宿主与插件在同一个内置上游 Node 进程中执行，使用正常的 realpath 解析；Desktop 不启用 `--preserve-symlinks`。CLI 不能启动或修改此 profile。
+
+本地启动页提供启动状态和可用恢复操作；加载后的 dsh 渲染进程仅接收桌面协议标记。独立插件窗口接收结构化的列表、安装、删除、更新和更新检查操作；两个渲染进程都无法访问文件系统、原始 Electron IPC、shell 或任意 pnpm 参数。
+
+Electron 根据应用 locale 选择类型化的英文或中文桌面壳文案，并以英文作为 fallback。菜单、原生对话框、启动页与插件管理渲染进程使用同一 locale 数据；仓库的 Client UI i18n gate 会检查这些桌面源文件。
+
+### 运行时与插件激活
+
+签名资源中的 `resources/dsh/desktop-runtime.json` 绑定 shell 版本、内置 Node 版本、平台、架构、共享包版本和最终文件清单。启动读取元数据，并检查共享包记录。发布 schema、shell 版本、目标兼容性和文件完整性在打包时验证。首次启动不会把核心包复制到 profile 存储或通过 pnpm 安装核心包。
+
+1. 主窗口在 profile 准备或后端启动前显示本地加载页。新 profile 创建清单和共享包链接，保留无关文件，然后启动一次实际后端。未变化的启动复用 profile，不扫描已安装插件的清单。
+2. 兼容的应用升级在当前 profile 中刷新共享链接，并检查已启用插件的 peer 要求。插件文件、配置、版本和锁文件留在原处；不运行 pnpm。
+3. 内置 Node 版本、平���或架构变化时，禁用脚本重新安装锁定的插件依赖图，验证并链接宿主包，然后运行已批准的待执行构建并再次验证。
+4. 插件添加、更新和删除使用内置 pnpm 及 Desktop 独有的包管理器状态。保留的宿主包必须声明为 peer；共享包的嵌套副本和别名会被验证拒绝。普通插件依赖必须解析到 profile 内部。
+5. 插件变更在直接修改当前 profile 前停止后端。准备成功后启动 Host。包操作或 Host 启动失败会保留已修改文件并报告错误。未完成的包操作保留标记，使下次启动重试锁定依赖的安装和待执行构建。Desktop 不创建 staging 目录、激活日志或回滚副本。
+
+加载页不依赖 Host。错误页提供重启和重装指导。只有已打包应用的资源支持 profile 恢复时，才提供禁用插件和重置 Desktop；开发模式和早期初始化失败只提供重启。应用菜单仍提供插件管理器入口。每次后端启动前都会检查运行时标识；插件修改不自动回滚。
+
+重置删除 `$DSH_HOME/profiles/desktop` 中除所持事务锁外的所有条目，然后初始化内置 profile。它删除 Desktop 配置和已安装第三方包，不保留备份。共享任务、设置和 Harness-home `.env` 保持不变。壳资源和 preload 失败时使用独立文档显示可用恢复操作和诊断；其控件不依赖 preload。
+
+包事务独占持有 `$DSH_HOME/profiles/desktop/lock`，直到 pnpm 进程退出。重置保留目录及其锁，直到初始化和 Host 启动完成。共享链接在 macOS/Linux 使用目录软链接，在 Windows 使用 junction；清理只移除链接，不删除其目标。共享包使用文件系统的规范路径识别，因此 Windows 路径大小写变化不会单独触发 profile 激活。原生构建遵循 profile 中经过审查的 `allowBuilds` 列表；新安装的包如果需要构建但未在列表中获准，事务会失败。
+
+## 开发
+
+`dev:desktop` 会构建当前 Host、客户端 bundle、Web 前端和 Electron 壳，把已构建的 CLI 包、私有 Desktop Host 包及其 workspace 依赖投影为一次性桌面 npm 项目，然后直接启动 Electron；这条路径不下载安装包内的 Node.js，也不从 npm 解析 dsh：
+
+```sh
+pnpm run dev:desktop
+```
+
+开发 Harness 状态默认写入 `apps/desktop/.desktop-build/development/home`，一次性 npm 项目位于 `apps/desktop/.desktop-build/development/project`，Electron 浏览器数据则位于 `apps/desktop/.desktop-build/development/electron-user-data`。因此，会话、设置、凭据、包链接和浏览器数据都不会进入用户正常使用的 Harness home；显式 `DSH_HOME` 只会替换开发 Harness home。Renderer DevTools 默认自动打开，Main、Renderer 和 dsh Host 调试端口依次为 9229、9222 和 9230。`DSH_DESKTOP_MAIN_INSPECT_PORT`、`DSH_DESKTOP_RENDERER_DEBUG_PORT` 与 `DSH_DESKTOP_HOST_INSPECT_PORT` 可以替换这些端口，`DSH_DESKTOP_OPEN_DEVTOOLS=0` 则保持 Renderer 调试窗口关闭。
+
+显式构建完成后，`start:desktop` 会重新生成一次性项目，并跳过构建直接启动已有产物：
+
+```sh
+pnpm run start:desktop
+```
+
+Workspace 开发使用调用命令的 Node.js 运行当前 CLI 与私有 Desktop Host 包，并禁用桌面包修改；只有该模式明确链接的一次性 profile 可以从自身目录外解析 bundle。需要验证内置 Node.js、内置 pnpm、内置 dsh 资源、插件安装和修复时，应运行未封装安装器的应用目录。
+
+## 打包
+
+正常打包只需执行一条完整命令。该命令会先准备发布资源，再生成宿主平台的安装包与更新元数据。所有目标都要求通过 `DSH_DESKTOP_APP_ID` 提供反向域名形式的应用 ID。macOS 目标还要求通过 `DSH_DESKTOP_MACOS_SIGNING_IDENTITY` 提供 electron-builder 证书限定名，通过 `DSH_DESKTOP_MACOS_TEAM_ID` 提供对应的 10 字符 Apple Team ID，并提供一套完整的 notarytool 凭据方案。App Store Connect API Key 方式使用以下变量：
+
+```sh
+export DSH_DESKTOP_APP_ID='<reverse-DNS application ID>'
+export DSH_DESKTOP_MACOS_SIGNING_IDENTITY='<certificate name without the Developer ID Application prefix>'
+export DSH_DESKTOP_MACOS_TEAM_ID='<10-character Apple Team ID>'
+export APPLE_API_KEY='<absolute path to the .p8 file>'
+export APPLE_API_KEY_ID='<App Store Connect API Key ID>'
+export APPLE_API_ISSUER='<App Store Connect issuer UUID>'
+```
+
+无需提前执行 `prepare:desktop`：
+
+```sh
+pnpm run package:desktop
+```
+
+发布自动化使用固定目标命令，确保运行时准备、dsh 准备与 electron-builder 接收相同的平台和架构：
+
+```sh
+pnpm run package:desktop:mac:arm64
+pnpm run package:desktop:mac:x64
+pnpm run package:desktop:win:x64
+```
+
+macOS arm64 命令要求 Apple Silicon。macOS x64 命令可以在 Intel macOS 或带 Rosetta 的 Apple Silicon 上运行。Windows x64 命令要求 Windows x64。Linux 不是受支持的 Desktop 发布目标。
+
+每个目标都在 `apps/desktop/.desktop-build/targets/<target>/` 下持有自己的打包输入、已准备运行时、包集合、dsh 依赖树、pnpm 准备状态、未打包应用、更新元数据和最终产物。Node.js 归档缓存继续由 `.desktop-build/downloads` 共享，因为每个归档文件名都包含版本、平台和架构，并且在解包前经过验证。目标构建绝不读取其他目标的可变准备状态。
+
+### 运行时文件筛选
+
+生产包首先经过 npm 发布规则和依赖安装。[桌面文件规则](scripts/runtime-file-policy.ts)随后在签名和完整性封存之前过滤不可变的 `resources/dsh/node_modules` 副本。它排除 TypeScript 声明、明确属于 JavaScript/CSS/TypeScript 的 source map、TypeScript 构建缓存、Domino 测试目录、指定的原生编译产物，以及其他平台的 node-pty 预构建文件。它保留运行时 JavaScript、原生模块及其 DLL/EXE 辅助程序、WASM、未知资源、许可证和声明。规则不会修改 npm tarball、内置包管理器或用户安装的插件文件。
+
+打包应用运行编译后的 JavaScript 和预生成的 Typert 元数据，不编译 TypeScript 插件。源码级调试导航和编辑器声明仍可从开发包中获取。[复制规则测试](tests/runtime-file-policy.spec.ts)覆盖排除项和保留资源；`prepare:dsh` 在 Host smoke 和最终清单验证之前，使用内置 Node 执行[产物 smoke](tests/fixtures/runtime-payload-smoke.mjs)。
+
+Windows 发布验收还需在 Desktop 构建后手动运行[原生清理和替换检查](scripts/smoke-windows.ps1)。将 `$Electron` 设为已准备的 Electron 可执行文件，将 `$Makensis`、`$SevenZip` 和 `$PluginDir` 分别设为锁定版本构建器的 NSIS 编译器、7-Zip 可执行文件和 x86-unicode NSIS 插件目录。从仓库根目录运行以下命令。它验证 Electron junction 清理、安装器临时目录清理和两种文件占用替换方式；不属于单元测试通道。
+
+```powershell
+pwsh -NoProfile -File apps/desktop/scripts/smoke-windows.ps1 -Electron $Electron -Makensis $Makensis -SevenZip $SevenZip -PluginDir $PluginDir
+```
+
+### 上传更新
+
+`DSH_DESKTOP_AUTO_UPDATE_ENV` 同时选择打包时写入的更新 URL 与后续 COS 上传目标，可取 `test` 或 `production`；未设置时使用 `test`。测试打包必须通过 `DOWNLOAD_TEST_ORIGIN` 提供 HTTPS origin，生产 origin 仍为 `https://download.deepseek.com`。上传还必须通过 `DOWNLOAD_TEST_COS_BUCKET` 或 `DOWNLOAD_PROD_COS_BUCKET` 提供所选环境的 COS bucket。目标路径为 `_/harness/desktop/stable/<target>/`，其中 `target` 为 `mac-arm64`、`mac-x64` 或 `win-x64`。
+
+更新目标与上传凭据都与所选环境对应：
+
+| 环境 | 公开 origin | COS bucket | COS 凭据 |
+|---|---|---|---|
+| `test` 或未设置 | `DOWNLOAD_TEST_ORIGIN` | `DOWNLOAD_TEST_COS_BUCKET` | `DOWNLOAD_TEST_COS_SECRET_ID`、`DOWNLOAD_TEST_COS_SECRET_KEY` |
+| `production` | `https://download.deepseek.com` | `DOWNLOAD_PROD_COS_BUCKET` | `DOWNLOAD_PROD_COS_SECRET_ID`、`DOWNLOAD_PROD_COS_SECRET_KEY` |
+
+同一目标必须在同一环境下完成打包与上传。例如，默认测试环境使用：
+
+```sh
+export DOWNLOAD_TEST_ORIGIN='https://desktop-updates.example.com'
+pnpm run package:desktop:mac:arm64
+
+export DOWNLOAD_TEST_COS_BUCKET='<test COS bucket>'
+export DOWNLOAD_TEST_COS_SECRET_ID='<test COS SecretId>'
+export DOWNLOAD_TEST_COS_SECRET_KEY='<test COS SecretKey>'
+pnpm run upload:mac:arm64
+```
+
+生产发布需在打包前设置 `DSH_DESKTOP_AUTO_UPDATE_ENV=production`，再在执行 `upload:mac:arm64`、`upload:mac:x64` 或 `upload:win:x64` 前提供 `DOWNLOAD_PROD_COS_BUCKET` 与生产凭据对。打包不要求 COS bucket 或凭据。它会明确禁止 electron-builder 发布，从其子进程中删除全部四个 COS 凭据字段，并且只有在 electron-builder 以及全部签名或公证钩子成功后才写入目标完成记录。上传会先要求该记录与所选环境、目标、公开 URL 和当前 dsh 版本一致，再要求根 dsh 版本、Desktop 版本、频道元数据版本、产物名称、大小与 SHA-512 全部一致，之后才读取所选 COS 凭据对。它只上传该目标不可变且带版本的产物，最后以 `no-cache` 上传根据版本得出的频道元数据，并且不会删除历史对象。稳定版本使用 `latest-mac.yml` 或 `latest.yml`；`alpha` 等预发布版本则使用 `alpha-mac.yml` 或 `alpha.yml`，与 electron-builder 生成的文件名一致。
+
+macOS 配置使用必填发布环境，不会接受钥匙串中最先发现的证书。空值、格式错误的 Team ID、包含 electron-builder 不支持的 `Developer ID Application:` 前缀的签名身份，以及不完整的公证凭据都会被拒绝。macOS 打包要求已配置的身份及其私钥可用。运行时准备会把该身份、安全时间戳与 hardened runtime 应用到每个内嵌 Mach-O 文件；应用签名完成后，深度严格检查会拒绝其他叶证书 Authority 或 Team ID，验证通过才生成发布产物。macOS 固定目标安装包命令为已签名应用创建独立副本，并发执行两条产物流。一路先公证 App 并钉票，再生成 ZIP 及其更新元数据。另一路把已签名 App 副本封装进签名 DMG，再公证 DMG、钉票并验证；其中的 App 不单独附加票据。只有两路均成功结束，产物才会移入最终目录并写入发布完成记录。仅生成目录的命令同样需要公证凭据，并等待 Apple 公证和 App 钉票完成。[并行公证决策](../../.agents/notes/implemented/process/2026-09-09-parallel-macos-notarization.zh.md)负责副本隔离与容器票据语义。私钥可以来自登录钥匙串或 electron-builder 的标准 `CSC_LINK` 输入；环境中的 `CSC_NAME` 与证书发现顺序都不能选择发布所有者。公证凭据也可以使用 electron-builder 支持的完整 Apple ID 或钥匙串 profile 方式。手动执行 `pnpm --dir apps/desktop run verify:mac-signature -- <path-to-app>` 重复应用检查时，也必须提供两个 macOS 身份变量。
+
+macOS 签名遍历真实文件，不跟随 Framework 的软链接别名。PAK 资源保留全部随附语言，由外层 Framework 或应用签名记录完整性，不逐个签名。[发布策略](../../.agents/notes/implemented/architecture/2026-08-25-electron-desktop-packaging-and-updates.zh.md)负责依赖补丁和验证要求。
+
+可通过公司代理加速向 Apple 公证服务上传。代理配置参见公司内部文档。
+
+### 未签名 Windows 测试安装包
+
+在 Windows x64 上，使用完整的未签名打包命令进行本地安装测试：
+
+```sh
+pnpm run package:desktop:win:x64:unsigned
+```
+
+该命令要求设置 `DSH_DESKTOP_APP_ID` 并具备常规构建依赖，包括编译原生模块所需的 Python 和 Visual C++ 构建工具。Python 不在 `PATH` 中时，将 `PYTHON` 设置为其可执行文件路径。命令将安装包写入 `.desktop-build/targets/win-x64/unsigned-artifacts/`，省略自动更新配置，清除签名凭据，且不生成发布完成记录。它不需要 EV 凭据或更新源地址。签名打包和上传命令仍遵循正式发布要求。
+
+### Windows EV 签名
+
+Windows 打包将 7-Zip 过滤器固定为 `BCJ`，以兼容内置的 NSIS 解码器。这样可以保留 x64 安装包中由依赖携带的 ARM64 二进制文件；自动 ARM64 过滤会生成该解码器无法解压的条目。
+
+NSIS 在安装阶段清理临时解压目录，完成后才显示完成页或自动启动应用。已安装的生产依赖保持为普通文件；启动时不会再次解压。安装仍会写入完整的应用目录树。
+
+Windows 发布打包要求 `DSH_DESKTOP_WINDOWS_CER_FILE` 标识公开的 GlobalSign EV 叶证书，要求 `DSH_DESKTOP_WINDOWS_SIGNTOOL` 标识与 SafeNet 兼容的 SignTool 可执行文件，要求 `DSH_DESKTOP_WINDOWS_KEY_CONTAINER` 标识匹配的私钥容器，并要求 `DSH_DESKTOP_WINDOWS_TOKEN_PIN` 包含 SafeNet Token Password。证书文件保留在源码仓库之外，匹配的私钥仍位于 USB Token。运行固定 Windows 目标前设置这四个输入：
+
+```powershell
+$env:DSH_DESKTOP_WINDOWS_CER_FILE = 'C:\path\to\server.cer'
+$env:DSH_DESKTOP_WINDOWS_SIGNTOOL = 'C:\path\to\the\validated\signtool.exe'
+$env:DSH_DESKTOP_WINDOWS_KEY_CONTAINER = '<SafeNet private-key container name>'
+$env:DSH_DESKTOP_WINDOWS_TOKEN_PIN = '<SafeNet Token Password>'
+pnpm run package:desktop:win:x64
+```
+
+打包前插入并解锁 Token。electron-builder 钩子把每个产物交给采用 CRLF 的 `scripts/windows-sign.cmd`；该 CMD 只调用一次已配置的 SignTool，并指定 `/f`、SafeNet `/kc "[{{PIN}}]=容器"`、`/csp "eToken Base Cryptographic Provider"`、SHA-256 文件摘要和 DigiCert SHA-256 RFC 3161 时间戳。钩子不会改用 electron-builder 内置的 SignTool，也不会重试失败的签名请求。SignTool、证书、容器、PIN、Token 或签名不可用时，Windows 发布打包会失败，不会生成未签名产物。
+
+PIN 不能包含 `]`、引号或换行，因为这些字符用于分隔 SafeNet `/kc` 值或对应的 CMD 参数。CMD 会禁用延迟展开，因此包含 `!` 的 PIN 可以原样到达 SafeNet。打包流程不会把任何 `DSH_DESKTOP_WINDOWS_*` 字段传给构建与 运行时准备子进程；它只向 electron-builder 提供四个配置输入，在其他字段已经清理的环境中只向签名 CMD 提供经过校验的签名字段，在 SignTool 启动前清除这些字段，并遮盖 SignTool 诊断。SafeNet 仍要求 PIN 出现在 SignTool 进程命令行中。只能在连接了物理 Token 的受控 self-hosted Windows runner 上把它注入为临时 secret；绝不能提交该值、把它写进 `.env`，或持久保存为 Windows 用户或系统环境变量。
+
+使用对应的 `:dir` 命令可以生成可直接运行的应用目录，而不是安装包，例如：
+
+```sh
+pnpm run package:desktop:dir
+pnpm run package:desktop:mac:arm64:dir
+```
+
+需要检查或诊断为宿主目标准备的资源而不调用 electron-builder 时，可以让同一流水线在准备完成后��止：
+
+```sh
+pnpm run prepare:desktop
+```
+
+这条诊断命令是另一种停止位置，并非两条命令构建流程的前半段。之后执行 `package:desktop*` 时仍会重新完成正式构建与准备，避免使用陈旧的 dsh 包、运行时文件或 dsh 内容。
+
+每条打包命令都会构建仓库，打包以 dsh 和私有 Desktop Host 为根的第一方生产依赖闭包，并准备目标专用的 Node 与 pnpm 可执行文件。`prepare:dsh` 在构建时安装一次生产依赖图，把物化包复制到 `extraResources/dsh`，移除包管理器元数据，并生成包含共享包版本和最终文件哈希的 `desktop-runtime.json`。在 macOS 上，它先签名并验证原生文件，再生成清单；electron-builder 不对已签名的此目录重复进行嵌套签名。资源映射明确包含默认根目录过滤器会忽略的 `dsh/node_modules`；复制后的清单在签名前及签名后分别验证。签名安装包、公证、已安装应用升级和各目标原生模块的验收需要发布环境。
+
+未压缩产物包含 Electron、物化后的 dsh 生产依赖树、上游 Node.js 与 pnpm，以及壳应用。安装包大小与文件系统占用不同；发布验收需要测量两者，以及 profile 插件存储和首次启动耗时。此布局用更多应用内文件换取消除用户机器上的核心包安装过程。
+
+## 更新
+
+打包应用会在主窗口打开十秒后检查目标专用的发布流；本地化的 **检查更新…** 菜单项会手动触发同一检查。发现可用版本时，应用打开一个原生确认弹窗。用户确认后，应用等待正在进行的检查完成，下载并验证已签名的 Desktop 发布、停止 dsh 子进程，并把安装与重启交给 electron-updater。下次启动在显示本地加载页的同时校准版本绑定的运行时。
+
+签名打包为 `DSH_DESKTOP_AUTO_UPDATE_ENV` 选择的部署生成 generic-provider 频道元数据。NSIS 差分包与 macOS ZIP 目标让 electron-updater 可以复用未变化的数据块；供手动安装的 DMG 经过公证，但不生成 blockmap，因为它不是 macOS updater 的载荷。运行时与桌面壳仍属于同一个签名 Desktop 发布。macOS 签名与公证凭据使用 electron-builder 的标准环境变量；Windows EV 签名使用上文所述的公开证书、已验证 SignTool、SafeNet 容器和 runner PIN。必填 Desktop 发布环境选择构建所验证的应用身份与平台签名身份。
+
+## 底层开发覆盖项
+
+未打包的 Electron 进程使用应用目录下的 `.desktop-build/development/project` 作为开发项目。`DSH_DESKTOP_NODE_BINARY`、`DSH_DESKTOP_PNPM_ENTRY` 和 `DSH_DESKTOP_DSH_DIR` 用于选择明确的运行时资源。打包应用会忽略这些变量，从 `process.resourcesPath` 解析签名资源，并使用受管 Desktop profile。
+
+## 已知限制
+
+- Desktop 禁用 Web 的「在本地应用中打开…」操作，因为其 Host 插件依赖 HTTP 路由，而 Desktop 不提供 `webServer`。
+- 发布签名、公证、更新托管和跨上一版本的已安装产物验证需要生产发布环境。
+- 依赖包含 lifecycle script 的桌面插件，只有其包名进入桌面项目经过评审的 `allowBuilds` 策略后才能安装。
+- 桌面壳与 CLI dsh 共享 `$DSH_HOME` 下的会话、设置、凭据、工作区和存储，但可执行包、插件激活、锁文件与包管理器状态彼此隔离。

apps/desktop/electron-builder.config.d.mts

@@ -0,0 +1,49 @@
+/** Electron-builder fields asserted by the Desktop release tests. */
+export interface DesktopElectronBuilderConfig {
+  readonly appId: string
+  readonly directories: {
+    readonly output: string
+  }
+  readonly files: readonly [
+    string,
+    string,
+    string,
+    string,
+    { readonly from: string, readonly to: 'dsh', readonly filter: readonly ['**/*'] },
+    { readonly from: string, readonly to: 'dsh/node_modules', readonly filter: readonly ['**/*'] },
+  ]
+  readonly asarUnpack: readonly string[]
+  readonly extraResources: readonly [{ readonly from: string, readonly to: 'runtime' }]
+  readonly mac: {
+    readonly identity: string | undefined
+    readonly forceCodeSigning: boolean
+    readonly notarize: boolean
+    readonly signIgnore: readonly string[]
+  }
+  readonly dmg: {
+    readonly sign: boolean
+    readonly writeUpdateInfo: boolean
+  }
+  readonly nsis: {
+    readonly include: string
+  }
+  readonly artifactBuildCompleted: (artifact: { readonly file: string }) => Promise<void> | undefined
+  readonly publish: readonly [{ readonly provider: 'generic', readonly url: string }] | null
+}
+
+/**
+ * Create electron-builder configuration from one release environment.
+ * @param env - Packaging environment.
+ * @param hostPlatform - Build-host platform used when no explicit target is present.
+ * @param hostArch - Build-host architecture used when no explicit target is present.
+ * @returns electron-builder configuration.
+ */
+export function createElectronBuilderConfig(
+  env?: NodeJS.ProcessEnv,
+  hostPlatform?: NodeJS.Platform,
+  hostArch?: string,
+): DesktopElectronBuilderConfig
+
+declare const electronBuilderConfig: DesktopElectronBuilderConfig
+
+export default electronBuilderConfig

apps/desktop/electron-builder.config.mjs

@@ -0,0 +1,127 @@
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  resolveDesktopAppId,
+  resolveMacOSNotarizationEnvironment,
+  resolveMacOSSigningEnvironment,
+} from './scripts/desktop-release-environment.mjs'
+import { notarizeMacOSDiskImageArtifact } from './scripts/notarize-macos-disk-images.mjs'
+import { verifyMacOSSignatureAfterSign } from './scripts/verify-macos-signature.mjs'
+import {
+  createWindowsTokenSigner,
+  installWindowsNsisBootstrapSigner,
+} from './scripts/windows-sign.mjs'
+import { resolveDesktopAutoUpdateConfig } from './scripts/desktop-auto-update-environment.mjs'
+import { desktopTargetBuildPaths, resolveDesktopBuildTarget } from './scripts/desktop-build-paths.mjs'
+
+/**
+ * Create electron-builder configuration from one release environment.
+ * @param {NodeJS.ProcessEnv} env - Packaging environment.
+ * @param {NodeJS.Platform} hostPlatform - Build-host platform used when no explicit target is present.
+ * @param {string} hostArch - Build-host architecture used when no explicit target is present.
+ * @returns {object} electron-builder configuration.
+ */
+export function createElectronBuilderConfig(
+  env = process.env,
+  hostPlatform = process.platform,
+  hostArch = process.arch,
+) {
+  const appId = resolveDesktopAppId(env)
+  const targetPlatform = env.DSH_DESKTOP_TARGET_PLATFORM
+  const resolvedPlatform = targetPlatform ?? hostPlatform
+  const resolvedArch = env.DSH_DESKTOP_TARGET_ARCH ?? hostArch
+  if (env.DSH_DESKTOP_UNSIGNED !== undefined && !['0', '1'].includes(env.DSH_DESKTOP_UNSIGNED)) {
+    throw new Error('desktop package: DSH_DESKTOP_UNSIGNED must be 0 or 1')
+  }
+  const unsigned = env.DSH_DESKTOP_UNSIGNED === '1'
+  if (unsigned && resolvedPlatform !== 'win32') throw new Error('desktop package: unsigned builds require Windows')
+  const packagesMacOS = targetPlatform === 'darwin' || (targetPlatform === undefined && hostPlatform === 'darwin')
+  const packagesWindows = targetPlatform === 'win32'
+  const macOSSigning = packagesMacOS ? resolveMacOSSigningEnvironment(env) : undefined
+  if (packagesMacOS) resolveMacOSNotarizationEnvironment(env)
+  const windowsSigner = packagesWindows && !unsigned
+    ? createWindowsTokenSigner({
+        certificateFile: env.DSH_DESKTOP_WINDOWS_CER_FILE,
+        signTool: env.DSH_DESKTOP_WINDOWS_SIGNTOOL,
+        tokenPin: env.DSH_DESKTOP_WINDOWS_TOKEN_PIN,
+        keyContainer: env.DSH_DESKTOP_WINDOWS_KEY_CONTAINER,
+      })
+    : undefined
+  if (windowsSigner !== undefined) {
+    installWindowsNsisBootstrapSigner({ sign: windowsSigner })
+  }
+  const update = unsigned ? undefined : resolveDesktopAutoUpdateConfig(env, resolvedPlatform, resolvedArch)
+  const buildPaths = desktopTargetBuildPaths(resolveDesktopBuildTarget(env, hostPlatform, hostArch))
+  return {
+    appId,
+    productName: 'DeepSeek Harness',
+    artifactName: 'deepseek-harness-${version}-${os}-${arch}.${ext}',
+    directories: { output: unsigned ? join(buildPaths.root, 'unsigned-artifacts') : buildPaths.artifacts },
+    asar: true,
+    files: [
+      'lib/*.js',
+      'lib/*.cjs',
+      'renderer/**/*',
+      'package.json',
+      { from: buildPaths.dsh, to: 'dsh', filter: ['**/*'] },
+      // electron-builder excludes a source directory's root node_modules.
+      { from: join(buildPaths.dsh, 'node_modules'), to: 'dsh/node_modules', filter: ['**/*'] },
+    ],
+    asarUnpack: [
+      '**/*.{node,dylib,dll,so,exe}',
+      '**/*.so.*',
+      '**/spawn-helper',
+      '**/@vscode/ripgrep/bin/rg',
+    ],
+    extraResources: [
+      { from: buildPaths.runtime, to: 'runtime' },
+    ],
+    mac: {
+      category: 'public.app-category.developer-tools',
+      identity: macOSSigning?.signingIdentity,
+      forceCodeSigning: true,
+      hardenedRuntime: true,
+      // ASAR-unpacked native runtime files are pre-signed; PAK resources are sealed by their enclosing bundle.
+      signIgnore: ['/Contents/Resources/app\\.asar\\.unpacked/dsh(?:/|$)', '\\.pak$'],
+      notarize: true,
+      target: ['dmg', 'zip'],
+    },
+    dmg: {
+      sign: true,
+      writeUpdateInfo: false,
+    },
+    afterSign: async context => {
+      if (context.electronPlatformName !== 'darwin') return
+      verifyMacOSSignatureAfterSign(context, macOSSigning ?? resolveMacOSSigningEnvironment(env))
+    },
+    artifactBuildCompleted: artifact => {
+      if (!artifact.file.endsWith('.dmg')) return
+      return notarizeMacOSDiskImageArtifact(
+        artifact,
+        env,
+        macOSSigning ?? resolveMacOSSigningEnvironment(env),
+      )
+    },
+    win: {
+      forceCodeSigning: !unsigned,
+      signtoolOptions: {
+        sign: windowsSigner,
+        signingHashAlgorithms: ['sha256'],
+      },
+      target: ['nsis'],
+    },
+    linux: {
+      category: 'Development',
+      target: ['AppImage'],
+    },
+    nsis: {
+      include: fileURLToPath(new URL('./scripts/installer.nsh', import.meta.url)),
+      oneClick: false,
+      allowToChangeInstallationDirectory: true,
+      differentialPackage: true,
+    },
+    publish: update === undefined ? null : [{ provider: 'generic', url: update.publicUrl }],
+  }
+}
+
+export default createElectronBuilderConfig()

apps/desktop/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@deepseek-ai/dsh-desktop",
+  "description": "Electron desktop shell for a bundled dsh runtime and external plugins",
+  "version": "0.1.6-alpha.1",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "main": "lib/main.js",
+  "scripts": {
+    "build": "tsc -b && tsdown",
+    "dev": "tsx scripts/dev.ts",
+    "start": "tsx scripts/dev.ts --skip-build",
+    "prepare:runtime": "tsx scripts/prepare-runtime.ts",
+    "prepare:packages": "tsx scripts/prepare-package-set.ts",
+    "prepare:dsh": "tsx scripts/prepare-dsh.ts",
+    "prepare:package": "tsx scripts/package-target.ts --prepare-only",
+    "verify:mac-signature": "node scripts/verify-macos-signature.mjs",
+    "package": "tsx scripts/package-target.ts",
+    "package:dir": "tsx scripts/package-target.ts --dir",
+    "package:mac:arm64": "tsx scripts/package-target.ts mac-arm64",
+    "package:mac:arm64:dir": "tsx scripts/package-target.ts mac-arm64 --dir",
+    "package:mac:x64": "tsx scripts/package-target.ts mac-x64",
+    "package:mac:x64:dir": "tsx scripts/package-target.ts mac-x64 --dir",
+    "package:win:x64": "tsx scripts/package-target.ts win-x64",
+    "package:win:x64:unsigned": "tsx scripts/package-target.ts win-x64 --unsigned",
+    "package:win:x64:dir": "tsx scripts/package-target.ts win-x64 --dir",
+    "upload:mac:arm64": "tsx scripts/upload-target.ts mac-arm64",
+    "upload:mac:x64": "tsx scripts/upload-target.ts mac-x64",
+    "upload:win:x64": "tsx scripts/upload-target.ts win-x64"
+  },
+  "dependencies": {
+    "electron-updater": "^6.8.9",
+    "semver": "^7.8.5"
+  },
+  "devDependencies": {
+    "@aws-sdk/client-s3": "3.1067.0",
+    "@deepseek-ai/dsh-home-paths": "workspace:^",
+    "@electron/notarize": "2.5.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.20.0",
+    "@types/semver": "^7.8.0",
+    "app-builder-lib": "26.15.3",
+    "electron": "^44.0.0",
+    "electron-builder": "^26.15.3",
+    "extract-zip": "^2.0.1",
+    "js-yaml": "^4.2.0",
+    "pnpm": "11.7.0",
+    "tar": "^7.5.0",
+    "typescript": "^6.0.3"
+  }
+}

apps/desktop/tsconfig.json

@@ -0,0 +1,11 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../../packages/util/home-paths" }
+  ]
+}

apps/desktop/tsdown.config.ts

@@ -0,0 +1,27 @@
+import { defineConfig } from 'tsdown'
+
+export default defineConfig([
+  {
+    entry: ['lib/types/main.js'],
+    outDir: 'lib',
+    format: ['esm'],
+    platform: 'node',
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+    deps: { neverBundle: ['electron'] },
+  },
+  ...(['preload', 'preload-app'] as const).map(name => ({
+    // Sandboxed Electron preloads run as CommonJS even though the application package is ESM.
+    entry: { [name]: `lib/types/${name}.js` },
+    outDir: 'lib',
+    format: ['cjs'] as const,
+    platform: 'node' as const,
+    target: 'es2024',
+    fixedExtension: false,
+    dts: false,
+    clean: false,
+    deps: { neverBundle: ['electron'] },
+  })),
+])

apps/web/.npmignore

@@ -0,0 +1 @@
+*.map

apps/web/index.html

@@ -0,0 +1,14 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <link rel="manifest" href="/manifest.webmanifest" />
+    <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
+    <title>DSH Local Build</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

apps/web/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@deepseek-ai/dsh-web-frontend",
+  "description": "Web application entry: vite build over the @deepseek-ai/dsh-client-web shell library; dist/ served by apps/cli's dsh web",
+  "version": "0.1.6-alpha.1",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/deepseek-ai/deepseek-harness.git",
+    "directory": "apps/web"
+  },
+  "type": "module",
+  "exports": {
+    "./dist/*": "./dist/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "!dist/**/*.map",
+    "!dist/preview.html",
+    "!dist/preview"
+  ],
+  "scripts": {
+    "build": "vite build",
+    "dev": "vite",
+    "watch": "vite build --watch --no-emptyOutDir",
+    "build:preview": "pnpm --filter @deepseek-ai/dsh-experimental-webworker-runtime exec tsdown && pnpm --filter @deepseek-ai/dsh-experimental-webworker-packer exec tsdown && vite build && dsh-pack-vfs-image --out dist/preview/vfs-image.tar.gz",
+    "serve:preview": "http-server dist -a 0.0.0.0 -p 4173 -c-1"
+  },
+  "license": "MIT",
+  "devDependencies": {
+    "@deepseek-ai/cordis-plugin-group": "workspace:^",
+    "@deepseek-ai/dsh-client-modules": "workspace:^",
+    "@deepseek-ai/dsh-client-store": "workspace:^",
+    "@deepseek-ai/dsh-client-test-runtime": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-dockkit": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-primitives": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-slots": "workspace:^",
+    "@deepseek-ai/dsh-client-web": "workspace:^",
+    "@deepseek-ai/dsh-cmdline": "workspace:^",
+    "@deepseek-ai/dsh-pwsh-local": "workspace:^",
+    "@deepseek-ai/dsh-experimental-webworker-packer": "workspace:^",
+    "@deepseek-ai/dsh-experimental-webworker-runtime": "workspace:^",
+    "@deepseek-ai/dsh-remote-mock": "workspace:^",
+    "@types/node": "^22.0.0",
+    "@types/react": "~18.3.1",
+    "@types/react-dom": "~18.3.0",
+    "@types/ws": "8.18.1",
+    "@vitejs/plugin-react": "^4.0.0",
+    "http-server": "^14.1.1",
+    "fflate": "^0.8.2",
+    "playwright": "^1.49.0",
+    "react": "^18.2.0",
+    "react-dom": "^18.2.0",
+    "typescript": "^6.0.3",
+    "vite": "^6.0.0",
+    "vitest": "^4.1.8",
+    "ws": "8.21.0",
+    "@deepseek-ai/dsh-launch-environment": "workspace:^",
+    "@deepseek-ai/dsh-subprocess-local": "workspace:^",
+    "@deepseek-ai/dsh-experimental-auto-review": "workspace:^"
+  }
+}

apps/web/product-isolation.ts

@@ -0,0 +1,105 @@
+/** Vite adapters for recording product chunk, asset, CSS, and worker inputs. */
+
+import type { Plugin } from 'vite'
+import { WebProductBundleIsolation } from '../../scripts/web-product-bundle-isolation.ts'
+
+const DEPENDENCY_ANALYSIS_PLUGIN = 'dsh-browser-dependency-analysis'
+
+/**
+ * Identify a dependency-disclosure walk that deliberately leaves third-party imports external.
+ * @returns Analysis intent that refuses builds which can write output.
+ */
+export function browserDependencyAnalysis(): Plugin {
+  return {
+    name: DEPENDENCY_ANALYSIS_PLUGIN,
+    apply: 'build',
+    configResolved(config) { requireNonWritingAnalysis(config.build.write) },
+  }
+}
+
+function requireNonWritingAnalysis(write: boolean): void {
+  if (write !== false) throw new Error('browser dependency analysis requires build.write: false')
+}
+
+/**
+ * Reject experimental inputs reachable from the built default Web page.
+ * @param repository - repository root supplying package ownership.
+ * @param webRoot - Vite root containing index.html and public assets.
+ * @returns Build plugins that preserve Vite's output and fail before publication on a violation.
+ */
+export function productWebBundleIsolation(repository: string, webRoot: string): Plugin[] {
+  const inputs = new WebProductBundleIsolation(repository, webRoot)
+  let dependencyAnalysis = false
+  return [{
+    name: 'dsh-product-web-chunk-inputs',
+    apply: 'build',
+    generateBundle: {
+      order: 'pre',
+      handler(_options, bundle) {
+        if (!dependencyAnalysis) inputs.captureChunks(bundle)
+      },
+    },
+  }, {
+    name: 'dsh-product-web-bundle-isolation',
+    apply: 'build',
+    enforce: 'post',
+    config(config) {
+      const renderBuiltUrl = config.experimental?.renderBuiltUrl
+      const workerPlugins = config.worker?.plugins
+      return {
+        experimental: {
+          renderBuiltUrl(filename, context) {
+            inputs.assetReference(filename, context.hostId, context.type)
+            return renderBuiltUrl?.(filename, context)
+          },
+        },
+        worker: {
+          plugins: () => [...workerPlugins?.() ?? [], {
+            name: 'dsh-worker-build-inputs',
+            generateBundle: {
+              order: 'post',
+              handler(_options, bundle) { inputs.workerBundle(bundle, this.getWatchFiles()) },
+            },
+          }],
+        },
+      }
+    },
+    configResolved(config) {
+      dependencyAnalysis = config.plugins.some(plugin => plugin.name === DEPENDENCY_ANALYSIS_PLUGIN)
+      if (dependencyAnalysis) {
+        requireNonWritingAnalysis(config.build.write)
+        return
+      }
+      const cssPlugins = config.plugins.filter(plugin => plugin.name === 'vite:css')
+      const css = cssPlugins[0]
+      if (cssPlugins.length !== 1 || css?.transform === undefined) {
+        throw new Error('Web product isolation: Vite CSS input instrumentation is unavailable')
+      }
+      const transform = typeof css.transform === 'function' ? css.transform : css.transform.handler
+      css.transform = {
+        ...typeof css.transform === 'function' ? {} : css.transform,
+        handler(code, id, options) {
+          inputs.cssTransform(id)
+          const context = new Proxy(this, {
+            get(target, property) {
+              if (property === 'addWatchFile') return (file: string): void => {
+                inputs.cssDependency(id, file)
+                target.addWatchFile(file)
+              }
+              const value: unknown = Reflect.get(target, property, target)
+              return typeof value === 'function' ? value.bind(target) : value
+            },
+          })
+          return transform.call(context, code, id, options)
+        },
+      }
+    },
+    buildStart() { inputs.reset() },
+    generateBundle: {
+      order: 'post',
+      handler(_options, bundle) {
+        if (!dependencyAnalysis) inputs.verify(bundle, id => this.getModuleInfo(id))
+      },
+    },
+  }]
+}

apps/web/tsconfig.json

@@ -0,0 +1,148 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": ".",
+    "outDir": "lib/types",
+    "jsx": "react-jsx",
+    "lib": [
+      "ES2024",
+      "DOM",
+      "DOM.Iterable"
+    ],
+    "types": [
+      "node"
+    ]
+  },
+  "include": [
+    "src",
+    "tests"
+  ],
+  // The web e2e lane (scaffold + replay specs) boots the host spine and reads
+  // its Context merges — host-plane programs, checked in tsconfig.host.json;
+  // this client-registered project must not also hold them (one program
+  // cannot see both sides of the cordis Context merges).
+  "exclude": [
+    "tests/default-product-isolation.e2e.ts",
+    "tests/diff-context.e2e.ts",
+    "tests/scaffold.ts",
+    "tests/auto-review-fixture.ts",
+    "tests/scaffold-generation.spec.ts",
+    "tests/scaffold-hermetic.e2e.ts",
+    "tests/startup-rpc-budget.e2e.ts",
+    "tests/minimal-preset.snapshot.ts",
+    "tests/message-feedback-protocol.snapshot.ts",
+    "tests/preset-migration.snapshot.ts",
+    "tests/live-interactions.e2e.ts",
+    "tests/question-composer.e2e.ts",
+    "tests/approval-composer.e2e.ts",
+    "tests/ptc-escalation.e2e.ts",
+    "tests/plan-control-row.e2e.ts",
+    "tests/plan-review.e2e.ts",
+    "tests/steering.e2e.ts",
+    "tests/navigation-panes.e2e.ts",
+    "tests/chat-scroll-fixture.ts",
+    "tests/trajectory-virtualization.e2e.ts",
+    "tests/lifecycle-chrome.e2e.ts",
+    "tests/details-session-lifecycle.e2e.ts",
+    "tests/document-preview.e2e.ts",
+    "tests/plugin-config.e2e.ts",
+    "tests/settings-chrome.e2e.ts",
+    "tests/models-settings.e2e.ts",
+    "tests/deepseek-messages-settings.e2e.ts",
+    "tests/deepseek-messages-chat.e2e.ts",
+    "tests/models-settings-recovery.e2e.ts",
+    "tests/default-model.e2e.ts",
+    "tests/github-ready-review.e2e.ts",
+    "tests/streaming-fence-highlight.e2e.ts",
+    "tests/declared-reasoning.e2e.ts",
+    "tests/onboarding-deepseek-config.e2e.ts",
+    "tests/onboarding-usable-provider.e2e.ts",
+    "tests/remote-welcome.e2e.ts",
+    "tests/workspace-new-session-folding.e2e.ts",
+    "tests/workspace-management.e2e.ts",
+    "tests/workspace-recency.e2e.ts",
+    "tests/session-unarchive.e2e.ts",
+    "tests/replay-round-trip.e2e.ts",
+    "tests/hmr-live.e2e.ts",
+    "tests/preview-boot.e2e.ts",
+    "tests/seeded-history.e2e.ts",
+    "tests/stats-paged-history.e2e.ts",
+    "tests/sidebar-scrollbar.e2e.ts",
+    "tests/rail-search-expand.e2e.ts",
+    "tests/conversation-column-overflow.e2e.ts",
+    "tests/ptc-round.e2e.ts",
+    "tests/present.e2e.ts",
+    "tests/present-svg.e2e.ts",
+    "tests/composer-draft-scroll.e2e.ts",
+    "tests/composer-placeholder.e2e.ts",
+    "tests/cordis-tool-round.e2e.ts",
+    "tests/web-search-round.e2e.ts",
+    "tests/file-upload-round.e2e.ts",
+    "tests/message-actions.e2e.ts",
+    "tests/open-in-app-ssh.e2e.ts",
+    "tests/message-feedback.e2e.ts",
+    "tests/markdown-images.e2e.ts",
+    "tests/reference-composer.e2e.ts",
+    "tests/markdown-wide-table.e2e.ts",
+    "tests/math-rendering.e2e.ts",
+    "tests/markdown-cjk-strong.e2e.ts",
+    "tests/markdown-inline-code-links.e2e.ts",
+    "tests/clickable-links-gallery.e2e.ts",
+    "tests/queue-actions.e2e.ts",
+    "tests/queue-image.e2e.ts",
+    "tests/skill-invocation-policy.e2e.ts",
+    "tests/skill-user-invoke.e2e.ts",
+    "tests/permission-policy-context.e2e.ts",
+    "tests/access-confirmation.e2e.ts",
+    "tests/agent-preset-selection.e2e.ts",
+    "tests/agent-preset-authoring.e2e.ts",
+    "tests/shipped-composition.e2e.ts",
+    "tests/schedule-after.e2e.ts",
+    "tests/feedback-command.e2e.ts",
+    "tests/feedback-release.e2e.ts",
+    "tests/agent-team-panel.e2e.ts",
+    "tests/sidebar-right.e2e.ts",
+    "tests/sidebar-terminal.e2e.ts",
+    "tests/startup-auto-selection.e2e.ts",
+    "tests/produced-files.e2e.ts",
+    "tests/produced-file-mentions.e2e.ts",
+    "tests/goal-bar.e2e.ts",
+    "tests/goal-command-presentation.e2e.ts",
+    "tests/subagent-conversation.e2e.ts",
+    "tests/subagent-interrupt.e2e.ts",
+    "tests/subagent-interrupt-ui.e2e.ts",
+    "tests/sidebar-subagent-activity.e2e.ts",
+    "tests/background-job-list.e2e.ts",
+    "tests/auto-review-denial.e2e.ts",
+    "tests/bash-abort-row.e2e.ts",
+    "tests/skill-tool-row.e2e.ts",
+    "tests/turn-tail-actions.e2e.ts",
+    "tests/goal-multi-turn-actions.e2e.ts",
+    "tests/chat-scroll-fixture.ts",
+    "tests/chat-scroll-contract.e2e.ts",
+    "tests/chat-long-interactions.e2e.ts",
+    "tests/chat-continuous-conversation.e2e.ts",
+    "tests/composer-tab-geometry.e2e.ts",
+    "tests/complex-history.perf.ts",
+    "tests/pwsh-terminal.e2e.ts",
+    "tests/workflow-run.e2e.ts"
+  ],
+  "references": [
+    { "path": "../../packages/experimental/auto-review" },
+    {
+      "path": "../../packages/client/store"
+    },
+    {
+      "path": "../../packages/client/web"
+    },
+    {
+      "path": "../../packages/client/modules"
+    },
+    {
+      "path": "../../packages/test-support/client-runtime"
+    },
+    {
+      "path": "../../packages/test-support/remote-mock"
+    }
+  ]
+}

apps/web/vite.config.ts

@@ -0,0 +1,246 @@
+import { readFile, writeFile } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { defineConfig } from 'vite'
+import type { Plugin } from 'vite'
+import react from '@vitejs/plugin-react'
+import { clientBuildEnvironmentDefines } from '../../scripts/client-build-environment.ts'
+import { productWebBundleIsolation } from './product-isolation.ts'
+
+const src = (rel: string): string => fileURLToPath(new URL(rel, import.meta.url))
+const STANDALONE_ERROR = 'apps/web is not a standalone application: bare Vite cannot inject window.__DSH_BOOT__. '
+  + 'From a repository checkout, run `pnpm dsh web`; an installed package uses `dsh web`. '
+  + 'For client-plugin HMR, run `pnpm dsh web` together with `pnpm run dev:web`.'
+const DEFAULT_CLIENT_TITLE = 'DSH Local Build'
+
+/** Escape build-time text before placing it in the HTML title element. */
+function escapeHtmlText(value: string): string {
+  return value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
+/** Project the public build title into the initial HTML document. */
+function clientDocumentTitle(): Plugin {
+  const title = escapeHtmlText(process.env.DSH_CLIENT_TITLE ?? DEFAULT_CLIENT_TITLE)
+  return {
+    name: 'dsh-client-document-title',
+    transformIndexHtml(html) {
+      return html.replace('<title>DSH Local Build</title>', `<title>${title}</title>`)
+    },
+  }
+}
+
+/** Fail before a Vite dev or preview server can expose the boot-manifest-free shell. */
+function rejectStandaloneServe(): Plugin {
+  return {
+    name: 'dsh-reject-standalone-web-serve',
+    config(_config, env) {
+      if (env.command === 'serve') throw new Error(STANDALONE_ERROR)
+    },
+  }
+}
+
+/**
+ * Emit preview.html beside index.html: the built index page with one module
+ * script — the worker bootstrap entry — spliced ahead of its entry tag. Both
+ * pages share every chunk; the extra tag is the only difference, so the
+ * static worker deployment ships the served page verbatim plus its
+ * bootstrap.
+ */
+function emitPreviewPage(): Plugin {
+  let bootstrapFile: string | undefined
+  let write = true
+  let written = false
+  let outputDirectory = ''
+  return {
+    name: 'dsh-emit-preview-page',
+    configResolved(config) {
+      write = config.build.write
+      outputDirectory = resolve(config.root, config.build.outDir)
+    },
+    buildStart() {
+      bootstrapFile = undefined
+      written = false
+    },
+    generateBundle(_options, bundle) {
+      if (!write) return
+      for (const item of Object.values(bundle)) {
+        if (item.type === 'chunk' && item.isEntry && item.name === 'bootstrap') bootstrapFile = item.fileName
+      }
+      if (bootstrapFile === undefined) throw new Error('vite: preview bootstrap entry missing from the bundle')
+    },
+    writeBundle() { written = true },
+    async closeBundle() {
+      if (!write || !written || bootstrapFile === undefined) return
+      const page = await readFile(resolve(outputDirectory, 'index.html'), 'utf8')
+      const anchor = page.indexOf('<script type="module"')
+      if (anchor === -1) throw new Error('vite: built index.html lost its module entry tag')
+      const tag = `<script type="module" crossorigin src="./${bootstrapFile}"></script>`
+      await writeFile(resolve(outputDirectory, 'preview.html'), `${page.slice(0, anchor)}${tag}${page.slice(anchor)}`)
+    },
+  }
+}
+
+/**
+ * Vendor-chunk membership, by exact npm package name — the heavy render
+ * families (math, highlight, markdown) that change only on dependency bumps.
+ * Only packages workspace code imports DIRECTLY need listing: their private
+ * transitive dependencies (oniguruma machinery, character tables, …) are
+ * imported solely by these and rollup's chunk coloring pulls them into
+ * vendor automatically. A dependency shared with index-side code falls back
+ * to index — a few kB of dilution, never a correctness problem. Anything not
+ * listed (react family, the vendored cordis workspace, tiny helpers like
+ * anser/clsx, all workspace code) stays in the default `index` chunk, so
+ * editing shell code re-hashes only index and returning clients keep the
+ * cached vendor chunk.
+ *
+ * Every member must be React-free. A package that
+ * imports react/jsx-runtime must never be listed — rollup folds a module
+ * shared between the entry and a manual chunk into the manual chunk, so one
+ * react-importing member would drag the single shared react copy into
+ * vendor. The React side of markdown/math rendering is workspace code and
+ * rides index.
+ */
+const VENDOR_PACKAGES: ReadonlySet<string> = new Set([
+  // math
+  'katex',
+  // syntax highlight (@shikijs/langs is handled separately below —
+  // lazy grammars must not land here)
+  'shiki',
+  // markdown parse pipeline (micromark/mdast; the incremental React renderer
+  // over it is workspace code)
+  'mdast-util-from-markdown',
+  'mdast-util-gfm',
+  'mdast-util-math',
+  'micromark-core-commonmark',
+  'micromark-extension-gfm',
+  'micromark-extension-math',
+  'micromark-factory-space',
+  'micromark-util-character',
+  'micromark-util-classify-character',
+  'micromark-util-sanitize-uri',
+  'micromark-util-symbol',
+  'micromark-util-types',
+])
+
+/**
+ * Boot grammars statically imported by ui-primitives' highlight.ts
+ * (`@shikijs/langs/typescript` → `dist/typescript.mjs`, etc.). They live in
+ * the same package as the lazy read-card grammars, but unlike those they are
+ * part of the initial load and belong in the vendor chunk; the lazy ones must
+ * stay unassigned so each keeps its own on-demand chunk.
+ */
+const BOOT_GRAMMAR_FILES: readonly string[] = [
+  'dist/typescript.mjs',
+  'dist/shellscript.mjs',
+  'dist/json.mjs',
+]
+
+/** Font asset extensions routed to assets/fonts/ (KaTeX's woff2/woff/ttf faces). */
+const FONT_EXTENSIONS: readonly string[] = ['.woff2', '.woff', '.ttf']
+
+/**
+ * npm package name of a resolved module id: the segment after the last
+ * `node_modules/`. pnpm nests the real package under an inner node_modules.
+ */
+function npmPackageOf(id: string): string | undefined {
+  const parts = id.split('/node_modules/')
+  if (parts.length === 1) return undefined
+  const [first, second] = parts[parts.length - 1].split('/')
+  if (first.startsWith('.')) return undefined // .pnpm store segment, not a package
+  if (first.startsWith('@')) return second === undefined ? undefined : `${first}/${second}`
+  return first
+}
+
+export default defineConfig({
+  // Relative asset URLs: preview.html mounts the same output under any base
+  // directory, and the served index resolves identically from the site root.
+  base: './',
+  plugins: [
+    rejectStandaloneServe(), clientDocumentTitle(), react(), emitPreviewPage(),
+    productWebBundleIsolation(src('../..'), src('.')),
+  ],
+  build: {
+    // The worker bootstrap holds its page at top-level await; Vite's default
+    // `modules` target (es2020-era) rejects that syntax.
+    target: 'es2022',
+    sourcemap: true,
+    rollupOptions: {
+      input: {
+        index: src('./index.html'),
+        // Standalone entry, not an index.html script tag: Vite folds every
+        // module tag of one page into a single synthetic entry, and only a
+        // separate input keeps the shared page chunks bootstrap-free.
+        bootstrap: src('./src/preview.ts'),
+      },
+      output: {
+        // The worker-preview surface groups under dist/preview/ (the page
+        // itself stays at dist/preview.html), so the published payload can
+        // exclude it as one directory.
+        entryFileNames(chunk): string {
+          return chunk.name === 'bootstrap' ? 'preview/[name]-[hash].js' : 'assets/[name]-[hash].js'
+        },
+        // Output layout: the two main chunks stay at assets/ root; lazy
+        // @shikijs/langs grammar chunks group under assets/langs/; fonts
+        // (all KaTeX faces referenced by vendor.css) group under
+        // assets/fonts/. Sourcemaps need no arrangement: rollup writes each
+        // .map next to its js and references it by bare relative filename.
+        chunkFileNames(chunk): string {
+          // Grammar chunks are recognized by their member modules, not the
+          // facade: shared embedded-grammar chunks (e.g. html+javascript,
+          // split out because php/ruby/mdx embed them) have no facade at all.
+          // index and vendor are excluded by name — vendor legitimately
+          // carries the three boot grammars.
+          if (chunk.name === 'index' || chunk.name === 'vendor') return 'assets/[name]-[hash].js'
+          const isLangChunk = chunk.moduleIds.some(id => id.includes('/node_modules/@shikijs/langs/'))
+          return isLangChunk ? 'assets/langs/[name]-[hash].js' : 'assets/[name]-[hash].js'
+        },
+        assetFileNames(asset): string {
+          const fileName = asset.names[0] ?? ''
+          const isFont = FONT_EXTENSIONS.some(ext => fileName.endsWith(ext))
+          return isFont ? 'assets/fonts/[name]-[hash][extname]' : 'assets/[name]-[hash][extname]'
+        },
+        manualChunks(id: string): string | undefined {
+          const pkg = npmPackageOf(id)
+          if (pkg === undefined) return undefined // workspace + vendored cordis: index
+          if (pkg === '@shikijs/langs') {
+            return BOOT_GRAMMAR_FILES.some(file => id.endsWith(`/${file}`)) ? 'vendor' : undefined
+          }
+          return VENDOR_PACKAGES.has(pkg) ? 'vendor' : undefined
+        },
+      },
+    },
+  },
+  worker: {
+    // The preview worker rides dist/preview/ with the rest of that surface.
+    rollupOptions: { output: { entryFileNames: 'preview/[name]-[hash].js' } },
+  },
+  resolve: {
+    // One instance per shared npm identity: a bare specifier otherwise resolves
+    // from the importer's directory, so a diverging range ships a second React
+    // and splits hook and element identity. Entries are package ids — they cover
+    // react/jsx-runtime and react-dom/client — and resolve from this package's
+    // node_modules, so react must stay a devDependency here and any watcher must
+    // run vite from this directory (scripts/dev-web.ts). Workspace packages need
+    // no entry: pnpm links each of them to a single directory.
+    dedupe: ['react', 'react-dom'],
+    // Workspace packages are consumed as built lib products: each resolves
+    // through its own package.json exports from the importer's directory, and
+    // CSS still rides Vite's pipeline because the client build preset emits it
+    // beside the bundle. Plugin packages never enter this graph; they arrive as
+    // runtime bundles through the client module system. The remaining alias
+    // browserizes the vendored Cordis Loader's only Node import.
+    alias: [
+      { find: /^node:module$/, replacement: src('./src/node-module-stub.ts') },
+    ],
+  },
+  define: {
+    ...clientBuildEnvironmentDefines(process.env),
+    // vendored loader internal.ts: fromInternal() probes the Node major —
+    // "0.0.0" takes neither branch, returning undefined (exactly the empty
+    // internal slot the shell boot fills with the client module loader).
+    'process.versions.node': '"0.0.0"',
+    'process.execArgv': '[]',
+    // vendored loader index.ts: envData falls to its default branch.
+    'process.env.CORDIS_SHARED': 'undefined',
+  },
+})

benchmarks/AGENTS.md

@@ -0,0 +1,16 @@
+# AGENTS.md — Performance Benchmarks
+
+This tree owns required, repository-level performance gates whose measured user path crosses package ownership. Package-local diagnostics remain beside their owners and use the `.perf.ts` suffix instead of joining `test:bench`.
+
+- Organize benchmarks by measured user path, one directory per path. Do not mirror the package tree.
+- Host cases use `*.bench.ts`; Client-face cases use `*.bench.client.ts`. Worker, fixture, and support modules do not carry a benchmark suffix.
+- The private `@deepseek-ai/dsh-benchmarks` workspace owns benchmark-only dependencies. `test:bench` builds workspace libraries and `benchmarks/.dsh-build/` workers before Vitest orchestration. Timed CPU work runs in those workers under plain Node, without a TypeScript loader; runtime package imports must resolve to built `lib/` entries.
+- Browser workflow cases drive built Client bundles through the shared shipped-composition Web scaffold. Report its source-resolved test Host separately from published-Host evidence; two animation frames prove a rendering opportunity, not hardware presentation. Use fresh browsers and private scaffold worlds per sample.
+- Synthesize fixed inputs from reviewed constants. Never use recorded Sessions, user material, ambient repositories, or network services.
+- Run process-level wall-clock and retained-memory samples in fresh children with private `mkdtemp` roots. Pure synchronous folds create a fresh object graph per sample and must not mutate process-global state. Bound every child, await exit, and remove owned roots after failure as well as success.
+- Record reference-machine expectations separately from the shared CI time scale and variance headroom. Do not apply the time scale to memory or dimensionless ratios.
+- Report enough raw and aggregate measurements to explain each verdict, including whether a budget uses a median, minimum, absolute value, or ratio. Enforce reviewed source constants; environment variables must not override performance budgets.
+- Keep scenario-specific support beside its benchmark. Move a helper into `benchmarks/support/` only after at least two benchmark directories require the same behavior.
+- Exercise production entry points. Do not copy product algorithms, add production exports solely for measurement, or turn benchmark completion into duplicate semantic assertions.
+- A compiled worker may bundle a private integration adapter when no public Node export exposes the measured user path. Keep package imports external so product services resolve through their built package exports.
+- Record the workload, timing boundary, memory endpoint, calibration reference, alternatives, and known exclusions in the owning Agent Note.

benchmarks/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@deepseek-ai/dsh-benchmarks",
+  "version": "0.1.3-alpha.1",
+  "license": "MIT",
+  "private": true,
+  "type": "module",
+  "devDependencies": {
+    "playwright": "^1.49.0",
+    "@xterm/headless": "^6.0.0",
+    "@deepseek-ai/dsh-terminal": "workspace:^",
+    "@deepseek-ai/dsh-subprocess": "workspace:^",
+    "@deepseek-ai/dsh-llm-replay": "workspace:^",
+    "@deepseek-ai/cordis": "workspace:^",
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-agent-loop-testkit": "workspace:^",
+    "@deepseek-ai/dsh-agent-presets": "workspace:^",
+    "@deepseek-ai/dsh-api-session-controller": "workspace:^",
+    "@deepseek-ai/dsh-client-store": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-chat": "workspace:^",
+    "@deepseek-ai/dsh-deque": "workspace:^",
+    "@deepseek-ai/dsh-lazy-require": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-sdk-client": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
+    "@deepseek-ai/dsh-session-projection": "workspace:^",
+    "@deepseek-ai/dsh-session-query": "workspace:^",
+    "@deepseek-ai/dsh-session-stats": "workspace:^",
+    "@deepseek-ai/dsh-session-title": "workspace:^",
+    "@deepseek-ai/dsh-session-turn-outline": "workspace:^",
+    "@deepseek-ai/dsh-subagent": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-token-meter": "workspace:^",
+    "@deepseek-ai/dsh-typert-protocol": "workspace:^"
+  },
+  "peerDependencies": {
+    "@deepseek-ai/cordis": "workspace:^"
+  }
+}

benchmarks/tsdown.config.ts

@@ -0,0 +1,59 @@
+import { defineConfig } from 'tsdown'
+
+const shared = {
+  format: 'esm' as const,
+  platform: 'node' as const,
+  target: 'es2024',
+  fixedExtension: false,
+  dts: false,
+  deps: {
+    neverBundle: [/^@deepseek-ai\//],
+    onlyBundle: false as const,
+  },
+}
+
+/** Compile measured benchmark workers while keeping workspace packages on their built `lib` entries. */
+export default defineConfig([
+  {
+    ...shared,
+    entry: { 'terminal-io.worker': 'terminal-io/terminal-io.worker.ts' },
+    outDir: '.dsh-build/terminal-io',
+    clean: true,
+    tsconfig: 'tsconfig.host.json',
+  },
+  {
+    ...shared,
+    entry: { 'reconnect.worker': 'active-stream-reconnect/reconnect.worker.client.ts' },
+    outDir: '.dsh-build/active-stream-reconnect',
+    clean: true,
+    tsconfig: 'tsconfig.client.json',
+  },
+  {
+    ...shared,
+    entry: {
+      'agent-continuation.worker': 'agent-continuation/agent-continuation.worker.ts',
+      'child-catalog.worker': 'agent-continuation/child-catalog.worker.ts',
+      'profile-continuation.worker': 'agent-continuation/profile-continuation.worker.ts',
+      'profile-adapter': 'agent-continuation/profile-adapter.ts',
+    },
+    outDir: '.dsh-build/agent-continuation',
+    clean: true,
+    tsconfig: 'tsconfig.host.json',
+  },
+  {
+    ...shared,
+    entry: { 'session-open.worker': 'session-open/session-open.worker.ts' },
+    outDir: '.dsh-build/session-open',
+    clean: true,
+    tsconfig: 'tsconfig.host.json',
+  },
+  {
+    ...shared,
+    entry: {
+      'conversation-fold.worker': 'conversation-fold/conversation-fold.worker.client.ts',
+    },
+    outDir: '.dsh-build/conversation-fold',
+    clean: true,
+    tsconfig: 'tsconfig.client.json',
+  },
+])

docs/AGENTS.md

@@ -0,0 +1,76 @@
+# AGENTS.md — The documentation standard
+
+This file defines document structure, Markdown tiers, writing rules, and `verify-doc-budgets` ceilings. Use [dsh-doc](../.agents/skills/dsh-doc/SKILL.md) for placement and validation, and [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for required coverage and editorial judgment; the [doc-tiers Agent Note](../.agents/notes/implemented/process/2026-07-04-doc-tiers-and-budgets.md) owns rationale.
+
+## Document structure
+
+These rules apply to human-facing documentation; [Agent Notes](../.agents/notes/README.md) remain outside their scope. A [postmortem](postmortem/README.md) is an incident-scoped reference; chronology records evidence, not a teaching sequence. A document's subject and tree position fix its scope: describe its own subject at appropriate detail and direct children only by purpose, responsibility, and high-level behavior; link to the owning descendant for lower-level detail. Document type does not widen that scope. A reference may be exhaustive only about its own subject. Testing mechanisms, fixtures, and harnesses belong at the lowest owning level; higher documents link there.
+
+Classify every in-scope document as a tutorial or reference. Tutorials follow an ordered path to an outcome and introduce only what each step needs. References define a lookup scope and current behavior without a teaching sequence. Separate substantial tutorial and reference content; label a section when either part is small.
+
+Before writing a tutorial, privately classify the reader's starting knowledge and each concept as beginner, intermediate, or advanced. Establish prerequisites before dependent concepts, increase difficulty gradually, and move unnecessary advanced material to a later tutorial or reference.
+
+Author in this order: locate the document in the tree; set its permitted detail; choose tutorial or reference; for a tutorial, order concepts by prerequisite and difficulty; relocate descendant-owned detail; replace lower-level explanations with links to their owners.
+
+## The tier taxonomy: one home per fact
+
+Each fact has one home: the tier whose job it is; elsewhere, link there.
+
+| Tier | Job | Does NOT belong there |
+|---|---|---|
+| Root `AGENTS.md` | Standing orders: rules an agent needs in context in every session, one to three lines each, linking its home | Stories, worked examples, situational procedures, anything restated from a linked home |
+| Subtree `AGENTS.md` (`packages/`, `docs/`, `.agents/notes/`) | Orders specific to that subtree | Repo-wide rules the root file already carries |
+| [architecture.md](architecture.md) | Ordered map: composition, core packages, loop, seams, extension points; read before changing `packages/` | Type definitions (→ subsystems), per-package detail (→ package READMEs), decision rationale (→ Agent Notes), implementation-status annotations |
+| [subsystems/](subsystems/README.md) | One reference page per subsystem: type definitions, semantics, and the generated Cordis API | Behavior narration (→ architecture.md) |
+| [Agent Notes](../.agents/notes/README.md) | Active decision records: the why, what-was-given-up, and required verification; `implemented/` notes describe shipped reality in present tense | Migration plans, acceptance-task checklists, fixture walkthroughs, and spec-speak ("should…") once the decision has shipped; archived notes are frozen history, never current authority |
+| [postmortem/](postmortem/README.md) | Incident stories — the only tier where war-story narrative belongs | — |
+| [Persistence history](persistence-changes/README.md) and [format references](persistence-changes/historical-formats/README.md) | Type-change acknowledgements, release comparisons, and complete historical format schemas | Behavior-only changes; current runtime contracts |
+| [cookbook/](cookbook/adding-a-package.md) | Step-by-step how-tos with numbered verify steps | Design rationale (→ the Agent Note each guide links) |
+| [user/](user/index.md) | Product-facing guides published by the documentation website | Generated reference tables, contributor procedures, decision history |
+| Package README | The per-package contract: config, semantics, limitations, extension points, and [Model Experience](cookbook/adding-a-package.md#4-write-the-package-readme) | JSDoc restatement, generated-catalog restatement (event/tool tables), other packages' concerns |
+| [development.md](development.md) | Contributor setup, daily workflow, and a summary of CI; a bilingual pair under the [i18n contract](i18n/README.md) | Runtime/version rationale (→ Agent Notes), check-by-check lists that drift from `package.json` scripts |
+| Generated reference: the per-page `cordis-surface` regions in [subsystems/](subsystems/README.md), the [Cordis core API + inherited tier](cordis-api/context.md), [tool-catalog](tool-catalog.md), [config-catalog](config-catalog.md), [persistence-catalog](persistence-catalog.md), [module-graph.md](module-graph.md) | Exhaustive English sources regenerated from source and freshness-gated; reviewed Chinese counterparts follow the [pairing workflow](i18n/README.md#scope-and-exclusions) | Hand edits to generated English sources or regions; Chinese counterparts update through pairing only |
+| Skills (`.agents/skills/`) | Reusable workflows and specialized decision standards | Product and runtime contracts (→ docs or source) |
+
+Placement: bugs → postmortems; rationale → Agent Notes; procedures → cookbooks; type definitions → subsystems; package contracts → READMEs; standing orders → root `AGENTS.md` with a rationale link.
+
+## Writing rules
+
+- **Document current state.** Keep history in commits, PRs, Agent Notes, postmortems, or scoped persistence records. Other prose names live mechanisms, not changes or stack positions. General Session-format prose links [version/status authority](session-format-status.md); retain numbers for version-specific contracts, examples, or evidence.
+- **Every non-trivial change includes at least one Agent Note in the same PR.** Update the owning note or add one; only mechanical/local edits are exempt ([scope](../.agents/notes/README.md#when-to-write-one)).
+- **One physical line per paragraph** (`verify-md-wrap`): use editor soft-wrap. Code blocks, tables, and list structure keep their formatting; code comments stay under the linter's column limit.
+- **Fenced `ts` blocks must compile** (`doc-typecheck`); a pasted type declaration and its original JSDoc use ` ```ts type-equiv `, while a body-stripped public class declaration uses ` ```ts public-api `; register either in the manifest so neither can drift ([mechanics](development.md#documenting-types-verbatim-ts-type-equiv)).
+- **The owning [subsystems page](subsystems/README.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types; a type is documented on its declaring package group's page ([page scoping](../.agents/notes/implemented/process/2026-08-03-package-anchored-subsystem-pages.md)).
+- **Pairs update together**: [Terminology-guided](i18n/terminology.md), single-pass active-agent work repositions first-use annotations, preserves untouched prose, and re-records; `dsh-translate-docs` remains user-invoked ([contract](i18n/README.md)).
+- **Comments and JSDoc state complete contracts, not reasoning transcripts.** Preserve behavior, failure, timing, ownership, modality, exceptions, consequences, and non-obvious orientation; delete narration, test walkthroughs, review analysis, and code restatement. Keep the local contract and link its rationale. Use [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for details.
+- Write directly: name actors and facts ([decision](../.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md)). Reserve `seam` for the defined capability. Name the exact check, type, API, operation, or behavior instead of metaphorical "gate", "vocabulary", or "surface".
+
+## Wordcount Budgets
+
+[scripts/doc-budgets.manifest.json](../scripts/doc-budgets.manifest.json) sets standing-doc ceilings; `pnpm run verify-doc-budgets` rejects excess or missing files.
+
+When the gate goes red:
+
+1. **Relocate** content that belongs in another tier; leave a one-line link if needed.
+2. **Condense** content that belongs here but can be shorter.
+3. **Raise** the ceiling only when the words need the space; justify the manifest diff in the PR. A too-low ceiling is a budget bug.
+
+Ceilings are guardrails, not reduction targets. At or below target, retain at least 5% headroom; above target, freeze the ceiling until relocation or condensation brings the document under target. Lower a ceiling only when the document still has room. Targets: root `AGENTS.md` ≤ 1,950; `architecture.md` ≤ 2,400; subtree `AGENTS.md` ≤ 600, except `packages/AGENTS.md` ≤ 750 and this file ≤ 1,320; `packages/README.md` ≤ 994; plus `cordis-primer.md` 600, `defensive-patterns.md` 550, `testing.md` 1,300, `examples/AGENTS.md` 310. Review governs unbudgeted tiers.
+
+## The slop checklist
+
+Hunt these in any doc; [dsh-doc](../.agents/skills/dsh-doc/SKILL.md) runs this list as an audit:
+
+- Duplicated rules: search a distinctive phrase; keep one home and link the rest.
+- History outside its permitted tier: state current facts and link the historical owner.
+- Implementation-status annotations in prose or diagrams ("implemented!", "future: …"). Status rots; the repo layout and package manifests carry it.
+- Hand-restated catalogs, JSDoc, or inventories of tests, packages, and status when source or a generator is authoritative.
+- Reasoning transcripts: step-by-step implementation narration, proof of obvious branches, test walkthroughs, or rejected local alternatives. Keep the resulting contract or durable rationale; delete the path used to derive it.
+- Rationale repeated beside sibling methods instead of once at the owning capability or helper.
+- Paragraph walls: one paragraph carrying several rules and parenthetical asides. Split it or demote the detail to its home.
+- Emphasis inflation: bold, CAPS, or "critically" everywhere means nothing stands out. Reserve emphasis for the clause that changes behavior.
+- Spec-speak in `implemented/` Agent Notes: "should", migration plans, acceptance checklists. An implemented Agent Note describes what is, per the [implemented-note instructions](../.agents/notes/implemented/AGENTS.md).
+
+## Repository references
+
+Use relative Markdown links for current files and tags or PR numbers for historical references. `verify-md-links` checks local targets. [Reference validation](../scripts/verify-repository-references.ts) rejects actual commit identifiers and disallowed organization URLs in maintained files.

docs/agent-lifecycle.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 docs/agent-lifecycle.md
+agent-lifecycle.md: 6ffe3c2b47e766ac985b3192a1c08787821fc46e
+agent-lifecycle.zh.md: c4b2fa70dbdb0487c3871b6e65227eac8b062e24