Merge updated feedback base into telemetry stack

# Conflicts: # .agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.i18n.yaml # .agents/notes/implemented/feature/2026-07-23-session-telemetry-otel-revival.zh.md # .agents/notes/implemented/feature/2026-07-28-feedback-command.i18n.yaml # docs/config-catalog.md # docs/event-producer-consumer.md # docs/module-graph.md # examples/package.json # packages/feedback/command-feedback/README.i18n.yaml # packages/telemetry/README.i18n.yaml # packages/telemetry/README.md # packages/telemetry/README.zh.md # packages/telemetry/session-telemetry-otel/README.i18n.yaml # packages/telemetry/session-telemetry-otel/README.md # packages/telemetry/session-telemetry-otel/README.zh.md # packages/telemetry/session-telemetry-otel/package.json # packages/telemetry/session-telemetry-otel/src/index.ts # packages/telemetry/session-telemetry-otel/tests/otel.spec.ts # packages/telemetry/session-telemetry/README.i18n.yaml # packages/telemetry/session-telemetry/README.zh.md # pnpm-lock.yaml
2026-08-06 18:08:45 +08:00
parent ab94a2f7d6 4f595311f7
commit f8c3d3fff4
4133 changed files with 255372 additions and 59535 deletions
--- a/packages/examples/README.i18n.yaml
+++ b/packages/examples/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/README.md
-README.md: c229cef22087ac290bf862d6b3e31fdb533858c4
-README.zh.md: 208b9a138506785ea1dd2d83ddfbba29e4b7968e
+README.md: 64fff8cb3f53386d48a9a831c1cbdd946ad483cc
+README.zh.md: c346a41d297a545991a2441df625286e1b830998
--- a/packages/examples/README.md
+++ b/packages/examples/README.md
@@ -6,18 +6,13 @@ Pre-composed plugin bundles a thin leaf `cordis.yml` loads instead of assembling

 | Package | npm name | Role |
 |---|---|---|
-| `agent-spine-demo/` | `@deepseek-ai/dsh-agent-spine-demo` | The executor-less/UI-less agent spine as one bundle plugin, with fallback session titles and an opt-in persisted-goal stack |
-| `tui-demo/` | `@deepseek-ai/dsh-tui-demo` | Full-screen terminal app bundle: the spine + persisted goals + `/goal` command + JSONL persistence + `dsh-tui` + a pre-created `main` agent; no bin, booted by the [`dsh`](../../apps/cli/README.md) CLI |
-| `cli-demo/` | `@deepseek-ai/dsh-cli-demo` | Headless one-shot app: the spine + JSONL persistence + a pre-created `main` agent, with text and DSH-native JSON output |
-| `acp-demo/` | `@deepseek-ai/dsh-acp-demo` | ACP automation server app: the spine + persisted goals + JSONL persistence + the [`acp`](../acp/acp/README.md) bridge (no stdout logger), with a boot `bin` |
-| `jsonrpc-demo/` | `@deepseek-ai/dsh-jsonrpc-demo` | Bin-only runtime that boots an external `cordis.yml` for the stdio JSON-RPC SDK client |
+| [`agent-spine-demo/`](agent-spine-demo/README.md) | `@deepseek-ai/dsh-agent-spine-demo` | Reusable agent-spine bundle |
+| [`cli-demo/`](cli-demo/README.md) | `@deepseek-ai/dsh-cli-demo` | Headless one-shot application bundle |
+| [`acp-demo/`](acp-demo/README.md) | `@deepseek-ai/dsh-acp-demo` | ACP automation application bundle |
+| [`jsonrpc-demo/`](jsonrpc-demo/README.md) | `@deepseek-ai/dsh-jsonrpc-demo` | External-config JSON-RPC runtime |

-`agent-spine-demo` is the shared bundle; `tui-demo`, `cli-demo`, and `acp-demo` compose it with full-screen terminal, headless one-shot, and ACP automation front doors. `cli-demo` and `acp-demo` own their boot bins; `tui-demo` ships only the bundle plugin, and the product [`dsh`](../../apps/cli/README.md) CLI is its terminal front door. `jsonrpc-demo` mounts no composition of its own — it boots whatever tree the deployment's `cordis.yml` names, and is what the Python SDK runtime launches.
+`agent-spine-demo` is the shared bundle; `cli-demo` and `acp-demo` add their front doors, while `jsonrpc-demo` boots a deployment-owned plugin tree.

-These are **not** product API. The spine pieces they bundle live in [`core/`](../core/README.md), human/SDK channels and boot glue in [`ui/`](../ui/README.md), the automation transport in [`acp/`](../acp/README.md), and swappable backends in their capability groups; a demo bundle just picks one concrete composition of them. Swap or fork one freely.
+These packages are not product API. Product seams and front doors remain in their owning groups; demo bundles select concrete compositions.

 Do not confuse this group with the repo-root [`examples/`](../../examples/AGENTS.md): that directory holds the runnable `cordis.yml` **leaves**; this group holds the **bundles** those leaves load.
-
-## The jsonrpc bin/exe names are legacy
-
-`jsonrpc-demo` renamed like its siblings, but its bin is still `dsh-jsonrpc-agent` and the single-file executable is still `dsh-jsonrpc-agent-pkg` (referenced across the [Python distribution](../../python/sdk-runtime/README.md)). Those names are the SDK's runtime-startup surface; they are reconciled when the SDK unifies that startup flow, not by this move.
--- a/packages/examples/README.zh.md
+++ b/packages/examples/README.zh.md
@@ -2,22 +2,17 @@

 [English](README.md) | 中文

-预先组合的插件 bundle（组合包），供轻量叶节点 `cordis.yml` 加载，无需手工组装主干和前端入口。这些是 **演示／参考** 包（package）；npm 名称的 `-demo` 后缀把每个包标为非产品表层，直接查看包名即可辨认。仓库根目录 [`examples/`](../../examples/AGENTS.md) 下的可运行叶节点与 [Python SDK 运行时](../../python/sdk-runtime/README.md) 是消费方；每个消费方都只包含可替换后端和一个组合包入口。
+预先组合的插件 bundle（组合包），供轻量叶节点 `cordis.yml` 加载，无需手工组装主干和前端入口。这些是 **演示／参考** 包；npm 名称的 `-demo` 后缀把每个包标为非产品表层，直接查看包名即可辨认。仓库根目录 [`examples/`](../../examples/AGENTS.md) 下的可运行叶节点与 [Python SDK runtime](../../python/sdk-runtime/README.md) 是消费方；每个叶节点都只包含可替换后端和一个组合包入口。

 | 包 | npm 名称 | 角色 |
 |---|---|---|
-| `agent-spine-demo/` | `@deepseek-ai/dsh-agent-spine-demo` | 不含执行器和 UI 的 agent（智能体）主干，打包为一个组合包插件，带后备会话标题和可选择启用的持久化目标栈 |
-| `tui-demo/` | `@deepseek-ai/dsh-tui-demo` | 全屏终端应用组合包：主干 + 持久化目标 + `/goal` 命令 + JSONL 持久化 + `dsh-tui` + 预创建的 `main` agent；没有 bin，由 [`dsh`](../../apps/cli/README.md) CLI（命令行界面）启动 |
-| `cli-demo/` | `@deepseek-ai/dsh-cli-demo` | 无头单次应用：主干 + JSONL 持久化 + 预创建的 `main` agent，提供文本和 DSH 原生 JSON 输出 |
-| `acp-demo/` | `@deepseek-ai/dsh-acp-demo` | ACP（Agent Client Protocol）自动化服务器应用：主干 + 持久化目标 + JSONL 持久化 + [`acp`](../acp/acp/README.md) 桥接层（无 stdout logger），带启动 `bin` |
-| `jsonrpc-demo/` | `@deepseek-ai/dsh-jsonrpc-demo` | 只有 bin 的运行时，用于启动外部 `cordis.yml`，供 stdio JSON-RPC SDK 客户端使用 |
+| [`agent-spine-demo/`](agent-spine-demo/README.md) | `@deepseek-ai/dsh-agent-spine-demo` | 可复用的 agent 主干组合包 |
+| [`cli-demo/`](cli-demo/README.md) | `@deepseek-ai/dsh-cli-demo` | 无头单次应用组合包 |
+| [`acp-demo/`](acp-demo/README.md) | `@deepseek-ai/dsh-acp-demo` | ACP 自动化应用组合包 |
+| [`jsonrpc-demo/`](jsonrpc-demo/README.md) | `@deepseek-ai/dsh-jsonrpc-demo` | 外部配置 JSON-RPC 运行时 |

-`agent-spine-demo` 是共享组合包；`tui-demo`、`cli-demo` 和 `acp-demo` 分别将它与全屏终端、无头单次和 ACP 自动化前端入口组合。`cli-demo` 与 `acp-demo` 拥有各自的启动 bin；`tui-demo` 只交付组合包插件，产品 [`dsh`](../../apps/cli/README.md) CLI 是它的终端前端入口。`jsonrpc-demo` 自身不挂载任何组合，而是启动部署的 `cordis.yml` 所指名的任意插件树；Python SDK 运行时会启动它。
+`agent-spine-demo` 是共享组合包；`cli-demo` 与 `acp-demo` 添加各自的前端入口，`jsonrpc-demo` 则启动由部署方拥有的插件树。

-这些 **不是** 产品 API。它们打包的主干组件位于 [`core/`](../core/README.md)，人类／SDK 通道和启动粘合代码位于 [`ui/`](../ui/README.md)，自动化传输位于 [`acp/`](../acp/README.md)，可替换后端位于各自能力组；演示组合包只选定其中一种具体组合。可以自由替换或 fork。
+这些包不是产品 API。产品 seam 与前端入口仍位于各自的归属组；演示组合包只选择具体组合。

 不要将此组与仓库根目录的 [`examples/`](../../examples/AGENTS.md) 混淆：该目录存放可运行的 `cordis.yml` **叶节点**；此组存放这些叶节点加载的 **组合包**。
-
-## jsonrpc bin／exe 名称是历史遗留
-
-`jsonrpc-demo` 已像同级包一样重命名，但其 bin 仍为 `dsh-jsonrpc-agent`，单文件可执行程序仍为 `dsh-jsonrpc-agent-pkg`（在 [Python 分发](../../python/sdk-runtime/README.md)各处被引用）。这些名称属于 SDK 的运行时启动表层；只有 SDK 统一该启动流程时才会协调它们，而不会在此次移动中处理。
--- a/packages/examples/acp-demo/README.i18n.yaml
+++ b/packages/examples/acp-demo/README.i18n.yaml
@@ -3,4 +3,4 @@
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/examples/acp-demo/README.md
 README.md: 395ab230146568989c4e6d1361218efb72d857e7
-README.zh.md: bfba1f83e506e60ab117f11f85851b3d3a7ea16a
+README.zh.md: 667fc1a794eba15c7754ad9887f8083d3643f3e6
--- a/packages/examples/acp-demo/README.zh.md
+++ b/packages/examples/acp-demo/README.zh.md
@@ -2,7 +2,7 @@

 [English](README.md) | 中文

-ACP（Agent Client Protocol）自动化服务器应用：默认 agent（智能体）主干、客户端通过 [`@deepseek-ai/dsh-acp`](../../acp/acp/README.md) 创建的 agent、JSONL 持久化，以及由一个 JSON-RPC stdio bin 提供的语义检查点。程序化客户端创建新会话；此包（package）不挂载人工交互 UI。
+ACP（Agent Client Protocol）自动化服务器应用：默认 agent（智能体）主干、客户端通过 [`@deepseek-ai/dsh-acp`](../../acp/acp/README.md) 创建的 agent、JSONL 持久化，以及由一个 JSON-RPC stdio bin 提供的语义检查点。程序化客户端创建新会话；此包不挂载人工交互 UI。

 ## 组合

--- a/packages/examples/acp-demo/package.json
+++ b/packages/examples/acp-demo/package.json
@@ -29,9 +29,7 @@
    "lib/index.js",
    "lib/invariant.js",
    "lib/bin.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
+    "lib/types/**/*.d.ts"
  ],
  "license": "BSD-3-Clause",
  "peerDependencies": {
--- a/packages/examples/acp-demo/tests/acp-agent.spec.ts
+++ b/packages/examples/acp-demo/tests/acp-agent.spec.ts
@@ -46,7 +46,16 @@ async function isolatedSkillsConfig(catalogDescriptionMaxLength?: number): Promi

 async function composePrefix(ctx: Context): Promise<Message[]> {
  const agent = ctx.agentLoop.create(SessionId(`acp-demo-prefix-${randomUUID()}`), {}, { cwd: '/tmp' })
-  await agentEvents(ctx, agent).serial('agent/step', 1, 1, new AbortController().signal)
+  const signal = new AbortController().signal
+  const decision = await agentEvents(ctx, agent).waterfall(
+    'agent/pre-step', [], { turn: 1, step: 1, signal },
+    () => Promise.resolve({ kind: 'enter', messages: [] }),
+  )
+  if (decision.kind === 'enter') {
+    for (const message of decision.messages) {
+      agent.session.append('user/message', message, { surfaceOp: 'append' })
+    }
+  }
  return agent.session.deriveMessages()
 }

--- a/packages/examples/acp-demo/tests/load-path.e2e.ts
+++ b/packages/examples/acp-demo/tests/load-path.e2e.ts
@@ -42,7 +42,7 @@ const CORDIS_YML = `
 - id: acp-agent
  name: '@deepseek-ai/dsh-acp-demo'
  config:
-    provider: deepseek
+    provider: deepseek-official
    model: deepseek-v4-flash
    persona: 'You are a test agent.'
    workspaceContext: false
--- a/packages/examples/agent-spine-demo/README.i18n.yaml
+++ b/packages/examples/agent-spine-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/agent-spine-demo/README.md
-README.md: 359e7153be2f480ba3fea4b06782acdc9f89ebb9
-README.zh.md: acd8c06940b03e90e368314cd725846a2b92b656
+README.md: d1c3c28183956b4f66db7ed4a6f3a08588b5352c
+README.zh.md: 936a317d23bf942802ecdd87f5ea4005974e4125
--- a/packages/examples/agent-spine-demo/README.md
+++ b/packages/examples/agent-spine-demo/README.md
@@ -31,7 +31,7 @@ Read this package for the whole plugin tree and its composition order.
@deepseek-ai/dsh-scope/invariant
@deepseek-ai/dsh-agent-loop/invariant
                                  package-owned relational checks
-@deepseek-ai/dsh-tool-bash        the model-facing bash schema
+@deepseek-ai/dsh-tool-bash        the model-facing bash schema (unless toolBash=false)
@deepseek-ai/dsh-workspace-context  AGENTS.md/CLAUDE.md workspace context loader
@deepseek-ai/dsh-tool-skill       session-prefix skill catalog + model-facing loader schema
@deepseek-ai/dsh-tool-tasks       task_output/task_list/task_kill schemas + completion notices
@@ -47,7 +47,7 @@ The spine is everything COMMON to every front door. The swappable and front-door
 - **model-backed session-title providers** — the bundle mounts the fallback service with overridable example limits (5 words, 40 fallback bytes, 80 accepted-title bytes); a leaf may opt into exactly one first-message or all-messages LLM provider.
 - **the bash executor** — the bundle ships `tool-bash` (the consumer schema); the leaf provides `ctx.bash` (`bash-local` or a sandboxed impl).
 - **non-local skill providers** — the bundle ships the skill registry, the local filesystem provider, and the `skill` tool; deployments can add other providers such as embedded or remote catalogs as siblings.
- **front-door + per-app infra** — the terminal TUI or ACP automation transport and `hmr`. App packages ([`dsh-tui-demo`](../tui-demo/README.md), [`dsh-acp-demo`](../acp-demo/README.md)) own those choices. `timer` is in the spine because it is common and stdout-silent; front doors own stdout and remain outside.
+- **front-door + per-app infrastructure** — headless, ACP, and JSON-RPC app packages own transport, stdout, and reload choices. `timer` stays in the spine because it is common and stdout-silent.

 This is the [interface/implementation/consumer seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) raised to the composition level: the bundle owns the shared spine, the leaf owns the backends, the app package owns the front door.

@@ -55,11 +55,11 @@ This is the [interface/implementation/consumer seam](../../../.agents/notes/impl

 ```ts
 import type { Config } from '@deepseek-ai/dsh-agent-spine-demo'
-// { agents?, maxParallelToolCalls?, persona?, toolOrder?, tools?, dshHome?, sessionTitle?, skills?, workspaceContext, toolBash?, toolTasks?, goals?, invariants? }
+// { agents?, maxParallelToolCalls?, includeHarnessIdentity?, persona?, toolOrder?, tools?, dshHome?, sessionTitle?, skills?, workspaceContext, toolBash?, toolTasks?, goals?, invariants? }
 // workspaceContext requires { maxBytes } or false; the other owner schemas supply defaults.
 ```

-The bundle FORWARDS each field to the child that owns it: `agents` and `maxParallelToolCalls` to `agent-loop` (`agents` defaults to `[]`; the cap defaults there), so each app supplies its own pre-created agents — TUI and headless apps pre-create `main`, while the ACP app creates agents on demand at `session/new`; `persona` and `toolOrder` to `dsh-system-prompt`; `tools` to the tool registry for its presentation mode; `sessionTitle` to the fallback title service; `skills.registry`, `skills.local`, and `skills.tool` to the skill registry, local provider, and model-facing consumer; the required `workspaceContext` choice to `dsh-workspace-context` (`{ maxBytes }` enables loading and `false` disables it); `invariants` to the invariant service; and `toolBash`/`toolTasks` to the two model-facing tool plugins the bundle owns. It always mounts `dsh-llm-retry`, while each leaf adapter owns its nested `retryPolicy`. Omitted `sessionTitle` uses the explicit example policy of 5 words, 40 fallback bytes, and 80 accepted-title bytes. A `goals` object opts into the persisted domain, model tools, and same-session driver while forwarding `goals.domain` and `goals.tool` to their owners; omission or `false` leaves the stack absent so headless callers retain one-turn settlement. Set `skills.enabled: false` to omit both the local provider and model-facing skill tool, and set `toolTasks: false` to retain the task service for foreground producers without exposing `task_output` / `task_list` / `task_kill`. It resolves `dshHome` once through [`@deepseek-ai/dsh-paths`](../../util/paths/README.md) and forwards that absolute value to tool-bash's managed environment and enabled local skill discovery. An absent top-level `dshHome` adopts `skills.local.dshHome`; supplying both with different resolved paths fails loudly. `toolBash.enableRunInBackground` controls only the bash producer; independently loaded producers keep their own config. Workspace instructions register before the skill catalog so their session-prefix message renders first. App packages use `pickSpineConfig()` to copy only these bundle-owned fields.
+The bundle forwards each field to the child that owns it. App packages supply any pre-created agents: headless and JSON-RPC compositions create `main`, while the ACP app creates agents on demand at `session/new`. Prompt, tool, title, skill, workspace-context, invariant, goal, and task settings retain the schemas and defaults documented by their owning packages. `pickSpineConfig()` copies only fields owned by this bundle, and conflicting `dshHome` values fail during composition.

 For example, `{ invariants: { enabled: true, package_allowlist: ['^@deepseek-ai/dsh-'], package_blocklist: ['agent-loop$'] } }` keeps the package-owned companions mounted but suppresses the blocked owner. Blocklist matches override allowlist matches; see [`dsh-invariants`](../../support/invariants/README.md) for regex and lifecycle rules.

@@ -79,5 +79,5 @@ No direct invalidation; the named consumer owns any request-prefix changes.

 ## Known Limitations and Deferred Work

- **Most of the spine set is fixed in code** — `apply()` always mounts the core services and `tool-bash`; config can omit bundled goals, skills, and task-control tools, but swapping the loop or dropping another spine member means composing a different bundle.
+- **Most of the spine set is fixed in code** — `apply()` always mounts the core services; config can omit bundled goals, skills, bash, and task-control tools, but swapping the loop or dropping another spine member means composing a different bundle.
 - **The invariant seam and companions remain fixed members** — `invariants.enabled: false` or package filters suppress checks but do not remove the service or companion registrations; Session's always-on validation and freezing are separate.
--- a/packages/examples/agent-spine-demo/README.zh.md
+++ b/packages/examples/agent-spine-demo/README.zh.md
@@ -31,7 +31,7 @@
@deepseek-ai/dsh-scope/invariant
@deepseek-ai/dsh-agent-loop/invariant
                                  package-owned relational checks
-@deepseek-ai/dsh-tool-bash        the model-facing bash schema
+@deepseek-ai/dsh-tool-bash        the model-facing bash schema (unless toolBash=false)
@deepseek-ai/dsh-workspace-context  AGENTS.md/CLAUDE.md workspace context loader
@deepseek-ai/dsh-tool-skill       session-prefix skill catalog + model-facing loader schema
@deepseek-ai/dsh-tool-tasks       task_output/task_list/task_kill schemas + completion notices
@@ -47,7 +47,7 @@
 - **基于模型的会话标题提供方**：组合包挂载带可覆盖示例限制的后备服务（5 个词、40 个后备字节、80 个可接受标题字节）；叶节点可以恰好选用一个首消息或全消息 LLM 提供方。
 - **bash 执行器**：组合包交付 `tool-bash`（消费方 schema）；叶节点提供 `ctx.bash`（`bash-local` 或沙箱化实现）。
 - **非本地 skill 提供方**：组合包交付 skill 注册表、本地文件系统提供方和 `skill` 工具；部署可以把嵌入式目录或远程目录等其他提供方作为同级插件添加。
- **前端入口与各应用基础设施**：终端 TUI 或 ACP（Agent Client Protocol）自动化传输，以及 `hmr`。应用包（[`dsh-tui-demo`](../tui-demo/README.md)、[`dsh-acp-demo`](../acp-demo/README.md)）拥有这些选择。`timer` 位于主干中，因为它是共有组件且不写 stdout；前端入口拥有 stdout，因此留在组合包外。
+- **前端入口与各应用基础设施**：无头、ACP（Agent Client Protocol）和 JSON-RPC 应用包负责传输、stdout 与重新加载选择。`timer` 保留在主干中，因为它是共有组件且不写 stdout。

 这把[接口／实现／消费方 seam](../../../.agents/notes/implemented/architecture/2026-06-13-capability-seams.md) 提升到组合层：组合包拥有共享主干，叶节点拥有后端，应用包拥有前端入口。

@@ -55,11 +55,11 @@

 ```ts
 import type { Config } from '@deepseek-ai/dsh-agent-spine-demo'
-// { agents?, maxParallelToolCalls?, persona?, toolOrder?, tools?, dshHome?, sessionTitle?, skills?, workspaceContext, toolBash?, toolTasks?, goals?, invariants? }
+// { agents?, maxParallelToolCalls?, includeHarnessIdentity?, persona?, toolOrder?, tools?, dshHome?, sessionTitle?, skills?, workspaceContext, toolBash?, toolTasks?, goals?, invariants? }
 // workspaceContext requires { maxBytes } or false; the other owner schemas supply defaults.
 ```

-组合包将每个字段转发给拥有它的子节点：`agents` 与 `maxParallelToolCalls` 交给 `agent-loop`（`agents` 默认为 `[]`，上限在该处默认），因此每个应用提供自己的预创建 agent；TUI 和无头应用预创建 `main`，ACP 应用则在 `session/new` 按需创建 agent；`persona` 与 `toolOrder` 交给 `dsh-system-prompt`；`tools` 交给工具注册表以配置呈现模式；`sessionTitle` 交给后备标题服务；`skills.registry`、`skills.local` 与 `skills.tool` 分别交给 skill 注册表、本地提供方和面向模型的消费方；必填的 `workspaceContext` 选择交给 `dsh-workspace-context`（`{ maxBytes }` 启用加载，`false` 禁用）；`invariants` 交给不变式服务；`toolBash`/`toolTasks` 交给组合包拥有的两个面向模型工具插件。组合包始终挂载 `dsh-llm-retry`，而每个叶节点适配器拥有自己的嵌套 `retryPolicy`。省略 `sessionTitle` 时采用显式示例策略：5 个词、40 个后备字节、80 个可接受标题字节。`goals` 对象会选用持久化领域、模型工具和同会话 Goal Round 驱动器，并将 `goals.domain` 与 `goals.tool` 转发给各自拥有者；省略或设为 `false` 会让整个栈缺席，使无头调用方继续以单轮次结算。设置 `skills.enabled: false` 会同时省略本地提供方和面向模型的 skill 工具；设置 `toolTasks: false` 会保留供前台生产方使用的任务服务，但不公开 `task_output`/`task_list`/`task_kill`。它对 `dshHome` 只解析一次，解析通过 [`@deepseek-ai/dsh-paths`](../../util/paths/README.md) 完成，并将所得绝对值转发给 tool-bash 的托管环境和已启用的本地 skill 发现。顶层 `dshHome` 缺席时采用 `skills.local.dshHome`；两者同时提供但解析后的路径不同会明确失败。`toolBash.enableRunInBackground` 只控制 bash 生产方；独立加载的生产方保留各自配置。工作区指令先于 skill 目录注册，因此其会话前缀消息先渲染。应用包使用 `pickSpineConfig()`，只复制这些由组合包拥有的字段。
+组合包将每个字段转发给拥有它的子节点。应用包提供预创建的 agent：无头和 JSON-RPC 组合会创建 `main`，ACP 应用则在 `session/new` 按需创建 agent。提示词、工具、标题、skill、workspace context、不变式、goal 和任务设置沿用其所属包记录的 schema 与默认值。`pickSpineConfig()` 只复制该组合包拥有的字段，`dshHome` 值冲突会在组合时失败。

 例如，`{ invariants: { enabled: true, package_allowlist: ['^@deepseek-ai/dsh-'], package_blocklist: ['agent-loop$'] } }` 会让包拥有的配套插件保持挂载，但抑制被阻止的拥有者。Blocklist 匹配优先于 allowlist 匹配；正则表达式与生命周期规则见 [`dsh-invariants`](../../support/invariants/README.md)。

@@ -79,5 +79,5 @@ YAML include 可以去重配置，却无法拥有 bin 或提供前端入口默

 ## 已知限制与暂缓事项

- **大部分主干集合固定在代码中**：`apply()` 始终挂载核心服务与 `tool-bash`；配置可以省略组合包内的目标、skill 与任务控制工具，但要替换循环或删除其他主干成员，就必须组合另一个组合包。
+- **大部分主干集合固定在代码中**：`apply()` 始终挂载核心服务；配置可以省略组合包内的目标、skill、bash 与任务控制工具，但要替换循环或删除其他主干成员，就必须组合另一个组合包。
 - **不变式 seam 与配套插件仍是固定成员**：`invariants.enabled: false` 或包筛选器会抑制检查，但不会移除服务或配套插件注册；Session 始终启用的校验与冻结是另一套机制。
--- a/packages/examples/agent-spine-demo/package.json
+++ b/packages/examples/agent-spine-demo/package.json
@@ -21,9 +21,7 @@
  "files": [
    "lib/index.js",
    "lib/invariant.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
+    "lib/types/**/*.d.ts"
  ],
  "license": "BSD-3-Clause",
  "peerDependencies": {
@@ -43,6 +41,7 @@
    "@deepseek-ai/dsh-skill-local": "^0.0.1",
    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
    "@deepseek-ai/dsh-tasks-local": "^0.0.1",
+    "@deepseek-ai/dsh-bash-env": "^0.0.1",
    "@deepseek-ai/dsh-tool-bash": "^0.0.1",
    "@deepseek-ai/dsh-tool-goal": "^0.0.1",
    "@deepseek-ai/dsh-tool-skill": "^0.0.1",
@@ -55,6 +54,8 @@
    "@cordisjs/plugin-timer": "workspace:^",
    "@deepseek-ai/dsh-agent": "workspace:^",
    "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-bash-env": "workspace:^",
+    "@deepseek-ai/dsh-bash-local": "workspace:^",
    "@deepseek-ai/dsh-bash-sandbox": "workspace:^",
    "@deepseek-ai/dsh-fs-local": "workspace:^",
    "@deepseek-ai/dsh-fs-policy": "workspace:^",
--- a/packages/examples/agent-spine-demo/src/index.ts
+++ b/packages/examples/agent-spine-demo/src/index.ts
@@ -29,6 +29,7 @@ import * as agentInvariant from '@deepseek-ai/dsh-agent/invariant'
 import * as scopeInvariant from '@deepseek-ai/dsh-scope/invariant'
 import * as agentLoopInvariant from '@deepseek-ai/dsh-agent-loop/invariant'
 import * as toolBash from '@deepseek-ai/dsh-tool-bash'
+import * as bashEnv from '@deepseek-ai/dsh-bash-env'
 import * as workspaceContext from '@deepseek-ai/dsh-workspace-context'
 import * as toolSkill from '@deepseek-ai/dsh-tool-skill'
 import * as toolTasks from '@deepseek-ai/dsh-tool-tasks'
@@ -68,9 +69,9 @@ export interface GoalConfig {
 /**
 * Bundle config: each field forwarded verbatim to the child that owns it —
 * `agents` to the agent loop (an app that pre-creates no agents, like the ACP
- * bridge, simply omits it), `persona` and `toolOrder` to the system-prompt
- * plugin (the deployment's persona section and the explicit model-facing tool
- * order), the `tools` object to the tool registry (its presentation `mode`),
+ * bridge, simply omits it), `includeHarnessIdentity`, `persona`, and `toolOrder`
+ * to the system-prompt plugin (the fixed opener, deployment persona, and explicit
+ * model-facing tool order), the `tools` object to the tool registry (its presentation `mode`),
 * `dshHome` to bash environment and local skill discovery, `sessionTitle` to
 * the fallback title service, `skills` to the
 * skill registry/local provider/tool consumer, `workspaceContext` to the
@@ -83,13 +84,16 @@ export interface GoalConfig {
 * workspace context instead requires an explicit byte budget or `false` because
 * it changes model-visible input. Producer opt-in stays producer-local:
 * `toolBash` configures bash only; independently composed producers keep their
- * own config.
+ * own config. Set `toolBash: false` when another plugin owns the model-facing
+ * `bash` name.
 */
 export interface Config {
  /** The agent-loop `agents` list (see dsh-agent-loop's `Config`). */
  agents?: AgentLoopConfig['agents']
  /** Agent-loop concurrency cap; `1` is serial. */
  maxParallelToolCalls?: AgentLoopConfig['maxParallelToolCalls']
+  /** Whether the system prompt includes the fixed Harness identity (default true). */
+  includeHarnessIdentity?: SystemPromptConfig['includeHarnessIdentity']
  /** The deployment persona (see dsh-system-prompt's `Config`). */
  persona?: SystemPromptConfig['persona']
  /** The explicit model-facing tool order (see dsh-system-prompt's `Config`). */
@@ -102,10 +106,14 @@ export interface Config {
  sessionTitle?: SessionTitleConfig
  /** Workspace-context loader controls with an explicit byte budget; set `false` for hermetic prompts. */
  workspaceContext: workspaceContext.Config | false
-  /** Skill registry, local provider, and model-facing consumer config. */
+  /**
+   * Skill registry, local provider, and model-facing consumer config.
+   * Skills use `enabled` because one nested config controls a provider stack;
+   * single model-tool plugins use `Config | false` to disable that one consumer.
+   */
  skills?: SkillConfig
-  /** Model-facing bash tool config, including this producer's background opt-in. */
-  toolBash?: toolBash.Config
+  /** Model-facing bash tool config, or false when another plugin owns `bash`. */
+  toolBash?: toolBash.Config | false
  /** Generic background-task controls; set false to keep the task service without model-facing task tools. */
  toolTasks?: toolTasks.Config | false
  /** Global enablement and package-name filters for invariant companions. */
@@ -127,7 +135,8 @@ export const SessionTitleConfigSchema: z<SessionTitleConfig> = SessionTitleServi
  .default(EXAMPLE_SESSION_TITLE_CONFIG)

 /** The bash-tool config schema exported for app packages that forward `toolBash`. */
-export const ToolBashConfigSchema: z<toolBash.Config> = toolBash.Config
+export const ToolBashConfigSchema: z<toolBash.Config | false> =
+  z.union([z.const(false), toolBash.Config])

 /** The task-control-tool config schema exported for app packages that forward `toolTasks`. */
 export const ToolTasksConfigSchema: z<toolTasks.Config> = toolTasks.Config
@@ -163,6 +172,7 @@ export const Config = z.intersect([
 export function pickSpineConfig(config: Omit<Config, 'agents'>): Omit<Config, 'agents'> {
  return {
    ...config.maxParallelToolCalls !== undefined ? { maxParallelToolCalls: config.maxParallelToolCalls } : {},
+    ...config.includeHarnessIdentity !== undefined ? { includeHarnessIdentity: config.includeHarnessIdentity } : {},
    ...config.persona !== undefined ? { persona: config.persona } : {},
    ...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {},
    ...config.tools !== undefined ? { tools: config.tools } : {},
@@ -201,6 +211,7 @@ export function apply(ctx: Context, config: Config): void {
  ctx.plugin(SessionTitleService, config.sessionTitle ?? EXAMPLE_SESSION_TITLE_CONFIG)
  // Owner schemas resolve defaults; forward toolOrder only when explicitly set.
  ctx.plugin(SystemPrompt, {
+    includeHarnessIdentity: config.includeHarnessIdentity ?? true,
    persona: config.persona ?? '',
    ...config.toolOrder !== undefined ? { toolOrder: config.toolOrder } : {},
  })
@@ -223,7 +234,10 @@ export function apply(ctx: Context, config: Config): void {
  ctx.plugin(agentInvariant)
  ctx.plugin(scopeInvariant)
  ctx.plugin(agentLoopInvariant)
-  ctx.plugin(toolBash, Object.assign({}, config.toolBash, { dshHome }))
+  if (config.toolBash !== false) {
+    ctx.plugin(bashEnv, { dshHome })
+    ctx.plugin(toolBash, config.toolBash ?? {})
+  }
  if (config.workspaceContext !== false) {
    ctx.plugin(workspaceContext, config.workspaceContext)
  }
--- a/packages/examples/agent-spine-demo/tests/agent-core.spec.ts
+++ b/packages/examples/agent-spine-demo/tests/agent-core.spec.ts
@@ -4,13 +4,16 @@ import { join } from 'node:path'
 import { tmpdir } from 'node:os'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
-import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
+import { renderPrompt, TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
 import * as agentCore from '../src/index.ts'
 import { agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
 import { SessionId } from '@deepseek-ai/dsh-session'
+import LocalBashExecutor from '@deepseek-ai/dsh-bash-local'
 import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
-import { MockAdapter, textResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
-import { createUserMessage,
+import * as ToolFs from '@deepseek-ai/dsh-tool-fs'
+import { MockAdapter, textResponse, toolCallResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
+import {
+  createUserMessage,
  CallId,
  LlmAdapter,
  LlmError,
@@ -36,7 +39,16 @@ declare module '@deepseek-ai/dsh-tasks' {

 async function composePrefix(ctx: Context, cwd: string): Promise<Message[]> {
  const agent = ctx.agentLoop.create(SessionId('agent-spine-prefix'), {}, { cwd })
-  await agentEvents(ctx, agent).serial('agent/step', 1, 1, new AbortController().signal)
+  const signal = new AbortController().signal
+  const decision = await agentEvents(ctx, agent).waterfall(
+    'agent/pre-step', [], { turn: 1, step: 1, signal },
+    () => Promise.resolve({ kind: 'enter', messages: [] }),
+  )
+  if (decision.kind === 'enter') {
+    for (const message of decision.messages) {
+      agent.session.append('user/message', message, { surfaceOp: 'append' })
+    }
+  }
  return agent.session.deriveMessages()
 }

@@ -163,7 +175,6 @@ describe('dsh-agent-spine-demo bundle', () => {
    const session = ctx.sessions.create(SessionId('configured-title-limits'))
    session.append('turn/start', {
      turn: 1,
-      trigger: { kind: 'message', source: { kind: 'user' } },
    })
    session.append('user/message', createUserMessage({
      content: [{ type: 'text', text: 'One two three four' }],
@@ -206,8 +217,8 @@ describe('dsh-agent-spine-demo bundle', () => {
  it('mounts package companions and forwards invariant selection config', async () => {
    const nestedTurn = (ctx: Context): void => {
      const session = ctx.sessions.create()
-      session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
-      session.append('turn/start', { turn: 2, trigger: { kind: 'message', source: { kind: 'user' } } })
+      session.append('turn/start', { turn: 1 })
+      session.append('turn/start', { turn: 2 })
    }

    const enabled = await mount({ workspaceContext: false })
@@ -324,7 +335,7 @@ describe('dsh-agent-spine-demo bundle', () => {
    try {
      await mkdir(join(root, '.git'), { recursive: true })
      await writeFile(join(root, 'AGENTS.md'), 'bundled project rule')
-      const adapter = new MockAdapter([textResponse('ok')])
+      const adapter = new MockAdapter([textResponse('first')])
      const ctx = await mount({ workspaceContext: { maxBytes: 65536 } })
      await ctx.plugin(LocalFileSystem, { cwd: '/' })
      ctx.llm.registerAdapter(['mock'], adapter)
@@ -338,9 +349,10 @@ describe('dsh-agent-spine-demo bundle', () => {
      agent.followup(createUserMessage({ content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }))
      await waitForIdle(ctx, agent)

-      const sentText = adapter.requests[0]?.messages.map(messageText).join('\n')
-      expect(sentText).toContain('hi')
-      expect(sentText).toContain('bundled project rule')
+      expect(adapter.requests).toHaveLength(1)
+      const firstRequestText = adapter.requests[0]?.messages.map(messageText).join('\n')
+      expect(firstRequestText).toContain('hi')
+      expect(firstRequestText).toContain('bundled project rule')
      expect(adapter.requests[0]?.system).toContain('You are an AI agent powered by the DeepSeek Harness SDK.')
      expect(adapter.requests[0]?.system).not.toContain('bundled project rule')
      await handle.dispose()
@@ -404,6 +416,146 @@ describe('dsh-agent-spine-demo bundle', () => {
    await ctx.fiber.dispose()
  })

+  it('snapshots a created project skill through catalog refresh and progressive loading', async () => {
+    const root = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-skill-refresh-'))
+    const home = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-skill-refresh-home-'))
+    try {
+      await mkdir(join(root, '.git'), { recursive: true })
+      const skillPath = '.agents/skills/hot-skill/SKILL.md'
+      const skillSource = '---\nname: hot-skill\ndescription: Hot-added skill\n---\n\nUse the freshly loaded body.\n'
+      const adapter = new MockAdapter([
+        toolCallResponse('mkdir-skill', 'bash', {
+          command: 'mkdir -p .agents/skills/hot-skill',
+          description: 'Create the project skill directory',
+        }),
+        toolCallResponse('write-skill', 'write', {
+          file_path: skillPath,
+          content: skillSource,
+        }),
+        toolCallResponse('load-skill', 'skill', { name: 'hot-skill' }),
+        textResponse('SKILL_REFRESH_OK'),
+      ])
+      const ctx = await mount({
+        workspaceContext: false,
+        skills: {
+          local: {
+            dshHome: join(home, '.dsh'),
+            agentsHome: join(home, '.agents'),
+            watchStabilityThresholdMs: 20,
+            watchPollIntervalMs: 10,
+          },
+        },
+      })
+      await ctx.plugin(LocalBashExecutor, {})
+      await ctx.plugin(LocalFileSystem, { cwd: root })
+      await ctx.plugin(ToolFs)
+      ctx.llm.registerAdapter(['mock'], adapter)
+      const handle = await ctx.agents.create({
+        sessionId: SessionId('skill-refresh-session'),
+        meta: { cwd: root },
+        agentOptions: { provider: 'mock', model: 'mock' },
+      })
+
+      handle.agent.followup(createUserMessage({
+        content: [{ type: 'text', text: 'Create and load the project skill.' }],
+        source: { kind: 'user' },
+      }))
+      await waitForIdle(ctx, handle.agent)
+
+      expect(adapter.requests).toHaveLength(4)
+      expect(adapter.requests.slice(0, 2).map(request => request.messages.map(messageText).join('\n')))
+        .toEqual([
+          expect.not.stringContaining('hot-skill'),
+          expect.not.stringContaining('hot-skill'),
+        ])
+      const catalogRequest = adapter.requests[2]?.messages.map(messageText).join('\n')
+      expect(catalogRequest).toContain('The following skills are available in this session:')
+      expect(catalogRequest).toContain('- `hot-skill`: Hot-added skill')
+      const loadedRequest = JSON.stringify(adapter.requests[3]?.messages)
+      expect(loadedRequest).toContain('<skill_instructions>')
+      expect(loadedRequest).toContain('Use the freshly loaded body.')
+
+      const transcript = handle.agent.session.events.flatMap<Record<string, unknown>>((event) => {
+        if (event.type === 'user/message' && event.data.source.kind === 'skill-catalog') {
+          return [{
+            type: event.type,
+            source: event.data.source,
+            text: event.data.content.map(block => block.type === 'text' ? block.text : '').join('\n'),
+          }]
+        }
+        if (event.type === 'tool/result'
+          && ['write-skill', 'load-skill'].includes(event.data.message.source.callId)) {
+          const result = event.data.message.content[0]
+          return [{
+            type: event.type,
+            callId: event.data.message.source.callId,
+            isError: result.isError,
+            text: result.content.map(block => block.type === 'text' ? block.text : '').join('\n')
+              .replaceAll(root, '{{cwd}}'),
+          }]
+        }
+        return []
+      })
+      expect(transcript).toMatchInlineSnapshot(`
+        [
+          {
+            "callId": "write-skill",
+            "isError": false,
+            "text": "<path>{{cwd}}/.agents/skills/hot-skill/SKILL.md</path>
+        <type>file</type>
+        <content>
+        Created file
+        </content>",
+            "type": "tool/result",
+          },
+          {
+            "source": {
+              "entries": [
+                {
+                  "description": "Hot-added skill",
+                  "name": "hot-skill",
+                },
+              ],
+              "form": "catalog",
+              "kind": "skill-catalog",
+            },
+            "text": "<system-reminder>
+        A skill is a reusable set of task-specific instructions. The following skills are available in this session:
+
+        <available_skills>
+        - \`hot-skill\`: Hot-added skill
+        </available_skills>
+
+        If the user names a skill, or the task clearly matches a skill's description, call the \`skill\` tool with the exact skill name before taking task actions. Load all applicable skills, then follow their full instructions. This catalog contains summaries only; do not infer or follow a skill's instructions until it has been loaded.
+        </system-reminder>",
+            "type": "user/message",
+          },
+          {
+            "callId": "load-skill",
+            "isError": false,
+            "text": "<skill_content name="hot-skill">
+        <skill_resources>
+        Base directory for this skill: {{cwd}}/.agents/skills/hot-skill
+        Resolve relative paths mentioned by this skill against the base directory before using them. Load referenced resources only as needed.
+        </skill_resources>
+
+        <skill_instructions>
+        Use the freshly loaded body.
+        </skill_instructions>
+        </skill_content>",
+            "type": "tool/result",
+          },
+        ]
+      `)
+
+      await handle.dispose()
+      await ctx.fiber.dispose()
+    } finally {
+      await rm(root, { recursive: true, force: true })
+      await rm(home, { recursive: true, force: true })
+    }
+  })
+
  it('shares top-level dshHome between local skills and the managed bash environment', async () => {
    const home = await mkdtemp(join(tmpdir(), 'dsh-agent-core-shared-home-'))
    const agentsHome = await mkdtemp(join(tmpdir(), 'dsh-agent-core-shared-agents-'))
@@ -438,12 +590,12 @@ describe('dsh-agent-spine-demo bundle', () => {
    }).toThrow('agent-spine-demo: dshHome and skills.local.dshHome must resolve to the same directory')
  })

-  it('places workspace instructions before the skill catalog in the session prefix', async () => {
+  it('delivers workspace instructions ahead of the first-step skill catalog', async () => {
    const root = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-prefix-order-'))
    try {
      await mkdir(join(root, '.git'), { recursive: true })
      await writeFile(join(root, 'AGENTS.md'), 'workspace rule before skills')
-      const adapter = new MockAdapter([textResponse('ok')])
+      const adapter = new MockAdapter([textResponse('first')])
      const ctx = await mount({ workspaceContext: { maxBytes: 65536 } })
      await ctx.plugin(LocalFileSystem, { cwd: '/' })
      ctx.llm.registerAdapter(['mock'], adapter)
@@ -462,8 +614,16 @@ describe('dsh-agent-spine-demo bundle', () => {
      handle.agent.followup(createUserMessage({ content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } }))
      await waitForIdle(ctx, handle.agent)

-      expect(messageText(adapter.requests[0]?.messages[1])).toContain('workspace rule before skills')
-      expect(messageText(adapter.requests[0]?.messages[2])).toContain('prefix-order-skill')
+      expect(adapter.requests).toHaveLength(1)
+      const workspaceIndex = adapter.requests[0]!.messages.findIndex(
+        message => messageText(message).includes('workspace rule before skills'),
+      )
+      const catalogIndex = adapter.requests[0]!.messages.findIndex(
+        message => messageText(message).includes('prefix-order-skill'),
+      )
+      expect(workspaceIndex).toBeGreaterThanOrEqual(0)
+      expect(catalogIndex).toBeGreaterThanOrEqual(0)
+      expect(workspaceIndex).toBeLessThan(catalogIndex)
      await handle.dispose()
      await ctx.fiber.dispose()
    } finally {
@@ -515,9 +675,27 @@ describe('dsh-agent-spine-demo bundle', () => {
    await ctx.fiber.dispose()
  })

+  it('can omit the bundled bash tool and Harness identity for a compatibility deployment', async () => {
+    const ctx = await mount({
+      includeHarnessIdentity: false,
+      persona: 'You are a helpful software engineer assistant.',
+      workspaceContext: false,
+      skills: { enabled: false },
+      toolBash: false,
+      toolTasks: false,
+    }, true)
+
+    expect(ctx.tools.schemas()).toEqual([])
+    expect(renderPrompt(await ctx.systemPrompt.assemble()))
+      .toBe('You are a helpful software engineer assistant.')
+
+    await ctx.fiber.dispose()
+  })
+
  it('picks shared spine config without leaking front-door fields', () => {
    const appConfig = {
      model: 'front-door-only',
+      includeHarnessIdentity: false,
      persona: 'You are merged.',
      toolOrder: ['zulu'],
      tools: { mode: 'native' as const },
@@ -531,6 +709,7 @@ describe('dsh-agent-spine-demo bundle', () => {
    }

    expect(agentCore.pickSpineConfig(appConfig)).toEqual({
+      includeHarnessIdentity: appConfig.includeHarnessIdentity,
      persona: appConfig.persona,
      toolOrder: appConfig.toolOrder,
      tools: appConfig.tools,
--- a/packages/examples/agent-spine-demo/tsconfig.json
+++ b/packages/examples/agent-spine-demo/tsconfig.json
@@ -68,6 +68,9 @@
    {
      "path": "../../util/paths"
    },
+    {
+      "path": "../../bash/bash-env"
+    },
    {
      "path": "../../bash/tool-bash"
    },
--- a/packages/examples/cli-demo/README.i18n.yaml
+++ b/packages/examples/cli-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/cli-demo/README.md
-README.md: b8f2bde962738a1a23f0e57218ab0f90e8e0b705
-README.zh.md: 0e03375ced4e087d44eed7ff33666abf1f2cec10
+README.md: 6e46ae81421c23806524b0784a976e9f3c8eeab8
+README.zh.md: b032023fee4bf9d992217cc51731f6356f875daf
--- a/packages/examples/cli-demo/README.md
+++ b/packages/examples/cli-demo/README.md
@@ -2,7 +2,7 @@

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

-Headless one-shot app and bin for running one agent task without an interactive UI or editor client. It composes [`@deepseek-ai/dsh-agent-spine-demo`](../agent-spine-demo/README.md), JSONL persistence, and exactly one fresh top-level agent. The bin submits the task, waits for its durable turn ending, renders the selected output, disposes to quiescence, and exits.
+Headless one-shot app and bin for running one agent task without an interactive UI or editor client. It composes [`@deepseek-ai/dsh-agent-spine-demo`](../agent-spine-demo/README.md), JSONL persistence, and exactly one fresh top-level agent. The bin owns one idle-to-idle activity interval, renders its selected output, disposes to quiescence, and exits.

 The package mounts no console logger, interactive UI, user-interaction service, or `ask_user_question` tool. Stdout is reserved for the selected output format; diagnostics use stderr.

@@ -44,12 +44,12 @@ Loader configs resolve bare package specifiers through the optional native helpe
 ### Output formats

 - `text` writes the last assistant message containing text, followed by one newline.
- `json` writes one DSH-native result record: `{ type: "result", success, sessionId, turn, result, reason, usage? }`. `usage` sums each model step in the task turn once, including billed failed retry attempts that produced usage without a committed assistant message.
- `stream-json` writes each canonical event from the top-level session's task turn as `{ type: "session_event", sessionId, event }`, then the same result record. Child-agent activity appears only through the parent tool events and results.
+- `json` writes one DSH-native result record: `{ type: "result", sessionId, output, usage? }`. `output` is the last committed assistant text in the activity interval. `usage` sums each model step in that interval once, including billed failed attempts that produced usage without a committed assistant message.
+- `stream-json` writes each canonical event from the top-level session's owned activity interval as `{ type: "session_event", sessionId, event }`, then the same result record. Child-agent activity appears only through the parent tool events and results.

-Only `reason.kind === "completed"` exits successfully. Other durable turn endings still emit partial text or a result record, add a stderr diagnostic, and exit nonzero. Argument and boot failures leave stdout empty. SIGINT and SIGTERM cancel active work, await disposal, and exit 130 and 143 respectively.
+Normal idle completion exits successfully without assigning a turn reason to the task. Argument, boot, observation, and persistence failures leave stdout empty. SIGINT and SIGTERM cancel active work, await disposal, and exit 130 and 143 respectively.

-The task turn is explicitly flushed before final output. Session logs remain under `persistenceRoot` after the process exits.
+The owned activity is explicitly flushed before final output. Session logs remain under `persistenceRoot` after the process exits.

 ## Operational safety

@@ -57,11 +57,11 @@ The headless-agent leaf supplies local bash, filesystem, skill, subagent, workfl

 ## Model Experience

-### One-shot task turn
+### One-shot activity

 #### What the model sees

-The positional task becomes one user message. Through `dsh-agent-spine-demo`, the top-level agent also receives configured workspace instructions and persona, the skill catalog, visible tool schemas, and retained tool results needed for later steps in the same turn.
+The positional task becomes one user message. Through `dsh-agent-spine-demo`, the top-level agent also receives configured workspace instructions and persona, the skill catalog, visible tool schemas, and retained tool results needed for later steps in the owned activity.

 #### Token effect

@@ -75,4 +75,4 @@ Tool-round history is append-only while the one-shot agent's prompt, schemas, mo

 - **One fresh top-level session per process** — its workspace cwd is the launch directory; there is no resume, second prompt, stdin context, or concurrent top-level session in this app.
 - **No interactive question or approval provider** — tools that require a human answer cannot complete unless a different leaf composes a non-interactive provider with explicit policy.
- **Streaming is top-level-session-only** — child sessions are not flattened into the stream, and aggregate usage covers only model steps recorded on the parent task turn.
+- **Streaming is top-level-session-only** — child sessions are not flattened into the stream, and aggregate usage covers only model steps recorded on the parent activity interval.
--- a/packages/examples/cli-demo/README.zh.md
+++ b/packages/examples/cli-demo/README.zh.md
@@ -2,9 +2,9 @@

 [English](README.md) | 中文

-无头单次应用及 bin，用于在没有交互式 UI 或编辑器客户端的情况下运行一项 agent（智能体）任务。它组合 [`@deepseek-ai/dsh-agent-spine-demo`](../agent-spine-demo/README.md)、JSONL 持久化，以及恰好一个新建顶层 agent。bin 提交任务，等待其已持久化的轮次结束状态，渲染所选输出，执行 dispose（资源释放）直至完全停稳，然后退出。
+无头单次应用及 bin，用于在没有交互式 UI 或编辑器客户端的情况下运行一项 agent（智能体）任务。它组合 [`@deepseek-ai/dsh-agent-spine-demo`](../agent-spine-demo/README.md)、JSONL 持久化，以及恰好一个新建顶层 agent。bin 拥有一个从 idle 到 idle 的活动区间，渲染所选输出，执行 dispose（资源释放）直至完全停稳，然后退出。

-该包（package）不挂载 console logger、交互式 UI、用户交互服务或 `ask_user_question` 工具。Stdout 专用于所选输出格式；诊断使用 stderr。
+该包不挂载 console logger、交互式 UI、用户交互服务或 `ask_user_question` 工具。Stdout 专用于所选输出格式；诊断使用 stderr。

 ## 配置

@@ -44,12 +44,12 @@ loader 配置通过仓库安装的可选原生辅助程序解析裸包说明符
 ### 输出格式

 - `text` 写入最后一条含文本的 assistant 消息，后跟一个换行符。
- `json` 写入一条 DSH 原生结果记录：`{ type: "result", success, sessionId, turn, result, reason, usage? }`。`usage` 对任务轮次中的每个模型步骤恰好求和一次，包括产生用量但没有提交 assistant 消息的已计费失败重试。
- `stream-json` 将顶层会话任务轮次中的每个规范事件写成 `{ type: "session_event", sessionId, event }`，然后写入同一结果记录。子 agent 活动只通过父工具事件与结果出现。
+- `json` 写入一条 DSH 原生结果记录：`{ type: "result", sessionId, output, usage? }`。`output` 是活动区间内最后提交的 assistant 文本。`usage` 对该区间中的每个模型步骤恰好求和一次，包括产生用量但没有提交 assistant 消息的已计费失败尝试。
+- `stream-json` 将顶层会话自有活动区间中的每个规范事件写成 `{ type: "session_event", sessionId, event }`，然后写入同一结果记录。子 agent 活动只通过父工具事件与结果出现。

-只有 `reason.kind === "completed"` 会成功退出。其他已持久化的轮次结束状态仍会输出部分文本或结果记录，向 stderr 添加诊断，并以非零状态退出。参数和启动失败会让 stdout 保持为空。SIGINT 与 SIGTERM 会取消正在进行的工作，等待 dispose 完成，并分别以 130 和 143 退出。
+正常进入 idle 会成功退出，不会为该任务指定轮次原因。参数、启动、观测和持久化失败会让 stdout 保持为空。SIGINT 与 SIGTERM 会取消正在进行的工作，等待 dispose 完成，并分别以 130 和 143 退出。

-任务轮次会在最终输出前显式刷新。进程退出后，会话日志仍保留在 `persistenceRoot` 下。
+自有活动会在最终输出前显式刷新。进程退出后，会话日志仍保留在 `persistenceRoot` 下。

 ## 操作安全

@@ -57,11 +57,11 @@ headless-agent 叶节点提供本地 bash、文件系统、skill、subagent、

 ## 模型体验

-### 单次任务轮次
+### 单次活动

 #### 模型看到的内容

-任务位置参数会成为一条用户消息。通过 `dsh-agent-spine-demo`，顶层 agent 还会收到已配置的工作区指令与 persona、skill 目录、可见工具 schema，以及同一轮次后续步骤所需的保留工具结果。
+任务位置参数会成为一条用户消息。通过 `dsh-agent-spine-demo`，顶层 agent 还会收到已配置的工作区指令与 persona、skill 目录、可见工具 schema，以及自有活动后续步骤所需的保留工具结果。

 #### Token 影响

@@ -75,4 +75,4 @@ headless-agent 叶节点提供本地 bash、文件系统、skill、subagent、

 - **每个进程只创建一个新的顶层会话**：其工作区 cwd 是启动目录；此应用不支持恢复、第二条提示词、stdin 上下文或并发顶层会话。
 - **没有交互式问题或批准提供方**：需要人工回答的工具无法完成，除非其他叶节点按显式策略组合一个非交互式提供方。
- **流式输出仅限顶层会话**：子会话不会平铺到流中，聚合用量只涵盖父任务轮次记录的模型步骤。
+- **流式输出仅限顶层会话**：子会话不会平铺到流中，聚合用量只涵盖父活动区间记录的模型步骤。
--- a/packages/examples/cli-demo/package.json
+++ b/packages/examples/cli-demo/package.json
@@ -29,9 +29,7 @@
    "lib/index.js",
    "lib/invariant.js",
    "lib/bin.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
+    "lib/types/**/*.d.ts"
  ],
  "license": "BSD-3-Clause",
  "peerDependencies": {
--- a/packages/examples/cli-demo/src/cli.ts
+++ b/packages/examples/cli-demo/src/cli.ts
@@ -8,7 +8,7 @@ import { parseArgs } from 'node:util'
 import type { Context } from 'cordis'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import { createUserMessage, type TokenUsage } from '@deepseek-ai/dsh-llm'
-import type { SessionEvent, TurnEndReason } from '@deepseek-ai/dsh-session'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import { boot, loadEnv, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'

 const CLI_NAME = 'dsh-cli-demo'
@@ -32,11 +32,8 @@ export type CliCommand =
 /** DSH-native final record emitted by JSON modes. */
 export interface CliResult {
  readonly type: 'result'
-  readonly success: boolean
  readonly sessionId: string
-  readonly turn: number
-  readonly result: string
-  readonly reason: TurnEndReason
+  readonly output: string
  readonly usage?: TokenUsage
 }

@@ -148,7 +145,7 @@ export function parseCliArgs(args: readonly string[]): CliCommand {
    throw new CliArgumentError(`expected exactly one positional task or -p, received ${parsed.positionals.length} positional(s)`)
  }
  // Cardinality was checked above, so the fallback index zero exists.
-  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  // oxlint-disable-next-line typescript/no-non-null-assertion
  const task = prompt ?? parsed.positionals[0]!
  if (task.trim().length === 0) throw new CliArgumentError('task must not be blank')

@@ -203,13 +200,8 @@ async function waitForStartupIdle(agent: Agent, signal?: AbortSignal): Promise<v
 }

 /**
- * Run one message-triggered turn on the configured top-level agent, aggregate its
- * final text and model usage, wait for idle plus an explicit persistence flush,
- * and return its durable ending. Only the selected agent's task turn reaches
- * `onEvent`; startup injections and unrelated sessions are ignored. The context
- * must contain exactly one top-level agent. Signal abort cancels that agent; an
- * abort before the correlated task turn rejects. An observer throw cancels the
- * turn and is rethrown after the agent reaches idle and the session flushes.
+ * Run one owned activity interval on the configured top-level agent, from the
+ * task's durable enqueue receipt through whole-agent idle.
 * @param ctx - settled Loader root containing one agent plus `ctx.sessions`.
 * @param options - task, optional cancellation, and optional stream observer.
 * @returns the DSH-native result envelope after durable quiescence.
@@ -222,77 +214,49 @@ export async function runOneShot(ctx: Context, options: OneShotOptions): Promise
  }
  await waitForStartupIdle(agent, options.signal)

-  let targetTurn: number | undefined
-  let reason: TurnEndReason | undefined
-  let result = ''
+  const message = createUserMessage({ content: [{ type: 'text', text: options.task }], source: { kind: 'user' } })
+  let received = false
+  let output = ''
  const usageByStep = new Map<string, TokenUsage>()
  let outputError: Error | undefined
-  let resolveTurn!: () => void
-  let rejectTurn!: (error: Error) => void
-  let firstTurnEnded = false
-  const turnEnded = new Promise<void>((resolve, reject) => {
-    resolveTurn = resolve
-    rejectTurn = reject
-  })
-
-  const settleResolved = (): void => {
-    if (firstTurnEnded) return
-    firstTurnEnded = true
-    resolveTurn()
-  }
-  const settleRejected = (error: Error): void => {
-    // The once-registered abort listener is the only rejecter, and a settled
-    // prompt makes targetTurn defined so onAbort skips rejection entirely;
-    // kept for symmetry with settleResolved.
-    /* v8 ignore next -- unreachable second settlement, see above */
-    if (firstTurnEnded) return
-    firstTurnEnded = true
-    rejectTurn(error)
-  }
+  let interrupted: CliInterruptedError | undefined
  const observe = (sessionId: string, event: SessionEvent): void => {
    if (outputError !== undefined || options.onEvent === undefined) return
    try {
      options.onEvent(sessionId, event)
    } catch (error: unknown) {
      outputError = toError(error)
-      agent.cancel({ kind: 'user' })
+      queueMicrotask(() => {
+        agent.cancel({ kind: 'user' })
+      })
    }
  }

  const disposeListener = ctx.on('session/event', (session, event) => {
    if (session !== agent.session) return
-    if (targetTurn === undefined) {
-      if (event.type !== 'turn/start' || event.data.trigger.kind !== 'message') return
-      targetTurn = event.data.turn
-    } else if (event.type === 'turn/start' && event.data.trigger.kind === 'retry'
-      && reason?.kind === 'error') {
-      targetTurn = event.data.turn
-      reason = undefined
+    if (!received) {
+      if (event.type !== 'agent/inbox/spliced'
+        || !event.data.inserted.some(inserted => inserted.id === message.id)) return
+      received = true
    }
    observe(session.id, event)
-    if (event.type === 'assistant/chunk'
-      && event.data.turn === targetTurn
-      && event.data.chunk.type === 'usage') {
+    if (event.type === 'assistant/chunk' && event.data.chunk.type === 'usage') {
      usageByStep.set(`${event.data.turn}/${event.data.step}`, event.data.chunk.usage)
    }
-    if (event.type === 'assistant/message' && event.data.turn === targetTurn) {
-      result = assistantText(event) ?? result
+    if (event.type === 'assistant/message') {
+      output = assistantText(event) ?? output
      if (event.data.usage !== undefined) {
        usageByStep.set(`${event.data.turn}/${event.data.step}`, event.data.usage)
      }
    }
-    if (event.type === 'turn/end' && event.data.turn === targetTurn) {
-      reason = event.data.reason
-      settleResolved()
-    }
  })

  const signal = options.signal
  let onAbort: (() => void) | undefined
  if (signal !== undefined) {
    onAbort = (): void => {
+      interrupted ??= new CliInterruptedError(interruptionReason(signal))
      agent.cancel({ kind: 'user' })
-      if (targetTurn === undefined) settleRejected(new CliInterruptedError(interruptionReason(signal)))
    }
    signal.addEventListener('abort', onAbort, { once: true })
    /* v8 ignore next -- closes the race between startup-idle completion and listener registration */
@@ -300,37 +264,27 @@ export async function runOneShot(ctx: Context, options: OneShotOptions): Promise
  }

  try {
-    /* v8 ignore next -- skips send only when cancellation wins the listener-registration race above */
-    if (!firstTurnEnded) { // eslint-disable-line @typescript-eslint/no-unnecessary-condition
-      agent.followup(createUserMessage({ content: [{ type: 'text', text: options.task }], source: { kind: 'user' } }))
-    }
-    await turnEnded
+    if (interrupted === undefined) agent.followup(message)
+    await agent.whenIdle()
  } finally {
    if (onAbort !== undefined) signal?.removeEventListener('abort', onAbort)
-    await agent.whenIdle()
    disposeListener()
  }

-  /* v8 ignore next 3 -- turnEnded resolves only from the matching branch that assigns both values */
-  if (targetTurn === undefined || reason === undefined) {
-    throw new Error('task ended without a correlated turn/end event')
-  }
  await ctx.sessions.flush(agent.session)
  if (outputError !== undefined) throw outputError
+  if (interrupted !== undefined) throw interrupted
  const usage = [...usageByStep.values()].reduce<TokenUsage | undefined>(addUsage, undefined)
  return {
    type: 'result',
-    success: reason.kind === 'completed',
    sessionId: agent.session.id,
-    turn: targetTurn,
-    result,
-    reason,
+    output,
    ...usage === undefined ? {} : { usage },
  }
 }

 function renderResult(outputFormat: OutputFormat, result: CliResult): string {
-  return outputFormat === 'text' ? `${result.result}\n` : `${JSON.stringify(result)}\n`
+  return outputFormat === 'text' ? `${result.output}\n` : `${JSON.stringify(result)}\n`
 }

 /**
@@ -361,7 +315,7 @@ async function bootInterruptibly(
    return await Promise.race([booting, interruptedBoot])
  } catch (error: unknown) {
    // The awaited race permits the signal to change after the preflight check.
-    // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+    // oxlint-disable-next-line typescript/no-unnecessary-condition
    if (signal.aborted) {
      void booting.then(
        async (lateContext) => {
@@ -380,23 +334,6 @@ async function bootInterruptibly(
  }
 }

-/**
- * Render a non-completed turn reason for stderr.
- * @param reason - durable turn ending to describe.
- * @returns a concise diagnostic fragment.
- */
-export function formatTurnFailure(reason: TurnEndReason): string {
-  switch (reason.kind) {
-    case 'completed': return 'completed'
-    case 'aborted': return 'was aborted'
-    case 'error': return `failed at step ${reason.step}: ${'failure' in reason ? reason.failure.message : reason.message}`
-    case 'disposed': return 'was disposed'
-    case 'max-tokens': return 'reached the model output-token limit'
-    case 'interrupted': return 'was interrupted during persistence recovery'
-    default: return `ended with ${JSON.stringify(reason)}`
-  }
-}
-
 /**
 * Execute one CLI invocation. Argument and boot failures never write stdout;
 * context disposal is awaited before return, and its failure does not replace
@@ -451,8 +388,7 @@ export async function executeCli(args: readonly string[], runtime: CliRuntime =
        : {},
    })
    writeStdout(renderResult(command.outputFormat, result))
-    exitCode = result.success ? 0 : 1
-    if (!result.success) diagnostic = `${CLI_NAME}: turn ${result.turn} ${formatTurnFailure(result.reason)}\n`
+    exitCode = 0
  } catch (error: unknown) {
    diagnostic = `${CLI_NAME}: ${toError(error).message}\n`
  } finally {
--- a/packages/examples/cli-demo/tests/built-bin.e2e.ts
+++ b/packages/examples/cli-demo/tests/built-bin.e2e.ts
@@ -161,14 +161,26 @@ describe.skipIf(!existsSync(cliBin))('dsh-cli-demo BUILT bin', () => {

    const json = await runBuiltBin(consumer, ['--config', './cordis.yml', '--output-format', 'json', 'json task'])
    expect(JSON.parse(json.stdout)).toMatchObject({
-      type: 'result', success: true, result: 'BUILT: json task', reason: { kind: 'completed' },
+      type: 'result', output: 'BUILT: json task',
      usage: { inputTokens: 4, outputTokens: 2 },
    })

    const stream = await runBuiltBin(consumer, ['--config', './cordis.yml', '--output-format', 'stream-json', 'stream task'])
    const lines = stream.stdout.trimEnd().split('\n').map(line => JSON.parse(line) as Record<string, unknown>)
-    expect(lines[0]).toMatchObject({ type: 'session_event', event: { type: 'turn/start' } })
-    expect(lines.at(-1)).toMatchObject({ type: 'result', success: true, result: 'BUILT: stream task' })
+    expect(lines[0]).toMatchObject({
+      type: 'session_event',
+      event: {
+        type: 'agent/inbox/spliced',
+        data: {
+          target: 'next-turn',
+          start: 0,
+          inserted: [{ content: [{ type: 'text', text: 'stream task' }], source: { kind: 'user' } }],
+        },
+      },
+    })
+    expect(lines.findIndex(line =>
+      (line['event'] as { type?: string } | undefined)?.type === 'turn/start')).toBeGreaterThan(0)
+    expect(lines.at(-1)).toMatchObject({ type: 'result', output: 'BUILT: stream task' })
    const sessionsRoot = join(consumer, '.sessions')
    const files = await readdir(sessionsRoot, { recursive: true })
    const logs = files.filter(file => file.endsWith('.jsonl.zstd'))
@@ -205,7 +217,7 @@ describe.skipIf(!existsSync(cliBin))('dsh-cli-demo BUILT bin', () => {
      )
      expect(result, JSON.stringify(result)).toMatchObject({ code, signal: null })
      expect(result.stdout).toContain('"kind":"aborted"')
-      expect(result.stderr).toContain('turn 1 was aborted')
+      expect(result.stderr).toBe(`dsh-cli-demo: received ${signal}\n`)
    }, 30_000)
  })
 })
--- a/packages/examples/cli-demo/tests/cli-demo.spec.ts
+++ b/packages/examples/cli-demo/tests/cli-demo.spec.ts
@@ -43,7 +43,16 @@ async function mount(config: cliDemo.Config, withBash = false): Promise<Context>

 async function composePrefix(ctx: Context): Promise<Message[]> {
  const agent = ctx.agentLoop.create(SessionId(`cli-demo-prefix-${randomUUID()}`), {}, { cwd: '/tmp' })
-  await agentEvents(ctx, agent).serial('agent/step', 1, 1, new AbortController().signal)
+  const signal = new AbortController().signal
+  const decision = await agentEvents(ctx, agent).waterfall(
+    'agent/pre-step', [], { turn: 1, step: 1, signal },
+    () => Promise.resolve({ kind: 'enter', messages: [] }),
+  )
+  if (decision.kind === 'enter') {
+    for (const message of decision.messages) {
+      agent.session.append('user/message', message, { surfaceOp: 'append' })
+    }
+  }
  return agent.session.deriveMessages()
 }

--- a/packages/examples/cli-demo/tests/cli.spec.ts
+++ b/packages/examples/cli-demo/tests/cli.spec.ts
@@ -12,12 +12,11 @@ import { createUserMessage,
  type StreamChunk,
  type TokenUsage,
 } from '@deepseek-ai/dsh-llm'
-import { SessionId, type SessionEvent, type TurnEndReason } from '@deepseek-ai/dsh-session'
+import { SessionId, type SessionEvent } from '@deepseek-ai/dsh-session'
 import { afterEach, describe, expect, it } from 'vitest'
 import * as cliDemo from '../src/index.ts'
 import {
  executeCli,
-  formatTurnFailure,
  parseCliArgs,
  runOneShot,
  type CliResult,
@@ -114,14 +113,13 @@ const liveContexts: Context[] = []

 async function harness(script: readonly ScriptEntry[]): Promise<Harness> {
  const root = await mkdtemp(join(tmpdir(), 'dsh-cli-runner-'))
-  const skillHome = await mkdtemp(join(tmpdir(), 'dsh-cli-runner-skills-'))
  const ctx = new Context()
  liveContexts.push(ctx)
  await ctx.plugin(cliDemo, {
    provider: 'mock',
    model: 'mock',
    persistenceRoot: root,
-    skills: { local: { dshHome: join(skillHome, '.dsh'), agentsHome: join(skillHome, '.agents') } },
+    skills: { enabled: false },
    workspaceContext: false,
  })
  await new Promise(resolve => setTimeout(resolve, 80))
@@ -339,6 +337,16 @@ describe('runOneShot and executeCli', () => {
    expect(files.some(file => file.endsWith('.jsonl.zstd'))).toBe(true)
  })

+  it('writes correlated session events in stream-json mode', async () => {
+    const { ctx } = await harness([textResponse('streamed answer')])
+    const output = await invoke(ctx, ['--output-format', 'stream-json', 'task'])
+    const records = output.stdout.trim().split('\n').map(line => JSON.parse(line) as { type: string })
+
+    expect(output.code).toBe(0)
+    expect(records.some(record => record.type === 'session_event')).toBe(true)
+    expect(records.at(-1)).toMatchObject({ type: 'result', output: 'streamed answer' })
+  })
+
  it('sums usage across tool steps and selects the last text-bearing assistant message', async () => {
    const first = { inputTokens: 10, outputTokens: 3, cacheReadTokens: 2, cacheWriteTokens: 1 }
    const second = { inputTokens: 7, outputTokens: 5, cacheReadTokens: 4, reasoningTokens: 6 }
@@ -346,7 +354,7 @@ describe('runOneShot and executeCli', () => {
    const output = await invoke(ctx, ['--output-format', 'json', 'task'])
    const result = JSON.parse(output.stdout) as CliResult
    expect(output.code).toBe(0)
-    expect(result).toMatchObject({ type: 'result', success: true, turn: 1, result: 'done', reason: { kind: 'completed' } })
+    expect(result).toMatchObject({ type: 'result', output: 'done' })
    expect(result.usage).toEqual({
      inputTokens: 17,
      outputTokens: 8,
@@ -356,7 +364,7 @@ describe('runOneShot and executeCli', () => {
    })
  })

-  it('counts a failed retry attempt once even though it has no assistant message', async () => {
+  it('reports usage committed by the recovered assistant message', async () => {
    const failed = { inputTokens: 11, outputTokens: 2, cacheReadTokens: 3 }
    const recovered = { inputTokens: 7, outputTokens: 5, reasoningTokens: 4 }
    const { ctx } = await harness([failedResponse(failed), textResponse('done', recovered)])
@@ -364,9 +372,8 @@ describe('runOneShot and executeCli', () => {
    const result = await runOneShot(ctx, { task: 'task' })

    expect(result.usage).toEqual({
-      inputTokens: 18,
-      outputTokens: 7,
-      cacheReadTokens: 3,
+      inputTokens: 7,
+      outputTokens: 5,
      reasoningTokens: 4,
    })
  })
@@ -377,38 +384,120 @@ describe('runOneShot and executeCli', () => {
      reasoningResponse('reasoning only'),
    ])
    const result = await runOneShot(ctx, { task: 'task' })
-    expect(result.result).toBe('working')
+    expect(result.output).toBe('working')
  })

-  it('streams only the correlated main message turn and then the result envelope', async () => {
-    const { ctx, agent } = await harness([textResponse('streamed')])
+  it('observes only the correlated main message turn', async () => {
+    const { ctx, agent } = await harness([
+      textResponse('startup'),
+      textResponse('autonomous'),
+      textResponse('streamed'),
+    ])
    const other = ctx.sessions.create(SessionId('unrelated'))
-    let injected = false
-    ctx.on('agent/inbox/enqueue', (subject) => {
-      if (subject !== agent || injected) return
-      injected = true
-      agent.inject(createUserMessage({ content: [{ type: 'text', text: 'startup injection' }], source: { kind: 'plugin', plugin: 'test' } }))
-      other.append('turn/start', { turn: 1, trigger: { kind: 'injection', source: { kind: 'plugin', plugin: 'test' } } })
+    let startupStarted!: () => void
+    const started = new Promise<void>((resolve) => { startupStarted = resolve })
+    const releaseStartup = Promise.withResolvers<undefined>()
+    ctx.on('session/event', (session, event) => {
+      if (session === agent.session && event.type === 'assistant/message'
+        && event.data.turn === 1) startupStarted()
+    })
+    ctx.on('agent/turn-stopping', async (subject, turn) => {
+      if (subject === agent && turn === 1) await releaseStartup.promise
+    })
+    agent.followup(createUserMessage({
+      content: [{ type: 'text', text: 'startup' }],
+      source: { kind: 'plugin', plugin: 'startup' },
+    }))
+    await started
+
+    const followup = agent.followup.bind(agent)
+    let injectedBeforeReceipt = false
+    agent.followup = (input) => {
+      if (!injectedBeforeReceipt && input.source.kind === 'user') {
+        injectedBeforeReceipt = true
+        agent.inbox.append('next-step', createUserMessage({
+          content: [{ type: 'text', text: 'wrong receipt' }],
+          source: { kind: 'plugin', plugin: 'test-wrong-receipt' },
+        }))
+        other.append('user/message', createUserMessage({
+          content: [{ type: 'text', text: 'unrelated session event' }],
+          source: { kind: 'plugin', plugin: 'test' },
+        }), { surfaceOp: 'append' })
+        agent.session.append('user/message', createUserMessage({
+          content: [{ type: 'text', text: 'uncorrelated main-session event' }],
+          source: { kind: 'plugin', plugin: 'test-before-receipt' },
+        }), { surfaceOp: 'append' })
+      }
+      followup(input)
+    }
+
+    let replacementQueued = false
+    ctx.on('agent/status', (subject, status) => {
+      if (subject !== agent || status !== 'idle' || replacementQueued) return
+      replacementQueued = true
+      agent.followup(createUserMessage({
+        content: [{ type: 'text', text: 'autonomous' }],
+        source: { kind: 'plugin', plugin: 'test' },
+      }))
+      other.append('turn/start', { turn: 1 })
      other.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
    })
-    const output = await invoke(ctx, ['--output-format', 'stream-json', 'task'])
-    const lines = output.stdout.trimEnd().split('\n').map(line => JSON.parse(line) as Record<string, unknown>)
-    const events = lines.slice(0, -1).map(line => line['event'] as SessionEvent)
-    expect(lines.at(-1)).toMatchObject({ type: 'result', success: true, turn: 1, result: 'streamed' })
-    expect(events[0]).toMatchObject({ type: 'turn/start', data: { turn: 1, trigger: { kind: 'message' } } })
-    expect(events.at(-1)).toMatchObject({ type: 'turn/end', data: { turn: 1 } })
-    expect(lines.slice(0, -1).every(line => line['sessionId'] === agent.session.id)).toBe(true)
+    const streamed: { sessionId: string; event: SessionEvent }[] = []
+    const result = runOneShot(ctx, {
+      task: 'task',
+      onEvent: (sessionId, event) => { streamed.push({ sessionId, event }) },
+    })
+    releaseStartup.resolve(undefined)
+
+    const outcome = await result
+    expect(outcome).toMatchObject({ type: 'result', output: 'streamed' })
+    const events = streamed.map(item => item.event)
+    expect(events.find(event => event.type === 'turn/start'))
+      .toMatchObject({ type: 'turn/start', data: { turn: 3 } })
+    expect(events.at(-1)).toMatchObject({ type: 'turn/end', data: { turn: 3 } })
+    expect(streamed.every(item => item.sessionId === agent.session.id)).toBe(true)
    expect(events.some(event => event.type === 'user/message'
      && event.data.source.kind === 'plugin'
      && event.data.source.plugin === 'test')).toBe(false)
+    expect(events.some(event => event.type === 'user/message'
+      && event.data.source.kind === 'plugin'
+      && event.data.source.plugin === 'test-before-receipt')).toBe(false)
  })

-  it('emits partial data and a diagnostic for non-completed turns', async () => {
+  it('correlates a task whose step history is replaced', async () => {
+    const { ctx } = await harness([textResponse('rewritten answer')])
+    ctx.on('agent/pre-step', async () => ({
+      kind: 'enter',
+      messages: [createUserMessage({
+        content: [{ type: 'text', text: 'rewritten task' }],
+        source: { kind: 'plugin', plugin: 'test' },
+      })],
+    }))
+
+    await expect(runOneShot(ctx, { task: 'original task' })).resolves.toMatchObject({
+      type: 'result',
+      output: 'rewritten answer',
+    })
+  })
+
+  it('settles rejected tasks at whole-agent idle without attributing a result', async () => {
+    const blocked = await harness([])
+    blocked.ctx.on('agent/pre-step', async () => ({
+      kind: 'reject' as const,
+    }))
+    await expect(runOneShot(blocked.ctx, { task: 'task' })).resolves.toMatchObject({ output: '' })
+
+    const failed = await harness([])
+    failed.ctx.on('agent/pre-step', async () => { throw new Error('pre-step exploded') })
+    await expect(runOneShot(failed.ctx, { task: 'task' })).resolves.toMatchObject({ output: '' })
+  })
+
+  it('emits partial data without attributing a turn outcome', async () => {
    const { ctx } = await harness([textResponse('partial', { inputTokens: 2, outputTokens: 3 }, 'max-tokens')])
    const output = await invoke(ctx, ['--output-format', 'json', 'task'])
-    expect(JSON.parse(output.stdout)).toMatchObject({ success: false, result: 'partial', reason: { kind: 'max-tokens' } })
-    expect(output.code).toBe(1)
-    expect(output.stderr).toContain('output-token limit')
+    expect(JSON.parse(output.stdout)).toMatchObject({ type: 'result', output: 'partial' })
+    expect(output.code).toBe(0)
+    expect(output.stderr).toBe('')
  })

  it('cancels an active turn, emits its durable aborted result, and disposes', async () => {
@@ -423,9 +512,9 @@ describe('runOneShot and executeCli', () => {
    await running
    abort.abort('received SIGINT')
    const output = await outcome
-    expect(JSON.parse(output.stdout)).toMatchObject({ success: false, reason: { kind: 'aborted' } })
+    expect(output.stdout).toBe('')
    expect(output.code).toBe(1)
-    expect(output.stderr).toContain('turn 1 was aborted')
+    expect(output.stderr).toContain('received SIGINT')
    expect(agent.status).toBe('idle')
  })

@@ -446,6 +535,21 @@ describe('runOneShot and executeCli', () => {
    } as unknown as AbortSignal
    await expect(runOneShot(early.ctx, { task: 'task', signal: fakeSignal })).rejects.toThrow('interrupted')

+    const raced = await harness([textResponse('unused')])
+    let registrations = 0
+    const racedSignal = {
+      aborted: false,
+      reason: 'cancel before followup',
+      addEventListener: (_type: string, listener: () => void) => {
+        registrations += 1
+        if (registrations === 2) listener()
+      },
+      removeEventListener: () => {},
+    } as unknown as AbortSignal
+    await expect(runOneShot(raced.ctx, { task: 'task', signal: racedSignal }))
+      .rejects.toThrow('cancel before followup')
+    expect(raced.agent.session.events.some(event => event.type === 'turn/start')).toBe(false)
+
    const preBootAbort = new AbortController()
    preBootAbort.abort('before boot completed')
    const preBoot = await invoke(early.ctx, ['task'], { signal: preBootAbort.signal })
@@ -498,27 +602,13 @@ describe('runOneShot and executeCli', () => {

    const queued = await harness([textResponse('unused')])
    const queuedAbort = new AbortController()
-    queued.ctx.on('agent/inbox/enqueue', (agent) => {
-      if (agent === queued.agent) queuedAbort.abort('cancel queued')
+    queued.ctx.on('session/event', (session, event) => {
+      if (session === queued.agent.session && event.type === 'agent/inbox/spliced'
+        && event.data.inserted.some(message => message.source.kind === 'user')) {
+        queueMicrotask(() => { queuedAbort.abort('cancel queued') })
+      }
    })
    await expect(runOneShot(queued.ctx, { task: 'task', signal: queuedAbort.signal })).rejects.toThrow('cancel queued')
    await queued.agent.whenIdle()
  })
 })
-
-describe('formatTurnFailure', () => {
-  it('diagnoses every durable reason and preserves merge-extensible unknowns', () => {
-    const cases: [TurnEndReason, string][] = [
-      [{ kind: 'completed' }, 'completed'],
-      [{ kind: 'aborted' }, 'was aborted'],
-      [{ kind: 'aborted' }, 'was aborted'],
-      [{ kind: 'error', step: 2, message: 'bad' }, 'failed at step 2: bad'],
-      [{ kind: 'error', step: 3, failure: { message: 'provider bad', code: 'SERVER' } }, 'failed at step 3: provider bad'],
-      [{ kind: 'disposed' }, 'was disposed'],
-      [{ kind: 'max-tokens' }, 'output-token limit'],
-      [{ kind: 'interrupted' }, 'persistence recovery'],
-    ]
-    for (const [reason, expected] of cases) expect(formatTurnFailure(reason)).toContain(expected)
-    expect(formatTurnFailure({ kind: 'extension' } as unknown as TurnEndReason)).toContain('extension')
-  })
-})
--- 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: 75e9e3943982c08e53afdbb73d1e9085b2e332bc
-README.zh.md: 95a626285c2f531ff6c8cceed297b42626aed98c
+README.md: 2cc496da3e22baf9e87afe4c3ca183ae3f16a5ae
+README.zh.md: 98d397b3c346ee47e9a667b2ccec0179f009a05b
--- 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`](../../ui/jsonrpc/README.md) entry serves SDK clients over newline-delimited stdio. The config composes the spine, backends, and serving plugin. `lib/bin.js` is also the [single-executable runtime](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md) entry.
+Bin-only app that boots an external `cordis.yml`; its [`jsonrpc`](../../ui/jsonrpc/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.

 ## 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`](../../ui/jsonrpc/README.md) 入口通过按换行分隔的 stdio 为 SDK 客户端提供服务。配置负责组合主干、后端和服务插件。`lib/bin.js` 也是[单文件可执行运行时](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md) 的入口。
+只包含 bin 的应用，启动外部 `cordis.yml`；其 [`jsonrpc`](../../ui/jsonrpc/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)交付。

 ## 配置发现

@@ -12,7 +12,7 @@

 ## 退出生命周期

-stdin EOF 和 `SIGTERM` 会 dispose（释放资源）根上下文，等待完全停稳后以 0 退出；`SIGINT` 完成同样的 dispose 后以 130 退出。EOF 可能按[分发 Agent Note（agent 决策记录）](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md) 所述截断正在处理的轮次。`jsonrpc` 插件拥有先响应再退出的协议关闭流程；两条路径均幂等，即使发生竞态也安全。
+stdin EOF 和 `SIGTERM` 会 dispose（释放资源）根上下文，等待完全停稳后以 0 退出；`SIGINT` 完成同样的 dispose 后以 130 退出。EOF 可能按[分发 Agent Note](../../../.agents/notes/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md) 所述截断正在处理的轮次。`jsonrpc` 插件拥有先响应再退出的协议关闭流程；两条路径均幂等，即使发生竞态也安全。

 ## stdout 是协议

--- a/packages/examples/jsonrpc-demo/package.json
+++ b/packages/examples/jsonrpc-demo/package.json
@@ -29,9 +29,7 @@
    "lib/index.js",
    "lib/invariant.js",
    "lib/bin.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
+    "lib/types/**/*.d.ts"
  ],
  "license": "BSD-3-Clause",
  "dependencies": {
--- a/packages/examples/tui-demo/README.i18n.yaml
+++ b/packages/examples/tui-demo/README.i18n.yaml
@@ -1,6 +0,0 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
-#   pnpm run verify-translation-pairing --write packages/examples/tui-demo/README.md
-README.md: 058ebe87af5f041bd19fbfb205a97753ccacf6b9
-README.zh.md: 43681e9c77cbd77459ec0539b69e0ab73274d2c1
--- a/packages/examples/tui-demo/README.md
+++ b/packages/examples/tui-demo/README.md
@@ -1,112 +0,0 @@
-# @deepseek-ai/dsh-tui-demo
-
-English | [中文](README.zh.md)
-
-The full-screen terminal app bundle: a Cordis plugin that composes [`@deepseek-ai/dsh-agent-spine-demo`](../agent-spine-demo/README.md), persisted same-session goals, the human-command registry and `/goal` producer, JSONL persistence, keyboard-backed user interaction, a pre-created `main` agent, and [`@deepseek-ai/dsh-tui`](../../ui/tui/README.md). A `cordis.yml` mounts it as one entry; the [`dsh`](../../../apps/cli/README.md) CLI is the front door that boots such a config.
-
-Use [`@deepseek-ai/dsh-cli-demo`](../cli-demo/README.md) for pipes, scripts, and other non-interactive runs. This bundle requires a TTY pair and has no line-oriented fallback.
-
-## What it bakes in
-
-| Plugin | Why it is here |
-|---|---|
-| `@deepseek-ai/dsh-agent-spine-demo` | Shared services, model-facing tools, and one configured `main` agent |
-| `@deepseek-ai/dsh-commands` | Human-only discovery and dispatch consumed by the TUI and command plugins |
-| `@deepseek-ai/dsh-command-goal` | Direct `/goal` status and mutation over the spine's persisted-goal stack |
-| `@deepseek-ai/dsh-session-persistence-jsonl` | Durable session log under `persistenceRoot` |
-| `@deepseek-ai/dsh-session-checkpoint-policy` | Semantic durability barriers before model requests and top-level tool effects, plus completed-step checkpoints |
-| `@deepseek-ai/dsh-session-query-sqlite` + `@deepseek-ai/dsh-session-reference` | Combined exact/FTS session queries and bounded `@session` snapshots consumed by the TUI; model-facing query tools remain a leaf opt-in |
-| `@deepseek-ai/dsh-user-interaction` | Provider-neutral human question service |
-| `@deepseek-ai/dsh-tui` | Full-screen transcript, editor, tool cards, plan, and question overlays |
-| `@deepseek-ai/dsh-tool-ask-user` | Model-facing `ask_user_question` tool |
-
-Swappable LLM, bash, filesystem, and other capability providers remain in the leaf config. `@cordisjs/plugin-hmr` also remains a leaf-only development entry because it requires Loader internals.
-
-## Config
-
-| Key | Default | Routed to |
-|---|---|---|
-| `provider` | required | Configured `main` agent provider |
-| `model` | required | Configured `main` agent model |
-| `maxParallelToolCalls` | agent-loop default | Bundled loop concurrency cap |
-| `persona` | — | System-prompt persona template |
-| `toolOrder` | lexicographic | Explicit model-facing tool order |
-| `tools` | owner default | Tool presentation mode |
-| `dshHome` | owner default | Harness home used by bash and skills |
-| `sessionTitle` | spine example limits | Fallback title word/byte limits |
-| `skills` | owner defaults | Skill registry, local provider, and tool config |
-| `toolBash` | owner defaults | Model-facing bash tool config |
-| `toolTasks` | owner defaults | Background-task control-tool config, or `false` |
-| `goals` | owner defaults | Persisted goal-domain and model-tool config; `false` removes the goal stack and `/goal` producer |
-| `workspaceContext` | required | Workspace-instruction config, or `false` |
-| `persistenceRoot` | `./.sessions` | JSONL persistence root and parent of the derived `session-query.db` index |
-| `persistenceCompression` | `'zstd'` | JSONL artifact encoding (`'zstd'` or raw `'none'`) |
-| `sessionReferences` | service defaults | Cross-session candidate and snapshot limits routed to `dsh-session-reference` |
-| `welcome` | `ready.` | TUI subtitle |
-| `resumeCommand` | — | Exit and no-host fallback command template; the selector itself uses session query and host handoff |
-| `ui` | owner defaults | TUI presentation settings such as reasoning, color, and card height |
-| `resumeSessionId` | — | Exact persisted session to resume |
-
-Fresh runs mint a `main-session-<uuid>` session id and pass it to both the TUI and configured agent. Resumed runs bind both components to `resumeSessionId`. The TUI mounts before the spine so it can render a matching config-start failure instead of leaving a blank terminal. The app composes persistence and session query for `/resume`; an embedding host may additionally provide `tuiResumeHost` for in-place process handoff.
-
-## Front door
-
-This package ships no bin. The [`dsh`](../../../apps/cli/README.md) CLI is the terminal front door: bare `dsh` boots the shipped `examples/tui-agent/cordis.yml` (which mounts this bundle), and `dsh --config <path-to-cordis.yml>` boots an alternate leaf config that mounts it. It loads the optional cwd `.env`, drives the Cordis Loader, and waits for the full plugin tree. The repository installs Loader's optional native helper, so bare package specifiers resolve under plain Node.
-
-## Example leaf
-
-```yaml
- id: llm-deepseek
-  name: '@deepseek-ai/dsh-llm-deepseek'
-  config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
- id: bash
-  name: '@deepseek-ai/dsh-bash-local'
- id: tui-agent
-  name: '@deepseek-ai/dsh-tui-demo'
-  config:
-    provider: deepseek
-    model: deepseek-v4-flash
-    workspaceContext:
-      maxBytes: 65536
-    welcome: 'Coding agent ready.'
-    ui:
-      showReasoning: true
-```
-
-## Model Experience
-
-### Interactive terminal turn
-
-#### What the model sees
-
-Each non-empty non-command editor submission becomes a user message; a submission during a running turn becomes steering. Slash-command input and output remain human-only, while accepted `/goal` mutations append domain-owned model-visible state. The shared spine contributes the configured persona, workspace instructions, skill catalog, goal controls, and visible tool schemas. TUI rendering itself is not model-visible.
-
-#### Token effect
-
-User, assistant, and tool history grows under the normal session and compaction rules. Headers, cards, plans, Markdown styling, and keybindings add no tokens.
-
-#### KV Cache effect
-
-Append-only while the composed prompt, schemas, route, and retained history prefix remain stable. Composition changes and compaction can invalidate reuse from the first changed token.
-
-### Human-question answer
-
-#### What the model sees
-
-`ask_user_question` retains the tool call and the compact answer or stable interruption error defined by `dsh-tool-ask-user`. The question overlay is terminal-only.
-
-#### Token effect
-
-Only the completed or failed tool result adds retained tokens.
-
-#### KV Cache effect
-
-Append-only; the answer follows the reusable request prefix.
-
-## Known Limitations and Deferred Work
-
- **TTY-only** — stdin and stdout must both be terminals; automation uses `dsh-cli-demo`.
- **One configured terminal session** — the transcript and editor bind to one exact session id.
- **The app cluster is fixed** — JSONL persistence and ask-user tooling are baked in; different policy requires another composition.
- **Approval is separate** — this app answers `ctx.userInteraction`, not `ctx.approval`; permission prompts require an approval service and answerer.
--- a/packages/examples/tui-demo/README.zh.md
+++ b/packages/examples/tui-demo/README.zh.md
@@ -1,112 +0,0 @@
-# @deepseek-ai/dsh-tui-demo
-
-[English](README.md) | 中文
-
-全屏终端应用组合包：一个 Cordis 插件，组合 [`@deepseek-ai/dsh-agent-spine-demo`](../agent-spine-demo/README.md)、持久化的同会话目标、人类命令注册表与 `/goal` 生产方、JSONL 持久化、键盘支持的用户交互、预创建的 `main` agent（智能体），以及 [`@deepseek-ai/dsh-tui`](../../ui/tui/README.md)。一份 `cordis.yml` 将它作为一个 Cordis 配置项挂载；[`dsh`](../../../apps/cli/README.md) CLI（命令行界面）是启动此类配置的入口。
-
-管道、脚本和其他非交互式运行应使用 [`@deepseek-ai/dsh-cli-demo`](../cli-demo/README.md)。此组合包需要一对 TTY，不提供面向行的回退。
-
-## 内置组件
-
-| 插件 | 设置在此处的原因 |
-|---|---|
-| `@deepseek-ai/dsh-agent-spine-demo` | 共享服务、面向模型的工具，以及一个已配置的 `main` agent |
-| `@deepseek-ai/dsh-commands` | 供 TUI 和命令插件消费、仅面向人类的命令发现与分发 |
-| `@deepseek-ai/dsh-command-goal` | 直接在主干的持久化目标栈上提供 `/goal` 状态与变更 |
-| `@deepseek-ai/dsh-session-persistence-jsonl` | 位于 `persistenceRoot` 下的持久会话日志 |
-| `@deepseek-ai/dsh-session-checkpoint-policy` | 模型请求和顶层工具 effect 前的语义持久性屏障，以及已完成步骤的检查点 |
-| `@deepseek-ai/dsh-session-query-sqlite` + `@deepseek-ai/dsh-session-reference` | TUI 消费的组合式精确／FTS 会话查询与有界 `@session` 快照；面向模型的查询工具仍由叶节点选用 |
-| `@deepseek-ai/dsh-user-interaction` | 与提供方无关的人类问题服务 |
-| `@deepseek-ai/dsh-tui` | 全屏 transcript（文本记录）、编辑器、工具卡片、计划与问题 overlay |
-| `@deepseek-ai/dsh-tool-ask-user` | 面向模型的 `ask_user_question` 工具 |
-
-可替换的 LLM（大语言模型）、bash、文件系统和其他能力提供方仍留在叶节点配置中。`@cordisjs/plugin-hmr` 也仍是仅叶节点使用的开发条目，因为它需要 Loader 内部实现。
-
-## 配置
-
-| 键 | 默认值 | 路由目标 |
-|---|---|---|
-| `provider` | 必填 | 已配置 `main` agent 的提供方 |
-| `model` | 必填 | 已配置 `main` agent 的模型 |
-| `maxParallelToolCalls` | agent-loop 默认值 | 组合包内循环的并发上限 |
-| `persona` | 无 | 系统提示词 persona 模板 |
-| `toolOrder` | 字典序 | 显式的面向模型工具顺序 |
-| `tools` | 拥有者默认值 | 工具呈现模式 |
-| `dshHome` | 拥有者默认值 | bash 与 skill（技能）使用的 harness 主目录 |
-| `sessionTitle` | 主干示例限制 | 后备标题词数／字节限制 |
-| `skills` | 拥有者默认值 | skill 注册表、本地提供方和工具配置 |
-| `toolBash` | 拥有者默认值 | 面向模型的 bash 工具配置 |
-| `toolTasks` | 拥有者默认值 | 后台任务控制工具配置，或 `false` |
-| `goals` | 拥有者默认值 | 持久目标领域与模型工具配置；`false` 会移除目标栈与 `/goal` 生产方 |
-| `workspaceContext` | 必填 | Workspace 指令配置，或 `false` |
-| `persistenceRoot` | `./.sessions` | JSONL 持久化根目录，以及派生 `session-query.db` 索引的父目录 |
-| `persistenceCompression` | `'zstd'` | JSONL 产物编码（`'zstd'` 或原始 `'none'`） |
-| `sessionReferences` | 服务默认值 | 路由到 `dsh-session-reference` 的跨会话候选项与快照限制 |
-| `welcome` | `ready.` | TUI 副标题 |
-| `resumeCommand` | 无 | 退出和无宿主回退的命令模板；选择器本身使用会话查询与宿主移交 |
-| `ui` | 拥有者默认值 | 推理（reasoning）、颜色、卡片高度等 TUI 呈现设置 |
-| `resumeSessionId` | 无 | 要恢复的确切持久化会话 |
-
-新运行会创建 `main-session-<uuid>` 会话 id，并将它同时传给 TUI 与已配置的 agent。恢复运行会将两个组件都绑定到 `resumeSessionId`。TUI 先于主干挂载，因此它可以渲染匹配的配置启动失败，而不会留下空白终端。应用为 `/resume` 组合持久化和会话查询；嵌入宿主还可以提供 `tuiResumeHost`，用于原地移交进程。
-
-## 入口
-
-此包（package）不交付 bin。[`dsh`](../../../apps/cli/README.md) CLI 是终端入口：裸 `dsh` 启动已交付的 `examples/tui-agent/cordis.yml`（它挂载此组合包），而 `dsh --config <path-to-cordis.yml>` 启动另一个挂载此组合包的叶节点配置。它加载 cwd 下可选的 `.env`，驱动 Cordis Loader，并等待完整插件树。仓库安装了 Loader 的可选原生辅助程序，因此裸包说明符可以在纯 Node 下解析。
-
-## 叶节点示例
-
-```yaml
- id: llm-deepseek
-  name: '@deepseek-ai/dsh-llm-deepseek'
-  config:
-    apiKey: !!js process.env.DEEPSEEK_API_KEY
- id: bash
-  name: '@deepseek-ai/dsh-bash-local'
- id: tui-agent
-  name: '@deepseek-ai/dsh-tui-demo'
-  config:
-    provider: deepseek
-    model: deepseek-v4-flash
-    workspaceContext:
-      maxBytes: 65536
-    welcome: 'Coding agent ready.'
-    ui:
-      showReasoning: true
-```
-
-## 模型体验
-
-### 交互式终端轮次
-
-#### 模型看到的内容
-
-每次非空、非命令的编辑器提交都会成为用户消息；运行中轮次内的提交成为 steering（中途引导）。斜杠命令输入和输出仍只面向人类，而已接受的 `/goal` 变更会追加领域拥有的模型可见状态。共享主干提供已配置的 persona、workspace 指令、skill 目录、目标控制和可见工具 schema。TUI 渲染本身对模型不可见。
-
-#### Token 影响
-
-用户、assistant 与工具历史按常规会话和压缩（compaction）规则增长。Header、卡片、计划、Markdown 样式和快捷键不增加 token。
-
-#### KV Cache 影响
-
-只要组合后的提示词、schema、路由和保留历史前缀保持稳定，就保持仅追加。组合方式变更与 compaction 可能从第一个变化的 token 起使复用失效。
-
-### 人类问题答案
-
-#### 模型看到的内容
-
-`ask_user_question` 会保留工具调用，以及 `dsh-tool-ask-user` 定义的精简答案或稳定中断错误。问题 overlay 只在终端显示。
-
-#### Token 影响
-
-只有已完成或失败的工具结果会增加保留 token。
-
-#### KV Cache 影响
-
-仅追加；答案跟在可复用请求前缀之后。
-
-## 已知限制与暂缓事项
-
- **只支持 TTY**：stdin 与 stdout 都必须是终端；自动化使用 `dsh-cli-demo`。
- **一个已配置的终端会话**：transcript 与编辑器绑定到一个确切会话 id。
- **应用集群固定不变**：JSONL 持久化与 ask-user 工具内置；不同策略需要另一种组合。
- **批准机制独立存在**：此应用回答 `ctx.userInteraction`，而不是 `ctx.approval`；权限提示需要批准服务和回答方。
--- a/packages/examples/tui-demo/package.json
+++ b/packages/examples/tui-demo/package.json
@@ -1,78 +0,0 @@
-{
-  "name": "@deepseek-ai/dsh-tui-demo",
-  "description": "Full-screen TUI app bundle plugin: agent spine + persisted goals + human commands + JSONL persistence + pi-tui front door + pre-created main agent (mounted by the dsh CLI's config)",
-  "version": "0.0.1",
-  "private": true,
-  "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/types/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./lib/types/index.d.ts",
-      "default": "./lib/index.js"
-    },
-    "./invariant": {
-      "types": "./lib/types/invariant.d.ts",
-      "default": "./lib/invariant.js"
-    },
-    "./src/*": "./src/*",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "lib/index.js",
-    "lib/invariant.js",
-    "lib/types/**/*.d.ts",
-    "lib/types/**/*.d.ts.map",
-    "src"
-  ],
-  "license": "BSD-3-Clause",
-  "peerDependencies": {
-    "@cordisjs/plugin-loader": "^1.0.0-rc.5",
-    "@deepseek-ai/dsh-agent": "^0.0.1",
-    "@deepseek-ai/dsh-agent-loop": "^0.0.1",
-    "@deepseek-ai/dsh-commands": "^0.0.1",
-    "@deepseek-ai/dsh-command-goal": "^0.0.1",
-    "@deepseek-ai/dsh-command-feedback": "^0.0.1",
-    "@deepseek-ai/dsh-agent-spine-demo": "^0.0.1",
-    "@deepseek-ai/dsh-invariants": "^0.0.1",
-    "@deepseek-ai/dsh-llm": "^0.0.1",
-    "@deepseek-ai/dsh-session": "^0.0.1",
-    "@deepseek-ai/dsh-session-checkpoint-policy": "^0.0.1",
-    "@deepseek-ai/dsh-session-query": "^0.0.1",
-    "@deepseek-ai/dsh-session-query-sqlite": "^0.0.1",
-    "@deepseek-ai/dsh-session-reference": "^0.0.1",
-    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
-    "@deepseek-ai/dsh-tui": "^0.0.1",
-    "@deepseek-ai/dsh-tool-ask-user": "^0.0.1",
-    "@deepseek-ai/dsh-tools": "^0.0.1",
-    "@deepseek-ai/dsh-user-interaction": "^0.0.1",
-    "@deepseek-ai/dsh-workspace-context": "^0.0.1",
-    "cordis": "^4.0.0-rc.7",
-    "schemastery": "^3.17.0"
-  },
-  "devDependencies": {
-    "@cordisjs/plugin-loader": "workspace:^",
-    "@deepseek-ai/dsh-agent": "workspace:^",
-    "@deepseek-ai/dsh-agent-loop": "workspace:^",
-    "@deepseek-ai/dsh-commands": "workspace:^",
-    "@deepseek-ai/dsh-command-goal": "workspace:^",
-    "@deepseek-ai/dsh-command-feedback": "workspace:^",
-    "@deepseek-ai/dsh-agent-spine-demo": "workspace:^",
-    "@deepseek-ai/dsh-invariants": "workspace:^",
-    "@deepseek-ai/dsh-llm": "workspace:^",
-    "@deepseek-ai/dsh-session": "workspace:^",
-    "@deepseek-ai/dsh-session-checkpoint-policy": "workspace:^",
-    "@deepseek-ai/dsh-session-query": "workspace:^",
-    "@deepseek-ai/dsh-session-query-sqlite": "workspace:^",
-    "@deepseek-ai/dsh-session-reference": "workspace:^",
-    "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
-    "@deepseek-ai/dsh-system-prompt": "workspace:^",
-    "@deepseek-ai/dsh-tui": "workspace:^",
-    "@deepseek-ai/dsh-tool-ask-user": "workspace:^",
-    "@deepseek-ai/dsh-tools": "workspace:^",
-    "@deepseek-ai/dsh-user-interaction": "workspace:^",
-    "@deepseek-ai/dsh-workspace-context": "workspace:^",
-    "cordis": "^4.0.0-rc.7",
-    "schemastery": "^3.17.0"
-  }
-}
--- a/packages/examples/tui-demo/src/index.ts
+++ b/packages/examples/tui-demo/src/index.ts
@@ -1,164 +0,0 @@
-/**
- * Full-screen terminal app: the default agent spine ({@link @deepseek-ai/dsh-agent-spine-demo})
- * plus persisted goals, human commands including `/feedback`, JSONL persistence, keyboard-backed
- * user interaction, and one pre-created agent whose exact session identity the
- * TUI drives. Swappable adapters, executors, optional tools, and HMR stay in the leaf. This Loader plugin
- * intentionally exposes named exports only; a default export would hide its
- * `Config` schema (see docs/postmortem/0001).
- * @module @deepseek-ai/dsh-tui-demo
- */
-
-import type { Context } from 'cordis'
-import { randomUUID } from 'node:crypto'
-import { join } from 'node:path'
-import z from 'schemastery'
-import { SessionId } from '@deepseek-ai/dsh-session'
-import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools'
-import CommandService from '@deepseek-ai/dsh-commands'
-import * as commandGoal from '@deepseek-ai/dsh-command-goal'
-import * as commandFeedback from '@deepseek-ai/dsh-command-feedback'
-import * as agentCore from '@deepseek-ai/dsh-agent-spine-demo'
-import * as workspaceContext from '@deepseek-ai/dsh-workspace-context'
-import SessionPersistenceJsonl, {
-  JsonlCompressionSchema,
-  type JsonlCompression,
-} from '@deepseek-ai/dsh-session-persistence-jsonl'
-import * as sessionCheckpointPolicy from '@deepseek-ai/dsh-session-checkpoint-policy'
-import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
-import SessionQuerySqlite from '@deepseek-ai/dsh-session-query-sqlite'
-import SessionReferenceService, { type Config as SessionReferenceConfig } from '@deepseek-ai/dsh-session-reference'
-import * as toolAskUser from '@deepseek-ai/dsh-tool-ask-user'
-import * as uiTui from '@deepseek-ai/dsh-tui'
-
-export const name = 'tui-demo'
-const DEFAULT_PERSISTENCE_ROOT = './.sessions'
-
-// Each front door keeps a complete Loader contract so its deployment config is
-// readable without a cross-package facade.
-/* jscpd:ignore-start */
-/** App config routed to the spine, TUI, configured agent, and JSONL backend. */
-export interface Config {
-  /** Provider route for the `main` agent. */
-  provider: string
-  /** Model name for the `main` agent; a matching adapter must be registered. */
-  model: string
-  /** Bundled agent-loop concurrency cap; `1` is serial and omission uses its default. */
-  maxParallelToolCalls?: number
-  /** Deployment persona forwarded to the system-prompt plugin. */
-  persona?: string
-  /** Explicit model-facing tool order forwarded to the system-prompt plugin. */
-  toolOrder?: string[]
-  /** Tool-registry presentation config forwarded through agent-spine-demo. */
-  tools?: ToolsConfig
-  /** DeepSeek Harness home directory exposed to bash and used for local skill discovery. */
-  dshHome?: string
-  /** Fallback session-title limits forwarded through agent-spine-demo. */
-  sessionTitle?: NonNullable<agentCore.Config['sessionTitle']>
-  /** Directory for JSONL sessions and the derived query index. Defaults to `./.sessions`. */
-  persistenceRoot?: string
-  /** JSONL artifact encoding; defaults to checksummed Zstandard frames. */
-  persistenceCompression?: JsonlCompression
-  /** Cross-session reference discovery and snapshot byte budgets. */
-  sessionReferences?: SessionReferenceConfig
-  /** TUI transcript's optional first line; absent renders nothing on start. */
-  welcome?: string
-  /**
-   * Shell command template the TUI prints on exit and lists under `/resume`,
-   * with `{session}` replaced by the live session id (forwarded to the front
-   * door). Set it to a command that resumes the session, e.g.
-   * `dsh --resume {session}`.
-   */
-  resumeCommand?: string
-  /** Full-screen TUI presentation settings. */
-  ui?: uiTui.TuiConfig
-  /** Skill registry, local-provider, and model-facing consumer config. */
-  skills?: agentCore.SkillConfig
-  /** Model-facing bash tool config forwarded through agent-spine-demo. */
-  toolBash?: NonNullable<agentCore.Config['toolBash']>
-  /** Generic background-task controls forwarded through agent-spine-demo; set false to omit them. */
-  toolTasks?: NonNullable<agentCore.Config['toolTasks']>
-  /** Persisted same-session goals; owner defaults enable them, or false disables the stack and command. */
-  goals?: agentCore.GoalConfig | false
-  /** Persisted session id to resume instead of creating a fresh session. */
-  resumeSessionId?: string
-  /** Controls automatic AGENTS.md/CLAUDE.md loading; configure a byte budget or set `false`. */
-  workspaceContext: agentCore.Config['workspaceContext']
-}
-
-export const Config: z<Config> = z.object({
-  provider: z.string().required(),
-  model: z.string().required(),
-  maxParallelToolCalls: z.number().step(1).min(1),
-  persona: z.string(),
-  // Absent means lexicographic order; schemastery's native array default is [].
-  toolOrder: z.array(z.string()).default(undefined as unknown as string[]),
-  tools: ToolRegistry.Config,
-  dshHome: z.string(),
-  sessionTitle: agentCore.SessionTitleConfigSchema,
-  persistenceRoot: z.string().default(DEFAULT_PERSISTENCE_ROOT),
-  persistenceCompression: JsonlCompressionSchema,
-  sessionReferences: SessionReferenceService.Config,
-  welcome: z.string(),
-  resumeCommand: z.string(),
-  ui: uiTui.TuiConfigSchema,
-  skills: agentCore.SkillConfigSchema,
-  toolBash: agentCore.ToolBashConfigSchema,
-  toolTasks: z.union([z.const(false), agentCore.ToolTasksConfigSchema]),
-  goals: z.union([z.const(false), agentCore.GoalConfigSchema]),
-  resumeSessionId: z.string(),
-  workspaceContext: z.union([z.const(false), workspaceContext.Config]).required(),
-})
-/* jscpd:ignore-end */
-
-/**
- * Compose the spine, TUI, JSONL persistence, and user-question tool around one
- * exact fresh or resumed session identity. The TUI subscribes to startup
- * failures before the spine creates the agent.
- * @param ctx - context receiving the app's child plugins.
- * @param config - validated app configuration.
- */
-export function composeTuiApp(ctx: Context, config: Config): void {
-  const resumeSessionId = config.resumeSessionId === '' ? undefined : config.resumeSessionId
-  const sessionId = SessionId(resumeSessionId ?? `main-session-${randomUUID()}`)
-  const goals = config.goals ?? {}
-  const persistenceRoot = config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT
-  ctx.plugin(CommandService)
-  ctx.plugin(commandFeedback)
-  if (goals !== false) ctx.plugin(commandGoal)
-  ctx.plugin(SessionPersistenceJsonl, {
-    root: persistenceRoot,
-    ...(config.persistenceCompression === undefined ? {} : { compression: config.persistenceCompression }),
-  })
-  ctx.plugin(sessionCheckpointPolicy)
-  ctx.plugin(SessionQuerySqlite, { path: join(persistenceRoot, 'session-query.db') })
-  ctx.plugin(SessionReferenceService, config.sessionReferences ?? {})
-  ctx.plugin(UserInteractionService)
-  ctx.plugin(uiTui.TuiPromptService)
-  ctx.plugin(uiTui, {
-    ...config.ui,
-    ...config.welcome === undefined ? {} : { welcome: config.welcome },
-    ...config.resumeCommand === undefined ? {} : { resumeCommand: config.resumeCommand },
-    sessionId,
-  })
-  ctx.plugin(agentCore, {
-    ...agentCore.pickSpineConfig(config),
-    goals,
-    agents: [{
-      id: SessionId('main'),
-      provider: config.provider,
-      model: config.model,
-      cwd: process.cwd(),
-      ...resumeSessionId === undefined ? { sessionId } : { resumeSessionId: sessionId },
-    }],
-  })
-  ctx.plugin(toolAskUser)
-}
-
-/**
- * Compose the configured full-screen terminal app.
- * @param ctx - context receiving the app's child plugins.
- * @param config - validated app configuration.
- */
-export function apply(ctx: Context, config: Config): void {
-  composeTuiApp(ctx, config)
-}
--- a/packages/examples/tui-demo/src/invariant.ts
+++ b/packages/examples/tui-demo/src/invariant.ts
@@ -1,30 +0,0 @@
-/**
- * Package-owned invariant companion for `@deepseek-ai/dsh-tui-demo`.
- * @module @deepseek-ai/dsh-tui-demo/invariant
- */
-
-/* jscpd:ignore-start */
-import type { Context } from 'cordis'
-import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
-
-const PACKAGE_NAME = '@deepseek-ai/dsh-tui-demo'
-
-/** Cordis companion plugin name. */
-export const name = 'tui-demo-invariant'
-/** Service required before the companion can reserve package ownership. */
-export const inject = ['invariants']
-
-/**
- * No runtime invariant: this composition-only package delegates mutable state and event streams
- * to the agent spine, persistence, and TUI packages that own their checks.
- */
-const install: InvariantInstaller = () => {}
-
-/**
- * Register this package's invariant companion.
- * @param ctx - Cordis context carrying the invariant service.
- * @returns the installed registration's disposer after setup succeeds.
- */
-export const apply = (ctx: Context): Promise<() => void> =>
-  Promise.resolve(ctx.invariants.register(PACKAGE_NAME, install))
-/* jscpd:ignore-end */
--- a/packages/examples/tui-demo/tests/tui-agent.spec.ts
+++ b/packages/examples/tui-demo/tests/tui-agent.spec.ts
@@ -1,155 +0,0 @@
-import { describe, expect, it } from 'vitest'
-import { join } from 'node:path'
-import { Context } from 'cordis'
-import Loader from '@cordisjs/plugin-loader'
-import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
-import * as tuiAgent from '../src/index.ts'
-
-interface PluginCall {
-  readonly name: string
-  readonly config: unknown
-}
-
-function recordingContext(): { readonly ctx: Context; readonly calls: PluginCall[] } {
-  const calls: PluginCall[] = []
-  const ctx = {
-    plugin(plugin: { name?: string }, config?: unknown) {
-      calls.push({ name: plugin.name ?? '', config })
-    },
-  } as unknown as Context
-  return { ctx, calls }
-}
-
-describe('dsh-tui-demo app', () => {
-  it('composes the TUI cluster around one fresh exact session identity', () => {
-    const { ctx, calls } = recordingContext()
-    tuiAgent.composeTuiApp(ctx, {
-      provider: 'mock',
-      model: 'mock-model',
-      maxParallelToolCalls: 3,
-      persona: 'test persona',
-      toolOrder: ['zulu', TOOL_ORDER_REST],
-      tools: { mode: 'code' },
-      dshHome: '/tmp/dsh-home',
-      persistenceRoot: '/tmp/tui-sessions',
-      persistenceCompression: 'none',
-      sessionReferences: {
-        maxReferences: 2,
-        candidateLimit: 7,
-        maxReferenceBytes: 1234,
-      },
-      welcome: 'TUI ready',
-      resumeCommand: 'dsh --resume {session}',
-      ui: { theme: { color: false }, maxToolOutputLines: 3 },
-      skills: { tool: { catalogDescriptionMaxLength: 8 } },
-      toolBash: { enableRunInBackground: false },
-      toolTasks: { waitTimeoutMs: 7, maxWaitTimeoutMs: 11 },
-      workspaceContext: false,
-    })
-
-    expect(calls.map(call => call.name)).toEqual([
-      'CommandService',
-      'command-feedback',
-      'command-goal',
-      'SessionPersistenceJsonl',
-      'session-checkpoint-policy',
-      'SessionQuerySqlite',
-      'SessionReferenceService',
-      'UserInteractionService',
-      'TuiPromptService',
-      'ui-tui',
-      'agent-spine-demo',
-      'tool-ask-user',
-    ])
-    expect(calls[0]?.config).toBeUndefined()
-    expect(calls[3]?.config).toEqual({ root: '/tmp/tui-sessions', compression: 'none' })
-    expect(calls[5]?.config).toEqual({ path: join('/tmp/tui-sessions', 'session-query.db') })
-    expect(calls[6]?.config).toEqual({
-      maxReferences: 2,
-      candidateLimit: 7,
-      maxReferenceBytes: 1234,
-    })
-    const tuiConfig = calls[9]?.config as { sessionId: string }
-    expect(tuiConfig).toMatchObject({
-      welcome: 'TUI ready',
-      resumeCommand: 'dsh --resume {session}',
-      theme: { color: false },
-      maxToolOutputLines: 3,
-    })
-    expect(tuiConfig.sessionId).toMatch(/^main-session-[0-9a-f-]{36}$/)
-    const spineConfig = calls[10]?.config as {
-      readonly agents: Array<Record<string, unknown>>
-      readonly goals: Record<string, never>
-      readonly maxParallelToolCalls: number
-      readonly persona: string
-      readonly toolOrder: string[]
-      readonly tools: { mode: string }
-    }
-    expect(spineConfig).toMatchObject({
-      maxParallelToolCalls: 3,
-      persona: 'test persona',
-      toolOrder: ['zulu', TOOL_ORDER_REST],
-      tools: { mode: 'code' },
-      goals: {},
-    })
-    expect(spineConfig.agents[0]).toMatchObject({
-      id: 'main',
-      provider: 'mock',
-      model: 'mock-model',
-      cwd: process.cwd(),
-      sessionId: tuiConfig.sessionId,
-    })
-  })
-
-  it('resumes the configured session and applies runtime defaults', () => {
-    const { ctx, calls } = recordingContext()
-    tuiAgent.composeTuiApp(ctx, {
-      provider: 'mock',
-      model: 'mock-model',
-      resumeSessionId: 'persisted-session',
-      workspaceContext: false,
-    })
-
-    expect(calls[3]?.config).toEqual({ root: './.sessions' })
-    expect(calls[6]?.config).toEqual({})
-    // No configured welcome forwards none: the TUI banner sweeps in without a subtitle.
-    expect(calls[9]?.config).toEqual({ sessionId: 'persisted-session' })
-    expect((calls[10]?.config as { agents: Array<Record<string, unknown>> }).agents[0]).toMatchObject({
-      id: 'main',
-      resumeSessionId: 'persisted-session',
-    })
-  })
-
-  it('normalizes an empty resume id and routes apply through the same composition', () => {
-    const { ctx, calls } = recordingContext()
-    tuiAgent.apply(ctx, {
-      provider: 'mock',
-      model: 'mock-model',
-      resumeSessionId: '',
-      goals: false,
-      workspaceContext: false,
-    })
-
-    const tuiConfig = calls[8]?.config as { sessionId: string }
-    expect(tuiConfig.sessionId).toMatch(/^main-session-[0-9a-f-]{36}$/)
-    expect((calls[9]?.config as { agents: Array<Record<string, unknown>> }).agents[0])
-      .toMatchObject({ sessionId: tuiConfig.sessionId })
-    expect(calls.map(call => call.name)).not.toContain('command-goal')
-    // `/feedback` is unconditional: disabling goals must not remove it.
-    expect(calls.map(call => call.name)).toContain('command-feedback')
-    expect(calls[9]?.config).toMatchObject({ goals: false })
-  })
-
-  it('has the namespace-plugin export shape so the Loader keeps its schema', () => {
-    expect(tuiAgent.name).toBe('tui-demo')
-    expect(tuiAgent.Config).toBeDefined()
-    expect('default' in tuiAgent).toBe(false)
-    expect(typeof tuiAgent.apply).toBe('function')
-
-    const loader = Object.create(Loader.prototype) as Loader
-    const unwrapped = loader.unwrapExports(tuiAgent) as Record<string, unknown>
-    expect(unwrapped).toBe(tuiAgent)
-    expect(unwrapped.name).toBe('tui-demo')
-    expect(unwrapped.Config).toBeDefined()
-  })
-})
--- a/packages/examples/tui-demo/tsconfig.json
+++ b/packages/examples/tui-demo/tsconfig.json
@@ -1,66 +0,0 @@
-{
-  "extends": "../../../tsconfig.base.json",
-  "compilerOptions": {
-    "rootDir": "src",
-    "outDir": "lib/types"
-  },
-  "include": [
-    "src"
-  ],
-  "references": [
-    {
-      "path": "../../../vendor/cordis"
-    },
-    {
-      "path": "../../../vendor/schemastery"
-    },
-    {
-      "path": "../../core/agent"
-    },
-    {
-      "path": "../../core/session"
-    },
-    {
-      "path": "../../session-query/session-query"
-    },
-    {
-      "path": "../../session-query/session-query-sqlite"
-    },
-    {
-      "path": "../../context/session-reference"
-    },
-    {
-      "path": "../../ui/commands"
-    },
-    {
-      "path": "../../goal/command-goal"
-    },
-    {
-      "path": "../../feedback/command-feedback"
-    },
-    {
-      "path": "../agent-spine-demo"
-    },
-    {
-      "path": "../../context/workspace-context"
-    },
-    {
-      "path": "../../ui/user-interaction"
-    },
-    {
-      "path": "../../ui/tui"
-    },
-    {
-      "path": "../../ui/tool-ask-user"
-    },
-    {
-      "path": "../../session-persistence/session-checkpoint-policy"
-    },
-    {
-      "path": "../../session-persistence/session-persistence-jsonl"
-    },
-    {
-      "path": "../../support/invariants"
-    }
-  ]
-}
--- a/packages/examples/tui-demo/tsdown.config.ts
+++ b/packages/examples/tui-demo/tsdown.config.ts
@@ -1,19 +0,0 @@
-import { defineConfig } from 'tsdown'
-
-/**
- * tui-demo ships the plugin (`index`) and its invariant companion; the CLI
- * front door is `dsh` (apps/cli), which mounts this bundle through its config.
- * The root tsdown builds only `lib/types/index.js`, so this override adds the
- * invariant entry. Declarations come from `tsc -b` (dts: false), matching
- * every package.
- */
-export default defineConfig({
-  entry: ['lib/types/index.js', 'lib/types/invariant.js'],
-  outDir: 'lib',
-  format: ['esm'],
-  platform: 'node',
-  target: 'es2024',
-  fixedExtension: false,
-  dts: false,
-  clean: false,
-})