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
--- a/packages/boot/app-boot/README.i18n.yaml
+++ b/packages/boot/app-boot/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/boot/app-boot/README.md
-README.md: be03bceb39935fafb7acc7d3a99c1fe3af686f94
-README.zh.md: 10165486712fc078cdf1f4147522397a15c88955
+README.md: f3ffdae3846edba6f1a1a4821adade7b6c7fce76
+README.zh.md: 4f31fd743f1ddc57edc9c215a42e79a16afcdecb
--- a/packages/boot/app-boot/README.md
+++ b/packages/boot/app-boot/README.md
@@ -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.

--- a/packages/boot/app-boot/README.zh.md
+++ b/packages/boot/app-boot/README.zh.md
@@ -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 包解析。

--- a/packages/boot/app-boot/src/index.ts
+++ b/packages/boot/app-boot/src/index.ts
@@ -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`
--- a/packages/boot/app-boot/tests/app-boot.spec.ts
+++ b/packages/boot/app-boot/tests/app-boot.spec.ts
@@ -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')
--- a/packages/bundle/web-app/cordis.patch.yml
+++ b/packages/bundle/web-app/cordis.patch.yml
@@ -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:
--- a/packages/client/ui-agent-preset/src/client/locales.ts
+++ b/packages/client/ui-agent-preset/src/client/locales.ts
@@ -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: '复制',
--- a/packages/core/system-prompt/README.i18n.yaml
+++ b/packages/core/system-prompt/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/system-prompt/README.md
-README.md: 13b05bfcd19212ade42f22ece455871d022e6260
-README.zh.md: 0f9e7a2358134018975db1bc3c6b7206a274b3ec
+README.md: cedda783d549633f5be9765a9a074e968d99500d
+README.zh.md: 41729cdd1cfe6ebbd86f38c15bab5c50bd6ff7d2
--- a/packages/core/system-prompt/README.md
+++ b/packages/core/system-prompt/README.md
@@ -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

--- a/packages/core/system-prompt/README.zh.md
+++ b/packages/core/system-prompt/README.zh.md
@@ -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 身份

--- a/packages/core/system-prompt/src/index.ts
+++ b/packages/core/system-prompt/src/index.ts
@@ -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] }
  }
 }

--- a/packages/core/system-prompt/tests/system-prompt.spec.ts
+++ b/packages/core/system-prompt/tests/system-prompt.spec.ts
@@ -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)
--- a/packages/examples/jsonrpc-demo/README.i18n.yaml
+++ b/packages/examples/jsonrpc-demo/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/examples/jsonrpc-demo/README.md
-README.md: fff8e78698cd3d6320606084ef5c533be7c52633
-README.zh.md: 75382b97ea1837cf1415e8a7f5004206596e168c
+README.md: 40ced3ee1fe2d3eac69b82501d417130267d7634
+README.zh.md: 451bdf7428f8265750082af240418d4653bb8595
--- a/packages/examples/jsonrpc-demo/README.md
+++ b/packages/examples/jsonrpc-demo/README.md
@@ -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

--- a/packages/examples/jsonrpc-demo/README.zh.md
+++ b/packages/examples/jsonrpc-demo/README.zh.md
@@ -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`：已打包的裸插件从封闭运行时包树解析，相对插件仍以配置目录为基准。

 ## 配置发现

--- a/packages/examples/jsonrpc-demo/package.json
+++ b/packages/examples/jsonrpc-demo/package.json
@@ -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",
--- a/packages/examples/jsonrpc-demo/src/bin.ts
+++ b/packages/examples/jsonrpc-demo/src/bin.ts
@@ -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()
--- a/packages/examples/jsonrpc-demo/src/index.ts
+++ b/packages/examples/jsonrpc-demo/src/index.ts
@@ -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
 */
--- a/packages/examples/jsonrpc-demo/src/packaged-bin.ts
+++ b/packages/examples/jsonrpc-demo/src/packaged-bin.ts
@@ -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)
--- a/packages/examples/jsonrpc-demo/src/runner.ts
+++ b/packages/examples/jsonrpc-demo/src/runner.ts
@@ -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 */
--- a/packages/examples/jsonrpc-demo/tsdown.config.ts
+++ b/packages/examples/jsonrpc-demo/tsdown.config.ts
@@ -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,
+  },
+])
--- a/packages/host/apiproxy/tests/api-proxy-agent-preset.spec.ts
+++ b/packages/host/apiproxy/tests/api-proxy-agent-preset.spec.ts
@@ -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.
--- a/packages/preset/agent-presets/README.i18n.yaml
+++ b/packages/preset/agent-presets/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/preset/agent-presets/README.md
-README.md: 632fc7828313a932512cb59a924050005067a008
-README.zh.md: 41dfab1af81149a221cb333a5613ab0a2d899899
+README.md: e31dc8e666096baf6fd6b2cf9407110c7678c6e1
+README.zh.md: cf7e24bb0f256623beec1b86c70473a70be03cb5
--- a/packages/preset/agent-presets/README.md
+++ b/packages/preset/agent-presets/README.md
@@ -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.
--- a/packages/preset/agent-presets/README.zh.md
+++ b/packages/preset/agent-presets/README.zh.md
@@ -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 一个要加载的东西。
--- a/packages/preset/persona/README.i18n.yaml
+++ b/packages/preset/persona/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/preset/persona/README.md
-README.md: 789776b32d907f7d217accccbca5508f88de0ed1
-README.zh.md: 4e28d75bbd4fd22b77a0fa3b18c5f19df08588d8
+README.md: 742141e65fa8d50b89e6b74e6d21aa8c5bfe98cd
+README.zh.md: add106adb5b81e45d8c6929a9a0f98b5c0072a01
--- a/packages/preset/persona/README.md
+++ b/packages/preset/persona/README.md
@@ -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

--- a/packages/preset/persona/README.zh.md
+++ b/packages/preset/persona/README.zh.md
@@ -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

--- a/packages/preset/persona/src/index.ts
+++ b/packages/preset/persona/src/index.ts
@@ -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()')
 }
--- a/packages/preset/persona/src/invariant.ts
+++ b/packages/preset/persona/src/invariant.ts
@@ -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 = () => {}

--- a/packages/preset/persona/tests/persona.spec.ts
+++ b/packages/preset/persona/tests/persona.spec.ts
@@ -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.')
+  })
 })
--- a/packages/sandbox/sandbox-windows-acl/package.json
+++ b/packages/sandbox/sandbox-windows-acl/package.json
@@ -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/packages/self-modification/tool-cordis/src/api-catalog.ts
+++ b/packages/self-modification/tool-cordis/src/api-catalog.ts
@@ -1114,7 +1114,7 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
      },
      {
        signature: 'async assemble(context: AssembleContext = {}): Promise<PromptAssembly>',
-        jsDoc: '/**\n * Assemble global and scoped providers, detach tool parameters, apply\n * canonical ordering, then run the assembly waterfall. Scoped sections and\n * variables shadow globals; the returned waterfall value is authoritative.\n * @param context - the optional scope and plugin-defined assembly fields.\n * @returns the authoritative post-waterfall assembly.\n */',
+        jsDoc: '/**\n * Assemble global and scoped providers, detach tool parameters, apply\n * canonical ordering, then run the assembly waterfall. Scoped sections and\n * variables shadow globals. The returned waterfall value is authoritative\n * except that an effective complete section is restored afterwards as the\n * sole prompt section.\n * @param context - the optional scope and plugin-defined assembly fields.\n * @returns the post-waterfall assembly with any complete prompt enforced.\n */',
      },
    ],
  },
@@ -1610,7 +1610,7 @@ export const EVENT_API: readonly EventApiEntry[] = [
    name: 'system-prompt/assemble',
    mode: 'waterfall',
    signature: '\'system-prompt/assemble\'(this: Scoped<SystemPrompt>, assembly: PromptAssembly, context: AssembleContext, next: () => Promise<PromptAssembly>): Promise<PromptAssembly>',
-    jsDoc: '/**\n * Expert waterfall over the assembled sections, contexts, tools, and variables.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners\n * receive only that scope\'s assemblies. The returned value is authoritative.\n * A supplied signal controls only this explicit assembly request and must not\n * be retained to control later turns.\n * @param assembly - the mutable assembly built from registered providers.\n * @param context - the caller\'s per-assembly context.\n * @mode waterfall\n */',
+    jsDoc: '/**\n * Expert waterfall over the assembled sections, contexts, tools, and variables.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners\n * receive only that scope\'s assemblies. The returned value is authoritative.\n * A supplied signal controls only this explicit assembly request and must not\n * be retained to control later turns. A registered complete section is\n * restored after this waterfall, so listeners cannot add to or replace\n * that scope\'s system prompt.\n * @param assembly - the mutable assembly built from registered providers.\n * @param context - the caller\'s per-assembly context.\n * @mode waterfall\n */',
    summary: 'Expert waterfall over the assembled sections, contexts, tools, and variables.',
  },
  {
@@ -2421,7 +2421,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
  },
  {
    name: 'PromptSection',
-    declaration: 'export interface PromptSection {\n    readonly name: string;\n    readonly order: number;\n    readonly text: string | ((context: AssembleContext) => string);\n}',
+    declaration: 'export interface PromptSection {\n    readonly name: string;\n    readonly order: number;\n    readonly text: string | ((context: AssembleContext) => string);\n    readonly complete?: boolean;\n}',
  },
  {
    name: 'ProviderRequestId',