Merge origin/master into fix/subagent-empty-terminal-message-output

2026-08-10 23:41:27 +08:00
parent f27bdb2be3 1fdc502ea0
commit 820be286a8
132 changed files with 2453 additions and 1357 deletions
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md
-2026-07-10-single-file-executable-sdk-runtime-distribution.md: a45678c9bb5fcae340ff7134687890879f56c630
-2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: f1fccc508471356dd6434da0e126ed38f15ed3ba
+2026-07-10-single-file-executable-sdk-runtime-distribution.md: c2b6d9ff1825915e39738bf8f782c302ecfc1d0d
+2026-07-10-single-file-executable-sdk-runtime-distribution.zh.md: d7758a77083e07b1d2cac99ae2be3f15e6edd2dc
@@ -34,27 +34,27 @@ Config discovery has two channels and fails loudly when both are missing: the `D

 ### Plugin resolution: the VFS holds a real package tree, the closure manifest IS the deploy root

-Inside the exe's VFS sits a **real package tree in build-artifact form** (each package's `lib/` plus a real `node_modules`); the Loader resolves plugin names through standard dynamic `import()`: bare specifiers resolve upward along `node_modules` from the Loader's position inside the VFS, and land inside the VFS naturally. The closed set needs no allowlist code — the set is whatever the VFS has installed, and importing a name outside the set fails.
+Inside the exe's VFS sits a **real package tree in build-artifact form** (each package's `lib/` plus a real `node_modules`). The packaged JSON-RPC entry supplies its installed harness base to app-boot's root Include: relative plugin specifiers resolve from the external configuration directory, while bare package names resolve from the VFS, so a configuration inside another Node project cannot shadow the packaged plugin set. The ordinary development bin leaves bare packages configuration-owned. Bare specifiers in the packaged entry resolve upward along `node_modules` from the entry's position inside the VFS and land inside the VFS naturally. The closed set needs no allowlist code — the set is whatever the VFS has installed, and importing a name outside the set fails.

 The deploy root is [`python/sdk-runtime/package.json`](../../../../python/sdk-runtime/package.json) (`dsh-jsonrpc-agent-pkg`, a pnpm workspace member and a zero-code pure dependency manifest) — the unified source of truth for "which plugins the exe ships" and "what the Python runtime distributes". Adding a plugin to the exe = adding one dependency line to the manifest and repackaging. [`scripts/verify-runtime-closure.ts`](../../../../scripts/verify-runtime-closure.ts) traverses every workspace package covered by that manifest and requires every non-optional workspace peer at the runtime root, reporting the complete referencing-package → missing-peer chain; `pnpm run hygiene`, CI static, and the single-exe build run it before packaging. Deploy also packs by each package's `files`, so the shared chunks tsdown splits out must be covered by `files`.

 ### Build pipeline and artifacts

-[`scripts/build-exe-for-python-sdk.ts`](../../../../scripts/build-exe-for-python-sdk.ts): runtime closure verification → `pnpm run build` → (after clearing) `pnpm --filter dsh-jsonrpc-agent-pkg deploy --legacy --prod --config.node-linker=hoisted --config.auto-install-peers=false --config.link-workspace-packages=true` **directly into** `python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/` → inject the pkg configuration (`bin` points at `node_modules/@deepseek-ai/dsh-jsonrpc-demo/lib/bin.js` inside the closure, `assets` is a full glob — dynamic import is invisible to pkg's static analysis, so everything must be packed in explicitly) → stage the target `node-pty` addon → one `pkg --sea` per target → the executables `dsh-jsonrpc-agent-pkg-<platform>-<arch>` land in `dist-exe/` and are copied back into the runtime directory. Linux installs build `pty.node` from source, so the builder copies it from the root install into the staged closure because legacy deploy omits that side-effect directory; macOS uses its target prebuild and emits the required `-spawn-helper` beside the executable. CI treats these products as intermediate test inputs and retains their platform wheels. All four deploy flags are grounded in measurement: `--legacy` is the mandatory path with inject-workspace-packages off; hoisted yields a zero-symlink file tree (most stable for the pkg VFS, physically guaranteeing a single cordis instance); disabling automatic peer installation keeps unpublished package names from triggering registry resolution; link-workspace-packages points the closure at workspace/vendor sources.
+[`scripts/build-exe-for-python-sdk.ts`](../../../../scripts/build-exe-for-python-sdk.ts): runtime closure verification → `pnpm run build` → (after clearing) `pnpm --filter dsh-jsonrpc-agent-pkg deploy --legacy --prod --config.node-linker=hoisted --config.auto-install-peers=false --config.link-workspace-packages=true` **directly into** `python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/` → restore any direct workspace package that legacy deploy hoisted back under the source manifest's `node_modules`, omitting its package-local dependency tree and rejecting any remaining manifest gap → replace every staged dependency symlink with its target bytes, remove package-manager `.bin` links, and fail if any symlink remains → inject the pkg configuration (`bin` points at `node_modules/@deepseek-ai/dsh-jsonrpc-demo/lib/packaged-bin.js` inside the closure, `assets` is a full glob — dynamic import is invisible to pkg's static analysis, so everything must be packed in explicitly) → stage the target `node-pty` addon → one `pkg --sea` per target → the executables `dsh-jsonrpc-agent-pkg-<platform>-<arch>` land in `dist-exe/` and are copied back into the runtime directory. Linux installs build `pty.node` from source, so the builder copies it from the root install into the staged closure because legacy deploy omits that side-effect directory; macOS uses its target prebuild and emits the required `-spawn-helper` beside the executable. CI treats these products as intermediate test inputs and retains their platform wheels. All four deploy flags are grounded in measurement: `--legacy` is the mandatory path with inject-workspace-packages off; hoisted gives pkg a stable single-instance layout that the explicit materialization pass makes symlink-free; disabling automatic peer installation prevents undeclared peers from expanding the closure; link-workspace-packages selects direct workspace dependencies. [`pnpm-workspace.yaml`](../../../../pnpm-workspace.yaml) overrides the transitive `@deepseek-ai/cosmokit` and `@deepseek-ai/schemastery` semver requests to the pinned vendor sources so legacy deploy never resolves those unpublished names from a registry.

 CI: [`.github/workflows/build-exe-for-python-sdk.yml`](../../../../.github/workflows/build-exe-for-python-sdk.yml), triggered explicitly only — `workflow_dispatch`, or the `build-exe` label on a pull request; native builds on the three platforms linux-x64 / linux-arm64 (`ubuntu-24.04-arm`) / macos-arm64, with `~/.pkg-cache` cached; macOS ad-hoc signing is handled by pkg. Each leg drives a mock SSE model through the SDK with the default config and a custom `cordis.yml`, drives the exe directly over NDJSON JSON-RPC, verifies the JSONL and final response, and installs release-shaped wheels into a clean venv without `runtime_bin`; Linux additionally inspects GLIBC requirements and runs in a manylinux 2.28 container. A full three-target run retains four artifacts, each containing one release file: the platform-independent SDK wheel and three native runtime wheels; a subset dispatch retains the SDK wheel and selected runtime wheels. Bare executables and source bundles remain intermediate test inputs. [`.gitlab-ci.yml`](../../../../.gitlab-ci.yml) accepts only `python-vX.Y.Z` tag pipelines whose version matches the root `package.json`, builds one SDK wheel and three native runtime wheels, then a single serialized job checks and publishes all four to the project PyPI registry. Windows is a non-goal.

 ### Python SDK distribution: two carriers, exe for production, node for development

-The Python SDK lives at [`python/`](../../../../python/README.md): `python/sdk` (the client) + `python/sdk-runtime` (the runtime carrier package). The runtime package's data directory holds the checked-in default `runtime/cordis.yml`, the build-injected platform exe and optional helper, and the build-injected `runtime/node/` closure tree. `resolve_bundled_launch_args()` automatic resolution **finds the exe only**; the node carrier is enabled only by an explicit `DSH_RUNTIME_MODE=node` (running `runtime/node/node_modules/@deepseek-ai/dsh-jsonrpc-demo/lib/bin.js`, requiring a system node ≥22.19), positioned as the development-verification channel for members of this repo, and does not enter wheel distributions.
+The Python SDK lives at [`python/`](../../../../python/README.md): `python/sdk` (the client) + `python/sdk-runtime` (the runtime carrier package). The runtime package's data directory holds the checked-in default `runtime/cordis.yml`, the build-injected platform exe and optional helper, and the build-injected `runtime/node/` closure tree. `resolve_bundled_launch_args()` automatic resolution **finds the exe only**; the node carrier is enabled only by an explicit `DSH_RUNTIME_MODE=node` (running `runtime/node/node_modules/@deepseek-ai/dsh-jsonrpc-demo/lib/packaged-bin.js`, requiring a system node ≥22.19), positioned as the development-verification channel for members of this repo, and does not enter wheel distributions.

-[`scripts/build-python-release.py`](../../../../scripts/build-python-release.py) reads the authoritative stable `X.Y.Z` from the repository root `package.json` and stages both packages at that version, with the SDK depending exactly on `deepseek-harness-runtime-bin==X.Y.Z`. An optional `python-vX.Y.Z` release tag is a consistency assertion and is rejected when it differs from the repository version; the source `pyproject.toml` development sentinel never determines a release version. The SDK is a `py3-none-any` wheel; each wheel-only runtime package contains one exe, and the macOS wheel also contains its architecture-matched helper. Runtime wheels use one of `py3-none-manylinux_2_28_x86_64`, `py3-none-manylinux_2_28_aarch64`, or `py3-none-macosx_11_0_arm64`; the Hatch hook rejects sdists, universal tags, mixed-platform payloads, missing or extra helpers, and unsupported platforms.
+[`scripts/build-python-release.py`](../../../../scripts/build-python-release.py) reads the authoritative stable `X.Y.Z` from the repository root `package.json` and stages both packages at that version, with `deepseek-harness-sdk` depending exactly on `deepseek-harness-runtime-bin==X.Y.Z`. An optional `python-vX.Y.Z` release tag is a consistency assertion and is rejected when it differs from the repository version; the source `pyproject.toml` development sentinel never determines a release version. The SDK is a `py3-none-any` wheel; each wheel-only runtime package contains one exe, and the macOS wheel also contains its architecture-matched helper. Runtime wheels use one of `py3-none-manylinux_2_28_x86_64`, `py3-none-manylinux_2_28_aarch64`, or `py3-none-macosx_11_0_arm64`; the Hatch hook rejects sdists, universal tags, mixed-platform payloads, missing or extra helpers, and unsupported platforms.

 The exe's "must be explicitly configured" hard semantic is unchanged; the zero-config experience is restored by the wrapper: when the caller gave no `cordis`, named no explicit runtime, and the environment has no `DSH_CORDIS_CONFIG`, the client explicitly injects the checked-in default `cordis.yml` (agent-core + preloaded llm-deepseek + JSONL persistence + bash-local + the `dsh-jsonrpc` serving entry, with `!!js` environment-variable fallbacks) via `DSH_CORDIS_CONFIG`.

 ### Naming lineage

-`@deepseek-ai/dsh-jsonrpc-demo` (the package) → `dsh-jsonrpc-agent` (the bin) → `dsh-jsonrpc-agent-pkg` (the closure manifest; no scope prefix, deliberately sidestepping the constraints' package-shape rules for `@deepseek-ai/dsh-*`) → `dsh-jsonrpc-agent-pkg-<platform>-<arch>` (the exe artifacts). The wire `serverInfo.name` stays `deepseek-harness-sdk-runtime` (a protocol-stable value); the Python dist names are `deepseek-harness` / `deepseek-harness-runtime-bin`.
+`@deepseek-ai/dsh-jsonrpc-demo` (the package) → `dsh-jsonrpc-agent` (the bin) → `dsh-jsonrpc-agent-pkg` (the closure manifest; no scope prefix, deliberately sidestepping the constraints' package-shape rules for `@deepseek-ai/dsh-*`) → `dsh-jsonrpc-agent-pkg-<platform>-<arch>` (the exe artifacts). The wire `serverInfo.name` stays `deepseek-harness-sdk-runtime` (a protocol-stable value); the Python distribution names are `deepseek-harness-sdk` / `deepseek-harness-runtime-bin`, while the import modules remain `deepseek_harness` / `deepseek_harness_runtime`.

 ## Disposition of worker-style plugins

@@ -62,7 +62,7 @@ The exe's "must be explicitly configured" hard semantic is unchanged; the zero-c

 ## Testing

-The verification surface has three tiers. Mechanism tier: the measured conclusions for the `--sea` chain are embedded in the Decision sections (ESM dynamic import inside the VFS, single cordis instance, fail-loud config chain, `node:sqlite`, macOS ad-hoc signing runs). SDK tier: the complete keyless pytest suite covers the client protocol against a fake runtime peer, subprocess cleanup, absolute cwd propagation, dual-carrier launch, and carrier resolution; root CI runs it on Python 3.10. End-to-end tier: every platform build completes a turn against a mock endpoint through the default SDK path, a custom config, and the direct binary protocol, with final text and JSONL checked. The custom config additionally drives `run_code` and a zero-agent `workflow` through their real worker files inside the packaged VFS. The same build leg runs a committed executable-specific snapshot through the Python SDK: a keyless scripted model mounts a Cordis plugin that registers a tool, invokes that tool from `run_code`, runs a direct spawn subagent and a workflow that starts a second spawn child, then unmounts the plugin. The fixture explicitly disables its unused bundled Bash and local skill discovery so its tool set does not depend on repository-external state, and the comparison normalizes opaque message IDs in the SDK result and notification stream plus the parent and two child JSONL logs. This harness stays separate from ACP's `pnpm run test:snapshot` because the protocols and build artifacts differ. The platform wheel is then installed in a clean venv and run without `runtime_bin`.
+The verification surface has three tiers. Mechanism tier: the measured conclusions for the `--sea` chain are embedded in the Decision sections (ESM dynamic import inside the VFS, single cordis instance, fail-loud config chain, `node:sqlite`, macOS ad-hoc signing runs). SDK tier: the complete keyless pytest suite covers the client protocol against a fake runtime peer, subprocess cleanup, absolute cwd propagation, dual-carrier launch, and carrier resolution; root CI runs it on Python 3.10. End-to-end tier: every platform build completes a turn against a mock endpoint through the default SDK path, a custom config, the checked-in standalone minimal composition, and the direct binary protocol, with final text and JSONL checked. The minimal run asserts its exact system prompt and two-tool catalog, retains Bash state across calls, and invokes the editor. The custom config additionally drives `run_code` and a zero-agent `workflow` through their real worker files inside the packaged VFS. The same build leg runs a committed executable-specific snapshot through the Python SDK: a keyless scripted model mounts a Cordis plugin that registers a tool, invokes that tool from `run_code`, runs a direct spawn subagent and a workflow that starts a second spawn child, then unmounts the plugin. The fixture explicitly disables its unused bundled Bash and local skill discovery so its tool set does not depend on repository-external state, and the comparison normalizes opaque message IDs in the SDK result and notification stream plus the parent and two child JSONL logs. This harness stays separate from ACP's `pnpm run test:snapshot` because the protocols and build artifacts differ. The platform wheel is then installed in a clean venv and run without `runtime_bin`.

 Manual-driving caveat: the bin treats stdin EOF as "the client is gone" and disposes immediately, so a short-lived pipe aborts an in-flight turn — pipe-driven runs must keep stdin open until the turn ends.

@@ -34,27 +34,27 @@ exe 使用 [@yao-pkg/pkg](https://github.com/yao-pkg/pkg)（vercel/pkg 归档后

 ### 插件解析：VFS 装载真实包树，闭包 manifest（元数据清单）就是部署根目录

-exe 的 VFS 内是**构建产物形态的真实包树**（各包的 `lib/` + 真实 `node_modules`）。loader 通过标准动态 `import()` 解析插件名：裸包名从 VFS 内 loader 所在位置沿 `node_modules` 向上解析，自然落在 VFS 内。封闭集不需要白名单代码——VFS 中安装了什么，集合中就有什么；`import()` 集合外的名称会失败。
+exe 的 VFS 内是**构建产物形态的真实包树**（各包的 `lib/` + 真实 `node_modules`）。打包专用 JSON-RPC 入口会向 app-boot 的根 Include 提供自身已安装 harness 的基准位置：相对插件说明符从外部配置目录解析，裸包名则从 VFS 解析，因此位于另一个 Node 项目内的配置无法遮蔽已打包的插件集合。普通开发 bin 仍由配置项目提供裸包。打包入口中的裸包名从该入口在 VFS 内的位置沿 `node_modules` 向上解析，自然落在 VFS 内。封闭集不需要白名单代码——VFS 中安装了什么，集合中就有什么；`import()` 集合外的名称会失败。

 部署根目录是 [`python/sdk-runtime/package.json`](../../../../python/sdk-runtime/package.json)（`dsh-jsonrpc-agent-pkg`，pnpm 工作区成员、零代码纯依赖 manifest），也是「exe 安装哪些插件」与「Python 运行时分发什么」的统一真源。向 exe 添加插件，就是在 manifest 中增加一行依赖后重新打包。[`scripts/verify-runtime-closure.ts`](../../../../scripts/verify-runtime-closure.ts) 遍历该 manifest 覆盖的全部工作区包，要求每个非可选的工作区对等依赖（peer dependency）都显式列在运行时根目录，并报告“引用包 → 缺失对等依赖”的完整链路；`pnpm run hygiene`、CI 静态检查与 single-exe 构建都会在打包前运行该门禁。部署还会依据各包的 `files` 字段打包，因此 tsdown 拆出的共享分片必须被 `files` 覆盖。

 ### 构建管线与产物

-[`scripts/build-exe-for-python-sdk.ts`](../../../../scripts/build-exe-for-python-sdk.ts)：运行时闭包校验 → `pnpm run build` →（清空后）`pnpm --filter dsh-jsonrpc-agent-pkg deploy --legacy --prod --config.node-linker=hoisted --config.auto-install-peers=false --config.link-workspace-packages=true` **直接写入** `python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/` → 注入 pkg 配置（`bin` 指向闭包内的 `node_modules/@deepseek-ai/dsh-jsonrpc-demo/lib/bin.js`；`assets` 使用全量 glob，因为动态 `import()` 对 pkg 静态分析不可见，必须显式打入全部内容）→ 暂存目标平台的 `node-pty` addon → 每个构建目标调用一次 `pkg --sea` → 可执行文件 `dsh-jsonrpc-agent-pkg-<platform>-<arch>` 写入 `dist-exe/`，并拷回运行时目录。Linux 安装会从源码构建 `pty.node`，而 `--legacy` 部署会省略该副作用目录，因此构建器会把它从根安装目录复制到暂存闭包；macOS 使用对应目标的预构建产物，并在可执行文件旁生成所需的 `-spawn-helper`。CI 将这些产物作为测试中间输入，只保留对应平台的 wheel 包。四个部署标志都有实测依据：未启用 `inject-workspace-packages` 时必须使用 `--legacy`；`hoisted` 产出无符号链接的文件树（对 pkg VFS 最稳定，并从物理上保证只有一个 Cordis 实例）；关闭对等依赖自动安装可避免未发布包名触发注册表解析；`link-workspace-packages` 让闭包指向工作区/vendor 源码。
+[`scripts/build-exe-for-python-sdk.ts`](../../../../scripts/build-exe-for-python-sdk.ts)：运行时闭包校验 → `pnpm run build` →（清空后）`pnpm --filter dsh-jsonrpc-agent-pkg deploy --legacy --prod --config.node-linker=hoisted --config.auto-install-peers=false --config.link-workspace-packages=true` **直接写入** `python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/` → 恢复被 legacy deploy 提升回源 manifest 的 `node_modules` 下的任何直接工作区包，同时省略其包内依赖树，并拒绝剩余的 manifest 缺口 → 将暂存依赖中的每个符号链接替换为目标文件内容，删除包管理器的 `.bin` 链接，并在仍有任何符号链接时失败 → 注入 pkg 配置（`bin` 指向闭包内的 `node_modules/@deepseek-ai/dsh-jsonrpc-demo/lib/packaged-bin.js`；`assets` 使用全量 glob，因为动态 `import()` 对 pkg 静态分析不可见，必须显式打入全部内容）→ 暂存目标平台的 `node-pty` addon → 每个构建目标调用一次 `pkg --sea` → 可执行文件 `dsh-jsonrpc-agent-pkg-<platform>-<arch>` 写入 `dist-exe/`，并拷回运行时目录。Linux 安装会从源码构建 `pty.node`，而 `--legacy` 部署会省略该副作用目录，因此构建器会把它从根安装目录复制到暂存闭包；macOS 使用对应目标的预构建产物，并在可执行文件旁生成所需的 `-spawn-helper`。CI 将这些产物作为测试中间输入，只保留对应平台的 wheel 包。四个部署标志都有实测依据：未启用 `inject-workspace-packages` 时必须使用 `--legacy`；`hoisted` 为 pkg 提供稳定的单实例布局，再由显式物化步骤消除符号链接；关闭对等依赖自动安装可防止未声明的对等依赖扩大闭包；`link-workspace-packages` 选择直接工作区依赖。[`pnpm-workspace.yaml`](../../../../pnpm-workspace.yaml) 将传递的 `@deepseek-ai/cosmokit` 与 `@deepseek-ai/schemastery` semver 请求覆盖到固定的 vendor 源码，使 legacy deploy 不会从注册表解析这些未发布名称。

 CI 使用 [`.github/workflows/build-exe-for-python-sdk.yml`](../../../../.github/workflows/build-exe-for-python-sdk.yml)，且只允许显式触发：手动派发 `workflow_dispatch`，或给 PR（Pull Request）添加 `build-exe` 标签。linux-x64、linux-arm64（`ubuntu-24.04-arm`）和 macos-arm64 三个平台分别进行原生构建，并缓存 `~/.pkg-cache`；macOS 的 ad-hoc 签名由 pkg 处理。每个平台都使用 mock SSE（Server-Sent Events）模型，分别通过默认配置和自定义 `cordis.yml` 驱动 SDK，再通过 NDJSON JSON-RPC 直接驱动 exe，校验 JSONL 与最终响应；最后把发布形态的 wheel 包安装到干净的 venv 中，并在不传 `runtime_bin` 的情况下运行。Linux 还会检查 GLIBC 依赖，并在 manylinux 2.28 容器中运行。完整构建三个目标时保留 4 个产物，每个产物只含一个发布文件：平台无关的 SDK wheel 包与 3 个原生运行时 wheel 包；手动选择部分目标时保留 SDK wheel 与所选运行时 wheel。裸 exe 与源码包只作为测试中间输入。[`.gitlab-ci.yml`](../../../../.gitlab-ci.yml) 只接受版本与根目录 `package.json` 匹配的 `python-vX.Y.Z` 标签流水线，构建一个 SDK wheel 包和 3 个原生运行时 wheel 包，再由单个串行任务校验并将这 4 个文件发布到项目的 PyPI 注册表。Windows 不在目标范围内。

 ### Python SDK 分发：双载体，exe 用于生产，`node` 用于开发

-Python SDK 位于 [`python/`](../../../../python/README.md)：`python/sdk` 是客户端，`python/sdk-runtime` 是运行时载体包。运行时包的数据目录包含检入的默认 `runtime/cordis.yml`、构建注入的平台 exe 与可选 helper，以及构建注入的 `runtime/node/` 闭包树。`resolve_bundled_launch_args()` 的自动解析**只查找 exe**；`node` 载体仅在显式设置 `DSH_RUNTIME_MODE=node` 时启用（运行 `runtime/node/node_modules/@deepseek-ai/dsh-jsonrpc-demo/lib/bin.js`，需要系统 Node ≥22.19），定位为本仓库成员的开发验证通道，不随 wheel 包分发。
+Python SDK 位于 [`python/`](../../../../python/README.md)：`python/sdk` 是客户端，`python/sdk-runtime` 是运行时载体包。运行时包的数据目录包含检入的默认 `runtime/cordis.yml`、构建注入的平台 exe 与可选 helper，以及构建注入的 `runtime/node/` 闭包树。`resolve_bundled_launch_args()` 的自动解析**只查找 exe**；`node` 载体仅在显式设置 `DSH_RUNTIME_MODE=node` 时启用（运行 `runtime/node/node_modules/@deepseek-ai/dsh-jsonrpc-demo/lib/packaged-bin.js`，需要系统 Node ≥22.19），定位为本仓库成员的开发验证通道，不随 wheel 包分发。

-[`scripts/build-python-release.py`](../../../../scripts/build-python-release.py) 从仓库根目录的 `package.json` 读取权威的稳定版本 `X.Y.Z`，以该版本暂存两个包，并让 SDK 精确依赖 `deepseek-harness-runtime-bin==X.Y.Z`。可选的 `python-vX.Y.Z` 发布标签只是一项一致性断言，与仓库版本不同时会被拒绝；源码 `pyproject.toml` 中的开发占位版本从不决定发布版本。SDK 是 `py3-none-any` wheel 包；每个只提供 wheel 包的运行时包都包含一个 exe，macOS wheel 包还包含与其架构匹配的 helper。运行时 wheel 包使用 `py3-none-manylinux_2_28_x86_64`、`py3-none-manylinux_2_28_aarch64` 或 `py3-none-macosx_11_0_arm64` 三种标签之一；Hatch 钩子拒绝 sdist、通用标签、混合平台载荷、helper 缺失或多余，以及不支持的平台。
+[`scripts/build-python-release.py`](../../../../scripts/build-python-release.py) 从仓库根目录的 `package.json` 读取权威的稳定版本 `X.Y.Z`，以该版本暂存两个包，并让 `deepseek-harness-sdk` 精确依赖 `deepseek-harness-runtime-bin==X.Y.Z`。可选的 `python-vX.Y.Z` 发布标签只是一项一致性断言，与仓库版本不同时会被拒绝；源码 `pyproject.toml` 中的开发占位版本从不决定发布版本。SDK 是 `py3-none-any` wheel 包；每个只提供 wheel 包的运行时包都包含一个 exe，macOS wheel 包还包含与其架构匹配的 helper。运行时 wheel 包使用 `py3-none-manylinux_2_28_x86_64`、`py3-none-manylinux_2_28_aarch64` 或 `py3-none-macosx_11_0_arm64` 三种标签之一；Hatch 钩子拒绝 sdist、通用标签、混合平台载荷、helper 缺失或多余，以及不支持的平台。

 exe「必须显式配置」的硬语义不变；零配置体验由包装层恢复：调用方没有提供 `cordis`、没有显式指定运行时，且环境中没有 `DSH_CORDIS_CONFIG` 时，客户端将检入的默认 `cordis.yml`（`agent-core` + 预载的 `llm-deepseek` + JSONL 持久化 + `bash-local` + `dsh-jsonrpc` 对外服务条目，并通过 `!!js` 使用环境变量兜底）显式注入 `DSH_CORDIS_CONFIG`。

 ### 命名血统

-`@deepseek-ai/dsh-jsonrpc-demo`（包）→ `dsh-jsonrpc-agent`（`bin`）→ `dsh-jsonrpc-agent-pkg`（闭包 manifest；没有作用域前缀，刻意避开 `constraints` 对 `@deepseek-ai/dsh-*` 的包形状规则）→ `dsh-jsonrpc-agent-pkg-<platform>-<arch>`（exe 产物）。协议字段 `serverInfo.name` 保持为 `deepseek-harness-sdk-runtime`（协议稳定值）；Python 分发名为 `deepseek-harness` / `deepseek-harness-runtime-bin`。
+`@deepseek-ai/dsh-jsonrpc-demo`（包）→ `dsh-jsonrpc-agent`（`bin`）→ `dsh-jsonrpc-agent-pkg`（闭包 manifest；没有作用域前缀，刻意避开 `constraints` 对 `@deepseek-ai/dsh-*` 的包形状规则）→ `dsh-jsonrpc-agent-pkg-<platform>-<arch>`（exe 产物）。协议字段 `serverInfo.name` 保持为 `deepseek-harness-sdk-runtime`（协议稳定值）；Python 分发包名为 `deepseek-harness-sdk` / `deepseek-harness-runtime-bin`，导入模块名仍为 `deepseek_harness` / `deepseek_harness_runtime`。

 ## 工作线程插件

@@ -62,7 +62,7 @@ exe 内支持 `dsh-workflow-workerthread` 与 `dsh-code-runtime-worker`。两个

 ## 测试

-验证面分三层。机制层：`--sea` 链路的实测结论内嵌在「决策」各节（VFS 内 ESM 动态 `import()`、单一 Cordis 实例、明确报错的配置链路、`node:sqlite`、macOS ad-hoc 签名可运行）。SDK 层：完整的无密钥 pytest 套件以 mock 运行时对端覆盖客户端协议、子进程清理、绝对 `cwd` 传递、双载体启动与载体解析；根 CI 在 Python 3.10 上运行全部用例。端到端层：每个平台构建都通过默认 SDK 路径、自定义配置和直接二进制协议，对 mock 端点完成一个轮次，并校验最终文本与 JSONL。自定义配置还会通过打包进 VFS 的真实工作线程文件执行 `run_code` 和不启动 agent 的 `workflow`。同一构建任务还会经 Python SDK 运行一组检入的 exe 专用快照：无密钥脚本化模型挂载一个会注册工具的 Cordis 插件，从 `run_code` 调用该工具，运行一个直接 spawn 的 subagent 和一个会通过 spawn 启动第二个 subagent 的工作流，随后卸载该插件。该 fixture（测试前置数据）会显式禁用组合包中未使用的 Bash 和本地 skill（技能）发现，使其工具集不依赖仓库外部状态；比较时会规范化以下各处的不透明消息 ID：SDK 结果与通知流，以及父会话和两个子会话的 JSONL 日志。该 harness 与 ACP 的 `pnpm run test:snapshot` 保持独立，因为二者的协议和构建产物不同。随后把平台 wheel 包安装进干净的 venv，并在不传 `runtime_bin` 的情况下运行。
+验证面分三层。机制层：`--sea` 链路的实测结论内嵌在「决策」各节（VFS 内 ESM 动态 `import()`、单一 Cordis 实例、明确报错的配置链路、`node:sqlite`、macOS ad-hoc 签名可运行）。SDK 层：完整的无密钥 pytest 套件以 mock 运行时对端覆盖客户端协议、子进程清理、绝对 `cwd` 传递、双载体启动与载体解析；根 CI 在 Python 3.10 上运行全部用例。端到端层：每个平台构建都通过默认 SDK 路径、自定义配置、仓库内置的独立 minimal 组合和直接二进制协议，对 mock 端点完成一个轮次，并校验最终文本与 JSONL。minimal 运行会断言其精确系统提示词与双工具目录，跨调用保留 Bash 状态，并调用编辑器。自定义配置还会通过打包进 VFS 的真实工作线程文件执行 `run_code` 和不启动 agent 的 `workflow`。同一构建任务还会经 Python SDK 运行一组检入的 exe 专用快照：无密钥脚本化模型挂载一个会注册工具的 Cordis 插件，从 `run_code` 调用该工具，运行一个直接 spawn 的 subagent 和一个会通过 spawn 启动第二个 subagent 的工作流，随后卸载该插件。该 fixture（测试前置数据）会显式禁用组合包中未使用的 Bash 和本地 skill（技能）发现，使其工具集不依赖仓库外部状态；比较时会规范化以下各处的不透明消息 ID：SDK 结果与通知流，以及父会话和两个子会话的 JSONL 日志。该 harness 与 ACP 的 `pnpm run test:snapshot` 保持独立，因为二者的协议和构建产物不同。随后把平台 wheel 包安装进干净的 venv，并在不传 `runtime_bin` 的情况下运行。

 手工驱动注意：`bin` 将 stdin EOF 视为「客户端已离开」并立即 dispose，短命管道会中止进行中的轮次——管道驱动必须保持 stdin 打开，直到轮次结束。

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-09-layered-skill-registry.md
-2026-08-09-layered-skill-registry.md: 3f092cfb4b722e3dd51fa4dc46c620259eaffa39
-2026-08-09-layered-skill-registry.zh.md: 38b17329c8d46ee9bbd0863f3fae7cf6be39aa75
+2026-08-09-layered-skill-registry.md: 73897c3cb7e0055ff59221b7ea47c5d6ced06991
+2026-08-09-layered-skill-registry.zh.md: 655780d4ef154434d6debf478134d3293d6c564f
@@ -24,7 +24,7 @@ The composition moves with it: the web-app bundle re-enables the base `skill` re

 **A deployment-level skill reaches every preset-composed session that mounts `tool-skill`.** The repository-plugin e2e's skill root and assertions are restored; the shipped-Web e2e proves the badge row (the same host-registration shape) merges into a standard-preset agent's catalog while the host view stays global-only.

-**Layer visibility and consumption stay separate choices.** A core-web agent can read the global layer in principle, but composes no `skill` tool — whether an agent has skills at all remains the preset's decision, made by mounting or omitting `tool-skill`.
+**Layer visibility and consumption stay separate choices.** A `minimal` agent can read the global layer in principle, but composes no `skill` tool — whether an agent has skills at all remains the preset's decision, made by mounting or omitting `tool-skill`.

 **Provider options are still the borrowed caller object.** `SkillViewOptions` extends `SkillLookupOptions`; the registry consumes `scope` and providers read only their own contract from the same readonly object, preserving the existing borrow-identity guarantee.

@@ -24,7 +24,7 @@ agent-preset stack 曾把整个 skill 能力——注册表、本地提供方和

 **部署级 skill 会到达每个挂载 `tool-skill` 的 preset 会话。**repository-plugin e2e 的 skill 根目录与断言已恢复；shipped-Web e2e 证明 badge 行（同一种宿主注册形态）汇入 standard preset agent 的目录，而宿主视图保持仅全局。

-**层可见性与消费仍是两个独立选择。**core-web agent 原则上可读全局层，但不组合 `skill` 工具——agent 是否拥有 skill 依旧由 preset 通过挂载或省略 `tool-skill` 决定。
+**层可见性与消费仍是两个独立选择。** `minimal` agent 原则上可读全局层，但不组合 `skill` 工具——agent 是否拥有 skill 依旧由 preset 通过挂载或省略 `tool-skill` 决定。

 **提供方选项仍是借用的调用方对象。**`SkillViewOptions` 扩展 `SkillLookupOptions`；注册表消费 `scope`，提供方只从同一个只读对象中读取自己的契约，保持既有的借用恒等保证。

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-08-10-minimal-preset-owns-rl-composition.md
+2026-08-10-minimal-preset-owns-rl-composition.md: 002cad0827e969b322997821dc978db85e2955f3
+2026-08-10-minimal-preset-owns-rl-composition.zh.md: e957b57395c68b336695bdae07ea15a54ca1ea4e
@@ -0,0 +1,39 @@
+# Agent Note: The minimal preset owns the complete RL agent composition
+
+Status: implemented
+
+English | [中文](2026-08-10-minimal-preset-owns-rl-composition.zh.md)
+
+## Problem
+
+The Web surface offered two owners for the Claude SWE-compatible RL agent: a process-wide `core-web.cordis.yml` patch and the per-session `minimal` preset. Once [agent presets](../architecture/2026-08-03-per-session-agent-presets.md) became the agent-composition boundary, the preset's scoped `deployment:persona` shadowed the overlay's corrected global persona with stale coding-agent text. The overlay test mounted no preset, while the preset test booted without the overlay, so neither exercised the composition users selected.
+
+The split also hid other drift. The preset mounted one-shot Bash rather than the [persistent Bash](../feature/2026-07-29-persistent-bash-str-replace-editor.md) used by the RL harness and omitted the RL compaction policy. Keeping both owners makes every future prompt, tool, and policy change a cross-product.
+
+## Decision
+
+The shipped Web `minimal` preset is the sole Web owner of the RL agent composition. It declares an entry-local PTY registry and local backend, persistent `bash` with the RL environment description and 300-second timeout, `str_replace_editor`, and an entry-local compaction backend. Tool presentation remains a deployment choice. The compaction policy keeps the RL threshold, absolute retention, generation cap, and retry count; model capacity comes from routed adapter metadata because `contextWindow` is no longer a compact-basic config field. The editor accepts no `requireAbsolutePath` setting because absolute paths are its unconditional contract.
+
+The preset persona is exactly `You are a helpful software engineer assistant.` and sets `complete: true`. A complete `PromptSection` participates in ordinary assembly so tools, contexts, variables, and cooperative listeners still resolve; after the `system-prompt/assemble` waterfall, the prompt registry restores a detached copy of that section as the sole system-prompt section. Multiple effective complete sections reject assembly. This final registry constraint prevents harness identity, Web orientation, tool guidance, or an assembly listener from appending prompt text.
+
+The process-wide `core-web.cordis.yml` patch is absent. Browser UI, workspace attachment, persistence, filesystem, subprocess, sandbox, permission, model routing, and other cross-session services remain host-owned. Selecting `minimal` changes one agent's model-facing composition without changing other sessions in the Web process.
+
+## Verification
+
+System-prompt and persona package tests prove final complete-section enforcement, including waterfall mutation and duplicate rejection. The shipped-preset composition test asserts the exact prompt, Bash description, absolute editor schema, and two-tool catalog under the default native presentation. The keyless Web replay sends a real request through a `minimal` agent while global identity, Web surface text, and a test section are registered, then executes two persistent Bash calls to prove environment and cwd state survive and executes the editor through an absolute path.
+
+The standalone [`minimal.cordis.yml`](../../../../examples/jsonrpc-agent/minimal.cordis.yml) mirrors the same prompt, tools, timeouts, and compaction policy for the bundled JSON-RPC runtime. Its keyless SDK replay asserts the assembled system prompt and two-tool catalog, executes persistent Bash across calls, and exercises the editor; the Python SDK tutorial provides the runnable entry point.
+
+## Alternatives considered
+
+**Keep `core-web.cordis.yml` as a compatibility patch.** Rejected because a process patch and a session preset are two independent owners for one agent contract; precedence makes either one capable of silently undoing the other.
+
+**Disable every known prompt contributor in the preset.** Rejected because host rows are process-wide and new contributors would reopen the prompt. A final complete-section constraint expresses the negative guarantee at the registry that assembles the prompt.
+
+**Filter sections only with a prepended waterfall listener.** Rejected because another prepended wrapper can run outside it and append after the filter. Enforcement after the complete waterfall has stable final authority.
+
+**Mount PTY services on the Web host.** Rejected because only the minimal agent consumes them. An entry-local `pty` realm gives the services the same lifetime and scope as their sole consumer without publishing a process-global service from a preset.
+
+## Consequences
+
+The RL prompt is fixed rather than environment-overridable. The Web preset and standalone JSON-RPC example state the same contract for their respective launch surfaces. The model sees only persistent `bash` and `str_replace_editor`; shell state is per agent and disappears with that agent. The preset pays for its own PTY and compaction service instances, while other presets pay nothing for them. The local persistent-shell backend requires the supported POSIX terminal substrate, so this preset is not a Windows agent surface.
@@ -0,0 +1,39 @@
+# Agent Note: minimal preset 拥有完整的 RL agent 组合
+
+Status: implemented
+
+[English](2026-08-10-minimal-preset-owns-rl-composition.md) | 中文
+
+## 问题
+
+Web surface 同时由两个位置定义与 Claude SWE 兼容的 RL agent（智能体）：进程级 `core-web.cordis.yml` patch，以及逐会话的 `minimal` preset。[agent preset](../architecture/2026-08-03-per-session-agent-presets.md) 成为 agent 组合边界后，preset 中带作用域的 `deployment:persona` 会用陈旧的 coding-agent 文本遮蔽 overlay 修正过的全局 persona。overlay 测试没有挂载 preset，而 preset 测试启动时没有 overlay，因此两者都没有覆盖用户实际选择的组合。
+
+这种拆分还掩盖了其他偏差。preset 挂载了一次性 Bash，而不是 RL harness 使用的[持久 Bash](../feature/2026-07-29-persistent-bash-str-replace-editor.md)，并且遗漏了 RL 压缩（compaction）策略。保留两个所有者，会使今后每次修改提示词、工具或策略时都必须验证二者的交叉组合。
+
+## 决策
+
+随附的 Web `minimal` preset 是 RL agent 组合在 Web 中的唯一所有者。它声明 entry 本地的 PTY 注册表与本地后端、带 RL 环境描述且超时为 300 秒的持久 `bash`、`str_replace_editor`，以及 entry 本地的压缩后端。工具呈现仍由部署选择。压缩策略保留 RL 的阈值、绝对保留量、生成上限和重试次数；模型容量来自经路由选定的适配器元数据，因为 `contextWindow` 已不再是 compact-basic 的配置字段。编辑器不接受 `requireAbsolutePath` 设置，因为要求绝对路径是它的无条件约定。
+
+preset persona 恰好是 `You are a helpful software engineer assistant.`，并设置 `complete: true`。complete `PromptSection` 参与常规组装，因此工具、上下文、变量和协作式监听器仍会解析；`system-prompt/assemble` waterfall（瀑布式事件）结束后，提示词注册表会将该段落的独立副本恢复为唯一的系统提示词段落。存在多个有效 complete 段时，组装会被拒绝。这项最终注册表约束可防止 harness 身份、Web 定位、工具引导或组装监听器追加提示词文本。
+
+进程级 `core-web.cordis.yml` patch 不再存在。浏览器 UI、workspace 附加、持久化、文件系统、子进程、沙箱、权限、模型路由及其他跨会话服务仍由宿主持有。选择 `minimal` 只会改变一个 agent 面向模型的组合，不会改变 Web 进程中的其他会话。
+
+## 验证
+
+系统提示词与 persona 包测试证明了 complete 段的最终约束，包括 waterfall 修改与重复项拒绝。交付 preset 组合测试在默认原生呈现下断言精确的提示词、Bash 描述、要求绝对路径的编辑器 schema 和双工具目录。无密钥 Web 回放通过 `minimal` agent 发送一个真实请求，同时注册全局身份、Web surface 文本和一个测试段落；随后执行两次持久 Bash 调用，证明环境与 cwd 状态能够保留，并通过绝对路径执行编辑器。
+
+独立的 [`minimal.cordis.yml`](../../../../examples/jsonrpc-agent/minimal.cordis.yml) 为内置 JSON-RPC 运行时复现相同的提示词、工具、超时和压缩策略。其无密钥 SDK 回放会断言组装后的系统提示词与双工具目录，跨调用执行持久 Bash，并使用编辑器；Python SDK 教程提供可运行的入口。
+
+## 考虑过的替代方案
+
+**将 `core-web.cordis.yml` 保留为兼容 patch。** 被拒绝，因为进程 patch 与会话 preset 是同一 agent 约定的两个独立所有者；优先级会使任意一方都能静默撤销另一方的配置。
+
+**在 preset 中禁用每个已知的提示词贡献方。** 被拒绝，因为宿主行属于整个进程，新的贡献方也会重新开放提示词。由组装提示词的注册表实施最终 complete 段约束，才能表达这项否定保证。
+
+**仅使用前置 waterfall 监听器筛选段落。** 被拒绝，因为另一个前置包装层可以在该监听器外执行，并在筛选后追加内容。在整个 waterfall 结束后实施约束，才能稳定拥有最终决定权。
+
+**在 Web 宿主上挂载 PTY 服务。** 被拒绝，因为只有 minimal agent 消费这些服务。entry 本地的 `pty` realm 与唯一消费方具有相同的生命周期和作用域，无需由 preset 发布进程级全局服务。
+
+## 后果
+
+RL 提示词固定不变，不能通过环境覆盖。Web preset 与独立 JSON-RPC 示例分别在各自的启动界面声明相同的约定。模型只看到持久 `bash` 与 `str_replace_editor`；shell 状态按 agent 隔离，并随该 agent 一并消失。preset 为自身的 PTY 与压缩服务实例承担开销，其他 preset 无需承担。持久 shell 的本地后端需要受支持的 POSIX 终端基础环境，因此该 preset 不适用于 Windows agent surface。
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-29-persistent-bash-str-replace-editor.md
-2026-07-29-persistent-bash-str-replace-editor.md: c4750e30370bfd253064c39cb1adc0f5b2baa60d
-2026-07-29-persistent-bash-str-replace-editor.zh.md: 83159d9792fd9fadaaa342cc289300b35da34e4a
+2026-07-29-persistent-bash-str-replace-editor.md: 2c077a08e6027245779a0db364c83d17a9c74fce
+2026-07-29-persistent-bash-str-replace-editor.zh.md: f642f2100cbc40ddf688400c5e6124ca9a6ff72d
@@ -18,7 +18,7 @@ Some deployments need a one-call Bash schema whose shell state survives across m

 Both plugins are included in the Python runtime closure. The persistent Bash closure also includes the PTY service/local backend and the sandbox services required by that backend. Because `node-pty` executes a native `spawn-helper` on macOS, each packaged macOS runtime executable ships with a `-spawn-helper` sibling; Linux uses `forkpty` directly. A pinned `node-pty` patch checks `DSH_NODE_PTY_SPAWN_HELPER` first, so it remains a true override for a current external consumer that supplies a non-sibling helper. When the override is unset, the patch resolves the packaged executable sibling if present and otherwise preserves upstream lookup in ordinary Node runs. The macOS builders fail before publication when the helper is absent or not executable.

-The shipped [`core-web.cordis.yml`](../../../../apps/cli/config/core-web.cordis.yml) overlay composes both plugins over the ordinary Web surface for the Claude SWE-compatible RL contract. It pins native tool mode and makes the complete system prompt `DSH_SYSTEM_PROMPT` when set or `You are a helpful software engineer assistant.` otherwise, with no harness identity, source-checkout section, Web orientation, Workspace instructions, or tool-mode guidance. It disables every other model-facing consumer, so the model receives exactly the persistent `bash` and `str_replace_editor` schemas, while the Web host, browser, Workspace, persistence, sandbox, and permission stack remains in place. The local PTY backend resolves the effective session sandbox mode when it creates the shell. While that owner has an open shell or a spawn in progress, a different permission mode is rejected before its session event commits; the editor continues through the Web filesystem sandbox.
+The shipped [`minimal` agent preset](../../../../apps/cli/config/agent-presets/minimal/agent.cordis.yml) composes both plugins for the Claude SWE-compatible RL contract. Its entry-local PTY realm carries the registry, local backend, and persistent Bash tool; the editor registers beside that realm against the host filesystem. The preset fixes the complete system prompt, follows the deployment tool-presentation mode, omits every other model-facing consumer, and leaves browser, Workspace, persistence, sandbox, and permission services on the shared Web host. The local PTY backend resolves the effective session sandbox mode when it creates the shell. While that owner has an open shell or a spawn in progress, a different permission mode is rejected before its session event commits; the editor continues through the Web filesystem sandbox. The [minimal-preset decision](../bug-fix/2026-08-10-minimal-preset-owns-rl-composition.md) owns this composition boundary.

 ## Alternatives considered

@@ -32,4 +32,4 @@ The shipped [`core-web.cordis.yml`](../../../../apps/cli/config/core-web.cordis.

 ## Consequences

-Profiles can reproduce an external agent by configuring persona and descriptions while the underlying packages remain general. Persistent Bash requires an owning Agent and real PTY backend. Shell exit, timeout, or cancellation loses state. The editor delegates security and mutation policy to the mounted filesystem stack. The Core Web profile retains Web permissions but must close its persistent shell before changing modes. Runtime-wheel consumers still need no Node installation; Linux wheels contain one executable, while macOS wheels also contain its private native helper.
+Profiles can reproduce an external agent by configuring persona and descriptions while the underlying packages remain general. Persistent Bash requires an owning Agent and real PTY backend. Shell exit, timeout, or cancellation loses state. The editor delegates security and mutation policy to the mounted filesystem stack. A minimal Web agent retains Web permissions but must close its persistent shell before changing modes. Runtime-wheel consumers still need no Node installation; Linux wheels contain one executable, while macOS wheels also contain its private native helper.
@@ -18,7 +18,7 @@ Status: implemented

 两个插件都进入 Python runtime 闭包。持久 Bash 的闭包还包含 PTY 服务／本地后端，以及该后端要求的沙箱服务。由于 `node-pty` 在 macOS 上会执行原生 `spawn-helper`，每个打包后的 macOS 运行时可执行文件都会携带一个 `-spawn-helper` 伴随文件；Linux 直接使用 `forkpty`。固定版本的 `node-pty` 补丁会先检查 `DSH_NODE_PTY_SPAWN_HELPER`，因此对当前提供非伴随 helper 的外部消费方而言，该变量仍是真正的覆盖项。未设置该覆盖时，补丁会在打包可执行文件的伴随文件存在时解析它，否则在普通 Node 运行中保留上游查找方式。若 helper 缺失或不可执行，macOS 构建器会在发布前失败。

-已交付的 [`core-web.cordis.yml`](../../../../apps/cli/config/core-web.cordis.yml) overlay 会在常规 Web 界面之上组合这两个插件，以满足与 Claude SWE 兼容的 RL 约定。它固定使用原生工具模式；完整的系统提示词在设置 `DSH_SYSTEM_PROMPT` 时采用其值，否则采用 `You are a helpful software engineer assistant.`，且不包含 harness 身份、源码 checkout 提示词段、Web 界面定位、Workspace 指令或工具模式指引。它会禁用其他所有面向模型的消费方，使模型恰好只收到持久 `bash` 和 `str_replace_editor` 两个 schema，同时保留 Web 宿主、浏览器、Workspace、持久化、沙箱与权限栈。本地 PTY 后端会在创建 shell 时解析会话的有效沙箱模式。只要该所有者仍有打开的 shell 或仍在进行中的 spawn，另一种权限模式就会在对应的会话事件提交前遭到拒绝；编辑器则继续经由 Web 文件系统沙箱运行。
+随附的 [`minimal` agent preset](../../../../apps/cli/config/agent-presets/minimal/agent.cordis.yml) 会组合这两个插件，以满足与 Claude SWE 兼容的 RL 约定。其 entry 本地 PTY realm 持有注册表、本地后端和持久 Bash 工具；编辑器在该 realm 旁注册，并使用宿主文件系统。preset 会固定完整系统提示词、跟随部署的工具呈现模式，省略其他所有面向模型的消费方，并将浏览器、Workspace、持久化、沙箱与权限服务留在共享 Web 宿主上。本地 PTY 后端会在创建 shell 时解析会话的有效沙箱模式。只要该所有者仍有打开的 shell 或仍在进行中的 spawn，另一种权限模式就会在对应的会话事件提交前遭到拒绝；编辑器则继续经由 Web 文件系统沙箱运行。这一组合边界由 [minimal-preset 决策](../bug-fix/2026-08-10-minimal-preset-owns-rl-composition.md)负责说明。

 ## 考虑过的替代方案

@@ -32,4 +32,4 @@ Status: implemented

 ## 后果

-Profile 可以通过配置 persona 和描述复现外部 Agent，而底层包保持通用。持久 Bash 需要拥有它的 Agent 与真实 PTY 后端；shell 退出、超时或取消会丢失状态。编辑器把安全与变更策略委托给挂载的文件系统栈。Core Web profile 保留 Web 权限，但必须先关闭持久 shell 才能更改权限模式。运行时 wheel 包的消费方仍无需安装 Node；Linux wheel 包包含一个可执行文件，macOS wheel 包还包含其私有原生 helper。
+Profile 可以通过配置 persona 和描述复现外部 Agent，而底层包保持通用。持久 Bash 需要拥有它的 Agent 与真实 PTY 后端；shell 退出、超时或取消会丢失状态。编辑器把安全与变更策略委托给挂载的文件系统栈。minimal Web agent 保留 Web 权限，但必须先关闭持久 shell 才能更改权限模式。运行时 wheel 包的消费方仍无需安装 Node；Linux wheel 包包含一个可执行文件，macOS wheel 包还包含其私有原生 helper。
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-31-even-out-shipped-tool-rosters.md
-2026-07-31-even-out-shipped-tool-rosters.md: 0195620055da5e570d2f54792d950a88bab8d652
-2026-07-31-even-out-shipped-tool-rosters.zh.md: ab6982e33c4a0a25cbc2fde386456840ce99d9c5
+2026-07-31-even-out-shipped-tool-rosters.md: 7647506e5d9c39d64b686ab18923f9681a48cd87
+2026-07-31-even-out-shipped-tool-rosters.zh.md: f04a59c9f00455b00f70975ad9b6bd4defd3d847
@@ -12,11 +12,11 @@ The result was a user-visible difference nobody had decided: the same model, ask

 ## Decision

-The rows that are not surface-specific move into [`base.cordis.yml`](../../../../packages/bundle/base/cordis.patch.yml), and three more join them: `tool-session-query`, `tool-str-replace-editor`, and `repeat-tool-guard`. Web search moves there too; its [deployment decision](2026-07-31-web-default-search.md) owns the security boundary while the shared base owns its surface-neutral mount. Both surfaces assemble the same roster: twenty-two tools on every host — the twenty shared rows plus `glob` and `grep`, which are fixed members because `dsh-tool-fs-search` spawns the [packaged ripgrep binary](../architecture/2026-08-01-packaged-ripgrep-search.md). `tool-session-query` joined and then left again — the [session-search-not-shipped-default decision](2026-08-02-session-search-not-shipped-default.md) keeps the model-facing consumer opt-in — while the rest of this roster stands.
+The rows that are not surface-specific move into [`base.cordis.yml`](../../../../packages/bundle/base/cordis.patch.yml), and three more join them: `tool-session-query`, `tool-str-replace-editor`, and `repeat-tool-guard`. Web search moves there too; its [deployment decision](2026-07-31-web-default-search.md) owns the security boundary while the shared base owns its surface-neutral mount. Both surfaces assemble the same roster, including fixed `glob` and `grep` members because `dsh-tool-fs-search` spawns the [packaged ripgrep binary](../architecture/2026-08-01-packaged-ripgrep-search.md). Two later decisions narrow that roster: the [session-search decision](2026-08-02-session-search-not-shipped-default.md) keeps `tool-session-query` opt-in, and the [single-editor decision](../simplification/2026-08-10-default-presets-single-editor.md) keeps `tool-str-replace-editor` out of the general-purpose presets while retaining it in `minimal`.

 Two rows stay surface-specific. `tmux-context` is TUI-only because a browser surface has no terminal multiplexer to describe. `session-reference` is TUI-only because it drives the shared session-query index from the launcher's process-local path, and the browser sidebar reconciles that index on its own first search.

-**This roster decision added only at the time.** No tool row was removed from either surface when it landed, and a catalog comparison found additions and nothing else. One of those additions, `tool-session-query`, was subsequently removed by the [session-search-not-shipped-default decision](2026-08-02-session-search-not-shipped-default.md). The shared executors, sandbox composition, and access default are owned independently by the [workspace-write default decision](2026-07-31-workspace-write-surface-default.md).
+**This roster decision added only at the time.** No tool row was removed from either surface when it landed, and a catalog comparison found additions and nothing else. The later session-search and single-editor decisions own their respective default-roster exceptions. The shared executors, sandbox composition, and access default are owned independently by the [workspace-write default decision](2026-07-31-workspace-write-surface-default.md).

 ### What stays unmounted, and why

@@ -12,11 +12,11 @@ Status: implemented

 ## 决策

-那些并非 surface 专属的行移入 [`base.cordis.yml`](../../../../packages/bundle/base/cordis.patch.yml)，另有三行加入：`tool-session-query`、`tool-str-replace-editor` 和 `repeat-tool-guard`。Web 搜索也一并移入；其[部署决策](2026-07-31-web-default-search.md)负责安全边界，共享 base 则负责与 surface 无关的挂载。两个 surface 组装同一份清单：每台宿主上都有二十二个工具——二十个共享行加上 `glob` 和 `grep`，它们成为固定成员，因为 `dsh-tool-fs-search` 直接 spawn [打包的 ripgrep 二进制](../architecture/2026-08-01-packaged-ripgrep-search.md)。`tool-session-query` 加入后又退出了——[session-search-not-shipped-default 决策](2026-08-02-session-search-not-shipped-default.md)让面向模型的消费方保持需显式启用——而这份清单的其余部分保持不变。
+那些并非 surface 专属的行移入 [`base.cordis.yml`](../../../../packages/bundle/base/cordis.patch.yml)，另有三行加入：`tool-session-query`、`tool-str-replace-editor` 和 `repeat-tool-guard`。Web 搜索也一并移入；其[部署决策](2026-07-31-web-default-search.md)负责安全边界，共享 base 则负责与 surface 无关的挂载。两个 surface 组装同一份清单，其中 `glob` 和 `grep` 是固定成员，因为 `dsh-tool-fs-search` 直接 spawn [打包的 ripgrep 二进制](../architecture/2026-08-01-packaged-ripgrep-search.md)。之后有两项决策收窄这份清单：[session-search 决策](2026-08-02-session-search-not-shipped-default.md)让 `tool-session-query` 保持需显式启用，[单一编辑器决策](../simplification/2026-08-10-default-presets-single-editor.md)让通用 preset 不提供 `tool-str-replace-editor`，但在 `minimal` 中保留它。

 有两行仍是 surface 专属。`tmux-context` 只在 TUI，因为浏览器 surface 没有终端复用器可描述。`session-reference` 只在 TUI，因为它以 launcher 的进程本地路径驱动共享的 session-query 索引，而浏览器侧边栏会在自己的首次搜索里重建该索引。

-**本次工具清单决策当时只做加法。** 落地时两个 surface 均未移除任何工具行，目录对比只发现了新增，别无其他。这些新增中的一项 `tool-session-query` 随后被[session-search-not-shipped-default 决策](2026-08-02-session-search-not-shipped-default.md)移除。共享执行器、沙箱组合与访问默认值独立归属[workspace-write 默认值决策](2026-07-31-workspace-write-surface-default.md)。
+**本次工具清单决策当时只做加法。** 落地时两个 surface 均未移除任何工具行，目录对比只发现了新增，别无其他。后续的 session-search 与单一编辑器决策分别负责对应的默认清单例外。共享执行器、沙箱组合与访问默认值独立归属[workspace-write 默认值决策](2026-07-31-workspace-write-surface-default.md)。

 ### 什么保持不挂，以及为什么

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-02-session-search-not-shipped-default.md
-2026-08-02-session-search-not-shipped-default.md: 65bd72fff76210b726e7562fb8e88e5f8802434a
-2026-08-02-session-search-not-shipped-default.zh.md: 4eb0851c1e584b84847b6bb5118c8bb2f3156845
+2026-08-02-session-search-not-shipped-default.md: c1bfd7f8e354a4480c5635619514fe782ea71d2c
+2026-08-02-session-search-not-shipped-default.zh.md: 9b80c549425c26055700480dd57f1a0a7d01e4a8
@@ -10,7 +10,7 @@ The [shipped-roster decision](2026-07-31-even-out-shipped-tool-rosters.md) made

 ## Decision

-The shipped TUI, Web, and headless surfaces no longer mount `@deepseek-ai/dsh-tool-session-query`: the row is removed from the shared `cordis.patch.yml`, the now-dangling `disabled` patch in the opt-in [`core-web.cordis.yml`](../../../../apps/cli/config/core-web.cordis.yml) profile goes with it, and the workspace dependency drops from `apps/cli/package.json`. The consumer stays opt-in exactly as the model-facing-session-query-tools note describes: the ACP example's [`session-query.cordis.yml`](../../../../examples/acp-agent/session-query.cordis.yml) and its snapshot counterpart remain the mounted reference, and a custom composition can mount the package with the timeout and spill policies.
+The shipped TUI, Web, and headless surfaces do not mount `@deepseek-ai/dsh-tool-session-query`, and no shipped agent preset carries it. The consumer stays opt-in exactly as the model-facing-session-query-tools note describes: the ACP example's [`session-query.cordis.yml`](../../../../examples/acp-agent/session-query.cordis.yml) and its snapshot counterpart remain the mounted reference, and a custom composition can mount the package with the timeout and spill policies.

 The `ctx.sessionQuery` service itself stays mounted. `session-query-sqlite` remains a base row — the TUI's `session-reference` consumes it for `/resume` — and the Web overlay keeps patching it to an in-memory index for the browser content search. Only the model-facing consumer is removed.

@@ -10,7 +10,7 @@ Status: implemented

 ## 决策

-交付的 TUI、Web 与无头 surface 不再挂载 `@deepseek-ai/dsh-tool-session-query`：该行从共享的 `cordis.patch.yml` 移除，opt-in 的 [`core-web.cordis.yml`](../../../../apps/cli/config/core-web.cordis.yml) profile 中那条已悬空的 `disabled` patch 也随之删除，workspace 依赖也从 `apps/cli/package.json` 中移除。该消费方仍保持 opt-in，与面向模型的会话查询工具决策所述完全一致：ACP（Agent Client Protocol）示例的 [`session-query.cordis.yml`](../../../../examples/acp-agent/session-query.cordis.yml) 及其快照对侧文件仍是挂载参考，自定义组合也可以连同超时与 spill 策略一起挂载该包。
+交付的 TUI、Web 与无头 surface 均不挂载 `@deepseek-ai/dsh-tool-session-query`，交付的 agent preset 也都不包含它。该消费方仍保持 opt-in，与面向模型的会话查询工具决策所述完全一致：ACP（Agent Client Protocol）示例的 [`session-query.cordis.yml`](../../../../examples/acp-agent/session-query.cordis.yml) 及其快照对侧文件仍是挂载参考，自定义组合也可以连同超时与 spill 策略一起挂载该包。

 `ctx.sessionQuery` 服务本身保持挂载。`session-query-sqlite` 仍是 base 的一行，TUI 的 `session-reference` 消费它来实现 `/resume`，Web overlay 也继续把它 patch 成内存索引，供浏览器内容搜索使用。被移除的只有面向模型的消费方。

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-08-10-default-presets-single-editor.md
+2026-08-10-default-presets-single-editor.md: 82f254079080aeb88d76f4e7cc2c7ab195646ec4
+2026-08-10-default-presets-single-editor.zh.md: 22bbc19feadfb71fe3a9480bc60b8777e1fb50c2
@@ -0,0 +1,25 @@
+# Agent Note: One editor family in general-purpose presets
+
+Status: implemented
+
+English | [中文](2026-08-10-default-presets-single-editor.zh.md)
+
+## Problem
+
+The `standard`, `code`, and `cordis` presets exposed both the `read`/`write`/`edit` filesystem tools and `str_replace_editor`. The two interfaces overlap for ordinary file inspection and editing, so every request carried an additional tool schema without adding a distinct default capability. The `minimal` preset has a different composition contract: its exact two-tool roster intentionally includes `str_replace_editor` beside persistent `bash`.
+
+## Decision
+
+The `standard`, `code`, and `cordis` preset configurations mount `dsh-tool-fs` and `dsh-tool-fs-search`, but do not mount `dsh-tool-str-replace-editor`. Code Mode therefore omits `str_replace_editor` from both its registry and generated SDK. The `minimal` preset continues to mount `dsh-tool-str-replace-editor`, and deployments or user-authored presets may still mount the plugin explicitly.
+
+This decision narrows the preset roster rather than removing the tool package or its Python runtime support. The earlier [shared-roster decision](../feature/2026-07-31-even-out-shipped-tool-rosters.md) continues to own why surface-neutral tools live in preset composition; this note owns the editor exception.
+
+## Alternatives considered
+
+**Keep both editing interfaces in the general-purpose presets.** Rejected because the overlapping model-visible schemas increase tool choice without supplying a separate default operation.
+
+**Remove `str_replace_editor` from every shipped composition.** Rejected because the `minimal` preset intentionally exposes that schema as one of its two tools, and explicit deployments remain valid consumers of the standalone plugin.
+
+## Consequences
+
+General-purpose agents use `read`, `write`, and `edit` for filesystem mutations, while the minimal agent retains `str_replace_editor`. Preset composition tests pin its absence from the standard roster, the Cordis roster, and the Code Mode SDK, while the minimal assertions continue to pin its presence.
@@ -0,0 +1,25 @@
+# Agent Note: 通用 preset 只提供一套编辑工具
+
+Status: implemented
+
+[English](2026-08-10-default-presets-single-editor.md) | 中文
+
+## 问题
+
+`standard`、`code` 和 `cordis` preset 同时提供 `read`/`write`/`edit` 文件系统工具与 `str_replace_editor`。两套接口在常规文件查看和编辑上重叠，导致每次请求都携带额外的工具 schema，却没有增加独立的默认能力。`minimal` preset 具有不同的组合约定：它固定的双工具清单有意在持久 `bash` 之外提供 `str_replace_editor`。
+
+## 决策
+
+`standard`、`code` 和 `cordis` preset 配置挂载 `dsh-tool-fs` 与 `dsh-tool-fs-search`，但不挂载 `dsh-tool-str-replace-editor`。因此 Code Mode 的注册表和生成的 SDK 均不包含 `str_replace_editor`。`minimal` preset 继续挂载 `dsh-tool-str-replace-editor`，部署配置或用户自定义 preset 仍可显式挂载该插件。
+
+此决策收窄 preset 工具清单，不移除工具包及其 Python 运行时支持。较早的[共享清单决策](../feature/2026-07-31-even-out-shipped-tool-rosters.md)继续说明与 surface 无关的工具为何归 preset 组合所有；本记录说明编辑器例外。
+
+## 曾考虑的替代方案
+
+**在通用 preset 中保留两套编辑接口。** 不予采用，因为重叠的模型可见 schema 增加了工具选择，却没有提供不同的默认操作。
+
+**从所有交付组合中移除 `str_replace_editor`。** 不予采用，因为 `minimal` preset 有意将该 schema 作为两个工具之一，显式部署仍是该独立插件的有效消费方。
+
+## 后果
+
+通用 agent 使用 `read`、`write` 和 `edit` 完成文件系统修改，minimal agent 保留 `str_replace_editor`。preset 组合测试固定其不会出现在 standard 清单、Cordis 清单及 Code Mode SDK 中，同时 minimal 断言继续固定其存在。
@@ -92,7 +92,7 @@ jobs:

  sdk-wheel:
    needs: plan
-    name: deepseek_harness-${{ needs.plan.outputs.version }}-py3-none-any.whl
+    name: deepseek_harness_sdk-${{ needs.plan.outputs.version }}-py3-none-any.whl
    runs-on: ubuntu-latest
    timeout-minutes: 5
    steps:
@@ -113,8 +113,8 @@ jobs:

      - uses: actions/upload-artifact@v7
        with:
-          name: deepseek_harness-${{ needs.plan.outputs.version }}-py3-none-any.whl
-          path: dist-python/deepseek_harness-${{ needs.plan.outputs.version }}-py3-none-any.whl
+          name: deepseek_harness_sdk-${{ needs.plan.outputs.version }}-py3-none-any.whl
+          path: dist-python/deepseek_harness_sdk-${{ needs.plan.outputs.version }}-py3-none-any.whl
          if-no-files-found: error

  build:
@@ -197,7 +197,7 @@ jobs:

      - uses: actions/download-artifact@v8
        with:
-          name: deepseek_harness-${{ needs.plan.outputs.version }}-py3-none-any.whl
+          name: deepseek_harness_sdk-${{ needs.plan.outputs.version }}-py3-none-any.whl
          path: dist-python

      - name: Install only the SDK into a clean venv and run zero-config
@@ -208,7 +208,7 @@ jobs:
          python -m venv "$RUNNER_TEMP/dsh-sdk-smoke"
          "$RUNNER_TEMP/dsh-sdk-smoke/bin/python" -m pip install \
            --find-links dist-python \
-            deepseek-harness=="$VERSION"
+            deepseek-harness-sdk=="$VERSION"
          "$RUNNER_TEMP/dsh-sdk-smoke/bin/python" scripts/smoke-python-runtime.py \
            --scenario sdk-default

@@ -238,7 +238,7 @@ jobs:
          esac
          docker run --rm -e VERSION -v "$PWD:/work" -w /work "$image" bash -euxo pipefail -c '
            /opt/python/cp310-cp310/bin/python -m venv /tmp/dsh-sdk
-            /tmp/dsh-sdk/bin/python -m pip install --find-links /work/dist-python deepseek-harness=="$VERSION"
+            /tmp/dsh-sdk/bin/python -m pip install --find-links /work/dist-python deepseek-harness-sdk=="$VERSION"
            /tmp/dsh-sdk/bin/python /work/scripts/smoke-python-runtime.py --scenario sdk-default
          '

@@ -42,7 +42,7 @@ sdk-wheel:
    - uv run --python 3.10 --group test --project python/sdk python scripts/smoke-python-runtime.py --scenario all --exe "$EXE"
    - python scripts/build-python-release.py --package runtime --tag "$CI_COMMIT_TAG" --platform "$PLATFORM" --runtime-exe "$EXE" --output-dir "release/$PLATFORM"
    - python -m venv .wheel-smoke
-    - .wheel-smoke/bin/python -m pip install --find-links "release/$PLATFORM" --find-links release/sdk deepseek-harness=="$DSH_VERSION"
+    - .wheel-smoke/bin/python -m pip install --find-links "release/$PLATFORM" --find-links release/sdk deepseek-harness-sdk=="$DSH_VERSION"
    - .wheel-smoke/bin/python scripts/smoke-python-runtime.py --scenario sdk-default
    - |
      if [ "${PLATFORM#linux-}" != "$PLATFORM" ]; then
@@ -55,7 +55,7 @@ sdk-wheel:
          linux-arm64) image=quay.io/pypa/manylinux_2_28_aarch64 ;;
          *) echo "Unsupported Linux platform $PLATFORM"; exit 1 ;;
        esac
-        docker run --rm -v "$PWD:/work" -w /work "$image" bash -euxo pipefail -c "/opt/python/cp310-cp310/bin/python -m venv /tmp/dsh-sdk && /tmp/dsh-sdk/bin/python -m pip install --find-links /work/release/$PLATFORM --find-links /work/release/sdk deepseek-harness==$DSH_VERSION && /tmp/dsh-sdk/bin/python /work/scripts/smoke-python-runtime.py --scenario sdk-default"
+        docker run --rm -v "$PWD:/work" -w /work "$image" bash -euxo pipefail -c "/opt/python/cp310-cp310/bin/python -m venv /tmp/dsh-sdk && /tmp/dsh-sdk/bin/python -m pip install --find-links /work/release/$PLATFORM --find-links /work/release/sdk deepseek-harness-sdk==$DSH_VERSION && /tmp/dsh-sdk/bin/python /work/scripts/smoke-python-runtime.py --scenario sdk-default"
      fi
  artifacts:
    paths: [release/$PLATFORM/*.whl]
@@ -112,7 +112,7 @@ publish-python:
    - python -m pip install twine==6.2.0
  script:
    - test "$(find release -name '*.whl' | wc -l | tr -d ' ')" = 4
-    - test -f "release/sdk/deepseek_harness-${DSH_VERSION}-py3-none-any.whl"
+    - test -f "release/sdk/deepseek_harness_sdk-${DSH_VERSION}-py3-none-any.whl"
    - test -f "release/linux-x64/deepseek_harness_runtime_bin-${DSH_VERSION}-py3-none-manylinux_2_28_x86_64.whl"
    - test -f "release/linux-arm64/deepseek_harness_runtime_bin-${DSH_VERSION}-py3-none-manylinux_2_28_aarch64.whl"
    - test -f "release/macos-arm64/deepseek_harness_runtime_bin-${DSH_VERSION}-py3-none-macosx_11_0_arm64.whl"
@@ -180,7 +180,7 @@ Direct dependencies of the `pyproject.toml` manifests, plus `uv` as the developm
 | Package | License | Role |
 | --- | --- | --- |
 | [`hatchling`](https://github.com/pypa/hatch) | MIT | build backend |
-| [`pydantic`](https://github.com/pydantic/pydantic) | MIT | runtime dependency of `deepseek-harness` |
+| [`pydantic`](https://github.com/pydantic/pydantic) | MIT | runtime dependency of `deepseek-harness-sdk` |
 | [`pytest`](https://github.com/pytest-dev/pytest) | MIT | test-only |
 | [`uv`](https://github.com/astral-sh/uv) | MIT / Apache-2.0 | development workflow tool |

@@ -53,7 +53,7 @@

 # ── filesystem ──────────────────────────────────────────────────────────────

-# All three register into the host `tools` registry and provide nothing, so
+# Both register into the host `tools` registry and provide nothing, so
 # they need no realm. The `fs` service and its policy stay in the host.
 - id: tool-fs
  name: '@deepseek-ai/dsh-tool-fs'
@@ -63,11 +63,6 @@
  config:
    sampleOverCapGlobResults: false

- id: tool-str-replace-editor
-  name: '@deepseek-ai/dsh-tool-str-replace-editor'
-  config:
-    maxOutputChars: 16000
-
 # ── background tasks ────────────────────────────────────────────────────────

 # Only the model-facing controls. The task REGISTRY stays on the host plane:
@@ -47,7 +47,7 @@

 # ── filesystem ──────────────────────────────────────────────────────────────

-# All three register into the host `tools` registry and provide nothing, so
+# Both register into the host `tools` registry and provide nothing, so
 # they need no realm. The `fs` service and its policy stay in the host.
 - id: tool-fs
  name: '@deepseek-ai/dsh-tool-fs'
@@ -57,11 +57,6 @@
  config:
    sampleOverCapGlobResults: false

- id: tool-str-replace-editor
-  name: '@deepseek-ai/dsh-tool-str-replace-editor'
-  config:
-    maxOutputChars: 16000
-
 # ── background tasks ────────────────────────────────────────────────────────

 # Only the model-facing controls. The task REGISTRY stays on the host plane:
@@ -1,39 +1,70 @@
-# The `minimal` agent preset: the two-tool benchmark surface.
+# The `minimal` agent preset: a fixed-prompt, two-tool coding surface.
 #
-# The native model surface is exactly persistent `bash` plus
-# `str_replace_editor`. Everything else a session could reach — skills, goals,
-# plan mode, delegation, workflows, todo, web — is simply absent rather than
-# disabled, because a preset composes what an agent has instead of subtracting
-# from a shared default.
-#
-# The host composition is unchanged: this agent still runs inside the same
-# sandbox, approval, persistence, and model routing as any other session.
+# The persona is the complete system prompt, so global identity, Web surface,
+# tool guidance, and later assembly listeners cannot add prompt text. The model
+# composes only the persistent `bash` and `str_replace_editor` tools.

 - id: persona
  name: '@deepseek-ai/dsh-persona'
  config:
-    text: >-
-      You are a coding agent powered by the {{model}} model. Your working directory is {{cwd}}.
+    text: You are a helpful software engineer assistant.
+    complete: true

-# `bash-env` stays in the HOST composition: `apps/cli/src/web.ts` injects it to
-# publish `DSH_WEB_URL`/`DSH_WEB_MODE`, and a host row that injects a service is
-# the criterion for host-plane ownership — injection resolves before any session
-# exists, so there is no agent to key by. Behind a preset realm those variables
-# never reached the model's shell at all. `tool-bash` consumes the host registry
-# from here; the executor behind it (`bash-sandbox`) is host-plane too, where the
-# sandbox policy owns it.
-#
-# `run_in_background` is off because this preset mounts no `tool-tasks`. The
-# host registry already refuses a start for an owner no attached control
-# surface serves, so this is not the safety boundary — it is the model-facing
-# one: an agent that could never collect a task should not be offered the
-# parameter at all, and disabling it drops the parameter from the schema.
- id: tool-bash
-  name: '@deepseek-ai/dsh-tool-bash'
+# The PTY registry is an agent-owned service, so it lives in an entry-local
+# realm. The backend still consumes the host sandbox policy and subprocess
+# implementation, while the tool registers into this agent's scoped catalog.
+- id: persistent-shell
+  name: cordis:group
+  group: true
+  isolate:
+    pty: true
  config:
-    enableRunInBackground: false
+    - id: pty
+      name: '@deepseek-ai/dsh-pty'

- id: tool-str-replace-editor
+    - id: pty-local
+      name: '@deepseek-ai/dsh-pty-local'
+      config:
+        timeoutMs: 300000
+
+    - id: persistent-bash
+      name: '@deepseek-ai/dsh-tool-bash-persistent'
+      config:
+        timeoutMs: 300000
+        description: |-
+          Run commands in a bash shell
+          * When invoking this tool, the contents of the "command" parameter does NOT need to be XML-escaped.
+          * You don't have access to the internet via this tool.
+          * You do have access to a mirror of common linux and python packages via apt and pip.
+          * 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.
+
+# The editor requires absolute paths unconditionally.
+- id: str-replace-editor
  name: '@deepseek-ai/dsh-tool-str-replace-editor'
  config:
    maxOutputChars: 16000
+
+# Model capacity comes from routed model metadata; this block states the
+# compaction policy explicitly.
+- id: compaction
+  name: cordis:group
+  group: true
+  isolate:
+    tokenMeter: true
+    compact: true
+  config:
+    - id: token-meter
+      name: '@deepseek-ai/dsh-token-meter'
+
+    - id: compact-basic
+      name: '@deepseek-ai/dsh-compact-basic'
+      config:
+        thresholdRatio: 0.8
+        retainTokens: 20480
+        summarizationProvider: ''
+        summarizationModel: ''
+        maxTokens: 8192
+        compactionRetries: 1
@@ -1,3 +1,3 @@
 name: 极简模式
-description: 仅提供 bash 与 str_replace_editor 的双工具编码 Agent，用于基准测试和最小复现。
+description: 仅提供持久 bash 与 str_replace_editor 的双工具编码 Agent。
 order: 3
@@ -46,7 +46,7 @@

 # ── filesystem ──────────────────────────────────────────────────────────────

-# All three register into the host `tools` registry and provide nothing, so
+# Both register into the host `tools` registry and provide nothing, so
 # they need no realm. The `fs` service and its policy stay in the host.
 - id: tool-fs
  name: '@deepseek-ai/dsh-tool-fs'
@@ -56,11 +56,6 @@
  config:
    sampleOverCapGlobResults: false

- id: tool-str-replace-editor
-  name: '@deepseek-ai/dsh-tool-str-replace-editor'
-  config:
-    maxOutputChars: 16000
-
 # ── background tasks ────────────────────────────────────────────────────────

 # Only the model-facing controls. The task REGISTRY stays on the host plane:
@@ -1,113 +0,0 @@
-# Opt-in Web shell for the RL core agent contract. The model receives exactly
-# the configured persona plus the native `bash` and `str_replace_editor`
-# schemas; the Web host, browser shell, persistence, and permission stack stay.
-
-# Match the Claude SWE-compatible RL core prompt. Disabling the Web runtime's
-# surface context removes its GUI orientation, managed shell variables, and the
-# launcher's source-checkout section through one configuration contract.
-# Workspace instructions are model-visible user context rather than a system
-# section, but RL core disables them as part of the same prompt contract.
- id: system-prompt
-  config:
-    includeHarnessIdentity: false
-    persona: !!js process.env.DSH_SYSTEM_PROMPT ?? 'You are a helpful software engineer assistant.'
-
- id: web-runtime
-  config:
-    surfaceContext: false
-
- id: workspace-context
-  disabled: true
-
- id: tools
-  config:
-    mode: native
-
-# Disable every model-facing consumer in the base/Web tree. plan-mode owns the
-# always-registered exit_plan_mode tool even while the session is not planning.
- id: tool-bash
-  disabled: true
-
- id: tool-tasks
-  disabled: true
-
- id: tool-fs
-  disabled: true
-
- id: tool-fs-search
-  disabled: true
-
- id: tool-web
-  disabled: true
-
- id: tool-skill
-  disabled: true
-
- id: plan-mode
-  disabled: true
-
- id: tool-subagent-control
-  disabled: true
-
- id: tool-subagent-list-agents
-  disabled: true
-
- id: tool-subagent
-  disabled: true
-
- id: tool-subagent-fork
-  disabled: true
-
- id: tool-workflow
-  disabled: true
-
- id: tool-todo
-  disabled: true
-
-# These consumers are shared defaults on the ordinary shipped surfaces, but
-# this opt-in profile keeps exactly its two named tools.
- id: tool-goal
-  disabled: true
-
- id: tool-ralph
-  disabled: true
-
- id: tool-str-replace-editor
-  disabled: true
-
-# The matching browser controls must not offer surfaces whose tool this
-# overlay omits: the panels would render for a capability the model does not
-# have. Turning the row off no longer removes a tool — `ui-question`'s host
-# half is empty and `tool-ask-user` is composed per preset — so this is a UI
-# decision now, not a capability one.
- id: ui-plan
-  disabled: true
-
- id: ui-question
-  disabled: true
-
- insert:
-    - id: pty
-      name: '@deepseek-ai/dsh-pty'
-
-    # This backend consumes the existing Web sandbox and permission policy.
-    # It loads only on Linux/macOS; Windows and other platforms fail at boot.
-    # Its 300s send wait matches the persistent Bash command timeout instead of
-    # pty-local's 30s default. An open persistent shell fences permission-mode
-    # changes until it closes.
-    - id: pty-local
-      name: '@deepseek-ai/dsh-pty-local'
-      config:
-        timeoutMs: 300000
-
-    - id: persistent-bash
-      name: '@deepseek-ai/dsh-tool-bash-persistent'
-      config:
-        timeoutMs: 300000
-
-    # The editor consumes the Web fs-sandbox provider and therefore retains
-    # the selected session permission mode.
-    - id: str-replace-editor
-      name: '@deepseek-ai/dsh-tool-str-replace-editor'
-      config:
-        maxOutputChars: 16000
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write apps/cli/reference/README.md
-README.md: 7f0bd7b0bd50482b3ba7ee95adf6aaf1defb6d28
-README.zh.md: 55f23c5644b8b063ef12fb56fa587ff5d2eb21a2
+README.md: 756fed1f1802600e82948ce8ca808706b2299660
+README.zh.md: edd20c7fc3a3103097aa5e3949418e373172cadb
@@ -59,9 +59,7 @@ All modes treat the invoking directory as the default workspace root, load appli

 New sessions default to the `workspace-write` permission preset. Bash and filesystem mutations are restricted to the session workspace and platform temporary roots; reads, network access, and process visibility are not confined. `DSH_PERMISSION_MODE` changes the process fallback. Stored General-settings permissions affect later Web sessions, not an already-open one.

-`DSH_TOOLS_MODE` selects `native`, `code`, or `both` for the process; another value fails at boot. [`config/core-web.cordis.yml`](../config/core-web.cordis.yml) is an optional RL-compatible `--patch` overlay that pins native mode, renders only `DSH_SYSTEM_PROMPT` or `You are a helpful software engineer assistant.` as the system prompt, disables Workspace instructions and every Web runtime prompt contribution, and exposes only persistent `bash` and `str_replace_editor` while retaining the shipped host, browser, workspace, persistence, and permission composition.
-
-`DSH_SYSTEM_PROMPT` is passed as the system-prompt [`persona`](../../../packages/core/system-prompt/README.md#config): complete `{{…}}` groups use that contract's strict variable interpolation rules and have no literal-brace escape; any set value, including an empty string, is authoritative and an empty value therefore removes the system prompt, while only an unset variable selects the fallback.
+`DSH_TOOLS_MODE` selects `native`, `code`, 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 persistent `bash` plus `str_replace_editor`. 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

@@ -59,9 +59,7 @@ dsh web --dump-config

 新会话默认使用 `workspace-write` 权限预设。Bash 和文件系统修改仅限于会话 workspace 与平台临时根目录；读取、网络访问和进程可见性不受限制。`DSH_PERMISSION_MODE` 更改进程后备值。General settings 中存储的权限影响后续 Web 会话，不改变已打开的会话。

-`DSH_TOOLS_MODE` 为进程选择 `native`、`code` 或 `both`；其他值会导致启动失败。[`config/core-web.cordis.yml`](../config/core-web.cordis.yml) 是可选的 RL 兼容 `--patch` overlay：它固定使用 `native` 模式，仅将 `DSH_SYSTEM_PROMPT` 或 `You are a helpful software engineer assistant.` 渲染为系统提示词，禁用 Workspace 指令与所有 Web 运行时提示词贡献，并且在保留随附宿主、浏览器、workspace、持久化和权限组合的同时，仅暴露持久 `bash` 和 `str_replace_editor`。
-
-`DSH_SYSTEM_PROMPT` 会传给系统提示词的 [`persona`](../../../packages/core/system-prompt/README.md#config)：完整的 `{{…}}` 分组遵循该约定的严格变量插值规则，且无法转义为字面花括号；任何已设置的值（包括空字符串）都具有权威性，因此空值会移除系统提示词，只有未设置该变量时才会选择后备值。
+`DSH_TOOLS_MODE` 为进程选择 `native`、`code` 或 `both`；其他值会导致启动失败。随附的 `minimal` agent preset 会保留该部署的呈现方式，将完整系统提示词固定为 `You are a helpful software engineer assistant.`，并且仅组合持久 `bash` 和 `str_replace_editor`。创建 Web 会话时请选择极简模式；该 agent 不包含任何其他提示词段落或面向模型的插件，而共享的浏览器、workspace、持久化、沙箱与权限宿主保持不变。

 ## 共享部署行为

@@ -9,7 +9,6 @@ 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))
 const dshBin = join(repoRoot, 'apps/cli/lib/bin.js')
-const coreWebOverlay = fileURLToPath(new URL('../config/core-web.cordis.yml', import.meta.url))
 const invalidProvider = fileURLToPath(new URL('./fixtures/invalid-provider.cordis.yml', import.meta.url))

 async function runBuiltBin(
@@ -543,16 +542,5 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
      expect(stdout).toContain(`patched by ${profilePatch}, ${overlay}`)
      expect(stderr).toContain('patch: entry "absent-row" not found')
    }, 30_000)
-
-    it('shows the RL Web patch disabling runtime surface context', async () => {
-      const { stdout, code, stderr } = await runBuiltBin(
-        ['web', '--patch', coreWebOverlay, '--dump-config'],
-        { DSH_HOME: home },
-      )
-      expect(code).toBe(0)
-      expect(stderr).toBe('')
-      expect(stdout).toContain("name: '@deepseek-ai/dsh-web-app'")
-      expect(stdout).toContain('surfaceContext: false')
-    }, 30_000)
  })
 })
@@ -13,6 +13,7 @@ import { settingsNamespace } from '@deepseek-ai/dsh-settings'
 import { resolveSessionPreset, SETTINGS_NAMESPACE } from '@deepseek-ai/dsh-agent-presets'
 import { applyChildComposition, childSessionMeta } from '@deepseek-ai/dsh-subagent'
 import { CallId } from '@deepseek-ai/dsh-llm'
+import type { BasicCompactService } from '@deepseek-ai/dsh-compact-basic'
 import type {} from '@deepseek-ai/dsh-skill'
 import type {} from '@deepseek-ai/dsh-tools'

@@ -23,6 +24,15 @@ 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')
 /** 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.
+* You don't have access to the internet via this tool.
+* You do have access to a mirror of common linux and python packages via apt and pip.
+* 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,
@@ -135,7 +145,7 @@ describe('the shipped Web composition', () => {
      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', 'list_agents', 'ralph', 'read', 'send_message', 'skill',
-        'str_replace_editor', 'subagent', 'subagent_fork', 'task_kill',
+        'subagent', 'subagent_fork', 'task_kill',
        'task_list', 'task_output', 'todo_write', 'update_goal', 'web_search',
        'workflow', 'write',
      ])
@@ -144,14 +154,30 @@ describe('the shipped Web composition', () => {
    }
  })

-  it('composes exactly two tools from `minimal`', async () => {
+  it('composes the exact RL prompt and two tools from `minimal`', async () => {
    const handle = await ctx.agents.create({
      sessionId: SessionId('preset-minimal'),
      setup: agentCtx => ctx.agentPresets.mount(agentCtx, 'minimal').then(() => undefined),
    })
    try {
-      // Exactly what the preset lists — nothing arrives from the host.
-      expect(toolNames(ctx, handle.agent)).toEqual(['bash', 'str_replace_editor'])
+      const assembly = await ctx.systemPrompt.assemble({ scope: handle.agent })
+      expect(assembly.sections).toEqual([
+        { name: 'deployment:persona', text: MINIMAL_PROMPT },
+      ])
+      expect(assembly.tools.map(tool => tool.name)).toEqual(['bash', 'str_replace_editor'])
+      expect(assembly.tools.find(tool => tool.name === 'bash')?.description).toBe(MINIMAL_BASH_DESCRIPTION)
+      expect(JSON.stringify(assembly.tools.find(tool => tool.name === 'str_replace_editor')?.parameters))
+        .toContain('Absolute path')
+      const compact = ctx.agentPresets.serviceFor(handle.agent, 'compact')
+      expect(compact).toBeDefined()
+      expect((compact as BasicCompactService).config).toMatchObject({
+        thresholdRatio: 0.8,
+        retainTokens: 20480,
+        summarizationProvider: '',
+        summarizationModel: '',
+        maxTokens: 8192,
+        compactionRetries: 1,
+      })
    } finally {
      await handle.dispose()
    }
@@ -191,6 +217,7 @@ describe('the shipped Web composition', () => {
      expect(tools).toEqual(expect.arrayContaining(['cordis_inspect', 'cordis_mount', 'cordis_unmount']))
      // 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')

      // 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.
@@ -217,9 +244,9 @@ describe('the shipped Web composition', () => {
      // 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)).toContain('str_replace_editor')
+      expect(toolNames(ctx, coded.agent)).not.toContain('str_replace_editor')
      const sdk = assembly.sections.find(section => section.name === 'tools:sdk')?.text ?? ''
-      expect(sdk).toContain('str_replace_editor')
+      expect(sdk).not.toContain('str_replace_editor')
      expect(sdk).toContain('web_search')

      // The presentation is this agent's alone: the deployment default is
@@ -340,20 +367,6 @@ describe('the shipped Web composition', () => {

    expect(await readFile(path, 'utf8')).toBe(before)
  })
-
-  it('gives each session its own persona', async () => {
-    const handle = await ctx.agents.create({
-      sessionId: SessionId('preset-persona'),
-      setup: agentCtx => ctx.agentPresets.mount(agentCtx, 'minimal').then(() => undefined),
-    })
-    try {
-      const assembly = await ctx.systemPrompt.assemble({ scope: handle.agent })
-      expect(assembly.sections.find(section => section.name === 'deployment:persona')?.text)
-        .toContain('You are a coding agent powered by')
-    } finally {
-      await handle.dispose()
-    }
-  })
 })

 describe('a switch survives the session', () => {
@@ -161,7 +161,7 @@ describe('web e2e: agent-preset authoring is a host-side copy', () => {
    expect(composition).toBe(await readFile(join(SHIPPED_PRESETS, 'minimal', 'agent.cordis.yml'), 'utf8'))
    const metadata = await readFile(join(userRoot, 'my-agent', 'preset.yml'), 'utf8')
    expect(metadata).toContain('name: 我的模式')
-    expect(metadata).toContain('description: 仅提供 bash 与 str_replace_editor 的双工具编码 Agent，用于基准测试和最小复现。')
+    expect(metadata).toContain('description: 仅提供持久 bash 与 str_replace_editor 的双工具编码 Agent。')
    expect(metadata).not.toContain('order:')
  }, 60_000)

@@ -1,137 +0,0 @@
-import { writeFile } from 'node:fs/promises'
-import { join } from 'node:path'
-import { fileURLToPath } from 'node:url'
-import { afterAll, beforeAll, describe, expect, it } from 'vitest'
-import type { AgentHandle } from '@deepseek-ai/dsh-agent'
-import { CallId, createUserMessage } from '@deepseek-ai/dsh-llm'
-import { SessionId } from '@deepseek-ai/dsh-session'
-import { assertFixtureInventory, launchWebScaffold, type WebScaffold } from './scaffold.ts'
-
-const CORE_WEB_OVERLAY = fileURLToPath(new URL('../../cli/config/core-web.cordis.yml', import.meta.url))
-const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/core-web-profile', import.meta.url))
-const FIXTURE = join(SNAPSHOT_DIR, 'session.jsonl')
-const PROMPT = 'Reply exactly CORE_WEB_REQUEST_OK and stop.'
-
-describe('core Web profile', () => {
-  let scaffold: WebScaffold
-  let agentHandle: AgentHandle
-
-  beforeAll(async () => {
-    const systemPrompt = process.env.DSH_SYSTEM_PROMPT
-    Reflect.deleteProperty(process.env, 'DSH_SYSTEM_PROMPT')
-    try {
-      scaffold = await launchWebScaffold({ extraOverlayPath: CORE_WEB_OVERLAY, replayFixture: FIXTURE })
-    } finally {
-      if (systemPrompt !== undefined) process.env.DSH_SYSTEM_PROMPT = systemPrompt
-    }
-    agentHandle = await scaffold.ctx.agents.create({
-      sessionId: SessionId('core-web-profile-smoke'),
-      meta: { cwd: scaffold.workspaceCwd },
-      agentOptions: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-    })
-  })
-
-  afterAll(async () => {
-    const failures: unknown[] = []
-    await agentHandle?.dispose().catch((error: unknown) => failures.push(error))
-    await scaffold?.close().catch((error: unknown) => failures.push(error))
-    if (failures.length === 1) throw failures[0]
-    if (failures.length > 1) throw new AggregateError(failures, 'core Web profile smoke teardown failed')
-  })
-
-  it('sends the RL prompt and tool schemas through a real request, then executes both tools', async () => {
-    agentHandle.agent.followup(createUserMessage({
-      content: [{ type: 'text', text: PROMPT }],
-      source: { kind: 'user' },
-    }))
-    await agentHandle.agent.whenIdle()
-
-    const requestHeader = agentHandle.agent.session.requestHeader()
-    if (requestHeader === undefined) throw new Error('the core Web agent issued no model request')
-
-    const seedPath = join(scaffold.workspaceCwd, 'profile-smoke.txt')
-    await writeFile(seedPath, 'CORE_WEB_EDITOR_OK\n')
-    const signal = new AbortController().signal
-    const bash = await scaffold.ctx.tools.execute({
-      signal,
-      callId: CallId('core-web-bash-smoke'),
-      name: 'bash',
-      arguments: { command: "printf 'CORE_WEB_BASH_OK\\n'" },
-      agent: agentHandle.agent,
-    })
-    const editor = await scaffold.ctx.tools.execute({
-      signal,
-      callId: CallId('core-web-editor-smoke'),
-      name: 'str_replace_editor',
-      arguments: { command: 'view', path: seedPath },
-      agent: agentHandle.agent,
-    })
-
-    const text = (result: typeof bash): string => result.content
-      .filter(block => block.type === 'text')
-      .map(block => block.text)
-      .join('')
-      .replaceAll(scaffold.workspaceCwd, '{{cwd}}')
-      .trimEnd()
-
-    expect({
-      prompt: requestHeader.system,
-      tools: requestHeader.tools?.map(tool => tool.name),
-      bash: text(bash),
-      editor: text(editor),
-    }).toMatchInlineSnapshot(`
-      {
-        "bash": "CORE_WEB_BASH_OK",
-        "editor": "Here's the content of {{cwd}}/profile-smoke.txt with line numbers (which has a total of 2 lines):
-           1  CORE_WEB_EDITOR_OK
-           2",
-        "prompt": "You are a helpful software engineer assistant.",
-        "tools": [
-          "bash",
-          "str_replace_editor",
-        ],
-      }
-    `)
-    expect(requestHeader.tools).toEqual(scaffold.ctx.tools.schemas(agentHandle.agent))
-
-    const entries = [...scaffold.ctx.loader.entries()]
-    expect(entries.find(entry => entry.options.id === 'persistent-bash')?.fiber).toBeDefined()
-    expect(entries.find(entry => entry.options.id === 'pty-local')?.fiber).toBeDefined()
-    expect(entries.find(entry => entry.options.id === 'str-replace-editor')?.fiber).toBeDefined()
-    expect(entries.find(entry => entry.options.id === 'web-runtime')?.fiber).toBeDefined()
-    expect(entries.find(entry => entry.options.id === 'workspace-context')?.fiber).toBeUndefined()
-    await assertFixtureInventory(SNAPSHOT_DIR, ['session.jsonl'])
-  })
-
-  it('uses DSH_SYSTEM_PROMPT as the complete prompt when configured', async () => {
-    const previous = process.env.DSH_SYSTEM_PROMPT
-    process.env.DSH_SYSTEM_PROMPT = 'RL prompt override'
-    let overrideScaffold: WebScaffold | undefined
-    let overrideAgent: AgentHandle | undefined
-    try {
-      overrideScaffold = await launchWebScaffold({ extraOverlayPath: CORE_WEB_OVERLAY, replayFixture: FIXTURE })
-      overrideAgent = await overrideScaffold.ctx.agents.create({
-        sessionId: SessionId('core-web-profile-override'),
-        meta: { cwd: overrideScaffold.workspaceCwd },
-        agentOptions: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
-      })
-      overrideAgent.agent.followup(createUserMessage({
-        content: [{ type: 'text', text: PROMPT }],
-        source: { kind: 'user' },
-      }))
-      await overrideAgent.agent.whenIdle()
-      expect(overrideAgent.agent.session.requestHeader()?.system).toBe('RL prompt override')
-    } finally {
-      try {
-        await overrideAgent?.dispose()
-      } finally {
-        try {
-          await overrideScaffold?.close()
-        } finally {
-          if (previous === undefined) Reflect.deleteProperty(process.env, 'DSH_SYSTEM_PROMPT')
-          else process.env.DSH_SYSTEM_PROMPT = previous
-        }
-      }
-    }
-  })
-})
@@ -0,0 +1,115 @@
+import { mkdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import type { AgentHandle } from '@deepseek-ai/dsh-agent'
+import { CallId, createUserMessage } from '@deepseek-ai/dsh-llm'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-agent-presets'
+import type {} from '@deepseek-ai/dsh-system-prompt'
+import { assertFixtureInventory, launchWebScaffold, type WebScaffold } from './scaffold.ts'
+
+const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/minimal-preset', import.meta.url))
+const FIXTURE = join(SNAPSHOT_DIR, 'session.jsonl')
+const PROMPT = 'Reply exactly MINIMAL_PRESET_REQUEST_OK and stop.'
+
+describe('minimal agent preset', () => {
+  let scaffold: WebScaffold
+  let agentHandle: AgentHandle
+  let disposeInjectedPrompt: () => void
+
+  beforeAll(async () => {
+    scaffold = await launchWebScaffold({ replayFixture: FIXTURE })
+    disposeInjectedPrompt = scaffold.ctx.systemPrompt.section({
+      name: 'test:injected-prompt',
+      order: 999,
+      text: 'THIS TEXT MUST NOT REACH THE MODEL.',
+    })
+    agentHandle = await scaffold.ctx.agents.create({
+      sessionId: SessionId('minimal-preset-smoke'),
+      meta: { cwd: scaffold.workspaceCwd, agentPreset: 'minimal' },
+      agentOptions: { provider: 'deepseek-official', model: 'deepseek-v4-flash' },
+      setup: agentCtx => scaffold.ctx.agentPresets.mount(agentCtx, 'minimal').then(() => undefined),
+    })
+  })
+
+  afterAll(async () => {
+    const failures: unknown[] = []
+    await agentHandle?.dispose().catch((error: unknown) => failures.push(error))
+    try {
+      disposeInjectedPrompt?.()
+    } catch (error: unknown) {
+      failures.push(error)
+    }
+    await scaffold?.close().catch((error: unknown) => failures.push(error))
+    if (failures.length === 1) throw failures[0]
+    if (failures.length > 1) throw new AggregateError(failures, 'minimal preset smoke teardown failed')
+  })
+
+  it('sends the exact RL prompt and schemas, then executes the persistent shell and editor', async () => {
+    agentHandle.agent.followup(createUserMessage({
+      content: [{ type: 'text', text: PROMPT }],
+      source: { kind: 'user' },
+    }))
+    await agentHandle.agent.whenIdle()
+
+    const requestHeader = agentHandle.agent.session.requestHeader()
+    if (requestHeader === undefined) throw new Error('the minimal agent issued no model request')
+
+    const stateDir = join(scaffold.workspaceCwd, 'persistent-state')
+    await mkdir(stateDir)
+    const signal = new AbortController().signal
+    await scaffold.ctx.tools.execute({
+      signal,
+      callId: CallId('minimal-bash-state-setup'),
+      name: 'bash',
+      arguments: { command: `cd ${JSON.stringify(stateDir)} && export DSH_MINIMAL_STATE=PERSISTED` },
+      agent: agentHandle.agent,
+    })
+    const bash = await scaffold.ctx.tools.execute({
+      signal,
+      callId: CallId('minimal-bash-state-read'),
+      name: 'bash',
+      arguments: { command: 'printf \'%s:%s\n\' "$DSH_MINIMAL_STATE" "$PWD"' },
+      agent: agentHandle.agent,
+    })
+    const seedPath = join(scaffold.workspaceCwd, 'preset-smoke.txt')
+    await writeFile(seedPath, 'MINIMAL_EDITOR_OK\n')
+    const editor = await scaffold.ctx.tools.execute({
+      signal,
+      callId: CallId('minimal-editor-smoke'),
+      name: 'str_replace_editor',
+      arguments: { command: 'view', path: seedPath },
+      agent: agentHandle.agent,
+    })
+
+    const text = (result: typeof bash): string => result.content
+      .filter(block => block.type === 'text')
+      .map(block => block.text)
+      .join('')
+      .replaceAll(scaffold.workspaceCwd, '{{cwd}}')
+      .trimEnd()
+
+    expect({
+      prompt: requestHeader.system,
+      tools: requestHeader.tools?.map(tool => tool.name),
+      bash: text(bash),
+      editor: text(editor),
+    }).toMatchInlineSnapshot(`
+      {
+        "bash": "PERSISTED:{{cwd}}/persistent-state",
+        "editor": "Here's the content of {{cwd}}/preset-smoke.txt with line numbers (which has a total of 2 lines):
+           1  MINIMAL_EDITOR_OK
+           2",
+        "prompt": "You are a helpful software engineer assistant.",
+        "tools": [
+          "bash",
+          "str_replace_editor",
+        ],
+      }
+    `)
+    expect(requestHeader.tools?.toSorted((left, right) => left.name.localeCompare(right.name)))
+      .toEqual(scaffold.ctx.tools.schemas(agentHandle.agent).toSorted((left, right) => left.name.localeCompare(right.name)))
+    await assertFixtureInventory(SNAPSHOT_DIR, ['session.jsonl'])
+  })
+})
@@ -38,7 +38,6 @@ const EXPECTED_TOOLS = [
  'read',
  'send_message',
  'skill',
-  'str_replace_editor',
  'subagent',
  'subagent_fork',
  'task_kill',
@@ -40,7 +40,7 @@
        - text: 复制
    - listitem:
      - 'button "设为默认: 极简模式"':
-        - text: 极简模式 内置 仅提供 bash 与 str_replace_editor 的双工具编码 Agent，用于基准测试和最小复现。
+        - text: 极简模式 内置 仅提供持久 bash 与 str_replace_editor 的双工具编码 Agent。
        - code: minimal
      - 'button "查看: 极简模式"':
        - img
@@ -62,7 +62,7 @@
  - list:
    - listitem:
      - 'button "设为默认: 我的模式"':
-        - text: 我的模式 自定义 仅提供 bash 与 str_replace_editor 的双工具编码 Agent，用于基准测试和最小复现。
+        - text: 我的模式 自定义 仅提供持久 bash 与 str_replace_editor 的双工具编码 Agent。
        - code: my-agent
      - 'button "查看路径: 我的模式"':
        - img
@@ -40,7 +40,7 @@
        - text: 复制
    - listitem:
      - 'button "设为默认: 极简模式"':
-        - text: 极简模式 内置 仅提供 bash 与 str_replace_editor 的双工具编码 Agent，用于基准测试和最小复现。
+        - text: 极简模式 内置 仅提供持久 bash 与 str_replace_editor 的双工具编码 Agent。
        - code: minimal
      - 'button "查看: 极简模式"':
        - img
@@ -40,7 +40,7 @@
        - text: 复制
    - listitem:
      - 'button "设为默认: 极简模式"':
-        - text: 极简模式 内置 仅提供 bash 与 str_replace_editor 的双工具编码 Agent，用于基准测试和最小复现。
+        - text: 极简模式 内置 仅提供持久 bash 与 str_replace_editor 的双工具编码 Agent。
        - code: minimal
      - 'button "查看: 极简模式"':
        - img
@@ -3,5 +3,5 @@
    - text: Standard mode Full coding agent with file editing, shell, file and web search, skills, planning, goals, subagents, and workflows.
    - img
  - menuitem "Code mode All Standard mode capabilities, with tools exposed through the Code Mode SDK so the model can combine multi-step operations in one TypeScript program."
-  - menuitem "Minimal mode Two-tool coding agent with only bash and str_replace_editor, for benchmarks and minimal reproductions."
+  - menuitem "Minimal mode Two-tool coding agent with persistent bash and str_replace_editor."
  - menuitem "Creator mode Built for creating custom agent presets, with all Standard mode capabilities plus runtime inspection, plugin experiments, and preset-authoring guidance."
@@ -1,7 +1,7 @@
-{"type":"session","version":0,"id":"{{sessionId}}","createdAt":1785974400000,"cwd":"{{cwd}}"}
-{"type":"user/message","seq":0,"time":1785974400001,"data":{"content":[{"type":"text","text":"Reply exactly CORE_WEB_REQUEST_OK and stop."}],"source":{"kind":"user","rpcId":"{{rpcId}}"}},"surfaceOp":"append"}
+{"type":"session","version":0,"id":"{{sessionId}}","createdAt":1785974400000,"cwd":"{{cwd}}","agentPreset":"minimal"}
+{"type":"user/message","seq":0,"time":1785974400001,"data":{"content":[{"type":"text","text":"Reply exactly MINIMAL_PRESET_REQUEST_OK and stop."}],"source":{"kind":"user","rpcId":"{{rpcId}}"}},"surfaceOp":"append"}
 {"type":"assistant/chunk","seq":1,"time":1785974400002,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
-{"type":"assistant/chunk","seq":2,"time":1785974400003,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"CORE_WEB_REQUEST_OK"}}}
-{"type":"assistant/chunk","seq":3,"time":1785974400004,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"CORE_WEB_REQUEST_OK"}}}}
+{"type":"assistant/chunk","seq":2,"time":1785974400003,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"MINIMAL_PRESET_REQUEST_OK"}}}
+{"type":"assistant/chunk","seq":3,"time":1785974400004,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"MINIMAL_PRESET_REQUEST_OK"}}}}
 {"type":"assistant/chunk","seq":4,"time":1785974400005,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":10,"outputTokens":4}}}}
 {"type":"assistant/chunk","seq":5,"time":1785974400006,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
@@ -24,7 +24,7 @@
  "exclude": [
    "tests/scaffold.ts",
    "tests/scaffold-hermetic.e2e.ts",
-    "tests/core-web-profile.snapshot.ts",
+    "tests/minimal-preset.snapshot.ts",
    "tests/live-interactions.e2e.ts",
    "tests/question-composer.e2e.ts",
    "tests/approval-composer.e2e.ts",
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/config-catalog.md
-config-catalog.md: 10078dea5221cfe76b1c028ef83216f5a4575940
-config-catalog.zh.md: 38ed9f94bee9b0c11f5ea4dad4ba48532cce6450
+config-catalog.md: 64c7722a3cc3788d110eab8d9be161129684b942
+config-catalog.zh.md: 4cc146a38b408d9f1a7e5067419fead48520ae11
@@ -1161,6 +1161,8 @@ export interface Config {
   * variables. Empty text drops the section at render, matching the registry.
   */
  text: string
+  /** Make this persona the complete system prompt, suppressing every other section. */
+  complete?: boolean
 }
 ```

@@ -1987,7 +1989,7 @@ export interface Config {
 }
 ```

-Source: [`packages/core/system-prompt/src/index.ts:177`](../packages/core/system-prompt/src/index.ts)
+Source: [`packages/core/system-prompt/src/index.ts:186`](../packages/core/system-prompt/src/index.ts)

 ## `@deepseek-ai/dsh-time-context`

@@ -1163,6 +1163,8 @@ export interface Config {
   * variables. Empty text drops the section at render, matching the registry.
   */
  text: string
+  /** Make this persona the complete system prompt, suppressing every other section. */
+  complete?: boolean
 }
 ```

@@ -1989,7 +1991,7 @@ export interface Config {
 }
 ```

-来源：[`packages/core/system-prompt/src/index.ts:177`](../packages/core/system-prompt/src/index.ts)
+来源：[`packages/core/system-prompt/src/index.ts:186`](../packages/core/system-prompt/src/index.ts)

 ## `@deepseek-ai/dsh-time-context`

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/event-producer-consumer.md
-event-producer-consumer.md: 61d51677842c6e27dfa11bba56f6af145206c165
-event-producer-consumer.zh.md: 2f454cedc23f388d745fbb6c399d575681281afb
+event-producer-consumer.md: 19e2e660e58101b54054091b3d55b362d25d29dc
+event-producer-consumer.zh.md: d29cab8974d206b74b8869057b8efcf7542c1161
@@ -41,8 +41,8 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:139`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
 | `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:145`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
 | `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:156`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`subagent`](../packages/subagent/subagent) |
-| `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:29`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | [`agent`](../packages/core/agent), [`system-prompt`](../packages/core/system-prompt) |
-| `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:35`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
+| `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:31`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | [`agent`](../packages/core/agent), [`system-prompt`](../packages/core/system-prompt) |
+| `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:37`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
 | `telemetry/record` | `waterfall` | [`packages/session/session-telemetry/src/index.ts:43`](../packages/session/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/session/session-telemetry) (`waterfall`) | - |
 | `tools/change` | `emit` | [`packages/core/tools/src/index.ts:193`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
 | `tools/code-dispatch-log` | `waterfall` | [`packages/core/tools/src/index.ts:175`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) |
@@ -43,8 +43,8 @@
 | `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:139`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
 | `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:145`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
 | `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:156`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`subagent`](../packages/subagent/subagent) |
-| `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:29`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | [`agent`](../packages/core/agent), [`system-prompt`](../packages/core/system-prompt) |
-| `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:35`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
+| `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:31`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | [`agent`](../packages/core/agent), [`system-prompt`](../packages/core/system-prompt) |
+| `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:37`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
 | `telemetry/record` | `waterfall` | [`packages/session/session-telemetry/src/index.ts:43`](../packages/session/session-telemetry/src/index.ts) | [`session-telemetry`](../packages/session/session-telemetry) (`waterfall`) | - |
 | `tools/change` | `emit` | [`packages/core/tools/src/index.ts:193`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
 | `tools/code-dispatch-log` | `waterfall` | [`packages/core/tools/src/index.ts:175`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`waterfall`) | [`spill-policy`](../packages/spill/spill-policy) |
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/system-prompt.md
-system-prompt.md: bdc0e994fb8e784a19814574c405d8cc3dce2d11
-system-prompt.zh.md: db6932b18f4721020fed567d49727f863eb06608
+system-prompt.md: 56617ef9d3d8da89673a4624abcef73e58d72cab
+system-prompt.zh.md: cafea4f9689879b3fd8d0e1fff7249fcb02a7c12
@@ -39,7 +39,7 @@ interface ToolProviderResult {

 ## Prompt sections

-`PromptSection` is a readonly same-process registration contract. Its text may be static or resolved from the current assembly context.
+`PromptSection` is a readonly same-process registration contract. Its text may be static or resolved from the current assembly context. One effective `complete` section becomes the sole prompt section after cooperative assembly.

 ```ts type-equiv
 /** One contributed section of the system prompt (registry input). */
@@ -58,6 +58,13 @@ interface PromptSection {
   * interpolated later, by {@link renderPrompt}.
   */
  readonly text: string | ((context: AssembleContext) => string)
+  /**
+   * Treat this contribution as the complete system prompt. Assembly still
+   * runs the cooperative waterfall so tools, contexts, and variables can be
+   * resolved, then restores this exact section as the sole prompt section.
+   * More than one effective complete section makes assembly fail.
+   */
+  readonly complete?: boolean
 }
 ```

@@ -132,14 +139,16 @@ variable(name: string, provider: (context: AssembleContext) => string | undefine
 /**
 * Assemble global and scoped providers, detach tool parameters, apply
 * canonical ordering, then run the assembly waterfall. Scoped sections and
- * variables shadow globals; the returned waterfall value is authoritative.
+ * variables shadow globals. The returned waterfall value is authoritative
+ * except that an effective complete section is restored afterwards as the
+ * sole prompt section.
 * @param context - the optional scope and plugin-defined assembly fields.
- * @returns the authoritative post-waterfall assembly.
+ * @returns the post-waterfall assembly with any complete prompt enforced.
 */
 async assemble(context: AssembleContext = {}): Promise<PromptAssembly>
 ```

-Source: [`packages/core/system-prompt/src/index.ts:325`](../../packages/core/system-prompt/src/index.ts)
+Source: [`packages/core/system-prompt/src/index.ts:334`](../../packages/core/system-prompt/src/index.ts)

 <a id="system-prompt-events"></a>

@@ -149,7 +158,7 @@ Source: [`packages/core/system-prompt/src/index.ts:325`](../../packages/core/sys

 #### `system-prompt/assemble` — waterfall

-Expert waterfall over the assembled sections, contexts, tools, and variables. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners receive only that scope's assemblies. The returned value is authoritative. A supplied signal controls only this explicit assembly request and must not be retained to control later turns.
+Expert waterfall over the assembled sections, contexts, tools, and variables. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners receive only that scope's assemblies. The returned value is authoritative. A supplied signal controls only this explicit assembly request and must not be retained to control later turns. A registered complete section is restored after this waterfall, so listeners cannot add to or replace that scope's system prompt.

 ```ts cordis-catalog
 /**
@@ -157,7 +166,9 @@ Expert waterfall over the assembled sections, contexts, tools, and variables. Sc
 * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners
 * receive only that scope's assemblies. The returned value is authoritative.
 * A supplied signal controls only this explicit assembly request and must not
- * be retained to control later turns.
+ * be retained to control later turns. A registered complete section is
+ * restored after this waterfall, so listeners cannot add to or replace
+ * that scope's system prompt.
 * @param assembly - the mutable assembly built from registered providers.
 * @param context - the caller's per-assembly context.
 * @mode waterfall
@@ -167,7 +178,7 @@ Expert waterfall over the assembled sections, contexts, tools, and variables. Sc

 Types: [Scoped](scope.md)

-Source: [`packages/core/system-prompt/src/index.ts:29`](../../packages/core/system-prompt/src/index.ts)
+Source: [`packages/core/system-prompt/src/index.ts:31`](../../packages/core/system-prompt/src/index.ts)

 <a id="system-promptchange--emit"></a>

@@ -184,5 +195,5 @@ Emitted when any prompt provider changes. This registry notification is unfilter
 'system-prompt/change'(): void
 ```

-Source: [`packages/core/system-prompt/src/index.ts:35`](../../packages/core/system-prompt/src/index.ts)
+Source: [`packages/core/system-prompt/src/index.ts:37`](../../packages/core/system-prompt/src/index.ts)
 <!-- END GENERATED cordis-surface -->
@@ -39,7 +39,7 @@ interface ToolProviderResult {

 ## 提示词段落

-`PromptSection` 是一份只读的同进程注册约定。其文本可以是静态的，也可以从当前组装上下文动态解析。
+`PromptSection` 是一份只读的同进程注册约定。其文本可以是静态的，也可以从当前组装上下文动态解析。协作式组装完成后，一个有效的 `complete` 段会成为唯一的提示词段落。

 ```ts type-equiv
 /** One contributed section of the system prompt (registry input). */
@@ -58,6 +58,13 @@ interface PromptSection {
   * interpolated later, by {@link renderPrompt}.
   */
  readonly text: string | ((context: AssembleContext) => string)
+  /**
+   * Treat this contribution as the complete system prompt. Assembly still
+   * runs the cooperative waterfall so tools, contexts, and variables can be
+   * resolved, then restores this exact section as the sole prompt section.
+   * More than one effective complete section makes assembly fail.
+   */
+  readonly complete?: boolean
 }
 ```

@@ -132,14 +139,16 @@ variable(name: string, provider: (context: AssembleContext) => string | undefine
 /**
 * Assemble global and scoped providers, detach tool parameters, apply
 * canonical ordering, then run the assembly waterfall. Scoped sections and
- * variables shadow globals; the returned waterfall value is authoritative.
+ * variables shadow globals. The returned waterfall value is authoritative
+ * except that an effective complete section is restored afterwards as the
+ * sole prompt section.
 * @param context - the optional scope and plugin-defined assembly fields.
- * @returns the authoritative post-waterfall assembly.
+ * @returns the post-waterfall assembly with any complete prompt enforced.
 */
 async assemble(context: AssembleContext = {}): Promise<PromptAssembly>
 ```

-Source: [`packages/core/system-prompt/src/index.ts:325`](../../packages/core/system-prompt/src/index.ts)
+Source: [`packages/core/system-prompt/src/index.ts:334`](../../packages/core/system-prompt/src/index.ts)

 <a id="system-prompt-events"></a>

@@ -149,7 +158,7 @@ Source: [`packages/core/system-prompt/src/index.ts:325`](../../packages/core/sys

 #### `system-prompt/assemble` — waterfall

-Expert waterfall over the assembled sections, contexts, tools, and variables. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners receive only that scope's assemblies. The returned value is authoritative. A supplied signal controls only this explicit assembly request and must not be retained to control later turns.
+Expert waterfall over the assembled sections, contexts, tools, and variables. Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners receive only that scope's assemblies. The returned value is authoritative. A supplied signal controls only this explicit assembly request and must not be retained to control later turns. A registered complete section is restored after this waterfall, so listeners cannot add to or replace that scope's system prompt.

 ```ts cordis-catalog
 /**
@@ -157,7 +166,9 @@ Expert waterfall over the assembled sections, contexts, tools, and variables. Sc
 * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners
 * receive only that scope's assemblies. The returned value is authoritative.
 * A supplied signal controls only this explicit assembly request and must not
- * be retained to control later turns.
+ * be retained to control later turns. A registered complete section is
+ * restored after this waterfall, so listeners cannot add to or replace
+ * that scope's system prompt.
 * @param assembly - the mutable assembly built from registered providers.
 * @param context - the caller's per-assembly context.
 * @mode waterfall
@@ -167,7 +178,7 @@ Expert waterfall over the assembled sections, contexts, tools, and variables. Sc

 Types: [Scoped](scope.md)

-Source: [`packages/core/system-prompt/src/index.ts:29`](../../packages/core/system-prompt/src/index.ts)
+Source: [`packages/core/system-prompt/src/index.ts:31`](../../packages/core/system-prompt/src/index.ts)

 <a id="system-promptchange--emit"></a>

@@ -184,5 +195,5 @@ Emitted when any prompt provider changes. This registry notification is unfilter
 'system-prompt/change'(): void
 ```

-Source: [`packages/core/system-prompt/src/index.ts:35`](../../packages/core/system-prompt/src/index.ts)
+Source: [`packages/core/system-prompt/src/index.ts:37`](../../packages/core/system-prompt/src/index.ts)
 <!-- END GENERATED cordis-surface -->
@@ -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/user/guide/python-sdk.md
+python-sdk.md: c48bc95c9334cfd16a925d12726c20b2f968c753
+python-sdk.zh.md: dc31c391a180a742c7dc10807f6ed2ef8d11927d
@@ -0,0 +1,130 @@
+# Get started with the Python SDK
+
+English | [中文](python-sdk.zh.md)
+
+This tutorial installs the Python SDK, runs a checked-in Cordis composition without the Web UI, and uses the same API in your own program. It uses the compact [`minimal.cordis.yml`](../../../examples/jsonrpc-agent/minimal.cordis.yml) configuration as a complete example with a fixed system prompt, tool catalog, persistent-shell behavior, and compaction policy.
+
+## Prerequisites
+
+- Python 3.10 or newer
+- Linux x64, Linux arm64, or macOS arm64
+- A DeepSeek-compatible API endpoint and credential
+- An isolated workspace that the agent may modify
+
+## Install the SDK
+
+Choose either the public package or a source build. Both install the `deepseek-harness-sdk` distribution and expose the `deepseek_harness` Python module.
+
+### Install from PyPI
+
+Create a virtual environment and install the SDK with its same-version bundled runtime:
+
+```sh
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install deepseek-harness-sdk
+```
+
+### Build from source
+
+A source build additionally requires Git, Node.js ^22.19 or >= 24, Corepack-enabled pnpm 11, and `uv`. The following commands build the runtime for the current supported host platform, build both wheels, and install them into the active virtual environment:
+
+```sh
+git clone https://github.com/deepseek-ai/deepseek-harness-sdk.git deepseek-harness
+cd deepseek-harness
+python -m pip install uv==0.11.23
+corepack enable
+pnpm install
+
+case "$(uname -s):$(uname -m)" in
+  Linux:x86_64) runtime_platform=linux-x64 ;;
+  Linux:aarch64|Linux:arm64) runtime_platform=linux-arm64 ;;
+  Darwin:arm64) runtime_platform=macos-arm64 ;;
+  *) echo "unsupported platform" >&2; exit 1 ;;
+esac
+
+pnpm exec tsx scripts/build-exe-for-python-sdk.ts --targets="node24-$runtime_platform"
+version="$(node -p "require('./package.json').version")"
+python scripts/build-python-release.py --package sdk --output-dir dist-python
+python scripts/build-python-release.py \
+  --package runtime \
+  --platform "$runtime_platform" \
+  --runtime-exe "dist-exe/dsh-jsonrpc-agent-pkg-$runtime_platform" \
+  --output-dir dist-python
+python -m pip install --find-links dist-python "deepseek-harness-sdk==$version"
+```
+
+The runtime wheel contains the JSON-RPC executable and every plugin used by the complete [`minimal.cordis.yml`](../../../examples/jsonrpc-agent/minimal.cordis.yml), so neither installation path needs Node.js after installation.
+
+## Run the checked-in example
+
+Set the credential in the environment. Set `DEEPSEEK_BASE_URL` as well when the model is served by an OpenAI-compatible proxy rather than the default DeepSeek endpoint.
+
+```sh
+export DEEPSEEK_API_KEY=sk-your-key-here
+# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
+```
+
+Run one task from the repository checkout:
+
+```sh
+python examples/jsonrpc-agent/minimal.py \
+  --workspace /absolute/path/to/workspace \
+  --session-root /absolute/path/to/sessions \
+  --session-id example-001 \
+  "Inspect the repository and fix the failing tests."
+```
+
+The script prints the final assistant response. The session root receives a JSONL session log containing the assembled model request and every tool call.
+
+## Use the SDK in your own program
+
+The example is a thin wrapper around this SDK call:
+
+```python
+from pathlib import Path
+
+from deepseek_harness import DeepSeekHarness
+
+config = Path("examples/jsonrpc-agent/minimal.cordis.yml").resolve()
+workspace = Path("/absolute/path/to/workspace").resolve()
+sessions = Path("/absolute/path/to/sessions").resolve()
+
+with DeepSeekHarness(
+    provider="deepseek-official",
+    model="deepseek-v4-flash",
+    max_tokens=49_152,
+    cwd=str(workspace),
+    session_root=str(sessions),
+    cordis=str(config),
+) as harness:
+    result = harness.run(
+        "Inspect the repository and fix the failing tests.",
+        session_id="example-001",
+    )
+
+print(result.final_response)
+```
+
+`DeepSeekHarness` starts the bundled JSON-RPC runtime lazily and reuses it until the context manager exits. Reusing the same harness and session id across calls also preserves the session-owned Bash process, including its working directory, exported variables, and shell functions.
+
+## Understand the example configuration
+
+| Surface | Fixed value |
+|---|---|
+| System prompt | `You are a helpful software engineer assistant.` |
+| Model-facing tools | Persistent `bash` and `str_replace_editor` only |
+| Bash timeout | 300 seconds |
+| Editor output limit | 16,000 characters |
+| Compaction | Trigger ratio `0.8`, retain `20,480` tokens, summary cap `8,192` tokens, one retry |
+| Session persistence | Uncompressed JSONL under `DSH_SESSION_ROOT` |
+
+The configuration omits harness identity, workspace prompt text, skills, one-shot Bash, task tools, and every other model-facing plugin. Filesystem policy facts are logged as runtime user context rather than appended to the system prompt. The editor requires absolute paths as an unconditional current contract, so the obsolete `requireAbsolutePath` option is absent.
+
+## Choose workspace and session IDs
+
+`cwd` selects the workspace available to the agent, while `session_root` stores session logs and state. Use a fresh session id for an independent task; reuse an id only when the next call should continue the same conversation and persistent shell state.
+
+The composition uses `danger-full-access`. Run it only inside a disposable checkout or container: Bash and the editor can modify any path allowed to the runtime process. The persistent PTY backend requires a POSIX terminal substrate and is not a Windows agent surface.
+
+For the complete SDK lifecycle and result contract, see the [Python SDK reference](../../../python/sdk/README.md). For Cordis composition syntax, see [Configuration](./config.md).
@@ -0,0 +1,130 @@
+# Python SDK 快速上手
+
+[English](python-sdk.md) | 中文
+
+本教程介绍如何安装 Python SDK、在不使用 Web UI 的情况下运行仓库内置 Cordis 组合，以及如何在自己的程序中调用同一套 API。教程使用精简且完整的 [`minimal.cordis.yml`](../../../examples/jsonrpc-agent/minimal.cordis.yml) 作为示例，其中固定了系统提示词、工具目录、持久 shell 行为和压缩（compaction）策略。
+
+## 前置要求
+
+- Python 3.10 或更高版本
+- Linux x64、Linux arm64 或 macOS arm64
+- DeepSeek 兼容的 API 端点与凭据
+- agent 可以修改的隔离 workspace
+
+## 安装 SDK
+
+可以选择安装公开包或从源码构建。两种方式都会安装 `deepseek-harness-sdk` 分发包，并提供 `deepseek_harness` Python 模块。
+
+### 从 PyPI 安装
+
+请创建虚拟环境，并安装 SDK 及其同版本内置运行时：
+
+```sh
+python -m venv .venv
+. .venv/bin/activate
+python -m pip install deepseek-harness-sdk
+```
+
+### 从源码构建
+
+从源码构建还需要 Git、Node.js ^22.19 或 >= 24、通过 Corepack 启用的 pnpm 11，以及 `uv`。以下命令为当前受支持的宿主平台构建运行时和两个 wheel 包，并将它们安装进当前虚拟环境：
+
+```sh
+git clone https://github.com/deepseek-ai/deepseek-harness-sdk.git deepseek-harness
+cd deepseek-harness
+python -m pip install uv==0.11.23
+corepack enable
+pnpm install
+
+case "$(uname -s):$(uname -m)" in
+  Linux:x86_64) runtime_platform=linux-x64 ;;
+  Linux:aarch64|Linux:arm64) runtime_platform=linux-arm64 ;;
+  Darwin:arm64) runtime_platform=macos-arm64 ;;
+  *) echo "unsupported platform" >&2; exit 1 ;;
+esac
+
+pnpm exec tsx scripts/build-exe-for-python-sdk.ts --targets="node24-$runtime_platform"
+version="$(node -p "require('./package.json').version")"
+python scripts/build-python-release.py --package sdk --output-dir dist-python
+python scripts/build-python-release.py \
+  --package runtime \
+  --platform "$runtime_platform" \
+  --runtime-exe "dist-exe/dsh-jsonrpc-agent-pkg-$runtime_platform" \
+  --output-dir dist-python
+python -m pip install --find-links dist-python "deepseek-harness-sdk==$version"
+```
+
+运行时 wheel 包含 JSON-RPC 可执行文件，以及完整 [`minimal.cordis.yml`](../../../examples/jsonrpc-agent/minimal.cordis.yml) 使用的每个插件，因此两种安装方式完成后都不再需要 Node.js。
+
+## 运行仓库内置示例
+
+请在环境中设置凭据。如果模型不是由默认 DeepSeek 端点提供，而是通过 OpenAI 兼容代理提供，还需要设置 `DEEPSEEK_BASE_URL`。
+
+```sh
+export DEEPSEEK_API_KEY=sk-your-key-here
+# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
+```
+
+从仓库 checkout 运行一个任务：
+
+```sh
+python examples/jsonrpc-agent/minimal.py \
+  --workspace /absolute/path/to/workspace \
+  --session-root /absolute/path/to/sessions \
+  --session-id example-001 \
+  "Inspect the repository and fix the failing tests."
+```
+
+脚本会打印 assistant 的最终回复。会话根目录会收到 JSONL 会话日志，其中包含组装后的模型请求与每次工具调用。
+
+## 在自己的程序中使用 SDK
+
+该示例是以下 SDK 调用的轻量包装层：
+
+```python
+from pathlib import Path
+
+from deepseek_harness import DeepSeekHarness
+
+config = Path("examples/jsonrpc-agent/minimal.cordis.yml").resolve()
+workspace = Path("/absolute/path/to/workspace").resolve()
+sessions = Path("/absolute/path/to/sessions").resolve()
+
+with DeepSeekHarness(
+    provider="deepseek-official",
+    model="deepseek-v4-flash",
+    max_tokens=49_152,
+    cwd=str(workspace),
+    session_root=str(sessions),
+    cordis=str(config),
+) as harness:
+    result = harness.run(
+        "Inspect the repository and fix the failing tests.",
+        session_id="example-001",
+    )
+
+print(result.final_response)
+```
+
+`DeepSeekHarness` 会延迟启动内置 JSON-RPC 运行时，并持续复用，直至退出上下文管理器。在多次调用中复用同一个 harness 和 session id，还会保留该会话拥有的 Bash 进程，包括其工作目录、已导出的变量与 shell 函数。
+
+## 了解示例配置
+
+| 方面 | 固定值 |
+|---|---|
+| 系统提示词 | `You are a helpful software engineer assistant.` |
+| 面向模型的工具 | 仅持久 `bash` 与 `str_replace_editor` |
+| Bash 超时 | 300 秒 |
+| 编辑器输出上限 | 16,000 个字符 |
+| 压缩 | 触发比例 `0.8`、保留 `20,480` 个 token、摘要上限 `8,192` 个 token、重试 1 次 |
+| 会话持久化 | `DSH_SESSION_ROOT` 下未压缩的 JSONL |
+
+该配置省略了 harness 身份、workspace 提示词文本、skill（技能）、一次性 Bash、任务工具和其他所有面向模型的插件。文件系统策略事实记录为运行时用户上下文，而不会追加到系统提示词中。编辑器无条件要求绝对路径，因此配置中没有已经废弃的 `requireAbsolutePath` 选项。
+
+## 选择 workspace 与 session id
+
+`cwd` 用于选择 agent 可访问的 workspace，`session_root` 用于保存会话日志和状态。独立任务应使用新的 session id；只有下一次调用需要延续同一段对话和持久 shell 状态时，才复用原有 id。
+
+该组合使用 `danger-full-access`。只能在可丢弃的 checkout 或容器内运行：Bash 与编辑器可以修改运行时进程有权访问的任何路径。持久 PTY 后端需要 POSIX 终端环境，因此该模式不适用于 Windows agent。
+
+完整的 SDK 生命周期与结果约定见 [Python SDK 参考](../../../python/sdk/README.md)。Cordis 组合语法见[配置](./config.md)。
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/user/guide/quickstart.md
-quickstart.md: ce196641f205324334533c025b4ac1dc791f857d
-quickstart.zh.md: 3a5d6d0748ec0c7ec83c74570d0fad1e8d66a97c
+quickstart.md: 6a0b292ce12b32b7993b7de56b35f1df2e7a7153
+quickstart.zh.md: 008245f136e28630c7e8368eeec536e11112a885
@@ -57,6 +57,7 @@ Open `http://127.0.0.1:3080`. The agent can read and write files, run commands,

 ## Next steps

+- [Get started with the Python SDK](./python-sdk.md) — install the SDK and run a complete Cordis configuration without the Web UI
 - [Configure models](./providers.md) — reach providers beyond DeepSeek, and custom gateways
 - [Configuration](./config.md) — understand the `cordis.yml` format
 - [Develop a plugin](../develop/basic/) — build your own tool or backend
@@ -57,6 +57,7 @@ pnpm run dsh web

 ## 下一步

+- [Python SDK 快速上手](./python-sdk.md) — 安装 SDK，并在不使用 Web UI 的情况下运行完整 Cordis 配置
 - [配置模型](./providers.md) — 接入 DeepSeek 之外的提供方与自定义网关
 - [配置文件](./config.md) — 了解 `cordis.yml` 的格式
 - [开发插件](../develop/basic/) — 编写自己的工具或后端
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write examples/jsonrpc-agent/README.md
-README.md: bcc1027d2edb30ab374dfa2ed13ad8e6360d923b
-README.zh.md: ce255e4dd70bf8c5c6edc51afbe03bb4c66560a0
+README.md: 5f60a64a4888c64e4fd68835f78e4a334ffed263
+README.zh.md: 8d2f9807ff259000b5a6823357f8c41b43bfa434
@@ -21,16 +21,16 @@ The surrounding runtime also loads JSONL session persistence and automatic conte
 | `DEEPSEEK_BASE_URL` | Host endpoint used by `dsh-llm-deepseek` |
 | `DSH_CWD` | Agent workspace for bash and filesystem tools |
 | `DSH_MAX_TOKENS_AS_SUCCESS` | `true` (default) accepts token-limited results; `false` reports them as errors |
-| `DSH_SESSION_ROOT` | JSONL trajectory directory |
+| `DSH_SESSION_ROOT` | JSONL session directory |
 | `DSH_SYSTEM_PROMPT` | Deployment-provided coding persona |

 Pass the config path through the Python SDK's `cordis` option or `DSH_CORDIS_CONFIG`. The bundled executable already carries every plugin named by this file; the target machine does not need Node.js.

-## Persistent tools variant
+## Minimal variant

-[`persistent-tools.cordis.yml`](persistent-tools.cordis.yml) is a minimal runnable variant whose model-facing surface is exactly:
+[`minimal.cordis.yml`](minimal.cordis.yml) is the complete standalone counterpart of the Web `minimal` preset. It fixes the system prompt and compaction policy, and its model-facing surface is exactly:

 - owner-scoped persistent `bash`
 - `str_replace_editor` with `view`, `create`, `str_replace`, and `insert`

-It composes the local PTY, filesystem intent policy, and session sandbox policy.
+It composes the local PTY, filesystem intent policy, session sandbox policy, and JSONL persistence needed by the bundled runtime. [`minimal.py`](minimal.py) runs it through the Python SDK; the [Python SDK tutorial](../../docs/user/guide/python-sdk.md) uses this configuration to cover setup, session management, and the security boundary.
@@ -21,16 +21,16 @@
 | `DEEPSEEK_BASE_URL` | `dsh-llm-deepseek` 使用的宿主端点 |
 | `DSH_CWD` | bash 和文件系统工具使用的 agent workspace |
 | `DSH_MAX_TOKENS_AS_SUCCESS` | `true`（默认）接受受 token 上限限制的结果；`false` 将其报告为错误 |
-| `DSH_SESSION_ROOT` | JSONL 轨迹目录 |
+| `DSH_SESSION_ROOT` | JSONL 会话目录 |
 | `DSH_SYSTEM_PROMPT` | 由部署提供的编码人格 |

 通过 Python SDK 的 `cordis` 选项或 `DSH_CORDIS_CONFIG` 传入配置路径。内置可执行文件已携带此文件中指定的每个插件；目标机器无需 Node.js。

-## 持久化工具变体
+## 极简变体

-[`persistent-tools.cordis.yml`](persistent-tools.cordis.yml) 是一个最小可运行变体，面向模型的能力严格只有：
+[`minimal.cordis.yml`](minimal.cordis.yml) 是 Web `minimal` preset 的完整独立版本。它固定系统提示词与压缩策略，面向模型的能力严格只有：

 - 所有者作用域内持久化的 `bash`
 - 提供 `view`、`create`、`str_replace` 与 `insert` 的 `str_replace_editor`

-它组合了本地 PTY、文件系统意图策略与会话沙箱策略。
+它组合了内置运行时所需的本地 PTY、文件系统意图策略、会话沙箱策略与 JSONL 持久化。[`minimal.py`](minimal.py) 通过 Python SDK 运行该配置；[Python SDK 教程](../../docs/user/guide/python-sdk.md)以此配置介绍设置方式、会话管理与安全边界。
@@ -0,0 +1,91 @@
+# Complete unattended minimal-agent composition for the Python SDK. The model
+# sees one fixed system prompt and only the owner-scoped persistent Bash and
+# string-replace editor tools.
+
+- id: jsonrpc
+  name: '@deepseek-ai/dsh-jsonrpc'
+  config:
+    maxTokensAsSuccess: false
+
+- id: llm-deepseek
+  name: '@deepseek-ai/dsh-llm-deepseek'
+
+- id: sandbox
+  name: '@deepseek-ai/dsh-sandbox-local'
+
+- id: sandbox-policy
+  name: '@deepseek-ai/dsh-sandbox-policy'
+  config:
+    mode: danger-full-access
+    workspaceRoot: !!js process.env.DSH_CWD ?? process.cwd()
+
+- id: subprocess
+  name: '@deepseek-ai/dsh-subprocess-local'
+
+- id: pty
+  name: '@deepseek-ai/dsh-pty'
+
+- id: pty-local
+  name: '@deepseek-ai/dsh-pty-local'
+  config:
+    timeoutMs: 300000
+
+# The sandbox-aware filesystem backend applies the same per-session policy as
+# Bash. danger-full-access permits unrestricted workspace behavior while
+# keeping one policy boundary for both tools.
+- id: fs-sandbox
+  name: '@deepseek-ai/dsh-fs-sandbox'
+  config:
+    cwd: !!js process.env.DSH_CWD ?? process.cwd()
+
+- id: fs-policy
+  name: '@deepseek-ai/dsh-fs-policy'
+
+- id: agent-spine
+  name: '@deepseek-ai/dsh-agent-spine-demo'
+  config:
+    includeHarnessIdentity: false
+    persona: You are a helpful software engineer assistant.
+    workspaceContext: false
+    skills:
+      enabled: false
+    toolBash: false
+    toolTasks: false
+
+- id: persistent-bash
+  name: '@deepseek-ai/dsh-tool-bash-persistent'
+  config:
+    timeoutMs: 300000
+    description: |-
+      Run commands in a bash shell
+      * When invoking this tool, the contents of the "command" parameter does NOT need to be XML-escaped.
+      * You don't have access to the internet via this tool.
+      * You do have access to a mirror of common linux and python packages via apt and pip.
+      * 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.
+
+- id: str-replace-editor
+  name: '@deepseek-ai/dsh-tool-str-replace-editor'
+  config:
+    maxOutputChars: 16000
+
+- id: sessions
+  name: '@deepseek-ai/dsh-session-persistence-jsonl'
+  config:
+    root: !!js process.env.DSH_SESSION_ROOT ?? './.sessions'
+    compression: none
+
+- id: token-meter
+  name: '@deepseek-ai/dsh-token-meter'
+
+- id: compact-basic
+  name: '@deepseek-ai/dsh-compact-basic'
+  config:
+    thresholdRatio: 0.8
+    retainTokens: 20480
+    summarizationProvider: ''
+    summarizationModel: ''
+    maxTokens: 8192
+    compactionRetries: 1
@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""Run one minimal-agent turn through the bundled Python SDK runtime."""
+
+from __future__ import annotations
+
+import argparse
+from pathlib import Path
+
+from deepseek_harness import DeepSeekHarness
+
+
+CONFIG = Path(__file__).with_name("minimal.cordis.yml")
+
+
+def main() -> None:
+    """Parse one task and print the agent's final response."""
+    parser = argparse.ArgumentParser()
+    parser.add_argument("prompt", help="Task for the minimal agent")
+    parser.add_argument("--workspace", type=Path, default=Path.cwd())
+    parser.add_argument("--session-root", type=Path, default=Path(".dsh-sessions"))
+    parser.add_argument("--session-id")
+    parser.add_argument("--provider", default="deepseek-official")
+    parser.add_argument("--model", default="deepseek-v4-flash")
+    parser.add_argument("--max-tokens", type=int)
+    args = parser.parse_args()
+
+    workspace = args.workspace.resolve()
+    session_root = args.session_root.resolve()
+    with DeepSeekHarness(
+        provider=args.provider,
+        model=args.model,
+        max_tokens=args.max_tokens,
+        cwd=str(workspace),
+        session_root=str(session_root),
+        cordis=str(CONFIG.resolve()),
+    ) as harness:
+        result = harness.run(args.prompt, session_id=args.session_id)
+    print(result.final_response)
+
+
+if __name__ == "__main__":
+    main()
@@ -1,12 +1,10 @@
-# Keyless replay keeps the persistent-tool composition intact and replaces
-# only its live DeepSeek adapter with the fixture-backed provider. The catalog
-# below claims the same `deepseek-official` route the agent asks for: an
-# unowned route makes the SDK server mount the real adapter, which then demands
-# a key this keyless lane has no way to supply.
+# Keyless replay keeps the complete minimal composition intact and replaces
+# only its live DeepSeek adapter with the fixture-backed provider. The replay
+# catalog claims the same route initialized by the SDK.
 - id: base
  name: '@deepseek-ai/cordis-plugin-include'
  config:
-    path: ./persistent-tools.cordis.yml
+    path: ./minimal.cordis.yml
    patches:
      - id: llm-deepseek
        name: '@deepseek-ai/dsh-llm-deepseek'
@@ -1,59 +0,0 @@
-# Minimal unattended composition for the persistent Bash and string-replace
-# editor. It is runnable through the JSON-RPC example runtime and intentionally
-# keeps the model-facing surface to exactly these two tools.
-
- id: jsonrpc
-  name: '@deepseek-ai/dsh-jsonrpc'
-
- id: llm-deepseek
-  name: '@deepseek-ai/dsh-llm-deepseek'
-  config:
-
- id: sandbox
-  name: '@deepseek-ai/dsh-sandbox-local'
-
- id: sandbox-policy
-  name: '@deepseek-ai/dsh-sandbox-policy'
-  config:
-    mode: danger-full-access
-    workspaceRoot: !!js process.env.DSH_CWD ?? process.cwd()
-
- id: subprocess
-  name: '@deepseek-ai/dsh-subprocess-local'
-
- id: pty
-  name: '@deepseek-ai/dsh-pty'
-
- id: pty-local
-  name: '@deepseek-ai/dsh-pty-local'
-
- id: fs-sandbox
-  name: '@deepseek-ai/dsh-fs-sandbox'
-  config:
-    cwd: !!js process.env.DSH_CWD ?? process.cwd()
-
- id: fs-policy
-  name: '@deepseek-ai/dsh-fs-policy'
-
- id: agent-spine
-  name: '@deepseek-ai/dsh-agent-spine-demo'
-  config:
-    includeHarnessIdentity: false
-    persona: 'You are a helpful software engineer assistant.'
-    workspaceContext: false
-    skills:
-      enabled: false
-    toolBash: false
-    toolTasks: false
-
- id: persistent-bash
-  name: '@deepseek-ai/dsh-tool-bash-persistent'
-
- id: str-replace-editor
-  name: '@deepseek-ai/dsh-tool-str-replace-editor'
-
- id: sessions
-  name: '@deepseek-ai/dsh-session-persistence-jsonl'
-  config:
-    root: !!js process.env.DSH_SESSION_ROOT ?? './.sessions'
-    compression: none
@@ -33,11 +33,21 @@ const testsDir = dirOf(import.meta.url)
 const snapshotsDir = join(testsDir, 'snapshots')
 const liveConfig = join(testsDir, '..', 'cordis.yml')
 const replayConfig = join(testsDir, '..', 'cordis.snapshot.yml')
-const persistentToolsLiveConfig = join(testsDir, '..', 'persistent-tools.cordis.yml')
-const persistentToolsReplayConfig = join(testsDir, '..', 'persistent-tools.snapshot.cordis.yml')
+const minimalLiveConfig = join(testsDir, '..', 'minimal.cordis.yml')
+const minimalReplayConfig = join(testsDir, '..', 'minimal.snapshot.cordis.yml')
 const runtimeBin = fileURLToPath(new URL('../../../packages/examples/jsonrpc-demo/src/bin.ts', import.meta.url))
 const repoTsconfig = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))

+const MINIMAL_SYSTEM_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.
+* You don't have access to the internet via this tool.
+* You do have access to a mirror of common linux and python packages via apt and pip.
+* 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.`
+
 const mode = process.env.DSH_SNAPSHOT ?? 'replay'
 const recording = mode === 'record'
 const refreshing = mode === 'refresh'
@@ -61,6 +71,10 @@ interface SdkScenario {
  expectedFiles?: Readonly<Record<string, string>>
  /** Assembled model-facing tool names and required argument keys. */
  expectedTools?: Readonly<Record<string, readonly string[]>>
+  /** Exact assembled system prompt for the root request. */
+  expectedSystem?: string
+  /** Exact model-facing descriptions for selected tools. */
+  expectedToolDescriptions?: Readonly<Record<string, string>>
  /** Stable policy-context clauses the real assembled request must include or omit. */
  policyContext?: { includes: readonly string[]; excludes: readonly string[] }
 }
@@ -89,9 +103,11 @@ const SCENARIOS: SdkScenario[] = [
    prompt: 'Prove that bash state persists. Then create {{cwd}}/note.txt with a tab-indented line, view it, replace that literal tab-indented line, and make the persistent shell exit with code 9.',
    sessionId: 'persistent-tools-snapshot',
    children: 0,
-    configs: { live: persistentToolsLiveConfig, replay: persistentToolsReplayConfig },
+    configs: { live: minimalLiveConfig, replay: minimalReplayConfig },
    expectedFiles: { 'note.txt': 'target:\n\tnew\n' },
    expectedTools: { bash: ['command'], str_replace_editor: ['command', 'path'] },
+    expectedSystem: MINIMAL_SYSTEM_PROMPT,
+    expectedToolDescriptions: { bash: MINIMAL_BASH_DESCRIPTION },
    policyContext: {
      includes: ['Current DSH file policy: danger-full-access.', 'file modifications by available operations'],
      excludes: ['write and edit tools', 'terminal sessions', 'one-shot bash commands'],
@@ -125,16 +141,33 @@ async function persistedLogs(sessionsRoot: string): Promise<PersistedLog[]> {

 interface LoggedRequestHeader {
  type?: string
-  data?: { header?: { system?: unknown; tools?: Array<{ name: string; parameters: { required?: string[] } }> } }
+  data?: { header?: { system?: unknown; tools?: LoggedTool[] } }
 }

-function assembledToolRequirements(log: PersistedLog): Record<string, string[]> {
+interface LoggedTool {
+  readonly name: string
+  readonly description?: unknown
+  readonly parameters: { readonly required?: string[] }
+}
+
+function assembledTools(log: PersistedLog): LoggedTool[] {
  const event = log.content.trimEnd().split('\n')
    .map(line => JSON.parse(line) as LoggedRequestHeader)
    .find(candidate => candidate.type === 'request/header')
  const tools = event?.data?.header?.tools
  if (tools === undefined) throw new Error('session log has no request/header tools')
-  return Object.fromEntries(tools.map(tool => [tool.name, tool.parameters.required ?? []]))
+  return tools
+}
+
+function assembledToolRequirements(log: PersistedLog): Record<string, string[]> {
+  return Object.fromEntries(assembledTools(log).map(tool => [tool.name, tool.parameters.required ?? []]))
+}
+
+function assembledToolDescriptions(log: PersistedLog): Record<string, string> {
+  return Object.fromEntries(assembledTools(log).map((tool) => {
+    if (typeof tool.description !== 'string') throw new Error(`tool ${tool.name} has no description`)
+    return [tool.name, tool.description]
+  }))
 }

 function assembledSystem(log: PersistedLog): string {
@@ -400,6 +433,16 @@ describe('TypeScript SDK snapshots over the jsonrpc runtime', () => {
        if (parent === undefined) throw new Error(`${scenario.name} has no parent session log`)
        expect(assembledToolRequirements(parent)).toEqual(scenario.expectedTools)
      }
+      if (scenario.expectedSystem !== undefined) {
+        const parent = ordered[0]
+        if (parent === undefined) throw new Error(`${scenario.name} has no parent session log`)
+        expect(assembledSystem(parent)).toBe(scenario.expectedSystem)
+      }
+      if (scenario.expectedToolDescriptions !== undefined) {
+        const parent = ordered[0]
+        if (parent === undefined) throw new Error(`${scenario.name} has no parent session log`)
+        expect(assembledToolDescriptions(parent)).toMatchObject(scenario.expectedToolDescriptions)
+      }
      if (scenario.policyContext !== undefined) {
        const parent = ordered[0]
        if (parent === undefined) throw new Error(`${scenario.name} has no parent session log`)
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/boot/app-boot/README.md
-README.md: be03bceb39935fafb7acc7d3a99c1fe3af686f94
-README.zh.md: 10165486712fc078cdf1f4147522397a15c88955
+README.md: f3ffdae3846edba6f1a1a4821adade7b6c7fce76
+README.zh.md: 4f31fd743f1ddc57edc9c215a42e79a16afcdecb
@@ -15,10 +15,10 @@ Shared boot glue for the app bins ([`dsh`](../../../apps/cli/README.md) and [`ds
 | `assertEntriesActivated(ctx, binName)` | Include the `assertEntriesLoaded` check, then await every enabled entry after the Loader settles; throw with each failed plugin's original stack or each pending plugin's unresolved services |
 | `loadOptionalPatches(binName, file)` | Parse an optional patch-list file (a profile's `cordis.patch.yml`) — a top-level YAML array of include `PatchOptions` (id-targeted config overrides, `insert` lists, `!!js` allowed); absent file → `undefined`, an unreadable/unparsable/non-array file throws |
 | `loadOverlayPatches(binName, file)` | Parse a required top-level YAML array containing the same include `PatchOptions` entries described above; a missing file also throws because the caller named it |
-| `mountRootInclude(ctx, absoluteConfigPath, patches?)` | Register the statically imported `cordis:include` and `cordis:group` builtins, mount the include, and retain the exact root entry used by user patch-layer HMR |
+| `mountRootInclude(ctx, absoluteConfigPath, patches?, bareModuleBaseUrl?)` | Register the statically imported `cordis:include` and `cordis:group` builtins, mount the include, and retain the exact root entry used by user patch-layer HMR; an optional module base anchors bare package names to the installed host while relative names stay config-relative |
 | `watchUserPatches(ctx, options)` | Register the named patch file with the existing Cordis HMR service; each add/change/removal transactionally recomposes the full patch list through the caller's `compose` closure (app-owned layers around the current user layer) and returns an async disposer |
 | `resolveProfileDir` / `initProfile` / `loadProfile` / `readProfileManifest` / `writeProfileManifest` / `resolveBundleDir` / `composeEntries` / `healProfilesModuleFallback` / `PROFILE_TEMPLATES` / `DEFAULT_PROFILE_BUNDLES` / `PROFILES_DIR` / `PROFILE_PATCH_FILENAME` | Profile machinery (see [Profiles](#profiles)) |
-| `boot(binName, absoluteConfigPath, patches?, prepare?)` | Create the root context, expose `dshHomePath(...segments)` to Loader `!!js` config expressions, install Loader, run optional host preparation before config-tree entries mount (`prepare` may use Loader and provide launcher-owned context slots), then mount and await the include tree, assert entries loaded and activated, and return the root context — or dispose the partial context and reject a labelled error |
+| `boot(binName, absoluteConfigPath, patches?, prepare?, bareModuleBaseUrl?)` | Create the root context, expose `dshHomePath(...segments)` to Loader `!!js` config expressions, install Loader, run optional host preparation before config-tree entries mount (`prepare` may use Loader and provide launcher-owned context slots), then mount and await the include tree, assert entries loaded and activated, and return the root context — or dispose the partial context and reject a labelled error; the optional module base has the same resolution semantics as `mountRootInclude` |
 | `renderConfigDump(binName, absoluteConfigPath, layers, warn?)` | Compose the base config and labeled overlay layers offline with the include's own parser and patch algorithm (`entryListSchema`/`applyEntryPatches`), so the result equals what `boot()` mounts, and render YAML with `!!js` expressions verbatim; each run of rows that shares one source file and the same patch layers is preceded by a `# ==` comment naming that file and those layers, keeping the output one loadable document; a patch matching no row goes to `warn` with its layer label (default: one stderr line), and read, parse, or field validation failures throw |
 | `addHarnessSourceSection(ctx, sourceRoot)` | Add a global `harness:source` prompt section (ordered just after the harness identity, before the persona) telling the agent the on-disk path to the DSH implementation checkout while warning it not to infer the current working directory from that path and to use `pwd` instead; a no-op returning `undefined` when the booted tree has no `systemPrompt` service. The section is registered against that service's fiber, so a dev HMR reload of the system prompt drops it until the next boot |
 | `HARNESS_SOURCE_SECTION` | The `'harness:source'` section name `addHarnessSourceSection` registers under |
@@ -29,7 +29,7 @@ The Loader mounts entries concurrently, so a surface can already own the termina

 `cordis:group` is registered beside `cordis:include` so a composition can give one `isolate` realm to a provider and its consumers together. Both load through the ambient module pipeline rather than the included tree's own specifier resolution, which is what lets a composition outside this workspace — an agent preset under the Harness home — use a group row at all.

-Bare plugin specifiers in a config (`@deepseek-ai/dsh-*`, npm packages) resolve through the Cordis Loader's internal module loader. Repository bins install Loader's optional `node-addon-require-builtin` peer; external callers must supply it or install plugins where plain Node import resolution can find them. Relative specifiers resolve against the config directory without the native helper. The built `dsh-app-boot` artifact embeds the statically mounted Include implementation while leaving Loader external, so the include tree and host bind to one Loader peer. The `dsh` source launcher additionally maps manifest-declared workspace packages to their TypeScript source; its configuration gate requires every shipped raw/Web bare plugin to appear in the resolver manifest's `dependencies`.
+Bare plugin specifiers in a config (`@deepseek-ai/dsh-*`, npm packages) resolve through the Cordis Loader's internal module loader. They resolve from the config directory by default; a closed runtime passes `bareModuleBaseUrl` to `boot` or `mountRootInclude` so its installed package tree remains authoritative even when the config lives inside another Node project. Relative specifiers always resolve against the config directory. Repository bins install Loader's optional `node-addon-require-builtin` peer; external callers must supply it or install plugins where plain Node import resolution can find them. The built `dsh-app-boot` artifact embeds the statically mounted Include implementation while leaving Loader external, so the include tree and host bind to one Loader peer. The `dsh` source launcher additionally maps manifest-declared workspace packages to their TypeScript source; its configuration gate requires every shipped raw/Web bare plugin to appear in the resolver manifest's `dependencies`.

 This package carries no loader hooks and no dev-mode surface. The [`dsh` app](../../../apps/cli/README.md) owns its Node source-launch hook and consumes these helpers for the boot sequence; built consumers continue to use plain Node package resolution.

@@ -15,10 +15,10 @@
 | `assertEntriesActivated(ctx, binName)` | 先执行 `assertEntriesLoaded` 检查，再在 Loader 结算后等待每个已启用配置项；抛出的错误包含每个失败插件的原始错误堆栈，或每个等待中插件尚未解析的服务 |
 | `loadOptionalPatches(binName, file)` | 解析一份可选的 patch 列表文件（即 profile 的 `cordis.patch.yml`）：其顶层是一个 YAML 数组，内容为 include 的 `PatchOptions`（按 id 定位的配置覆盖、`insert` 列表，允许 `!!js`）；文件不存在时返回 `undefined`，文件不可读、不可解析或内容不是数组时抛出异常 |
 | `loadOverlayPatches(binName, file)` | 解析必需的顶层 YAML 数组，其中包含与上文相同的 include `PatchOptions` 条目；文件缺失也会抛出异常，因为该文件是调用方指名的 |
-| `mountRootInclude(ctx, absoluteConfigPath, patches?)` | 注册静态导入的 `cordis:include` 与 `cordis:group` builtin，挂载 include，并保留用户 patch 层 HMR（热模块替换）使用的确切根配置项 |
+| `mountRootInclude(ctx, absoluteConfigPath, patches?, bareModuleBaseUrl?)` | 注册静态导入的 `cordis:include` 与 `cordis:group` builtin，挂载 include，并保留用户 patch 层 HMR（热模块替换）使用的确切根配置项；可选模块基准会把裸包名锚定到已安装宿主，而相对名称仍以配置目录为基准 |
 | `watchUserPatches(ctx, options)` | 向现有 Cordis HMR 服务注册指名的 patch 文件；每次新增、变更或移除都会通过调用方的 `compose` 闭包（应用自有层围绕当前用户层）以事务方式重新组合完整 patch 列表，并返回异步清理函数 |
 | `resolveProfileDir` / `initProfile` / `loadProfile` / `readProfileManifest` / `writeProfileManifest` / `resolveBundleDir` / `composeEntries` / `healProfilesModuleFallback` / `PROFILE_TEMPLATES` / `DEFAULT_PROFILE_BUNDLES` / `PROFILES_DIR` / `PROFILE_PATCH_FILENAME` | Profile 机制（见 [Profile](#profiles)） |
-| `boot(binName, absoluteConfigPath, patches?, prepare?)` | 创建根上下文，向 Loader `!!js` 配置表达式暴露 `dshHomePath(...segments)` 并安装 Loader，在配置树条目挂载前执行可选的宿主准备操作（`prepare` 可以使用 Loader，也可以提供由启动器拥有的上下文插槽），再挂载并等待 include 树结算，断言所有条目均已加载并激活，最后返回根上下文——失败时 dispose（资源释放）部分构造的上下文，并以带标签的错误 reject |
+| `boot(binName, absoluteConfigPath, patches?, prepare?, bareModuleBaseUrl?)` | 创建根上下文，向 Loader `!!js` 配置表达式暴露 `dshHomePath(...segments)` 并安装 Loader，在配置树条目挂载前执行可选的宿主准备操作（`prepare` 可以使用 Loader，也可以提供由启动器拥有的上下文插槽），再挂载并等待 include 树结算，断言所有条目均已加载并激活，最后返回根上下文——失败时 dispose（资源释放）部分构造的上下文，并以带标签的错误 reject；可选模块基准与 `mountRootInclude` 的解析语义相同 |
 | `renderConfigDump(binName, absoluteConfigPath, layers, warn?)` | 使用 include 自己的解析器和补丁算法（`entryListSchema`/`applyEntryPatches`）离线合成基础配置与带标签的覆盖层，使结果与 `boot()` 挂载的内容一致，再渲染为 YAML，并原样保留 `!!js` 表达式；每段来源于同一文件且由相同补丁层修改的连续行之前都有一条 `# ==` 注释，标明该文件和这些补丁层，输出仍是一份可加载的文档；未匹配到行的补丁连同其层标签交给 `warn`（默认：一行 stderr），读取、解析或字段验证失败则抛出 |
 | `addHarnessSourceSection(ctx, sourceRoot)` | 添加全局 `harness:source` 提示词段落（顺序紧随 harness 身份、位于 persona 之前），告知 agent（智能体）DSH 实现代码 checkout 的磁盘路径，同时提醒它不得据此推断当前工作目录，而应使用 `pwd`；如果已启动树没有此项服务，则不执行操作并返回 `undefined`。这里的服务是 `systemPrompt`；该段落注册到它的 fiber，因此开发环境 HMR（热模块替换）重新加载系统提示词后，它会消失直至下次启动 |
 | `HARNESS_SOURCE_SECTION` | `'harness:source'` 段落名称，供 `addHarnessSourceSection` 注册使用 |
@@ -29,7 +29,7 @@ Loader 并发挂载各个条目，因此当其他环节失败时，某个界面

 `cordis:group` 与 `cordis:include` 一并注册，使一份组装能把一个提供方与它的消费方放进同一个 `isolate` realm。两者都通过宿主的模块管线加载，而非被包含树自身的说明符解析，这正是让本工作区之外的组装——放在 Harness home 下的 agent preset——能够使用 group 行的原因。

-配置中的裸插件 specifier（`@deepseek-ai/dsh-*`、npm 包）通过 Cordis Loader 的内部模块 loader 解析。仓库 bin 会安装 Loader 的可选 peer `node-addon-require-builtin`；外部调用方必须提供该组件，或者把插件安装到普通 Node import 解析可以找到的位置。相对 specifier 无需原生 helper，并以配置目录为基准解析。构建后的 `dsh-app-boot` 产物内嵌静态挂载的 Include 实现，但仍将 Loader 保持为外部依赖，因此 include 树与宿主会绑定到同一个 Loader peer。`dsh` 源码启动器还会将 manifest（元数据清单）声明的 workspace 包映射到其 TypeScript 源码；其配置门禁要求每个随附的原始／Web 裸插件都出现在解析所用 manifest 的 `dependencies` 中。
+配置中的裸插件 specifier（`@deepseek-ai/dsh-*`、npm 包）通过 Cordis Loader 的内部模块 loader 解析。默认情况下，它们从配置目录解析；封闭运行时会向 `boot` 或 `mountRootInclude` 传入 `bareModuleBaseUrl`，使已安装包树保持权威，即使配置位于另一个 Node 项目中也不受遮蔽。相对 specifier 始终以配置目录为基准解析。仓库 bin 会安装 Loader 的可选 peer `node-addon-require-builtin`；外部调用方必须提供该组件，或者把插件安装到普通 Node import 解析可以找到的位置。构建后的 `dsh-app-boot` 产物内嵌静态挂载的 Include 实现，但仍将 Loader 保持为外部依赖，因此 include 树与宿主会绑定到同一个 Loader peer。`dsh` 源码启动器还会将 manifest（元数据清单）声明的 workspace 包映射到其 TypeScript 源码；其配置门禁要求每个随附的原始／Web 裸插件都出现在解析所用 manifest 的 `dependencies` 中。

 此包不包含 loader 钩子，也不提供开发模式接口。[`dsh` 应用](../../../apps/cli/README.md) 持有自己的 Node 源码启动钩子，并在启动序列中使用这些 helper；构建后的消费方仍使用普通 Node 包解析。

@@ -9,7 +9,7 @@
 import { pathToFileURL } from 'node:url'
 import { readFileSync } from 'node:fs'
 import { parseEnv } from 'node:util'
-import { basename, dirname, resolve } from 'node:path'
+import { basename, dirname, isAbsolute, resolve } from 'node:path'
 import * as yaml from 'js-yaml'
 import { Context, type FiberState } from '@deepseek-ai/cordis'
 import Loader, { type Entry, type EntryOptions } from '@deepseek-ai/cordis-plugin-loader'
@@ -476,6 +476,8 @@ function groupedDump(
 * @param ctx - context carrying an initialized Loader service.
 * @param absoluteConfigPath - absolute YAML or JSON configuration path.
 * @param patches - initial app and user patches, applied in order.
+ * @param bareModuleBaseUrl - optional installed-host base for bare package
+ * names; relative names continue to resolve beside the configuration file.
 * @returns the created root Include entry, or `undefined` when a surface
 * disposed the whole tree (taking the Loader service with it) while the
 * transactional create was still settling entry lifecycle.
@@ -484,8 +486,21 @@ export async function mountRootInclude(
  ctx: Context,
  absoluteConfigPath: string,
  patches: readonly PatchOptions[] = [],
+  bareModuleBaseUrl?: string,
 ): Promise<Entry | undefined> {
-  ctx.loader.builtins.include = Include
+  ctx.loader.builtins.include = bareModuleBaseUrl === undefined
+    ? Include
+    : class HostResolvedRootInclude extends Include {
+      override import(name: string, getOuterStack?: () => string[]): unknown {
+        const specifier = isAbsolute(name) ? pathToFileURL(name).href : name
+        if (name.startsWith('.') || name.startsWith('cordis:')) return super.import(specifier, getOuterStack)
+        const internal = this.ctx.loader.internal
+        /* v8 ignore next -- Node supplies the internal loader; this preserves the
+           original diagnostic for hypothetical embedders without it. */
+        if (internal === undefined) return super.import(specifier, getOuterStack)
+        return internal.import(specifier, bareModuleBaseUrl, {})
+      }
+    }
  // `cordis:group` alongside it: a group row is how a composition gives one
  // `isolate` realm to a provider and its consumers together, and an agent
  // preset living outside this workspace cannot resolve `@deepseek-ai/cordis-plugin-group`
@@ -495,13 +510,14 @@ export async function mountRootInclude(
  // Pinned id: the bootstrap include is app glue, not a config row, and its
  // id appears in Loader failure chains — a random id would make startup
  // diagnostics unstable across runs (and snapshot fixtures).
+  const includeConfig: Include.Config = {
+    path: pathToFileURL(absoluteConfigPath).href,
+    ...patches.length > 0 ? { patches: [...patches] } : {},
+  }
  const rootInclude: EntryOptions = {
    id: 'include',
    name: 'cordis:include',
-    config: {
-      path: pathToFileURL(absoluteConfigPath).href,
-      ...patches.length > 0 ? { patches: [...patches] } : {},
-    },
+    config: includeConfig,
  }
  const includeId = await ctx.loader.create(rootInclude)
  const loader = ctx.get('loader')
@@ -709,14 +725,13 @@ export async function assertEntriesActivated(ctx: Context, binName: string): Pro

 /**
 * Boot the Loader against `absoluteConfigPath` and return only after the whole
- * tree settles. Entry names load through the Loader's internal module loader
- * against `baseUrl` (the config directory), which may live outside
- * `node_modules` reach and, unbuilt, cannot load vendored source; the
- * bootstrap include is therefore statically imported and mounted as the
- * `cordis:include` builtin, loading through the ambient module pipeline
- * (vite/tsx/plain ESM) while the included tree's own specifiers stay
- * config-relative. The package build embeds Include while leaving Loader
- * external, so the built include tree and host share one Loader peer. Loader
+ * tree settles. Relative entry names resolve against the config directory;
+ * bare package names resolve there by default or against an explicit
+ * `bareModuleBaseUrl` for closed packaged runtimes. The bootstrap include
+ * is statically imported and mounted as the `cordis:include` builtin, loading
+ * through the ambient module pipeline (vite/tsx/plain ESM). The package build
+ * embeds Include while leaving Loader external, so the built include tree and
+ * host share one Loader peer. Loader
 * settlement rejects startup failures, which `boot` wraps after disposing the
 * partial context; a missing fiber or never-activating entry is rejected by
 * the final audit, {@link assertEntriesActivated}, which rethrows a plugin's
@@ -729,6 +744,9 @@ export async function assertEntriesActivated(ctx: Context, binName: string): Pro
 * @param patches - optional overlay patches applied over the included tree
 * (see {@link loadOptionalPatches}); an empty list mounts none.
 * @param prepare - optional host setup run after Loader installation and before any config-tree entry mounts.
+ * @param bareModuleBaseUrl - optional installed-host base for bare package
+ * names; use it when the host, rather than the configuration project, owns the
+ * complete plugin set.
 * @returns the root context once every entry has started, or as soon as a
 * surface disposed the tree while startup was still in flight.
 * @throws a labelled error after disposing the partial context — `host
@@ -740,6 +758,7 @@ export async function boot(
  absoluteConfigPath: string,
  patches?: PatchOptions[],
  prepare?: (ctx: Context) => Promise<void> | void,
+  bareModuleBaseUrl?: string,
 ): Promise<Context> {
  const ctx = new Context()
  // Two failure labels: `prepare` runs before any config-tree entry mounts,
@@ -751,7 +770,7 @@ export async function boot(
    await ctx.plugin(Loader)
    await prepare?.(ctx)
    stage = 'plugin tree failed to load'
-    await mountRootInclude(ctx, absoluteConfigPath, patches)
+    await mountRootInclude(ctx, absoluteConfigPath, patches, bareModuleBaseUrl)
    // A surface can finish and dispose the whole tree while startup is still
    // in flight, before the last entry settles. The Loader service goes with
    // it, and the activation audit describes a live tree — reading `ctx.loader`
@@ -1,6 +1,7 @@
 import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join, resolve, sep } from 'node:path'
+import { pathToFileURL } from 'node:url'
 import { describe, expect, it, vi } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import SystemPrompt, { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
@@ -557,6 +558,73 @@ describe('boot', () => {
    }
  })

+  it('can resolve bare plugins from the harness when the config project shadows their package name', async () => {
+    const dir = tmp()
+    const harness = tmp()
+    const absolutePlugin = join(dir, 'absolute.mjs')
+    const shadow = join(dir, 'node_modules', '@deepseek-ai', 'dsh-system-prompt')
+    const harnessPlugin = join(harness, 'node_modules', '@deepseek-ai', 'dsh-system-prompt')
+    mkdirSync(shadow, { recursive: true })
+    mkdirSync(harnessPlugin, { recursive: true })
+    writeFileSync(join(shadow, 'package.json'), JSON.stringify({
+      name: '@deepseek-ai/dsh-system-prompt',
+      type: 'module',
+      exports: './index.mjs',
+    }))
+    writeFileSync(join(shadow, 'index.mjs'), [
+      'export function apply(ctx) {',
+      '  ctx.provide("shadowPluginLoaded", true)',
+      '}',
+      '',
+    ].join('\n'))
+    writeFileSync(join(harnessPlugin, 'package.json'), JSON.stringify({
+      name: '@deepseek-ai/dsh-system-prompt',
+      type: 'module',
+      exports: './index.mjs',
+    }))
+    writeFileSync(join(harnessPlugin, 'index.mjs'), [
+      'export function apply(ctx) {',
+      '  ctx.provide("harnessPluginLoaded", true)',
+      '}',
+      '',
+    ].join('\n'))
+    writeFileSync(join(dir, 'relative.mjs'), 'export function apply(ctx) { ctx.provide("relativePluginLoaded", true) }\n')
+    writeFileSync(absolutePlugin, 'export function apply(ctx) { ctx.provide("absolutePluginLoaded", true) }\n')
+    const entries = [
+      '- id: prompt',
+      "  name: '@deepseek-ai/dsh-system-prompt'",
+      '- id: relative',
+      "  name: './relative.mjs'",
+    ]
+    const configOwnedPath = join(dir, 'config-owned.cordis.yml')
+    writeFileSync(configOwnedPath, [...entries, ''].join('\n'))
+    const hostOwnedPath = join(dir, 'host-owned.cordis.yml')
+    writeFileSync(hostOwnedPath, [
+      ...entries,
+      '- id: absolute',
+      `  name: ${JSON.stringify(absolutePlugin)}`,
+      '',
+    ].join('\n'))
+    const configOwned = await boot(NAME, configOwnedPath)
+    try {
+      expect(configOwned.get('shadowPluginLoaded')).toBe(true)
+      expect(configOwned.get('systemPrompt')).toBeUndefined()
+      expect(configOwned.get('relativePluginLoaded')).toBe(true)
+    } finally {
+      await configOwned.fiber.dispose()
+    }
+    const harnessBaseUrl = pathToFileURL(join(harness, 'entry.mjs')).href
+    const ctx = await boot(NAME, hostOwnedPath, undefined, undefined, harnessBaseUrl)
+    try {
+      expect(ctx.get('harnessPluginLoaded')).toBe(true)
+      expect(ctx.get('shadowPluginLoaded')).toBeUndefined()
+      expect(ctx.get('relativePluginLoaded')).toBe(true)
+      expect(ctx.get('absolutePluginLoaded')).toBe(true)
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
  it('runs host preparation before the Loader tree mounts', async () => {
    const dir = tmp()
    writeFileSync(join(dir, 'noop.mjs'), 'export const name = "noop"\nexport function apply() {}\n')
@@ -91,9 +91,9 @@
    # assembly fact of dsh-web-app, never user config), mounts the
    # frontend-static fallback owner, registers the web-surface prompt
    # section and bash runtime variables, and prints the URL line. `dsh web`
-    # patches mode/lanAddresses over these defaults; complete-prompt overlays
-    # set surfaceContext false to suppress every model- and shell-visible Web
-    # runtime contribution.
+    # patches mode/lanAddresses over these defaults. A complete agent-preset
+    # persona suppresses the prompt section for that agent while retaining
+    # these host-owned shell variables.
    - id: web-runtime
      name: '@deepseek-ai/dsh-web-app'
      config:
@@ -42,7 +42,7 @@ export const en: Record<AgentPresetSettingsKey, string> = {
    'All Standard mode capabilities, with tools exposed through the Code Mode SDK so the model can combine multi-step operations in one TypeScript program.',
  presetMinimalName: 'Minimal mode',
  presetMinimalDescription:
-    'Two-tool coding agent with only bash and str_replace_editor, for benchmarks and minimal reproductions.',
+    'Two-tool coding agent with persistent bash and str_replace_editor.',
  presetCordisName: 'Creator mode',
  presetCordisDescription:
    'Built for creating custom agent presets, with all Standard mode capabilities plus runtime inspection, plugin experiments, and preset-authoring guidance.',
@@ -103,7 +103,7 @@ export const zh: Record<AgentPresetSettingsKey, string> = {
  presetCodeName: '代码模式',
  presetCodeDescription: '具备标准模式的全部能力，并通过 Code Mode SDK 呈现工具，让模型用一个 TypeScript 程序组合多步操作。',
  presetMinimalName: '极简模式',
-  presetMinimalDescription: '仅提供 bash 与 str_replace_editor 的双工具编码 Agent，用于基准测试和最小复现。',
+  presetMinimalDescription: '仅提供持久 bash 与 str_replace_editor 的双工具编码 Agent。',
  presetCordisName: '创造模式',
  presetCordisDescription: '用于创建自定义 Agent preset：具备标准模式的全部能力，并提供运行时检查、插件实验和 preset 创作指导。',
  duplicate: '复制',
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/system-prompt/README.md
-README.md: 13b05bfcd19212ade42f22ece455871d022e6260
-README.zh.md: 0f9e7a2358134018975db1bc3c6b7206a274b3ec
+README.md: cedda783d549633f5be9765a9a074e968d99500d
+README.zh.md: 41729cdd1cfe6ebbd86f38c15bab5c50bd6ff7d2
@@ -16,19 +16,19 @@ System prompt assembly registry. Plugins contribute ordered sections, tool schem

 ### Public API

- `ctx.systemPrompt.section(section: PromptSection): () => void` Contribute a section. The layer is the calling context's scope: `agent.ctx` contributes to that agent alone, shadowing a same-named global section there. Duplicate names within one layer and non-finite orders throw. Disposed with the calling fiber.
+- `ctx.systemPrompt.section(section: PromptSection): () => void` Contribute a section. The layer is the calling context's scope: `agent.ctx` contributes to that agent alone, shadowing a same-named global section there. A `complete: true` section becomes the exact complete prompt after the assembly waterfall; more than one effective complete section rejects assembly. Duplicate names within one layer and non-finite orders throw. Disposed with the calling fiber.
 - `ctx.systemPrompt.tools(provider: (context: AssembleContext) => ToolProviderResult): () => void` Contribute tool schemas, evaluated at each assembly with that assembly's context. `ToolProviderResult` = `{ schemas, knownNames? }`: `schemas` is the post-restriction visible set; `knownNames` is the pre-restriction universe used by `toolOrder`. A provider must not return a schema named `TOOL_ORDER_REST`. Scoped providers are consulted only for their scope's assemblies. Disposed with the calling fiber.
 - `ctx.systemPrompt.variable(name: string, provider: (context) => string | undefined): () => void` Contribute a prompt variable, referenced from section text as `{{name}}`. Scoped variables shadow a same-named global for that agent. Duplicate-in-layer or unreferenceable names throw; `undefined` means "no value for this assembly". Disposed with the calling fiber.
- `ctx.systemPrompt.assemble(context?: AssembleContext): Promise<PromptAssembly>` Assemble the prompt for one caller: the global layer merged with `context.scope`'s layer, with tool schemas detached before the transform waterfall. Runs through the scope-filtered `system-prompt/assemble` waterfall and returns its authoritative result. An optional `context.signal` explicitly controls this assembly request; providers and listeners may cooperate with it but must not retain it for another turn. Rejects when a configured `toolOrder` names a tool outside the providers' `knownNames` universe, or when a provider returns the reserved rest-entry name.
+- `ctx.systemPrompt.assemble(context?: AssembleContext): Promise<PromptAssembly>` Assemble the prompt for one caller: the global layer merged with `context.scope`'s layer, with tool schemas detached before the transform waterfall. Runs through the scope-filtered `system-prompt/assemble` waterfall, then restores an effective complete section as the sole prompt section. An optional `context.signal` explicitly controls this assembly request; providers and listeners may cooperate with it but must not retain it for another turn. Rejects for multiple complete sections, when a configured `toolOrder` names a tool outside the providers' `knownNames` universe, or when a provider returns the reserved rest-entry name.

 ### Live events

-`system-prompt/assemble` is authoritative; listeners that replace entries must preserve any active Code Mode or structured-output protocol. Use [`ToolRegistry.restrict()`](../tools/README.md) when filtering must stay aligned across presentation, lookup, and execution. Registry-change notifications are unfiltered. The generated region of [system-prompt.md](../../../docs/subsystems/system-prompt.md#cordis-surface) owns signatures and dispatch contracts.
+`system-prompt/assemble` is authoritative for ordinary sections; a complete section is the final prompt constraint applied after the waterfall. Listeners that replace entries must preserve any active Code Mode or structured-output protocol. Use [`ToolRegistry.restrict()`](../tools/README.md) when filtering must stay aligned across presentation, lookup, and execution. Registry-change notifications are unfiltered. The generated region of [system-prompt.md](../../../docs/subsystems/system-prompt.md#cordis-surface) owns signatures and dispatch contracts.

 ### Key types

 - `AssembleContext` — what one `assemble()` call is FOR. Merge-extensible; declares `scope?: ScopeKey` (the layer selector) and `signal?: AbortSignal` (the explicit request control capability) here, while `dsh-agent` declares `agent?: Agent` (the typed DX field — never set without `scope`; use `assembleContextFor(agent, signal)`). Providers must tolerate absent fields because a bare `assemble()` carries an empty, scope-less, signal-less context. `signal` is a request value, not part of the ambient Agent execution frame.
- `PromptSection` — `{ name, order, text }`. Sections are concatenated in ascending `order`. Order bands: `-100` is the harness identity, `0` the deployment persona, tool guidance uses `100–199`.
+- `PromptSection` — `{ name, order, text, complete? }`. Sections are concatenated in ascending `order`. Order bands: `-100` is the harness identity, `0` the deployment persona, tool guidance uses `100–199`. One effective `complete` section suppresses all other sections after cooperative assembly.
 - `PromptAssembly` — `{ sections: AssembledSection[], tools: ToolSchema[], variables: Record<string, string | undefined> }`. Section texts arrive resolved but not yet interpolated; `variables` holds every registered variable resolved against the context. Tool schemas are part of the assembly by design: "what the model is told it can do" is one coherent thing, even though adapters transmit schemas as a separate wire field.
 - `renderPrompt(assembly)` — interpolates `{{variable}}` references in each section, drops empty sections, joins with blank lines. STRICT: an unknown reference (`Object.hasOwn` lookup — prototype names like `{{constructor}}` are unknown), a registered-but-valueless reference, a malformed complete `{{…}}` group, or a `{{` that opens no complete group while a `}}` still follows (`{{{model}}}`) throws — fail loud beats shipping a malformed prompt. A lone `{{` with no `}}` anywhere after it passes through verbatim; substituted values are never re-scanned.

@@ -39,7 +39,7 @@ Merge-extensible: plugins can declare extra fields on `PromptAssembly` and `Asse
 - Section providers: tool packages own their cross-call guidance (`tool:bash`, `tool:read`, …); this plugin owns `harness:identity` and `deployment:persona`.
 - Variable providers: the agent loop registers `model` and `cwd`; any plugin can register the facts it owns (a future `date`, git state, …).
 - Tool schema providers: `ToolRegistry` registers itself as a tool provider automatically.
- The [`system-prompt/assemble` waterfall](#live-events): cooperatively mutate or replace the assembly per caller.
+- The [`system-prompt/assemble` waterfall](#live-events): cooperatively mutate or replace the assembly per caller before any complete-section constraint is enforced.

 Design rationale: [the prompt-variables Agent Note](../../../.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md).

@@ -49,7 +49,7 @@ Design rationale: [the prompt-variables Agent Note](../../../.agents/notes/imple

 #### What the model sees

-By default every assembly starts with the harness identity below, then the configured persona and ordered plugin sections after strict variable interpolation. `includeHarnessIdentity: false` omits only that fixed opener for a deployment that owns the complete compatibility persona. Empty sections disappear; scoped sections and variables can shadow globals for one agent. The final `system-prompt/assemble` waterfall result is authoritative, so an expert listener's changes determine the delivered prompt and tool schemas.
+By default every assembly starts with the harness identity below, then the configured persona and ordered plugin sections after strict variable interpolation. `includeHarnessIdentity: false` omits only that fixed opener. Empty sections disappear; scoped sections and variables can shadow globals for one agent. The `system-prompt/assemble` waterfall determines the delivered prompt and tool schemas unless one effective section declares itself complete; that exact section then becomes the whole system prompt while the waterfall's contexts, tools, and variables remain.

 ##### Harness identity

@@ -16,21 +16,21 @@

 ### 公开 API

- `ctx.systemPrompt.section(section: PromptSection): () => void`：贡献一个段。层由调用上下文的作用域决定：`agent.ctx` 只为该 agent 贡献，并在该处遮蔽同名全局段。同一层中的重复名称和非有限顺序会抛出。随调用 fiber 一并 dispose（资源释放）。
+- `ctx.systemPrompt.section(section: PromptSection): () => void`：贡献一个段。层由调用上下文的作用域决定：`agent.ctx` 只为该 agent 贡献，并在该处遮蔽同名全局段。一个 `complete: true` 段会在组装 waterfall 之后成为精确的完整提示词；有效 complete 段超过一个时，组装会被拒绝。同一层中的重复名称和非有限顺序会抛出。随调用 fiber 一并 dispose（资源释放）。
 - `ctx.systemPrompt.tools(provider: (context: AssembleContext) => ToolProviderResult): () => void`：贡献工具 schema；每次组装时使用该次组装的上下文求值。`ToolProviderResult` = `{ schemas, knownNames? }`：`schemas` 是限制后的可见集合；`knownNames` 是限制前由 `toolOrder` 使用的全集。提供方不得返回名为 `TOOL_ORDER_REST` 的 schema。带作用域提供方只在其作用域的组装中查询。随调用 fiber 一并 dispose。
 - `ctx.systemPrompt.variable(name: string, provider: (context) => string | undefined): () => void`：贡献提示词变量，在段文本中以 `{{name}}` 引用。带作用域变量会为该 agent 遮蔽同名全局变量。同层重复或无法引用的名称会抛出；`undefined` 表示「本次组装没有值」。随调用 fiber 一并 dispose。
- `ctx.systemPrompt.assemble(context?: AssembleContext): Promise<PromptAssembly>`：为一个调用方组装提示词：将全局层与 `context.scope` 的层合并，并在变换 waterfall 前分离工具 schema。它经过按作用域筛选的 `system-prompt/assemble` waterfall，并返回其权威结果。可选的 `context.signal` 显式控制本次组装请求；提供方与监听器可以配合该信号，但不得将它保留给另一轮次。当已配置的 `toolOrder` 指名提供方 `knownNames` 全集以外的工具，或提供方返回保留的其余项名称时，调用会被拒绝。
+- `ctx.systemPrompt.assemble(context?: AssembleContext): Promise<PromptAssembly>`：为一个调用方组装提示词：将全局层与 `context.scope` 的层合并，并在变换 waterfall 前分离工具 schema。它经过按作用域筛选的 `system-prompt/assemble` waterfall，之后将一个有效的 complete 段恢复为唯一的提示词段落。可选的 `context.signal` 显式控制本次组装请求；提供方与监听器可以配合该信号，但不得将它保留给另一轮次。存在多个 complete 段、已配置的 `toolOrder` 指名提供方 `knownNames` 全集以外的工具，或提供方返回保留的其余项名称时，调用会被拒绝。

 <a id="live-events"></a>

 ### 实时事件

-`system-prompt/assemble` 是权威来源；替换条目的监听器必须保留任何活动 Code Mode 或结构化输出协议。筛选需要在呈现、查找与执行之间保持一致时，应使用 [`ToolRegistry.restrict()`](../tools/README.md)。注册表变更通知不经过筛选。[system-prompt.md](../../../docs/subsystems/system-prompt.md#cordis-surface) 的生成区块拥有签名与分发约定。
+`system-prompt/assemble` 对普通段落具有权威性；complete 段是在 waterfall 之后应用的最终提示词约束。替换条目的监听器必须保留任何活动 Code Mode 或结构化输出协议。筛选需要在呈现、查找与执行之间保持一致时，应使用 [`ToolRegistry.restrict()`](../tools/README.md)。注册表变更通知不经过筛选。[system-prompt.md](../../../docs/subsystems/system-prompt.md#cordis-surface) 的生成区块拥有签名与分发约定。

 ### 关键类型

 - `AssembleContext`：说明一次 `assemble()` 调用的用途。它可通过合并扩展；此处声明 `scope?: ScopeKey`（层选择器）与 `signal?: AbortSignal`（显式请求控制能力），而 `dsh-agent` 声明 `agent?: Agent`（类型化 DX 字段；绝不能在没有 `scope` 时设置，应使用 `assembleContextFor(agent, signal)`）。提供方必须容忍字段缺席，因为裸 `assemble()` 携带的是无作用域、无信号的空上下文。`signal` 是请求值，不是环境 Agent 执行 frame 的一部分。
- `PromptSection`：`{ name, order, text }`。各段按 `order` 升序拼接。顺序区间：`-100` 是 harness 身份，`0` 是部署 persona，工具引导使用 `100–199`。
+- `PromptSection`：`{ name, order, text, complete? }`。各段按 `order` 升序拼接。顺序区间：`-100` 是 harness 身份，`0` 是部署 persona，工具引导使用 `100–199`。协作式组装完成后，一个有效的 `complete` 段会抑制其他所有段落。
 - `PromptAssembly`：`{ sections: AssembledSection[], tools: ToolSchema[], variables: Record<string, string | undefined> }`。段文本到达时已解析，但尚未插值；`variables` 包含对上下文解析后的每个已注册变量。工具 schema 按设计属于组装结果：「模型获知自己能做什么」是一个连贯整体，尽管适配器把 schema 作为独立 wire 字段传输。
 - `renderPrompt(assembly)`：插值每个段中的 `{{variable}}` 引用，删除空段，并用空行连接。严格规则：未知引用（使用 `Object.hasOwn` 查找，因此 `{{constructor}}` 等原型名称未知）、已注册但无值的引用、格式错误的完整 `{{…}}` 组，或一个起始 `{{` 没有打开完整组、但后面仍有 `}}`（`{{{model}}}`），都会抛出；明确失败胜过交付格式错误的提示词。孤立的 `{{` 如果后面任何位置都没有 `}}`，会按字面量通过；替换值绝不再次扫描。

@@ -41,7 +41,7 @@
 - 段提供方：工具包拥有跨调用引导（`tool:bash`、`tool:read` 等）；此插件拥有 `harness:identity` 与 `deployment:persona`。
 - 变量提供方：agent loop（智能体循环）注册 `model` 与 `cwd`；任何插件都可以注册自己拥有的事实（未来的 `date`、git 状态等）。
 - 工具 schema 提供方：`ToolRegistry` 自动将自身注册为工具提供方。
- [`system-prompt/assemble` waterfall](#live-events)：按调用方协作式修改或替换组装结果。
+- [`system-prompt/assemble` waterfall](#live-events)：按调用方协作式修改或替换组装结果，之后再实施 complete 段约束。

 设计原理：[提示词变量 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-05-prompt-variables-and-tool-guidance-ownership.md)。

@@ -51,7 +51,7 @@

 #### 模型看到的内容

-默认情况下，每次组装都从下方 harness 身份开始，然后在严格变量插值后追加已配置 persona 与有序插件段。`includeHarnessIdentity: false` 仅为拥有完整兼容 persona 的部署省略这个固定开场白。空段会消失；带作用域的段和变量可以为一个 agent 遮蔽全局项。最终 `system-prompt/assemble` waterfall 结果是权威来源，因此专家监听器的变更决定交付的提示词与工具 schema。
+默认情况下，每次组装都从下方 harness 身份开始，然后在严格变量插值后追加已配置 persona 与有序插件段。`includeHarnessIdentity: false` 仅省略这个固定开场白。空段会消失；带作用域的段和变量可以为一个 agent 遮蔽全局项。`system-prompt/assemble` waterfall 决定交付的提示词与工具 schema，除非一个有效段声明自身为 complete；此时，该确切段落会成为完整的系统提示词，而 waterfall 得到的上下文、工具和变量保持不变。

 ##### Harness 身份

@@ -21,7 +21,9 @@ declare module '@deepseek-ai/cordis' {
     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners
     * receive only that scope's assemblies. The returned value is authoritative.
     * A supplied signal controls only this explicit assembly request and must not
-     * be retained to control later turns.
+     * be retained to control later turns. A registered complete section is
+     * restored after this waterfall, so listeners cannot add to or replace
+     * that scope's system prompt.
     * @param assembly - the mutable assembly built from registered providers.
     * @param context - the caller's per-assembly context.
     * @mode waterfall
@@ -63,6 +65,13 @@ export interface PromptSection {
   * interpolated later, by {@link renderPrompt}.
   */
  readonly text: string | ((context: AssembleContext) => string)
+  /**
+   * Treat this contribution as the complete system prompt. Assembly still
+   * runs the cooperative waterfall so tools, contexts, and variables can be
+   * resolved, then restores this exact section as the sole prompt section.
+   * More than one effective complete section makes assembly fail.
+   */
+  readonly complete?: boolean
 }

 /** Dynamic model context materialized as a durable user-role snapshot. */
@@ -428,9 +437,11 @@ export class SystemPrompt extends Service {
  /**
   * Assemble global and scoped providers, detach tool parameters, apply
   * canonical ordering, then run the assembly waterfall. Scoped sections and
-   * variables shadow globals; the returned waterfall value is authoritative.
+   * variables shadow globals. The returned waterfall value is authoritative
+   * except that an effective complete section is restored afterwards as the
+   * sole prompt section.
   * @param context - the optional scope and plugin-defined assembly fields.
-   * @returns the authoritative post-waterfall assembly.
+   * @returns the post-waterfall assembly with any complete prompt enforced.
   */
  // Keep configuration failures on the declared asynchronous error path.
  async assemble(context: AssembleContext = {}): Promise<PromptAssembly> {
@@ -467,13 +478,23 @@ export class SystemPrompt extends Service {
      collected.push(...schemas)
      for (const name of acceptedKnownNames) knownNames.add(name)
    }
-    const assembly: PromptAssembly = {
-      sections: [...sectionByName.values()]
-        .sort((a, b) => a.order - b.order)
-        .map(section => ({
+    const sectionDefinitions = [...sectionByName.values()].sort((a, b) => a.order - b.order)
+    const completeSections = sectionDefinitions.filter(section => section.complete === true)
+    if (completeSections.length > 1) {
+      throw new Error(`multiple complete prompt sections are active: ${completeSections.map(section => JSON.stringify(section.name)).join(', ')}`)
+    }
+    let completeSection: AssembledSection | undefined
+    const sections = sectionDefinitions
+      .map((section) => {
+        const assembled = {
          name: section.name,
          text: typeof section.text === 'function' ? section.text(context) : section.text,
-        })),
+        }
+        if (section.complete === true) completeSection = { ...assembled }
+        return assembled
+      })
+    const assembly: PromptAssembly = {
+      sections,
      contexts: [...contextByName.values()]
        .sort((a, b) => a.order - b.order)
        .map(entry => ({
@@ -483,10 +504,12 @@ export class SystemPrompt extends Service {
      tools: orderTools(collected, this.toolOrder, knownNames),
      variables,
    }
-    return this.ctx.waterfall(
+    const transformed = await this.ctx.waterfall(
      scopeTarget(this, scope), 'system-prompt/assemble', assembly, context,
      () => Promise.resolve(assembly),
    )
+    if (completeSection === undefined) return transformed
+    return { ...transformed, sections: [completeSection] }
  }
 }

@@ -264,6 +264,34 @@ describe('SystemPrompt', () => {
    expect(assembly.sections).toHaveLength(0)
  })

+  it('restores one complete section after the assembly waterfall', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    ctx.systemPrompt.section({ name: 'complete', order: 10, text: 'Exact prompt.', complete: true })
+    ctx.systemPrompt.section({ name: 'extra', order: 20, text: 'extra' })
+    ctx.on('system-prompt/assemble', async (assembly, _context, next) => {
+      const complete = assembly.sections.find(section => section.name === 'complete')
+      if (complete === undefined) throw new Error('complete section missing before waterfall')
+      complete.text = 'mutated'
+      assembly.sections.push({ name: 'late', text: 'late' })
+      return next()
+    }, { prepend: true })
+
+    expect((await ctx.systemPrompt.assemble()).sections).toEqual([
+      { name: 'complete', text: 'Exact prompt.' },
+    ])
+  })
+
+  it('rejects multiple effective complete sections', async () => {
+    const ctx = new Context()
+    await ctx.plugin(SystemPrompt)
+    ctx.systemPrompt.section({ name: 'first', order: 10, text: 'first', complete: true })
+    ctx.systemPrompt.section({ name: 'second', order: 20, text: 'second', complete: true })
+
+    await expect(ctx.systemPrompt.assemble())
+      .rejects.toThrow('multiple complete prompt sections are active: "first", "second"')
+  })
+
  it('assembles snapshots so one-step mutations do not leak into future assemblies', async () => {
    const ctx = new Context()
    await ctx.plugin(SystemPrompt)
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/examples/jsonrpc-demo/README.md
-README.md: fff8e78698cd3d6320606084ef5c533be7c52633
-README.zh.md: 75382b97ea1837cf1415e8a7f5004206596e168c
+README.md: 40ced3ee1fe2d3eac69b82501d417130267d7634
+README.zh.md: 451bdf7428f8265750082af240418d4653bb8595
@@ -2,7 +2,7 @@

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

-Bin-only app that boots an external `cordis.yml`; its [`jsonrpc`](../../scaffold/server/README.md) entry serves SDK clients over newline-delimited stdio. The config composes the spine, backends, and serving plugin. The published bin is `dsh-jsonrpc-agent`, and `lib/bin.js` also ships as the `dsh-jsonrpc-agent-pkg` [single-executable runtime](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md) used by the Python SDK.
+Bin-only app that boots an external `cordis.yml`; its [`jsonrpc`](../../scaffold/server/README.md) entry serves SDK clients over newline-delimited stdio. The config composes the spine, backends, and serving plugin. The published `dsh-jsonrpc-agent` bin resolves bare plugins from the configuration project. The Python SDK's `dsh-jsonrpc-agent-pkg` [single-executable runtime](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md) uses `lib/packaged-bin.js` instead: packaged bare plugins resolve from its closed runtime tree, while relative plugins remain configuration-relative.

 ## Config discovery

@@ -2,7 +2,7 @@

 [English](README.md) | 中文

-只包含 bin 的应用，启动外部 `cordis.yml`；其 [`jsonrpc`](../../scaffold/server/README.md) 入口通过按换行分隔的 stdio 为 SDK 客户端提供服务。配置负责组合主干、后端和服务插件。发布的 bin 名为 `dsh-jsonrpc-agent`，`lib/bin.js` 还会作为 Python SDK 使用的 `dsh-jsonrpc-agent-pkg` [单文件可执行运行时](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md)交付。
+只包含 bin 的应用，启动外部 `cordis.yml`；其 [`jsonrpc`](../../scaffold/server/README.md) 入口通过按换行分隔的 stdio 为 SDK 客户端提供服务。配置负责组合主干、后端和服务插件。发布的 `dsh-jsonrpc-agent` bin 从配置项目解析裸插件。Python SDK 的 `dsh-jsonrpc-agent-pkg` [单文件可执行运行时](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md)改用 `lib/packaged-bin.js`：已打包的裸插件从封闭运行时包树解析，相对插件仍以配置目录为基准。

 ## 配置发现

@@ -22,6 +22,10 @@
      "types": "./lib/types/bin.d.ts",
      "default": "./lib/bin.js"
    },
+    "./packaged-bin": {
+      "types": "./lib/types/packaged-bin.d.ts",
+      "default": "./lib/packaged-bin.js"
+    },
    "./src/*": "./src/*",
    "./package.json": "./package.json"
  },
@@ -29,6 +33,7 @@
    "lib/index.js",
    "lib/invariant.js",
    "lib/bin.js",
+    "lib/packaged-bin.js",
    "lib/types/**/*.d.ts"
  ],
  "license": "BSD-3-Clause",
@@ -1,52 +1,11 @@
 #!/usr/bin/env node
 /**
- * Boots an external `cordis.yml`; its `@deepseek-ai/dsh-jsonrpc` entry serves
- * newline-delimited JSON-RPC on stdio. `$DSH_CORDIS_CONFIG` wins over `argv[2]`;
- * empty or missing paths exit 1, with no default config or `DSH_SNAPSHOT` mode.
- * App-boot owns env loading, Loader guards, and settled-tree startup.
- * stdin EOF and SIGTERM dispose the root context and exit 0; SIGINT exits 130.
- * Protocol `shutdown` belongs to the server plugin. Stdout is reserved for frames.
+ * Generic JSON-RPC agent bin. External configurations own their bare plugin
+ * packages; the packaged runtime uses `packaged-bin.ts` instead.
 *
 * @module @deepseek-ai/dsh-jsonrpc-demo/bin
 */

-import { existsSync } from 'node:fs'
-import { boot, installFailLoud, loadEnv, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
+import { runJsonrpcAgent } from './runner.ts'

-const NAME = 'dsh-jsonrpc-agent'
-
-/* v8 ignore start -- composition over tested app-boot/jsonrpc and executable acceptance paths */
-installFailLoud(NAME)
-loadEnv(NAME)
-
-// Env wins over argv; empty values are absent. External config defines the deployment.
-const fromEnv = process.env['DSH_CORDIS_CONFIG']
-const fromArgv = process.argv[2]
-const requested = fromEnv !== undefined && fromEnv !== ''
-  ? fromEnv
-  : fromArgv !== undefined && fromArgv !== '' ? fromArgv : undefined
-const configPath = requested === undefined ? undefined : resolveConfigPath(requested, undefined)
-if (configPath === undefined || !existsSync(configPath)) {
-  process.stderr.write(
-    `usage: ${NAME} <path/to/cordis.yml> (or set DSH_CORDIS_CONFIG=<path>, which wins); the config is required — there is no built-in fallback\n`,
-  )
-  process.exit(1)
-}
-
-const ctx = await boot(NAME, configPath)
-let exiting = false
-
-async function disposeAndExit(code: number): Promise<void> {
-  if (exiting) return
-  exiting = true
-  try {
-    await ctx.fiber.dispose()
-  } finally {
-    process.exit(code)
-  }
-}
-
-process.stdin.on('end', () => { void disposeAndExit(0) })
-process.on('SIGTERM', () => { void disposeAndExit(0) })
-process.on('SIGINT', () => { void disposeAndExit(130) })
-/* v8 ignore stop */
+await runJsonrpcAgent()
@@ -1,7 +1,8 @@
 /**
- * Bin-only app package: `bin.ts` discovers an external `cordis.yml` and owns
- * process exit. This module exports no composition plugin; the config chooses
- * whether to load the {@link @deepseek-ai/dsh-jsonrpc} serving plugin.
+ * Bin-only app package: its generic and packaged entries discover an external
+ * `cordis.yml` and own process exit. This module exports no composition plugin;
+ * the config chooses whether to load the
+ * {@link @deepseek-ai/dsh-jsonrpc} serving plugin.
 *
 * @module @deepseek-ai/dsh-jsonrpc-demo
 */
@@ -0,0 +1,12 @@
+#!/usr/bin/env node
+/**
+ * Closed-runtime JSON-RPC agent bin. Bare plugins resolve from the installed
+ * runtime closure while relative plugins remain configuration-relative.
+ *
+ * @module @deepseek-ai/dsh-jsonrpc-demo/packaged-bin
+ */
+
+import { runJsonrpcAgent } from './runner.ts'
+
+/* v8 ignore next -- exercised through the built Python runtime carriers */
+await runJsonrpcAgent(import.meta.url)
@@ -0,0 +1,55 @@
+/**
+ * Shared process lifecycle for the generic and closed-runtime JSON-RPC bins.
+ *
+ * @module @deepseek-ai/dsh-jsonrpc-demo/runner
+ */
+
+import { existsSync } from 'node:fs'
+import { boot, installFailLoud, loadEnv, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
+
+/* v8 ignore start -- composition over tested app-boot/jsonrpc and executable acceptance paths */
+const NAME = 'dsh-jsonrpc-agent'
+
+/**
+ * Boot the explicitly selected external configuration and own process exit.
+ * @param bareModuleBaseUrl - optional installed-runtime base for bare plugins;
+ * omit it when the configuration project owns its plugin packages.
+ * @returns after process handlers are installed; process lifetime then belongs
+ * to stdin and signal events.
+ */
+export async function runJsonrpcAgent(bareModuleBaseUrl?: string): Promise<void> {
+  installFailLoud(NAME)
+  loadEnv(NAME)
+
+  // Env wins over argv; empty values are absent. External config defines the deployment.
+  const fromEnv = process.env['DSH_CORDIS_CONFIG']
+  const fromArgv = process.argv[2]
+  const requested = fromEnv !== undefined && fromEnv !== ''
+    ? fromEnv
+    : fromArgv !== undefined && fromArgv !== '' ? fromArgv : undefined
+  const configPath = requested === undefined ? undefined : resolveConfigPath(requested, undefined)
+  if (configPath === undefined || !existsSync(configPath)) {
+    process.stderr.write(
+      `usage: ${NAME} <path/to/cordis.yml> (or set DSH_CORDIS_CONFIG=<path>, which wins); the config is required — there is no built-in fallback\n`,
+    )
+    process.exit(1)
+  }
+
+  const ctx = await boot(NAME, configPath, undefined, undefined, bareModuleBaseUrl)
+  let exiting = false
+
+  async function disposeAndExit(code: number): Promise<void> {
+    if (exiting) return
+    exiting = true
+    try {
+      await ctx.fiber.dispose()
+    } finally {
+      process.exit(code)
+    }
+  }
+
+  process.stdin.on('end', () => { void disposeAndExit(0) })
+  process.on('SIGTERM', () => { void disposeAndExit(0) })
+  process.on('SIGINT', () => { void disposeAndExit(130) })
+}
+/* v8 ignore stop */
@@ -1,15 +1,21 @@
 import { defineConfig } from 'tsdown'

-/**
- * Build the doc-only module and CLI entry; `tsc -b` supplies declarations.
- */
-export default defineConfig({
-  entry: ['lib/types/index.js', 'lib/types/invariant.js', 'lib/types/bin.js'],
-  outDir: 'lib',
-  format: ['esm'],
-  platform: 'node',
-  target: 'es2024',
-  fixedExtension: false,
-  dts: false,
-  clean: false,
-})
+/** Builds each published entry as a self-contained file admitted by the package whitelist. */
+export default defineConfig([
+  {
+    entry: ['lib/types/index.js'], outDir: 'lib', format: ['esm'], platform: 'node', target: 'es2024',
+    fixedExtension: false, outputOptions: { codeSplitting: false }, dts: false, clean: false,
+  },
+  {
+    entry: ['lib/types/invariant.js'], outDir: 'lib', format: ['esm'], platform: 'node', target: 'es2024',
+    fixedExtension: false, outputOptions: { codeSplitting: false }, dts: false, clean: false,
+  },
+  {
+    entry: ['lib/types/bin.js'], outDir: 'lib', format: ['esm'], platform: 'node', target: 'es2024',
+    fixedExtension: false, outputOptions: { codeSplitting: false }, dts: false, clean: false,
+  },
+  {
+    entry: ['lib/types/packaged-bin.js'], outDir: 'lib', format: ['esm'], platform: 'node', target: 'es2024',
+    fixedExtension: false, outputOptions: { codeSplitting: false }, dts: false, clean: false,
+  },
+])
@@ -354,11 +354,11 @@ describe('agentPreset.select', () => {
  })

  it('records the switch in the log, and the list reads it back', async () => {
-    const { api, ctx } = await harness(['standard', 'core-web'])
+    const { api, ctx } = await harness(['standard', 'minimal'])
    await api.sessions.create(request({ sessionId: SessionId('sel-log'), agentPreset: 'standard' }))

    await api.agentPresets.select(
-      request({ sessionId: SessionId('sel-log'), agentPreset: 'core-web' }))
+      request({ sessionId: SessionId('sel-log'), agentPreset: 'minimal' }))

    // The header is written once at creation, so the switch lives in the log —
    // this is what a restart replays and what every projection resolves from.
@@ -366,11 +366,11 @@ describe('agentPreset.select', () => {
    const session = ctx.sessions.get(SessionId('sel-log'))
    if (session === undefined) throw new Error('unreachable')
    expect(session.header.agentPreset).toBe('standard')
-    expect(resolveSessionPreset(session)).toBe('core-web')
+    expect(resolveSessionPreset(session)).toBe('minimal')
    const listed = await api.sessions.list(request({}))
    if (!listed.result.ok) throw new Error('unreachable')
    expect(listed.result.value.items.find(item => item.sessionId === 'sel-log')?.agentPreset)
-      .toBe('core-web')
+      .toBe('minimal')
  })

  it('frames the committed switch so clients can drop that session\'s catalogs', async () => {
@@ -405,14 +405,14 @@ describe('agentPreset.select', () => {
  })

  it('serializes two concurrent selects on one session', async () => {
-    const { api, ctx } = await harness(['standard', 'core-web'])
+    const { api, ctx } = await harness(['standard', 'minimal'])
    await api.sessions.create(request({ sessionId: SessionId('sel-race'), agentPreset: 'standard' }))

    // Both pass the blank check; unserialized, the second unmount finds no
    // record because the first already removed it, and two compositions end up
    // in one agent layer. The client's busy flag is not enforcement.
    const [first, second] = await Promise.all([
-      api.agentPresets.select(request({ sessionId: SessionId('sel-race'), agentPreset: 'core-web' })),
+      api.agentPresets.select(request({ sessionId: SessionId('sel-race'), agentPreset: 'minimal' })),
      api.agentPresets.select(request({ sessionId: SessionId('sel-race'), agentPreset: 'standard' })),
    ])

@@ -635,7 +635,7 @@ describe('skills over the layered host registry', () => {
  })

  it('resolves a cold session to its recorded preset standing key', async () => {
-    const { api, ctx } = await harness(['standard', 'core-web'])
+    const { api, ctx } = await harness(['standard', 'minimal'])
    const seen: unknown[] = []
    ctx.provide('skills', {
      list: (options: { scope?: unknown }) => {
@@ -643,12 +643,12 @@ describe('skills over the layered host registry', () => {
        return Promise.resolve([])
      },
    } as never)
-    ctx.sessions.create(SessionId('h2'), { meta: { cwd: '/workspace/cold', agentPreset: 'core-web' } })
+    ctx.sessions.create(SessionId('h2'), { meta: { cwd: '/workspace/cold', agentPreset: 'minimal' } })

    const response = await api.skills.list(request({ sessionId: SessionId('h2') }))

    expect(response.result).toMatchObject({ ok: true, value: { skills: [] } })
-    expect(seen).toEqual([standingKeys.get('core-web')])
+    expect(seen).toEqual([standingKeys.get('minimal')])
  })

  it('serves the global view when the roster no longer supplies the recorded preset', async () => {
@@ -671,8 +671,8 @@ describe('skills over the layered host registry', () => {

 describe('session.history presenter scope', () => {
  it('asks the roster for the RECORDED preset\'s standing key on a cold read', async () => {
-    const { api } = await harness(['standard', 'core-web'])
-    await api.sessions.create(request({ sessionId: SessionId('p1'), agentPreset: 'core-web' }))
+    const { api } = await harness(['standard', 'minimal'])
+    await api.sessions.create(request({ sessionId: SessionId('p1'), agentPreset: 'minimal' }))
    // Cold: creation registered a live agent in this harness, so simulate the
    // cold path by asking for a session only persistence knows... the harness
    // has no persistence, so read the live one and assert no roster query.
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/preset/agent-presets/README.md
-README.md: 632fc7828313a932512cb59a924050005067a008
-README.zh.md: 41dfab1af81149a221cb333a5613ab0a2d899899
+README.md: e31dc8e666096baf6fd6b2cf9407110c7678c6e1
+README.zh.md: cf7e24bb0f256623beec1b86c70473a70be03cb5
@@ -73,7 +73,7 @@ A preset may publish display text in an optional `preset.yml` beside its composi

 ```yaml
 name: 极简模式
-description: 仅提供 bash 与 str_replace_editor 的双工具编码 Agent，用于基准测试和最小复现。
+description: 仅提供持久 bash 与 str_replace_editor 的双工具编码 Agent。
 ```

 It carries display text ONLY. `id` is the directory name and `trust` comes from the root the preset was discovered under, so neither is writable here — otherwise a locally authored preset could name itself into the shipped set. It is a separate file because the composition is a top-level list of plugin rows: YAML cannot carry sibling keys beside it, and a fake metadata row would hand the Loader something to load.
@@ -73,7 +73,7 @@ preset 可以在组装文件旁的可选 `preset.yml` 里发布展示文本：

 ```yaml
 name: 极简模式
-description: 仅提供 bash 与 str_replace_editor 的双工具编码 Agent，用于基准测试和最小复现。
+description: 仅提供持久 bash 与 str_replace_editor 的双工具编码 Agent。
 ```

 它**只**承载展示文本。`id` 是目录名，`trust` 取自 preset 被发现时所在的根目录，两者都不可写在这里——否则本地创作的 preset 就能把自己命名进随附集合。之所以是独立文件：组装是插件行的顶层列表，YAML 无法在其旁携带同级键，而伪造一个元信息行等于递给 Loader 一个要加载的东西。
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/preset/persona/README.md
-README.md: 789776b32d907f7d217accccbca5508f88de0ed1
-README.zh.md: 4e28d75bbd4fd22b77a0fa3b18c5f19df08588d8
+README.md: 742141e65fa8d50b89e6b74e6d21aa8c5bfe98cd
+README.zh.md: add106adb5b81e45d8c6929a9a0f98b5c0072a01
@@ -2,7 +2,7 @@

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

-The agent persona as a composable row. One config field, one prompt section.
+The agent persona as a composable row. It can either shadow the deployment persona or own the complete system prompt.

 [`dsh-system-prompt`](../../core/system-prompt/README.md) owns the deployment persona as its own config and registers that section unconditionally, so a process has exactly one. An [agent preset](../agent-presets/README.md) cannot mount the prompt registry itself — without a row of its own, a preset could change an agent's tools but never its identity. This package is that row.

@@ -15,8 +15,9 @@ Mounting this row outside an agent scope collides with the registry's own `deplo
 | Field | Default | Meaning |
 |---|---|---|
 | `text` | required | Persona prose rendered as the `deployment:persona` section |
+| `complete` | `false` | Restore this persona after assembly as the only system-prompt section |

-`text` is a template, like any prompt section: complete `{{…}}` groups resolve strictly against registered prompt variables when the prompt renders, not when it assembles. Empty text still occupies the slot, so it shadows the deployment persona away entirely and then disappears at render.
+`text` is a template, like any prompt section: complete `{{…}}` groups resolve strictly against registered prompt variables when the prompt renders, not when it assembles. Empty text still occupies the slot, so it shadows the deployment persona away entirely and then disappears at render. With `complete: true`, assembly still resolves contexts, tools, variables, and cooperative listeners, then the prompt registry restores this exact persona as the sole section; no identity, tool guidance, or listener can append prompt text.

 ## Model Experience

@@ -24,11 +25,11 @@ Mounting this row outside an agent scope collides with the registry's own `deplo

 #### What the model sees

-The `deployment:persona` section at order 0, immediately after the harness identity opener, carrying exactly this row's configured `text` with prompt variables resolved. For an agent whose preset mounts this row, it replaces whatever persona the deployment configured.
+The `deployment:persona` section at order 0, immediately after the harness identity opener, carrying exactly this row's configured `text` with prompt variables resolved. For an agent whose preset mounts this row, it replaces whatever persona the deployment configured. In complete mode, the model sees only this rendered section as its system prompt.

 #### Token effect

-Fixed for a given preset: the persona's own tokens on every request that agent makes, and none for any other agent. Empty text contributes nothing.
+Fixed for a given preset: the persona's own tokens on every request that agent makes, and none for any other agent. Empty text contributes nothing. Complete mode removes every other system-prompt token for that agent.

 #### KV Cache effect

@@ -2,7 +2,7 @@

 [English](README.md) | 中文

-把 agent（智能体）人设做成一个可组装的行：一个配置字段，一个提示词段落。
+把 agent（智能体）人设做成一个可组装的行：它既可以遮蔽部署级人设，也可以拥有完整系统提示词。

 [`dsh-system-prompt`](../../core/system-prompt/README.md) 以自身配置持有部署级人设，并且无条件注册该段落，因此一个进程只有一份。[agent preset](../agent-presets/README.md) 无法自行挂载提示词注册表——若没有属于自己的行，preset 能改变 agent 的工具，却永远改不了它的身份。本包就是那一行。

@@ -15,8 +15,9 @@
 | 字段 | 默认值 | 含义 |
 |---|---|---|
 | `text` | 必填 | 作为 `deployment:persona` 段落渲染的人设文本 |
+| `complete` | `false` | 组装后将此人设恢复为唯一的系统提示词段落 |

-`text` 与任何提示词段落一样是模板：完整的 `{{…}}` 组在提示词**渲染**时（而非组装时）严格解析为已注册的提示词变量。空文本同样占据该槽位，因此会把部署级人设整个遮蔽掉，然后在渲染时消失。
+`text` 与任何提示词段落一样是模板：完整的 `{{…}}` 组在提示词**渲染**时（而非组装时）严格解析为已注册的提示词变量。空文本同样占据该槽位，因此会把部署级人设整个遮蔽掉，然后在渲染时消失。启用 `complete: true` 时，组装仍会解析上下文、工具、变量和协作式监听器，之后提示词注册表将这份确切人设恢复为唯一段落；身份、工具引导或监听器都无法追加提示词文本。

 ## Model Experience

@@ -24,11 +25,11 @@

 #### What the model sees

-位于 order 0 的 `deployment:persona` 段落，紧随 harness 身份开场白之后，携带本行配置的 `text`，其中的提示词变量已解析。对于其 preset 挂载了本行的 agent，它会替换部署所配置的任何人设。
+位于 order 0 的 `deployment:persona` 段落，紧随 harness 身份开场白之后，携带本行配置的 `text`，其中的提示词变量已解析。对于其 preset 挂载了本行的 agent，它会替换部署所配置的任何人设。在完整模式下，模型只会看到这个渲染后的段落作为系统提示词。

 #### Token effect

-对给定 preset 而言是固定的：该 agent 的每次请求都携带人设自身的 token，其他 agent 一个都不带。空文本不贡献任何 token。
+对给定 preset 而言是固定的：该 agent 的每次请求都携带人设自身的 token，其他 agent 一个都不带。空文本不贡献任何 token。完整模式会移除该 agent 的其他所有系统提示词 token。

 #### KV Cache effect

@@ -38,23 +38,27 @@ export interface Config {
   * variables. Empty text drops the section at render, matching the registry.
   */
  text: string
+  /** Make this persona the complete system prompt, suppressing every other section. */
+  complete?: boolean
 }

 /** Runtime schema for the persona row. */
 export const Config: z<Config> = z.object({
  text: z.string().required(),
+  complete: z.boolean().default(false),
 })

 /**
 * Register the persona section for the mounting context's scope.
 * @param ctx - an agent scope context; an unscoped context collides with the
 * prompt registry's own persona registration and rejects.
- * @param config - the persona text.
+ * @param config - the persona text and complete-prompt policy.
 */
 export function apply(ctx: Context, config: Config): void {
  ctx.effect(() => ctx.systemPrompt.section({
    name: PERSONA_SECTION,
    order: PERSONA_ORDER,
    text: config.text,
+    ...(config.complete ? { complete: true } : {}),
  }), 'persona.section()')
 }
@@ -16,7 +16,8 @@ export const inject = ['invariants']

 /**
 * No runtime invariant: this row owns no event stream or mutable runtime data — it registers one
- * prompt section and the prompt registry owns section identity, shadowing, and disposal.
+ * prompt section and the prompt registry owns identity, complete-prompt enforcement, shadowing,
+ * and disposal.
 */
 const install: InvariantInstaller = () => {}

@@ -85,4 +85,21 @@ describe('the persona row', () => {
    expect(renderPrompt(await ctx.systemPrompt.assemble({ scope: key })))
      .toContain('You run on deepseek-v4-pro.')
  })
+
+  it('makes a complete persona the exact prompt after every other contribution', async () => {
+    const ctx = await harness('deployment identity')
+    const key: ScopeKey = { agent: 'a1' }
+    const scope = createScope(ctx, key)
+    ctx.systemPrompt.section({ name: 'global:extra', order: 100, text: 'global guidance' })
+
+    await scope.ctx.plugin(Persona, { text: 'Only this.', complete: true })
+    scope.ctx.on('system-prompt/assemble', async (assembly, _context, next) => {
+      assembly.sections.push({ name: 'late:extra', text: 'late guidance' })
+      return next()
+    }, { prepend: true })
+
+    const assembly = await ctx.systemPrompt.assemble({ scope: key })
+    expect(assembly.sections).toEqual([{ name: PERSONA_SECTION, text: 'Only this.' }])
+    expect(renderPrompt(assembly)).toBe('Only this.')
+  })
 })
@@ -26,6 +26,7 @@
    "lib/index.js",
    "lib/invariant.js",
    "lib/runner.js",
+    "lib/types-*.js",
    "lib/types/**/*.d.ts"
  ],
  "license": "BSD-3-Clause",
--- a/Show More
+++ b/Show More