Merge pull request #1995 from deepseek-harness/worktree/remove-dsh-cli-demo

cleanup(cli): remove separate dsh-cli-demo app
2026-08-08 15:26:56 +08:00
parent 1107db0fbb 90f9038061
commit d301dbdc7d
143 changed files with 1211 additions and 2360 deletions
--- a/packages/bundle/headless/README.i18n.yaml
+++ b/packages/bundle/headless/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/bundle/headless/README.md
-README.md: d08fb08e2aca3c4e5ccd733b37fc415d492974ca
-README.zh.md: 99a64ef04c4fd8fb0c6a979d3f09f1bd98b434a0
+README.md: 661b377817482d22f58f22b573075722646729a2
+README.zh.md: a6b91a8e60fdcc06ba23e07dcb2f4208ea1020f7
--- a/packages/bundle/headless/README.md
+++ b/packages/bundle/headless/README.md
@@ -2,7 +2,7 @@

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

-The dsh one-shot bundle. [`cordis.patch.yml`](cordis.patch.yml) rides over [`dsh-base`](../base/README.md) + [`dsh-web-app`](../web-app/README.md): it moves the webserver to an OS-assigned port (parallel runs never collide), silences the URL line, and inserts this package's `headless-runner` plugin (config `{task}`). The runner drives one task turn through the in-process API carrier (`InProcessApiClient` over `toFetchHandler(ctx.apiProxy)`, so the full wire chain — serialization, zod, SSE framing — really runs), aggregates the turn's final assistant text, writes it to stdout, and requests exit (completed → 0, else 1) through the launcher-provided `ctx.headlessIo` seam. The Web composition stays mounted, so the running session is observable in a browser at the stderr-announced URL. The launcher patches the task text in (`dsh --profile headless "task"`), and fails loud when a task is given to a profile without this row.
+The dsh one-shot bundle. [`cordis.patch.yml`](cordis.patch.yml) rides over [`dsh-base`](../base/README.md) + [`dsh-web-app`](../web-app/README.md): it moves the webserver to an OS-assigned port (parallel runs never collide), silences the URL line, and inserts this package's `headless-runner` plugin (config `{task}`). The runner drives one task turn through the in-process API carrier (`InProcessApiClient` over `toFetchHandler(ctx.apiProxy)`, so the full wire chain — serialization, zod, SSE framing — really runs), waits at idle until that mux has consumed the session's final event sequence, aggregates the turn's final assistant text, writes it to stdout, and requests exit (completed → 0, else 1) through the launcher-provided `ctx.headlessIo` seam. The Web composition stays mounted, so the running session is observable in a browser at the stderr-announced URL. The launcher patches the task text in (`dsh run "task"`), and fails loud when the selected profile lacks this row.

 ## Model Experience

--- a/packages/bundle/headless/README.zh.md
+++ b/packages/bundle/headless/README.zh.md
@@ -2,7 +2,7 @@

 [English](README.md) | 中文

-dsh 一次性任务组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在 [`dsh-base`](../base/README.md) + [`dsh-web-app`](../web-app/README.md) 之上：把 webserver 移到 OS 分配的端口（并行运行绝不冲突），关闭 URL 行输出，并插入本包的 `headless-runner` 插件（配置为 `{task}`）。runner 通过进程内 API 载体（架在 `toFetchHandler(ctx.apiProxy)` 之上的 `InProcessApiClient`，因此序列化、zod、SSE（Server-Sent Events）帧封装这整条 wire 链路都会真实运行）驱动一个任务轮次，聚合该轮次最终的 assistant 文本，写到 stdout，再经启动器提供的 `ctx.headlessIo` seam 请求退出（完成 → 0，否则 1）。Web 组合保持挂载，因此运行中的会话可在浏览器中通过 stderr 公告的 URL 观察。启动器把任务文本 patch 进来（`dsh --profile headless "task"`）；如果向没有这一行的 profile 传入任务，则大声失败。
+dsh 一次性任务组合包。[`cordis.patch.yml`](cordis.patch.yml) 叠加在 [`dsh-base`](../base/README.md) + [`dsh-web-app`](../web-app/README.md) 之上：把 webserver 移到 OS 分配的端口（并行运行绝不冲突），关闭 URL 行输出，并插入本包的 `headless-runner` 插件（配置为 `{task}`）。runner 通过进程内 API 载体（架在 `toFetchHandler(ctx.apiProxy)` 之上的 `InProcessApiClient`，因此序列化、zod、SSE（Server-Sent Events）帧封装这整条 wire 链路都会真实运行）驱动一个任务轮次，在 idle 时等待该 mux 消费完会话的最终事件序号，再聚合该轮次最终的 assistant 文本，写到 stdout，并经启动器提供的 `ctx.headlessIo` seam 请求退出（完成 → 0，否则 1）。Web 组合保持挂载，因此运行中的会话可在浏览器中通过 stderr 公告的 URL 观察。启动器把任务文本 patch 进来（`dsh run "task"`）；若所选 profile 缺少该行，则显式报错。

 ## 模型体验

--- a/packages/bundle/headless/src/index.ts
+++ b/packages/bundle/headless/src/index.ts
@@ -6,8 +6,7 @@
 * (InProcessApiClient over toFetchHandler(ctx.apiProxy), so the full wire
 * chain — serialization, zod, SSE framing — really runs), prints the final
 * assistant text at agent quiescence, and exits (completed → 0, else 1). The
- * task text arrives as launcher-patched config
- * (`dsh --profile headless "task"`).
+ * task text arrives as launcher-patched config (`dsh run "task"`).
 * @module @deepseek-ai/dsh-headless
 */

@@ -86,26 +85,31 @@ async function unwrap<T>(response: RpcResponse<T>, io: HeadlessIo): Promise<T> {
 * `agent/status` subscription; the stream itself carries no status frame.
 * @param frames - the mux stream opened before the prompt.
 * @param sessionId - the headless session.
- * @param idle - resolves when the agent reaches quiescence.
+ * @param idle - resolves to the final session-event sequence when the agent reaches quiescence.
 * @param io - process-facing effects for stream diagnostics.
 * @returns the aggregated outcome.
 */
 async function consumeUntilIdle(
  frames: AsyncIterable<RpcRequest<MuxFrame>>,
  sessionId: SessionId,
-  idle: Promise<void>,
+  idle: Promise<number>,
  io: HeadlessIo,
 ): Promise<TurnOutcome> {
  let started = false
  let text = ''
  let reason: string = 'error'
-  void (async () => {
+  let observedSeq = -1
+  let resolveProgress: (() => void) | undefined
+  const streamDone = (async () => {
    try {
      for await (const frame of frames) {
        const payload = frame.payload
        if (payload.type === 'stream/error') return
        if (payload.type !== 'session/event' || payload.sessionId !== sessionId) continue
        const event = payload.event
+        observedSeq = event.seq
+        resolveProgress?.()
+        resolveProgress = undefined
        if (event.type === 'turn/start') {
          started = true
          continue
@@ -121,7 +125,12 @@ async function consumeUntilIdle(
      io.stderr.write(`dsh: event stream failed: ${String(error)}\n`)
    }
  })()
-  await idle
+  const streamEnded = streamDone.then(() => 'ended' as const)
+  const idleSeq = await idle
+  while (observedSeq < idleSeq) {
+    const progress = new Promise<'progress'>((resolve) => { resolveProgress = () => { resolve('progress') } })
+    if (await Promise.race([progress, streamEnded]) === 'ended') break
+  }
  return { text, reason }
 }

@@ -154,9 +163,9 @@ export function apply(ctx: Context, config: Config): void {
    // port of this runner must replace it with a wire-visible idle signal.
    const abort = new AbortController()
    const frames = api.events.mux({}, abort.signal)
-    const idle = new Promise<void>((resolve) => {
+    const idle = new Promise<number>((resolve) => {
      ctx.on('agent/status', ({ agent, status }) => {
-        if (agent.id === created.sessionId && status === 'idle') resolve()
+        if (agent.id === created.sessionId && status === 'idle') resolve(agent.session.seq - 1)
      })
    })
    const done = consumeUntilIdle(frames, created.sessionId, idle, io)
--- a/packages/bundle/headless/tests/headless.spec.ts
+++ b/packages/bundle/headless/tests/headless.spec.ts
@@ -21,26 +21,45 @@ function stamped(event: ScriptedEvent): ScriptedEvent {

 interface RpcShapedRequest { rpcId: string }

+interface ScriptedApiOptions {
+  promptFails?: boolean
+  framesAfterPrompt?: boolean
+  onPrompt?: () => void
+}
+
 /** Build a fake apiProxy (echoing rpcIds like the real gateway) whose mux stream replays `events` for the created session. */
-function scriptedApi(events: ScriptedEvent[], options: { promptFails?: boolean } = {}): unknown {
+function scriptedApi(events: ScriptedEvent[], options: ScriptedApiOptions = {}): unknown {
+  let releaseFrames = (): void => {}
+  const framesReady = options.framesAfterPrompt === true
+    ? new Promise<void>((resolve) => { releaseFrames = resolve })
+    : Promise.resolve()
+  const prepared = events.map((event) => {
+    if (event.type === 'stream/error') return { streamError: true } as const
+    const { sessionId = 'S1', ...rest } = event
+    return { streamError: false, sessionId, event: stamped(rest) } as const
+  })
  return {
    sessions: {
      create: (request: RpcShapedRequest) =>
        Promise.resolve({ rpcId: request.rpcId, result: { ok: true, value: { sessionId: 'S1' } } }),
-      prompt: (request: RpcShapedRequest) => Promise.resolve(options.promptFails === true
-        // A code from the closed wire union: the carrier schema rejects invented codes.
-        ? { rpcId: request.rpcId, result: { ok: false, error: { code: 'agent-busy', message: 'agent is busy', details: { reason: 'test' } } } }
-        : { rpcId: request.rpcId, result: { ok: true, value: { accepted: true } } }),
+      prompt: (request: RpcShapedRequest) => {
+        releaseFrames()
+        options.onPrompt?.()
+        return Promise.resolve(options.promptFails === true
+          // A code from the closed wire union: the carrier schema rejects invented codes.
+          ? { rpcId: request.rpcId, result: { ok: false, error: { code: 'agent-busy', message: 'agent is busy', details: { reason: 'test' } } } }
+          : { rpcId: request.rpcId, result: { ok: true, value: { accepted: true } } })
+      },
    },
    events: {
      mux: async function* () {
-        for (const event of events) {
-          if (event.type === 'stream/error') {
+        await framesReady
+        for (const item of prepared) {
+          if (item.streamError) {
            yield { rpcId: 'e', payload: { type: 'stream/error', error: { code: 'cancelled', message: 'stream broke', details: {} } } }
            continue
          }
-          const { sessionId = 'S1', ...rest } = event
-          yield { rpcId: 'e', payload: { type: 'session/event', sessionId, event: stamped(rest) } }
+          yield { rpcId: 'e', payload: { type: 'session/event', sessionId: item.sessionId, event: item.event } }
        }
      },
    },
@@ -51,7 +70,10 @@ function scriptedApi(events: ScriptedEvent[], options: { promptFails?: boolean }
 * Mount the runner against a scripted API, emit the idle transition after the
 * scripted frames drain, and wait for its exit request.
 */
-async function run(events: ScriptedEvent[], options: { promptFails?: boolean } = {}): Promise<{ code: number; out: string; err: string }> {
+async function run(
+  events: ScriptedEvent[],
+  options: { promptFails?: boolean; framesAfterPrompt?: boolean; idleInPrompt?: boolean } = {},
+): Promise<{ code: number; out: string; err: string }> {
  const ctx = new Context()
  let out = ''
  let err = ''
@@ -63,16 +85,25 @@ async function run(events: ScriptedEvent[], options: { promptFails?: boolean } =
    }
    ctx.provide('headlessIo', io)
  })
-  ctx.provide('apiProxy', scriptedApi(events, options) as never)
+  const emitIdle = (): void => {
+    ctx.emit('agent/status', { agent: { id: 'S1', session: { seq: nextSeq + 1 } } as Agent, status: 'idle' })
+  }
+  ctx.provide('apiProxy', scriptedApi(events, {
+    ...options.promptFails === undefined ? {} : { promptFails: options.promptFails },
+    ...options.framesAfterPrompt === undefined ? {} : { framesAfterPrompt: options.framesAfterPrompt },
+    ...options.idleInPrompt === true ? { onPrompt: emitIdle } : {},
+  }) as never)
  ctx.provide('httpServer', { port: 12345 } as never)
  apply(ctx, { task: 'do the thing' })
  // Quiescence is out of band: give the scripted stream a beat to drain, then
  // flip the agent idle exactly as the loop would. Foreign agents and
  // non-idle transitions must not settle the run.
-  await new Promise(resolve => setTimeout(resolve, 10))
-  ctx.emit('agent/status', { agent: { id: 'OTHER' } as Agent, status: 'idle' })
-  ctx.emit('agent/status', { agent: { id: 'S1' } as Agent, status: 'running' })
-  ctx.emit('agent/status', { agent: { id: 'S1' } as Agent, status: 'idle' })
+  if (options.idleInPrompt !== true) {
+    await new Promise(resolve => setTimeout(resolve, 10))
+    ctx.emit('agent/status', { agent: { id: 'OTHER' } as Agent, status: 'idle' })
+    ctx.emit('agent/status', { agent: { id: 'S1' } as Agent, status: 'running' })
+    emitIdle()
+  }
  const code = await exited
  await ctx.fiber.dispose()
  return { code, out, err }
@@ -106,6 +137,15 @@ describe('headless runner', () => {
    expect(err).toContain('observing at http://127.0.0.1:12345')
  })

+  it('consumes through the idle sequence when queued frames arrive after the status transition', async () => {
+    const { code, out } = await run(
+      [messageTurn, text(1, 'race-free answer'), end(1, 'completed')],
+      { framesAfterPrompt: true, idleInPrompt: true },
+    )
+    expect(code).toBe(0)
+    expect(out).toBe('race-free answer\n')
+  })
+
  it('exits 1 when the final turn ends for any other reason', async () => {
    const { code } = await run([messageTurn, end(1, 'aborted')])
    expect(code).toBe(1)
@@ -168,7 +208,7 @@ describe('headless runner', () => {
    ctx.provide('httpServer', { port: 1 } as never)
    apply(ctx, { task: 't' })
    await new Promise(resolve => setTimeout(resolve, 10))
-    ctx.emit('agent/status', { agent: { id: 'S1' } as Agent, status: 'idle' })
+    ctx.emit('agent/status', { agent: { id: 'S1', session: { seq: nextSeq + 1 } } as Agent, status: 'idle' })
    expect(await exited).toBe(1)
    expect(err).toContain('event stream failed')
    await ctx.fiber.dispose()
--- 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: 64fff8cb3f53386d48a9a831c1cbdd946ad483cc
-README.zh.md: c346a41d297a545991a2441df625286e1b830998
+README.md: 2d672dcc307bb280cf3803f29128eba4988a8da0
+README.zh.md: e827e7cff4ff9d6521e5889e48270e06641ef38c
--- a/packages/examples/README.md
+++ b/packages/examples/README.md
@@ -7,11 +7,10 @@ Pre-composed plugin bundles a thin leaf `cordis.yml` loads instead of assembling
 | Package | npm name | Role |
 |---|---|---|
 | [`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; `cli-demo` and `acp-demo` add their front doors, while `jsonrpc-demo` boots a deployment-owned plugin tree.
+`agent-spine-demo` is the shared bundle; `acp-demo` adds its automation front door, while `jsonrpc-demo` boots a deployment-owned plugin tree. Product one-shot execution belongs to `dsh run`; no package in this directory provides it.

 These packages are not product API. Product seams and front doors remain in their owning groups; demo bundles select concrete compositions.

--- a/packages/examples/README.zh.md
+++ b/packages/examples/README.zh.md
@@ -7,11 +7,10 @@
 | 包 | npm 名称 | 角色 |
 |---|---|---|
 | [`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` 是共享组合包；`cli-demo` 与 `acp-demo` 添加各自的前端入口，`jsonrpc-demo` 则启动由部署方拥有的插件树。
+`agent-spine-demo` 是共享组合包；`acp-demo` 添加自动化入口，`jsonrpc-demo` 则启动由部署方拥有的插件树。产品单次执行归 `dsh run` 所有；本目录没有任何包提供该功能。

 这些包不是产品 API。产品 seam 与前端入口仍位于各自的归属组；演示组合包只选择具体组合。

--- a/packages/examples/cli-demo/README.i18n.yaml
+++ b/packages/examples/cli-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/cli-demo/README.md
-README.md: 6e46ae81421c23806524b0784a976e9f3c8eeab8
-README.zh.md: b032023fee4bf9d992217cc51731f6356f875daf
--- a/packages/examples/cli-demo/README.md
+++ b/packages/examples/cli-demo/README.md
@@ -1,78 +0,0 @@
-# @deepseek-ai/dsh-cli-demo
-
-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 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.
-
-## Config
-
-| Key | Default | Routed to |
-|---|---|---|
-| `provider` | required | the configured agent's provider route |
-| `model` | required | the configured agent's model |
-| `maxParallelToolCalls` | agent-loop default | positive-integer concurrent tool-call cap; `1` is serial |
-| `persona` | — | the deployment persona in `dsh-system-prompt` |
-| `toolOrder` | lexicographic | explicit model-facing tool order in `dsh-system-prompt` |
-| `tools` | `{ mode: 'native' }` | tool-registry presentation config through `dsh-agent-spine-demo` |
-| `dshHome` | `$DSH_HOME` or `~/.dsh` | Harness home exposed to model bash and used by local skill discovery |
-| `sessionTitle` | spine example limits | Fallback title word/byte limits through `dsh-agent-spine-demo` |
-| `skills` | owner defaults | skill registry, local provider, and model-facing skill tool |
-| `toolBash` | owner defaults | model-facing bash config, including this producer's background opt-in |
-| `toolTasks` | owner defaults | generic `task_output` wait bounds |
-| `persistenceRoot` | `./.sessions` | JSONL session root |
-| `persistenceCompression` | `'zstd'` | JSONL artifact encoding (`'zstd'` or raw `'none'`) |
-| `workspaceContext` | required | workspace-instruction byte budget, or `false` to disable loading |
-
-## CLI contract
-
-```sh
-dsh-cli-demo [--config path] [--output-format text|json|stream-json] <task>
-```
-
-`--config` defaults to `./cordis.yml`; `--output-format` defaults to `text`. Exactly one nonblank positional task is required, so quote tasks containing spaces. `--help` prints usage without booting. There is no `-p` or `--print` flag.
-
-The root headless-agent example supplies its leaf:
-
-```sh
-pnpm run demo:headless "inspect the failing test and fix it"
-```
-
-Loader configs resolve bare package specifiers through the optional native helper installed by the repository, so the root command needs no special Node flags.
-
-### Output formats
-
- `text` writes the last assistant message containing text, followed by one newline.
- `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.
-
-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 owned activity is explicitly flushed before final output. Session logs remain under `persistenceRoot` after the process exits.
-
-## Operational safety
-
-The headless-agent leaf supplies local bash, filesystem, skill, subagent, workflow, and todo capabilities. A task can therefore mutate the launch workspace, run commands, spawn child agents, and consume provider tokens. Run the CLI from the intended project directory, review the leaf's capability and sandbox configuration, and do not treat non-interactive execution as an approval boundary.
-
-## Model Experience
-
-### 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 owned activity.
-
-#### Token effect
-
-The task, prompt sections, tool schemas, assistant output, and tool results consume tokens on each model step. JSON event streaming and final rendering add no model tokens; delegated child work has its own model usage and is not included in the parent result's `usage` total.
-
-#### KV Cache effect
-
-Tool-round history is append-only while the one-shot agent's prompt, schemas, model route, and session prefix remain fixed. Changing that composition establishes a different request prefix; JSON output mode has no cache effect.
-
-## Known Limitations and Deferred Work
-
- **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 activity interval.
--- a/packages/examples/cli-demo/README.zh.md
+++ b/packages/examples/cli-demo/README.zh.md
@@ -1,78 +0,0 @@
-# @deepseek-ai/dsh-cli-demo
-
-[English](README.md) | 中文
-
-无头单次应用及 bin，用于在没有交互式 UI 或编辑器客户端的情况下运行一项 agent（智能体）任务。它组合 [`@deepseek-ai/dsh-agent-spine-demo`](../agent-spine-demo/README.md)、JSONL 持久化，以及恰好一个新建顶层 agent。bin 拥有一个从 idle 到 idle 的活动区间，渲染所选输出，执行 dispose（资源释放）直至完全停稳，然后退出。
-
-该包不挂载 console logger、交互式 UI、用户交互服务或 `ask_user_question` 工具。Stdout 专用于所选输出格式；诊断使用 stderr。
-
-## 配置
-
-| 键 | 默认值 | 路由目标 |
-|---|---|---|
-| `provider` | 必填 | 已配置 agent 的提供方路由 |
-| `model` | 必填 | 已配置 agent 的模型 |
-| `maxParallelToolCalls` | agent loop 默认值 | 正整数并发工具调用上限；`1` 表示串行 |
-| `persona` | 无 | `dsh-system-prompt` 中的部署 persona |
-| `toolOrder` | 字典序 | `dsh-system-prompt` 中显式的面向模型工具顺序 |
-| `tools` | `{ mode: 'native' }` | 通过 `dsh-agent-spine-demo` 提供的工具注册表呈现配置 |
-| `dshHome` | `$DSH_HOME` 或 `~/.dsh` | 向模型 bash 公开并用于本地 skill（技能）发现的 harness 主目录 |
-| `sessionTitle` | 主干示例限制 | 通过 `dsh-agent-spine-demo` 提供的后备标题词数／字节限制 |
-| `skills` | 拥有者默认值 | skill 注册表、本地提供方和面向模型的 skill 工具 |
-| `toolBash` | 拥有者默认值 | 面向模型的 bash 配置，包括此生产方对后台任务的显式启用 |
-| `toolTasks` | 拥有者默认值 | 通用 `task_output` 等待边界 |
-| `persistenceRoot` | `./.sessions` | JSONL 会话根目录 |
-| `persistenceCompression` | `'zstd'` | JSONL 产物编码（`'zstd'` 或原始 `'none'`） |
-| `workspaceContext` | 必填 | 工作区指令字节预算，或以 `false` 禁用加载 |
-
-## CLI（命令行界面）契约
-
-```sh
-dsh-cli-demo [--config path] [--output-format text|json|stream-json] <task>
-```
-
-`--config` 默认为 `./cordis.yml`；`--output-format` 默认为 `text`。必须恰好提供一个非空的任务位置参数，因此含空格的任务需要加引号。`--help` 在不启动的情况下打印用法。不存在 `-p` 或 `--print` 标志。
-
-根 headless-agent 示例提供其叶节点：
-
-```sh
-pnpm run demo:headless "inspect the failing test and fix it"
-```
-
-loader 配置通过仓库安装的可选原生辅助程序解析裸包说明符，因此根命令不需要特殊 Node 标志。
-
-### 输出格式
-
- `text` 写入最后一条含文本的 assistant 消息，后跟一个换行符。
- `json` 写入一条 DSH 原生结果记录：`{ type: "result", sessionId, output, usage? }`。`output` 是活动区间内最后提交的 assistant 文本。`usage` 对该区间中的每个模型步骤恰好求和一次，包括产生用量但没有提交 assistant 消息的已计费失败尝试。
- `stream-json` 将顶层会话自有活动区间中的每个规范事件写成 `{ type: "session_event", sessionId, event }`，然后写入同一结果记录。子 agent 活动只通过父工具事件与结果出现。
-
-正常进入 idle 会成功退出，不会为该任务指定轮次原因。参数、启动、观测和持久化失败会让 stdout 保持为空。SIGINT 与 SIGTERM 会取消正在进行的工作，等待 dispose 完成，并分别以 130 和 143 退出。
-
-自有活动会在最终输出前显式刷新。进程退出后，会话日志仍保留在 `persistenceRoot` 下。
-
-## 操作安全
-
-headless-agent 叶节点提供本地 bash、文件系统、skill、subagent、工作流和 todo 能力。因此任务可以修改启动工作区、运行命令、spawn 子 agent，并消耗提供方 token。请从目标项目目录运行 CLI，检查叶节点的能力与沙箱配置，不要把非交互式执行当作批准边界。
-
-## 模型体验
-
-### 单次活动
-
-#### 模型看到的内容
-
-任务位置参数会成为一条用户消息。通过 `dsh-agent-spine-demo`，顶层 agent 还会收到已配置的工作区指令与 persona、skill 目录、可见工具 schema，以及自有活动后续步骤所需的保留工具结果。
-
-#### Token 影响
-
-每个模型步骤中的任务、提示词段、工具 schema、assistant 输出和工具结果都会消耗 token。JSON 事件流式输出和最终渲染不增加模型 token；委派的子工作有自己的模型用量，不计入父结果的 `usage` 总量。
-
-#### KV Cache 影响
-
-只要单次 agent 的提示词、schema、模型路由和会话前缀保持不变，工具轮次历史就仅追加。改变该组合会建立不同的请求前缀；JSON 输出模式不影响缓存。
-
-## 已知限制与暂缓事项
-
- **每个进程只创建一个新的顶层会话**：其工作区 cwd 是启动目录；此应用不支持恢复、第二条提示词、stdin 上下文或并发顶层会话。
- **没有交互式问题或批准提供方**：需要人工回答的工具无法完成，除非其他叶节点按显式策略组合一个非交互式提供方。
- **流式输出仅限顶层会话**：子会话不会平铺到流中，聚合用量只涵盖父活动区间记录的模型步骤。
--- a/packages/examples/cli-demo/package.json
+++ b/packages/examples/cli-demo/package.json
@@ -1,68 +0,0 @@
-{
-  "name": "@deepseek-ai/dsh-cli-demo",
-  "description": "Headless one-shot agent app with text and DSH-native JSON output",
-  "version": "0.0.1",
-  "private": true,
-  "type": "module",
-  "main": "lib/index.js",
-  "types": "lib/types/index.d.ts",
-  "bin": {
-    "dsh-cli-demo": "lib/bin.js"
-  },
-  "exports": {
-    ".": {
-      "types": "./lib/types/index.d.ts",
-      "default": "./lib/index.js"
-    },
-    "./invariant": {
-      "types": "./lib/types/invariant.d.ts",
-      "default": "./lib/invariant.js"
-    },
-    "./bin": {
-      "types": "./lib/types/bin.d.ts",
-      "default": "./lib/bin.js"
-    },
-    "./src/*": "./src/*",
-    "./package.json": "./package.json"
-  },
-  "files": [
-    "lib/index.js",
-    "lib/invariant.js",
-    "lib/bin.js",
-    "lib/types/**/*.d.ts"
-  ],
-  "license": "BSD-3-Clause",
-  "peerDependencies": {
-    "@cordisjs/plugin-include": "^1.0.4",
-    "@cordisjs/plugin-loader": "^1.0.0-rc.5",
-    "@deepseek-ai/dsh-agent": "^0.0.1",
-    "@deepseek-ai/dsh-agent-spine-demo": "^0.0.1",
-    "@deepseek-ai/dsh-app-boot": "^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-persistence-jsonl": "^0.0.1",
-    "@deepseek-ai/dsh-tools": "^0.0.1",
-    "@deepseek-ai/dsh-workspace-context": "^0.0.1",
-    "cordis": "^4.0.0-rc.7",
-    "schemastery": "^3.17.0"
-  },
-  "devDependencies": {
-    "@cordisjs/plugin-include": "workspace:^",
-    "@cordisjs/plugin-loader": "workspace:^",
-    "@deepseek-ai/dsh-agent": "workspace:^",
-    "@deepseek-ai/dsh-agent-spine-demo": "workspace:^",
-    "@deepseek-ai/dsh-app-boot": "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-persistence-jsonl": "workspace:^",
-    "@deepseek-ai/dsh-system-prompt": "workspace:^",
-    "@deepseek-ai/dsh-tools": "workspace:^",
-    "@deepseek-ai/dsh-workspace-context": "workspace:^",
-    "cordis": "^4.0.0-rc.7",
-    "schemastery": "^3.17.0"
-  }
-}
--- a/packages/examples/cli-demo/src/bin.ts
+++ b/packages/examples/cli-demo/src/bin.ts
@@ -1,34 +0,0 @@
-#!/usr/bin/env node
-/**
- * Process wrapper for `dsh-cli-demo`; covered parsing and task execution live in
- * `cli.ts` while this entry owns Unix signal-to-exit-code mapping.
- * @module @deepseek-ai/dsh-cli-demo/bin
- */
-
-import { installFailLoud } from '@deepseek-ai/dsh-app-boot'
-import { executeCli } from './cli.ts'
-
-const NAME = 'dsh-cli-demo'
-
-/* v8 ignore start -- thin self-executing process glue; built-bin tests exercise
-   real argv, signals, Loader boot, output, and exit codes */
-const abort = new AbortController()
-let signalExitCode: number | undefined
-const interrupt = (signal: 'SIGINT' | 'SIGTERM', code: number): void => {
-  signalExitCode ??= code
-  if (!abort.signal.aborted) abort.abort(`received ${signal}`)
-}
-const onSigint = (): void => { interrupt('SIGINT', 130) }
-const onSigterm = (): void => { interrupt('SIGTERM', 143) }
-const uninstallFailLoud = installFailLoud(NAME)
-process.on('SIGINT', onSigint)
-process.on('SIGTERM', onSigterm)
-try {
-  const code = await executeCli(process.argv.slice(2), { signal: abort.signal })
-  process.exitCode = signalExitCode ?? code
-} finally {
-  process.off('SIGINT', onSigint)
-  process.off('SIGTERM', onSigterm)
-  uninstallFailLoud()
-}
-/* v8 ignore stop */
--- a/packages/examples/cli-demo/src/cli.ts
+++ b/packages/examples/cli-demo/src/cli.ts
@@ -1,406 +0,0 @@
-/**
- * Command parser and one-turn driver for `dsh-cli-demo`. The executable wrapper
- * owns process signals; this module owns output, durability, and cleanup.
- * @module @deepseek-ai/dsh-cli-demo/cli
- */
-
-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 } from '@deepseek-ai/dsh-session'
-import { boot, loadEnv, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
-
-const CLI_NAME = 'dsh-cli-demo'
-const DEFAULT_CONFIG_PATH = './cordis.yml'
-const OUTPUT_FORMATS = ['text', 'json', 'stream-json'] as const
-const USAGE = `Usage: ${CLI_NAME} [--config path] [--output-format text|json|stream-json] (-p <task> | <task>)\n`
-
-/** Supported CLI output encodings. */
-export type OutputFormat = typeof OUTPUT_FORMATS[number]
-
-/** Parsed command: help exits before boot; run carries one validated task. */
-export type CliCommand =
-  | { readonly kind: 'help' }
-  | {
-    readonly kind: 'run'
-    readonly configPath: string
-    readonly outputFormat: OutputFormat
-    readonly task: string
-  }
-
-/** DSH-native final record emitted by JSON modes. */
-export interface CliResult {
-  readonly type: 'result'
-  readonly sessionId: string
-  readonly output: string
-  readonly usage?: TokenUsage
-}
-
-/** Options for one turn against the configured top-level agent. */
-export interface OneShotOptions {
-  /** Exactly one nonblank user task. */
-  readonly task: string
-  /** Optional signal that cancels the selected agent. */
-  readonly signal?: AbortSignal
-  /** Synchronous task-turn observer; a throw cancels the agent and fails the run after flush. */
-  readonly onEvent?: (sessionId: string, event: SessionEvent) => void
-}
-
-/** Injectable process boundaries used by {@link executeCli}. */
-export interface CliRuntime {
-  /** Process cwd for config resolution and `.env` loading. */
-  readonly cwd?: string
-  /** Cancellation signal, normally aborted by SIGINT or SIGTERM. */
-  readonly signal?: AbortSignal
-  /** Loader boot boundary. */
-  readonly boot?: (name: string, absoluteConfigPath: string) => Promise<Context>
-  /** Optional `.env` loader boundary. */
-  readonly loadEnv?: (name: string, dir: string, warn: (line: string) => void) => void
-  /** Stdout sink; throws are treated as output failures. */
-  readonly writeStdout?: (chunk: string) => unknown
-  /** Stderr diagnostic sink. */
-  readonly writeStderr?: (chunk: string) => unknown
-  /** Context disposal boundary. */
-  readonly dispose?: (ctx: Context) => Promise<void>
-}
-
-interface ParsedArguments {
-  readonly values: {
-    readonly config?: string
-    readonly 'output-format'?: string
-    readonly help?: boolean
-    readonly prompt?: string
-  }
-  readonly positionals: string[]
-}
-
-class CliArgumentError extends Error {
-  constructor(message: string) {
-    super(message)
-    this.name = 'CliArgumentError'
-  }
-}
-
-class CliInterruptedError extends Error {
-  constructor(reason: string) {
-    super(reason)
-    this.name = 'CliInterruptedError'
-  }
-}
-
-/** Render an arbitrary value without trusting its type traps or string coercion. */
-function renderUnknown(value: unknown): string {
-  try {
-    return String(value)
-  } catch {
-    return '[unrenderable thrown value]'
-  }
-}
-
-/** Normalize an arbitrary thrown value without letting inspection escape containment. */
-function toError(error: unknown): Error {
-  try {
-    if (error instanceof Error) return error
-  } catch {
-    // A hostile proxy may throw during instanceof; use the total renderer below.
-  }
-  return new Error(renderUnknown(error))
-}
-
-function interruptionReason(signal: AbortSignal): string {
-  return signal.reason === undefined ? 'interrupted' : renderUnknown(signal.reason)
-}
-
-/**
- * Parse the bin arguments and enforce the one-positional-task contract.
- * @param args - arguments after the executable name.
- * @returns a help or run command.
- * @throws {@link CliArgumentError} for unknown flags, invalid formats, or task cardinality.
- */
-export function parseCliArgs(args: readonly string[]): CliCommand {
-  let parsed: ParsedArguments
-  try {
-    parsed = parseArgs({
-      args: [...args],
-      options: {
-        config: { type: 'string' },
-        'output-format': { type: 'string' },
-        help: { type: 'boolean' },
-        prompt: { type: 'string', short: 'p' },
-      },
-      allowPositionals: true,
-      strict: true,
-    })
-  } catch (error: unknown) {
-    throw new CliArgumentError(toError(error).message)
-  }
-
-  if (parsed.values.help === true) return { kind: 'help' }
-  const prompt = parsed.values.prompt
-  if (prompt !== undefined && parsed.positionals.length > 0) {
-    throw new CliArgumentError('-p/--prompt and a positional task are mutually exclusive')
-  }
-  if (prompt === undefined && parsed.positionals.length !== 1) {
-    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.
-  // 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')
-
-  const requestedFormat = parsed.values['output-format'] ?? 'text'
-  if (!OUTPUT_FORMATS.some(format => format === requestedFormat)) {
-    throw new CliArgumentError(`unsupported output format ${JSON.stringify(requestedFormat)}`)
-  }
-  return {
-    kind: 'run',
-    configPath: parsed.values.config ?? DEFAULT_CONFIG_PATH,
-    outputFormat: requestedFormat as OutputFormat,
-    task,
-  }
-}
-
-function addUsage(total: TokenUsage | undefined, step: TokenUsage): TokenUsage {
-  const next: TokenUsage = {
-    inputTokens: (total?.inputTokens ?? 0) + step.inputTokens,
-    outputTokens: (total?.outputTokens ?? 0) + step.outputTokens,
-  }
-  for (const key of ['cacheReadTokens', 'cacheWriteTokens', 'reasoningTokens'] as const) {
-    if (total?.[key] !== undefined || step[key] !== undefined) next[key] = (total?.[key] ?? 0) + (step[key] ?? 0)
-  }
-  return next
-}
-
-function assistantText(event: Extract<SessionEvent, { type: 'assistant/message' }>): string | undefined {
-  const blocks = event.data.message.content.filter(block => block.type === 'text')
-  return blocks.length === 0 ? undefined : blocks.map(block => block.text).join('')
-}
-
-/** Wait for startup quiescence while making pre-run cancellation terminal. */
-async function waitForStartupIdle(agent: Agent, signal?: AbortSignal): Promise<void> {
-  if (signal === undefined) {
-    await agent.whenIdle()
-    return
-  }
-  if (signal.aborted) {
-    agent.cancel({ kind: 'user' })
-    throw new CliInterruptedError(interruptionReason(signal))
-  }
-  await new Promise<void>((resolve, reject) => {
-    const onAbort = (): void => {
-      agent.cancel({ kind: 'user' })
-      reject(new CliInterruptedError(interruptionReason(signal)))
-    }
-    signal.addEventListener('abort', onAbort, { once: true })
-    void agent.whenIdle().then(resolve, reject).finally(() => {
-      signal.removeEventListener('abort', onAbort)
-    })
-  })
-}
-
-/**
- * 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.
- */
-export async function runOneShot(ctx: Context, options: OneShotOptions): Promise<CliResult> {
-  const agents = ctx.get('agents')?.roots() ?? []
-  const [agent] = agents
-  if (agent === undefined || agents.length !== 1) {
-    throw new Error(`config must create exactly one top-level agent, found ${agents.length}`)
-  }
-  await waitForStartupIdle(agent, options.signal)
-
-  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 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)
-      queueMicrotask(() => {
-        agent.cancel({ kind: 'user' })
-      })
-    }
-  }
-
-  const disposeListener = ctx.on('session/event', (session, event) => {
-    if (session !== agent.session) return
-    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.chunk.type === 'usage') {
-      usageByStep.set(`${event.data.turn}/${event.data.step}`, event.data.chunk.usage)
-    }
-    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)
-      }
-    }
-  })
-
-  const signal = options.signal
-  let onAbort: (() => void) | undefined
-  if (signal !== undefined) {
-    onAbort = (): void => {
-      interrupted ??= new CliInterruptedError(interruptionReason(signal))
-      agent.cancel({ kind: 'user' })
-    }
-    signal.addEventListener('abort', onAbort, { once: true })
-    /* v8 ignore next -- closes the race between startup-idle completion and listener registration */
-    if (signal.aborted) onAbort()
-  }
-
-  try {
-    if (interrupted === undefined) agent.followup(message)
-    await agent.whenIdle()
-  } finally {
-    if (onAbort !== undefined) signal?.removeEventListener('abort', onAbort)
-    disposeListener()
-  }
-
-  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',
-    sessionId: agent.session.id,
-    output,
-    ...usage === undefined ? {} : { usage },
-  }
-}
-
-function renderResult(outputFormat: OutputFormat, result: CliResult): string {
-  return outputFormat === 'text' ? `${result.output}\n` : `${JSON.stringify(result)}\n`
-}
-
-/**
- * Race Loader boot with cancellation without abandoning a context that becomes
- * available after the caller has been released. Waiting for that late context
- * would recreate the signal hang, so its disposal and diagnostics run detached.
- */
-async function bootInterruptibly(
-  start: () => Promise<Context>,
-  signal: AbortSignal | undefined,
-  disposeLateContext: (ctx: Context) => Promise<void>,
-  reportLateDisposalFailure: (error: unknown) => void,
-): Promise<Context> {
-  if (signal === undefined) return await start()
-  if (signal.aborted) throw new CliInterruptedError(interruptionReason(signal))
-
-  let onAbort!: () => void
-  const interruptedBoot = new Promise<never>((_resolve, reject) => {
-    onAbort = (): void => {
-      reject(new CliInterruptedError(interruptionReason(signal)))
-    }
-    signal.addEventListener('abort', onAbort, { once: true })
-    /* v8 ignore next -- closes registration against a non-standard synchronously mutating signal */
-    if (signal.aborted) onAbort()
-  })
-  const booting = Promise.resolve().then(start)
-  try {
-    return await Promise.race([booting, interruptedBoot])
-  } catch (error: unknown) {
-    // The awaited race permits the signal to change after the preflight check.
-    // oxlint-disable-next-line typescript/no-unnecessary-condition
-    if (signal.aborted) {
-      void booting.then(
-        async (lateContext) => {
-          try {
-            await disposeLateContext(lateContext)
-          } catch (error: unknown) {
-            reportLateDisposalFailure(error)
-          }
-        },
-        () => {},
-      )
-    }
-    throw error
-  } finally {
-    signal.removeEventListener('abort', onAbort)
-  }
-}
-
-/**
- * Execute one CLI invocation. Argument and boot failures never write stdout;
- * context disposal is awaited before return, and its failure does not replace
- * an earlier diagnostic.
- * @param args - arguments after the executable name.
- * @param runtime - optional injected process boundaries for tests and embedding.
- * @returns the ordinary process exit code; the thin bin overrides it for Unix signals.
- */
-export async function executeCli(args: readonly string[], runtime: CliRuntime = {}): Promise<number> {
-  /* v8 ignore next -- default process sinks are exercised by the built-bin smoke */
-  const writeStdout = runtime.writeStdout ?? (chunk => process.stdout.write(chunk))
-  /* v8 ignore next -- default process sinks are exercised by the built-bin smoke */
-  const writeStderr = runtime.writeStderr ?? (chunk => process.stderr.write(chunk))
-  let command: CliCommand
-  try {
-    command = parseCliArgs(args)
-  } catch (error: unknown) {
-    writeStderr(`${CLI_NAME}: ${toError(error).message}\n${USAGE}`)
-    return 1
-  }
-  if (command.kind === 'help') {
-    writeStdout(USAGE)
-    return 0
-  }
-
-  /* v8 ignore next -- default process cwd is exercised by the built-bin smoke */
-  const cwd = runtime.cwd ?? process.cwd()
-  /* v8 ignore next -- default env/boot boundaries are exercised by the Loader and built-bin smokes */
-  const loadEnvironment = runtime.loadEnv ?? loadEnv
-  /* v8 ignore next -- default env/boot boundaries are exercised by the Loader and built-bin smokes */
-  const bootContext = runtime.boot ?? boot
-  /* v8 ignore next -- default disposal is exercised by the built-bin smoke */
-  const disposeContext = runtime.dispose ?? (target => target.fiber.dispose())
-  let ctx: Context | undefined
-  let exitCode = 1
-  let diagnostic: string | undefined
-  try {
-    loadEnvironment(CLI_NAME, cwd, line => writeStderr(line))
-    ctx = await bootInterruptibly(
-      () => bootContext(CLI_NAME, resolveConfigPath(command.configPath, undefined, cwd)),
-      runtime.signal,
-      disposeContext,
-      error => writeStderr(`${CLI_NAME}: dispose after interrupted boot failed: ${toError(error).message}\n`),
-    )
-    const result = await runOneShot(ctx, {
-      task: command.task,
-      ...runtime.signal === undefined ? {} : { signal: runtime.signal },
-      ...command.outputFormat === 'stream-json'
-        ? { onEvent: (sessionId: string, event: SessionEvent) => {
-          writeStdout(`${JSON.stringify({ type: 'session_event', sessionId, event })}\n`)
-        } }
-        : {},
-    })
-    writeStdout(renderResult(command.outputFormat, result))
-    exitCode = 0
-  } catch (error: unknown) {
-    diagnostic = `${CLI_NAME}: ${toError(error).message}\n`
-  } finally {
-    if (ctx !== undefined) {
-      try {
-        await disposeContext(ctx)
-      } catch (error: unknown) {
-        diagnostic = `${diagnostic ?? ''}${CLI_NAME}: dispose failed: ${toError(error).message}\n`
-        exitCode = 1
-      }
-    }
-  }
-  if (diagnostic !== undefined) writeStderr(diagnostic)
-  return exitCode
-}
--- a/packages/examples/cli-demo/src/index.ts
+++ b/packages/examples/cli-demo/src/index.ts
@@ -1,96 +0,0 @@
-/**
- * Headless one-shot app composition: the default agent spine, JSONL session
- * persistence, and one fresh top-level agent. The CLI driver owns task
- * submission and output; the app deliberately mounts no interactive or logging
- * front door so stdout remains protocol-pure.
- * @module @deepseek-ai/dsh-cli-demo
- */
-
-import type { Context } from 'cordis'
-import z from 'schemastery'
-import { SessionId } from '@deepseek-ai/dsh-session'
-import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools'
-import * as agentCore from '@deepseek-ai/dsh-agent-spine-demo'
-import SessionPersistenceJsonl, {
-  JsonlCompressionSchema,
-  type JsonlCompression,
-} from '@deepseek-ai/dsh-session-persistence-jsonl'
-import * as sessionCheckpointPolicy from '@deepseek-ai/dsh-session-checkpoint-policy'
-import * as workspaceContext from '@deepseek-ai/dsh-workspace-context'
-
-const DEFAULT_PERSISTENCE_ROOT = './.sessions'
-
-export const name = 'cli-demo'
-
-/** App config forwarded to the spine, configured agent, and JSONL backend. */
-export interface Config {
-  /** Provider route for the configured agent. */
-  provider: string
-  /** Model name for the configured 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 the JSONL session backend writes under. Defaults to `./.sessions`. */
-  persistenceRoot?: string
-  /** JSONL artifact encoding; defaults to checksummed Zstandard frames. */
-  persistenceCompression?: JsonlCompression
-  /** 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 control-tool config forwarded through agent-spine-demo. */
-  toolTasks?: NonNullable<agentCore.Config['toolTasks']>
-  /** Controls automatic AGENTS.md/CLAUDE.md loading; configure a byte budget or set `false`. */
-  workspaceContext: agentCore.Config['workspaceContext']
-}
-
-// Each front door keeps a complete Loader schema so its deployment contract is
-// readable without a cross-package config facade.
-/* jscpd:ignore-start */
-export const Config: z<Config> = z.object({
-  provider: z.string().required(),
-  model: z.string().required(),
-  maxParallelToolCalls: z.number().step(1).min(1),
-  persistenceRoot: z.string().default(DEFAULT_PERSISTENCE_ROOT),
-  persistenceCompression: JsonlCompressionSchema,
-  persona: z.string(),
-  dshHome: z.string(),
-  sessionTitle: agentCore.SessionTitleConfigSchema,
-  skills: agentCore.SkillConfigSchema,
-  // Absent means lexicographic order; schemastery's native array default is [].
-  toolOrder: z.array(z.string()).default(undefined as unknown as string[]),
-  tools: ToolRegistry.Config,
-  toolBash: agentCore.ToolBashConfigSchema,
-  toolTasks: z.union([z.const(false), agentCore.ToolTasksConfigSchema]),
-  workspaceContext: z.union([z.const(false), workspaceContext.Config]).required(),
-})
-/* jscpd:ignore-end */
-
-/**
- * Compose the UI-less spine, a fresh top-level agent rooted at the process cwd,
- * and JSONL persistence. Swappable adapters, executors, and product tools stay
- * in the leaf `cordis.yml`.
- * @param ctx - app context that owns the composed child plugins.
- * @param config - validated app configuration.
- */
-export function apply(ctx: Context, config: Config): void {
-  ctx.plugin(agentCore, {
-    ...agentCore.pickSpineConfig(config),
-    agents: [{ id: SessionId('main'), provider: config.provider, model: config.model, cwd: process.cwd() }],
-  })
-  ctx.plugin(SessionPersistenceJsonl, {
-    root: config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT,
-    ...(config.persistenceCompression === undefined ? {} : { compression: config.persistenceCompression }),
-  })
-  ctx.plugin(sessionCheckpointPolicy)
-}
--- a/packages/examples/cli-demo/src/invariant.ts
+++ b/packages/examples/cli-demo/src/invariant.ts
@@ -1,30 +0,0 @@
-/**
- * Package-owned invariant companion for `@deepseek-ai/dsh-cli-demo`.
- * @module @deepseek-ai/dsh-cli-demo/invariant
- */
-
-/* jscpd:ignore-start */
-import type { Context } from 'cordis'
-import type { InvariantInstaller } from '@deepseek-ai/dsh-invariants'
-
-const PACKAGE_NAME = '@deepseek-ai/dsh-cli-demo'
-
-/** Cordis companion plugin name. */
-export const name = 'cli-demo-invariant'
-/** Service required before the companion can reserve package ownership. */
-export const inject = ['invariants']
-
-/**
- * No runtime invariant: this composition package owns no independent event stream or mutable data;
- * Loader and built-entry tests cover its wiring.
- */
-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/cli-demo/tests/built-bin.e2e.ts
+++ b/packages/examples/cli-demo/tests/built-bin.e2e.ts
@@ -1,223 +0,0 @@
-import { existsSync } from 'node:fs'
-import { mkdtemp, mkdir, readFile, readdir, rm, symlink, writeFile } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { dirname, join } from 'node:path'
-import { promisify } from 'node:util'
-import { fileURLToPath } from 'node:url'
-import { zstdDecompress } from 'node:zlib'
-import { execa } from 'execa'
-import { afterEach, describe, expect, it } from 'vitest'
-
-/**
- * Published-entry smoke: run `lib/bin.js` under plain Node in a symlinked external consumer.
- * The consumer's mock model is an example-local TypeScript plugin (Node 22.19+ — the engines
- * floor — strips types natively, so plain `node` loads it), its config carries a `disabled:
- * true` unresolvable entry (the fail-loud entry-load guard must not mistake an intentionally
- * fiber-less entry for a failed import), and the optional spill pair loads from the consumer
- * install — so every passing boot proves all three alongside the CLI's own output contract.
- */
-
-const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
-const cliBin = join(repoRoot, 'packages/examples/cli-demo/lib/bin.js')
-const decompress = promisify(zstdDecompress)
-const dshPackages = [
-  'examples/agent-spine-demo', 'examples/cli-demo', 'core/agent', 'core/session',
-  'core/system-prompt', 'core/tools', 'core/agent-loop', 'llm/llm', 'bash/bash',
-  'bash/bash-local', 'bash/tool-bash', 'subprocess/subprocess', 'subprocess/subprocess-local', 'support/invariants', 'ui/app-boot',
-  'session-persistence/session-persistence', 'session-persistence/session-checkpoint-policy',
-  'session-persistence/session-persistence-jsonl',
-  'context/workspace-context',
-  'spill/spill', 'spill/spill-local', 'spill/spill-policy', 'util/retention',
-]
-const vendorPackages = ['cordis', 'loader', 'include', 'timer', 'schemastery', 'cosmokit']
-
-async function packageName(dir: string): Promise<string> {
-  return (JSON.parse(await readFile(join(dir, 'package.json'), 'utf8')) as { name: string }).name
-}
-
-async function linkPackage(dir: string, nodeModules: string): Promise<void> {
-  const target = join(nodeModules, await packageName(dir))
-  await mkdir(dirname(target), { recursive: true })
-  await symlink(dir, target)
-}
-
-async function makeConsumer(): Promise<string> {
-  const dir = await mkdtemp(join(tmpdir(), 'cli-built-bin-'))
-  const nodeModules = join(dir, 'node_modules')
-  for (const rel of dshPackages) await linkPackage(join(repoRoot, 'packages', rel), nodeModules)
-  for (const rel of vendorPackages) await linkPackage(join(repoRoot, 'vendor', rel), nodeModules)
-  await writeFile(join(dir, 'mock-llm.ts'), [
-    // Real type annotations: this file exists to prove plain Node's type
-    // stripping loads an example-local TS plugin from a built consumer.
-    "import { LlmAdapter, type GenerateOptions, type StreamChunk } from '@deepseek-ai/dsh-llm'",
-    "import type { Context } from 'cordis'",
-    'class Mock extends LlmAdapter {',
-    '  async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {',
-    "    const text: string = options.messages.flatMap(message => message.content).filter(block => block.type === 'text').at(-1)?.text ?? ''",
-    "    yield { type: 'block-start', index: 0, blockType: 'text' }",
-    "    if (text === 'hang') {",
-    "      yield { type: 'text-delta', index: 0, text: 'partial' }",
-    '      await new Promise<never>((resolve, reject) => {',
-    "        const timer = setTimeout(() => reject(new Error('hang timeout')), 30000)",
-    "        const onAbort = () => { clearTimeout(timer); reject(new Error('aborted')) }",
-    '        if (options.signal.aborted) onAbort()',
-    "        else options.signal.addEventListener('abort', onAbort, { once: true })",
-    '      })',
-    '      return',
-    '    }',
-    '    const reply = `BUILT: ${text}`',
-    "    yield { type: 'text-delta', index: 0, text: reply }",
-    "    yield { type: 'block-end', index: 0, block: { type: 'text', text: reply } }",
-    "    yield { type: 'usage', usage: { inputTokens: 4, outputTokens: 2 } }",
-    "    yield { type: 'finish', reason: { kind: 'stop' } }",
-    '  }',
-    '}',
-    "export const name = 'built-cli-mock'",
-    "export const inject = ['llm']",
-    "export function apply(ctx: Context) { ctx.llm.registerAdapter(['built-cli-mock'], new Mock()) }",
-    '',
-  ].join('\n'))
-  await writeFile(join(dir, 'cordis.yml'), [
-    '- id: mock-llm',
-    "  name: './mock-llm.ts'",
-    '- id: subprocess',
-    "  name: '@deepseek-ai/dsh-subprocess-local'",
-    '- id: bash',
-    "  name: '@deepseek-ai/dsh-bash-local'",
-    '- id: cli-agent',
-    "  name: '@deepseek-ai/dsh-cli-demo'",
-    '  config:',
-    '    provider: built-cli-mock',
-    '    model: built-cli-mock',
-    "    persona: 'built CLI test'",
-    "    persistenceRoot: './.sessions'",
-    '    workspaceContext: false',
-    '- id: spill-local',
-    "  name: '@deepseek-ai/dsh-spill-local'",
-    '- id: spill-policy',
-    "  name: '@deepseek-ai/dsh-spill-policy'",
-    '  config:',
-    '    maxInlineBytes: 50000',
-    // A `disabled: true` entry settles without a fiber by design; the fail-loud
-    // entry-load guard must not mistake it for a failed import. The nonexistent
-    // path makes that distinction observable while a clean run proves boot continued.
-    '- id: off',
-    "  name: './does-not-exist.ts'",
-    '  disabled: true',
-    '',
-  ].join('\n'))
-  return dir
-}
-
-interface BinResult {
-  readonly code: number
-  readonly signal: NodeJS.Signals | null
-  readonly stdout: string
-  readonly stderr: string
-}
-
-async function runBuiltBin(cwd: string, args: readonly string[], interrupt?: NodeJS.Signals): Promise<BinResult> {
-  const subprocess = execa(process.execPath, [cliBin, ...args], {
-    cwd,
-    env: { DSH_HOME: join(cwd, '.dsh'), DSH_AGENTS_HOME: join(cwd, '.agents') },
-    stdin: 'ignore',
-    timeout: 25_000,
-    killSignal: 'SIGKILL',
-    reject: false,
-    stripFinalNewline: false,
-  })
-  // Genuinely custom mid-stream logic: the signal cases deliver `interrupt`
-  // once the first streamed chunk proves the turn is in flight.
-  if (interrupt !== undefined) {
-    let streamed = ''
-    let interrupted = false
-    subprocess.stdout.on('data', (chunk: Buffer) => {
-      streamed += chunk.toString('utf8')
-      if (!interrupted && streamed.includes('assistant/chunk')) {
-        interrupted = true
-        subprocess.kill(interrupt)
-      }
-    })
-  }
-  const result = await subprocess
-  if (result.timedOut) {
-    throw new Error(`built CLI did not exit. stdout:\n${result.stdout}\nstderr:\n${result.stderr}`)
-  }
-  return { code: result.exitCode ?? -1, signal: result.signal ?? null, stdout: result.stdout, stderr: result.stderr }
-}
-
-let consumer: string | undefined
-
-afterEach(async () => {
-  if (consumer !== undefined) await rm(consumer, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 })
-  consumer = undefined
-})
-
-describe.skipIf(!existsSync(cliBin))('dsh-cli-demo BUILT bin', () => {
-  it('runs text, json, and stream-json under plain Node and persists fresh sessions', async () => {
-    consumer = await makeConsumer()
-    const text = await runBuiltBin(consumer, ['--config', './cordis.yml', 'hello'])
-    expect(text).toMatchObject({ code: 0, signal: null, stdout: 'BUILT: hello\n', stderr: '' })
-
-    const json = await runBuiltBin(consumer, ['--config', './cordis.yml', '--output-format', 'json', 'json task'])
-    expect(JSON.parse(json.stdout)).toMatchObject({
-      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: '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'))
-    expect(logs).toHaveLength(3)
-    const compressed = await readFile(join(sessionsRoot, logs[0]!))
-    expect(compressed.subarray(0, 4).toString('hex')).toBe('28b52ffd')
-    expect(JSON.parse((await decompress(compressed)).toString())).toMatchObject({ type: 'session' })
-  }, 30_000)
-
-  it('keeps stdout empty for invalid argv and missing config', async () => {
-    consumer = await makeConsumer()
-    for (const args of [
-      ['--config', './cordis.yml'],
-      ['--config', './cordis.yml', 'one', 'two'],
-      ['--config', './missing.yml', 'task'],
-    ]) {
-      const result = await runBuiltBin(consumer, args)
-      expect(result.code).not.toBe(0)
-      expect(result.stdout).toBe('')
-      expect(result.stderr.length).toBeGreaterThan(0)
-    }
-  }, 30_000)
-
-  describe.skipIf(process.platform === 'win32')('POSIX signal delivery', () => {
-    it.each([
-      ['SIGINT', 130],
-      ['SIGTERM', 143],
-    ] as const)('cancels and disposes on %s with exit %i', async (signal, code) => {
-      consumer = await makeConsumer()
-      const result = await runBuiltBin(
-        consumer,
-        ['--config', './cordis.yml', '--output-format', 'stream-json', 'hang'],
-        signal,
-      )
-      expect(result, JSON.stringify(result)).toMatchObject({ code, signal: null })
-      expect(result.stdout).toContain('"kind":"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
@@ -1,202 +0,0 @@
-import { mkdtemp } from 'node:fs/promises'
-import { randomUUID } from 'node:crypto'
-import { tmpdir } from 'node:os'
-import { join } from 'node:path'
-import { Context } from 'cordis'
-import Loader from '@cordisjs/plugin-loader'
-import { agentEvents } from '@deepseek-ai/dsh-agent'
-import { SessionId } from '@deepseek-ai/dsh-session'
-import { CallId, type Message } from '@deepseek-ai/dsh-llm'
-import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
-import type { ToolExecution } from '@deepseek-ai/dsh-tools'
-import { afterEach, describe, expect, it, vi } from 'vitest'
-import * as cliDemo from '../src/index.ts'
-
-const testToolSignal = new AbortController().signal
-
-const contexts: Context[] = []
-
-async function skillConfig(catalogDescriptionMaxLength?: number): Promise<NonNullable<cliDemo.Config['skills']>> {
-  const home = await mkdtemp(join(tmpdir(), 'dsh-cli-demo-skills-'))
-  return {
-    local: { dshHome: join(home, '.dsh'), agentsHome: join(home, '.agents') },
-    ...catalogDescriptionMaxLength === undefined ? {} : { tool: { catalogDescriptionMaxLength } },
-  }
-}
-
-async function mount(config: cliDemo.Config, withBash = false): Promise<Context> {
-  const ctx = new Context()
-  if (withBash) {
-    ctx.provide('bash', {
-      sandboxMode: undefined,
-      resolve() { throw new Error('composition test does not execute bash') },
-      run() { throw new Error('composition test does not execute bash') },
-      start() { throw new Error('composition test does not execute bash') },
-    })
-  }
-  contexts.push(ctx)
-  config.persistenceRoot ??= await mkdtemp(join(tmpdir(), 'dsh-cli-demo-persistence-'))
-  await ctx.plugin(cliDemo, config)
-  await new Promise(resolve => setTimeout(resolve, 80))
-  return ctx
-}
-
-async function composePrefix(ctx: Context): Promise<Message[]> {
-  const agent = ctx.agentLoop.create(SessionId(`cli-demo-prefix-${randomUUID()}`), {}, { cwd: '/tmp' })
-  const signal = new AbortController().signal
-  const decision = await agentEvents(ctx, agent).waterfall(
-    'agent/pre-step', { messages: [], 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()
-}
-
-afterEach(async () => {
-  await Promise.all(contexts.splice(0).map(ctx => ctx.fiber.dispose()))
-})
-
-describe('dsh-cli-demo app composition', () => {
-  it('composes the UI-less spine, JSONL persistence, and a main agent', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'dsh-cli-demo-compose-'))
-    const ctx = await mount({
-      provider: 'mock',
-      model: 'mock',
-      persona: 'Headless.',
-      tools: { mode: 'native' },
-      persistenceRoot: root,
-      persistenceCompression: 'none',
-      skills: await skillConfig(),
-      workspaceContext: false,
-    })
-    const [agent] = ctx.get('agents')?.roots() ?? []
-    expect(ctx.get('agentLoop')).toBeDefined()
-    expect(ctx.get('sessionPersistence')).toBeDefined()
-    expect((ctx.get('sessionPersistence') as unknown as { config: { compression?: string } }).config.compression).toBe('none')
-    expect(agent?.session.header.cwd).toBe(process.cwd())
-    expect(ctx.get('userInteraction')).toBeUndefined()
-    expect(ctx.get('tools')?.get('ask_user_question')).toBeUndefined()
-  })
-
-  it('covers direct-apply defaults and forwards skill and tool-order config', async () => {
-    const oldDshHome = process.env.DSH_HOME
-    const oldAgentsHome = process.env.DSH_AGENTS_HOME
-    const home = await mkdtemp(join(tmpdir(), 'dsh-cli-demo-defaults-'))
-    process.env.DSH_HOME = join(home, '.dsh')
-    process.env.DSH_AGENTS_HOME = join(home, '.agents')
-    try {
-      const ctx = new Context()
-      contexts.push(ctx)
-      cliDemo.apply(ctx, { provider: 'mock', model: 'mock', workspaceContext: false })
-      await new Promise(resolve => setTimeout(resolve, 80))
-      expect(ctx.get('sessionPersistence')).toBeDefined()
-      const [agent] = ctx.get('agents')?.roots() ?? []
-      expect(agent?.session.id).toMatch(/^main-session-/)
-      expect(await ctx.skills.list()).toEqual([])
-    } finally {
-      if (oldDshHome === undefined) delete process.env.DSH_HOME
-      else process.env.DSH_HOME = oldDshHome
-      if (oldAgentsHome === undefined) delete process.env.DSH_AGENTS_HOME
-      else process.env.DSH_AGENTS_HOME = oldAgentsHome
-    }
-
-    const ctx = await mount({
-      provider: 'mock',
-      model: 'mock',
-      toolOrder: ['zulu', TOOL_ORDER_REST],
-      skills: await skillConfig(6),
-      workspaceContext: false,
-    })
-    ctx.skills.register({ name: 'cli-skill', description: 'CLI skill', source: 'runtime', content: 'body' })
-    for (const name of ['alpha', 'zulu']) {
-      ctx.tools.register({
-        name,
-        description: name,
-        parameters: {},
-        output: { schema: { type: 'null' }, render: () => [] },
-        execute: async () => null,
-      })
-    }
-    expect(JSON.stringify(await composePrefix(ctx))).toContain('- `cli-skill`: CLI...')
-    expect((await ctx.systemPrompt.assemble()).tools.map(tool => tool.name)).toEqual([
-      'zulu',
-      'alpha',
-      'skill',
-      'task_kill',
-      'task_list',
-      'task_output',
-    ])
-  })
-
-  it('forwards the complete shared spine configuration', async () => {
-    const dshHome = await mkdtemp(join(tmpdir(), 'dsh-cli-demo-home-'))
-    const agentsHome = await mkdtemp(join(tmpdir(), 'dsh-cli-demo-agents-'))
-    const ctx = await mount({
-      provider: 'mock',
-      model: 'mock',
-      maxParallelToolCalls: 3,
-      dshHome,
-      skills: { local: { agentsHome } },
-      toolBash: { enableRunInBackground: false },
-      toolTasks: { waitTimeoutMs: 7, maxWaitTimeoutMs: 11 },
-      workspaceContext: false,
-    }, true)
-
-    expect(ctx.get('agentLoop')?.config.maxParallelToolCalls).toBe(3)
-    const execution: ToolExecution = {
-      signal: testToolSignal,
-      token: Symbol('cli-demo-dsh-home-test') as ToolExecution['token'],
-      callId: CallId('cli-demo-dsh-home'),
-      name: 'bash',
-      arguments: { command: 'true' },
-    }
-    expect(ctx.bashEnv.collect(execution)).toMatchObject({ DSH_HOME: dshHome })
-    const bash = ctx.tools.schemas().find(tool => tool.name === 'bash')
-    expect(Object.keys((bash!.parameters as { properties: Record<string, unknown> }).properties))
-      .not.toContain('run_in_background')
-
-    const id = ctx.tasks.start({
-      kind: 'bash',
-      label: 'config forwarding probe',
-      run: () => ({ cancel: () => {}, done: Promise.resolve({ status: 'completed' }) }),
-    })
-    const wait = vi.spyOn(ctx.tasks, 'wait')
-    await ctx.tools.execute({
-      signal: testToolSignal,
-      callId: CallId('cli-demo-task-config'),
-      name: 'task_output',
-      arguments: { task_id: id, wait: true },
-    })
-    expect(wait).toHaveBeenCalledWith(id, 7, undefined, testToolSignal)
-  })
-
-  it('accepts false to keep task services without model-facing task controls', async () => {
-    const ctx = await mount({
-      provider: 'mock',
-      model: 'mock',
-      skills: { enabled: false },
-      toolTasks: false,
-      workspaceContext: false,
-    })
-
-    expect(ctx.get('tasks')).toBeDefined()
-    expect(ctx.get('tools')?.get('task_output')).toBeUndefined()
-    expect(ctx.get('tools')?.get('task_list')).toBeUndefined()
-    expect(ctx.get('tools')?.get('task_kill')).toBeUndefined()
-  })
-
-  it('exposes the Loader-safe namespace plugin shape and schema', () => {
-    expect(cliDemo.name).toBe('cli-demo')
-    expect(cliDemo.Config).toBeDefined()
-    expect('default' in cliDemo).toBe(false)
-    const loader = Object.create(Loader.prototype) as Loader
-    const unwrapped = loader.unwrapExports(cliDemo) as Record<string, unknown>
-    expect(unwrapped).toBe(cliDemo)
-    expect(unwrapped.name).toBe('cli-demo')
-    expect(typeof unwrapped.apply).toBe('function')
-  })
-})
--- a/packages/examples/cli-demo/tests/cli.spec.ts
+++ b/packages/examples/cli-demo/tests/cli.spec.ts
@@ -1,614 +0,0 @@
-import { readdir, mkdtemp } from 'node:fs/promises'
-import { tmpdir } from 'node:os'
-import { join, resolve } from 'node:path'
-import { Context } from 'cordis'
-import type { Agent } from '@deepseek-ai/dsh-agent'
-import { createUserMessage,
-  CallId,
-  LlmAdapter,
-  resolveRetryPolicy,
-  type GenerateOptions,
-  type ResolvedRetryPolicy,
-  type StreamChunk,
-  type TokenUsage,
-} from '@deepseek-ai/dsh-llm'
-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,
-  parseCliArgs,
-  runOneShot,
-  type CliResult,
-} from '../src/cli.ts'
-
-type ScriptEntry = readonly StreamChunk[] | 'hang'
-
-class ScriptedAdapter extends LlmAdapter {
-  readonly requests: GenerateOptions[] = []
-  private cursor = 0
-  private readonly retryPolicy = resolveRetryPolicy({
-    mode: 'normal',
-    backoff: { initialDelayMs: 1, maxDelayMs: 1, jitterRatio: 0 },
-  }, 'cli test provider retryPolicy')
-
-  constructor(private readonly script: readonly ScriptEntry[]) {
-    super()
-  }
-
-  override providerRetryPolicy(_provider: string): ResolvedRetryPolicy {
-    return this.retryPolicy
-  }
-
-  async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
-    this.requests.push(options)
-    const entry = this.script[this.cursor++]
-    if (entry === undefined) throw new Error('script exhausted')
-    if (entry === 'hang') {
-      yield { type: 'block-start', index: 0, blockType: 'text' }
-      yield { type: 'text-delta', index: 0, text: 'partial' }
-      await new Promise<void>((_resolve, reject) => {
-        if (options.signal?.aborted === true) {
-          reject(new Error('aborted'))
-          return
-        }
-        options.signal?.addEventListener('abort', () => { reject(new Error('aborted')) }, { once: true })
-      })
-      return
-    }
-    for (const chunk of entry) yield chunk
-  }
-}
-
-function textResponse(text: string, usage?: TokenUsage, finish: 'stop' | 'max-tokens' = 'stop'): StreamChunk[] {
-  return [
-    { type: 'block-start', index: 0, blockType: 'text' },
-    { type: 'text-delta', index: 0, text },
-    { type: 'block-end', index: 0, block: { type: 'text', text } },
-    ...usage === undefined ? [] : [{ type: 'usage', usage } as const],
-    { type: 'finish', reason: { kind: finish } },
-  ]
-}
-
-function toolResponse(usage: TokenUsage): StreamChunk[] {
-  const id = CallId('cli-call')
-  const args = JSON.stringify({ text: 'round trip' })
-  return [
-    { type: 'block-start', index: 0, blockType: 'text' },
-    { type: 'text-delta', index: 0, text: 'working' },
-    { type: 'block-end', index: 0, block: { type: 'text', text: 'working' } },
-    { type: 'block-start', index: 1, blockType: 'tool-call' },
-    { type: 'tool-call-delta', index: 1, id, name: 'echo', argumentsDelta: args },
-    { type: 'block-end', index: 1, block: { type: 'tool-call', id, name: 'echo', arguments: args } },
-    { type: 'usage', usage },
-    { type: 'finish', reason: { kind: 'tool-calls' } },
-  ]
-}
-
-function failedResponse(usage: TokenUsage): StreamChunk[] {
-  return [
-    { type: 'block-start', index: 0, blockType: 'text' },
-    { type: 'text-delta', index: 0, text: 'discarded' },
-    { type: 'usage', usage },
-    { type: 'finish', reason: { kind: 'error', failure: { message: 'temporary', code: 'SERVER' } } },
-  ]
-}
-
-function reasoningResponse(text: string): StreamChunk[] {
-  return [
-    { type: 'block-start', index: 0, blockType: 'reasoning' },
-    { type: 'reasoning-delta', index: 0, text },
-    { type: 'block-end', index: 0, block: { type: 'reasoning', text } },
-    { type: 'finish', reason: { kind: 'stop' } },
-  ]
-}
-
-interface Harness {
-  readonly ctx: Context
-  readonly agent: Agent
-  readonly persistenceRoot: string
-}
-
-const liveContexts: Context[] = []
-
-async function harness(script: readonly ScriptEntry[]): Promise<Harness> {
-  const root = await mkdtemp(join(tmpdir(), 'dsh-cli-runner-'))
-  const ctx = new Context()
-  liveContexts.push(ctx)
-  await ctx.plugin(cliDemo, {
-    provider: 'mock',
-    model: 'mock',
-    persistenceRoot: root,
-    skills: { enabled: false },
-    workspaceContext: false,
-  })
-  await new Promise(resolve => setTimeout(resolve, 80))
-  ctx.llm.registerAdapter(['mock'], new ScriptedAdapter(script))
-  ctx.tools.register({
-    name: 'echo',
-    description: 'Echo text.',
-    parameters: { text: { type: 'string', required: true } },
-    output: {
-      schema: { type: 'string' },
-      render: (_args, value) => [{ type: 'text', text: value as string }],
-    },
-    execute: async args => `ECHO: ${(args as { text: string }).text}`,
-  })
-  const [agent] = ctx.agents.roots()
-  if (agent === undefined) throw new Error('test main agent missing')
-  return { ctx, agent, persistenceRoot: root }
-}
-
-async function invoke(
-  ctx: Context,
-  args: readonly string[],
-  options: { signal?: AbortSignal; failStdout?: boolean; failDispose?: boolean } = {},
-): Promise<{ code: number; stdout: string; stderr: string }> {
-  let stdout = ''
-  let stderr = ''
-  const code = await executeCli(args, {
-    cwd: '/tmp/cli-cwd',
-    ...options.signal === undefined ? {} : { signal: options.signal },
-    boot: async () => ctx,
-    loadEnv: () => {},
-    writeStdout: (chunk) => {
-      if (options.failStdout === true) throw new Error('stdout closed')
-      stdout += chunk
-    },
-    writeStderr: (chunk) => { stderr += chunk },
-    ...options.failDispose === true
-      ? { dispose: async (target: Context) => {
-        await target.fiber.dispose()
-        throw new Error('dispose exploded')
-      } }
-      : {},
-  })
-  return { code, stdout, stderr }
-}
-
-afterEach(async () => {
-  await Promise.all(liveContexts.splice(0).map(ctx => ctx.fiber.dispose()))
-})
-
-describe('parseCliArgs', () => {
-  it('parses defaults, explicit options, spaces, and an option-like task after --', () => {
-    expect(parseCliArgs(['task with spaces'])).toEqual({
-      kind: 'run', configPath: './cordis.yml', outputFormat: 'text', task: 'task with spaces',
-    })
-    expect(parseCliArgs(['--config', 'custom.yml', '--output-format', 'stream-json', 'do it'])).toEqual({
-      kind: 'run', configPath: 'custom.yml', outputFormat: 'stream-json', task: 'do it',
-    })
-    expect(parseCliArgs(['--', '-task'])).toMatchObject({ task: '-task' })
-    expect(parseCliArgs(['-p', 'flag task'])).toMatchObject({ task: 'flag task' })
-    expect(parseCliArgs(['--prompt', 'long-flag task'])).toMatchObject({ task: 'long-flag task' })
-    expect(parseCliArgs(['--help', 'ignored'])).toEqual({ kind: 'help' })
-  })
-
-  it('rejects missing, blank, extra, invalid-format, and unsupported flags', () => {
-    expect(() => parseCliArgs([])).toThrow('received 0')
-    expect(() => parseCliArgs(['   '])).toThrow('must not be blank')
-    expect(() => parseCliArgs(['-p', '   '])).toThrow('must not be blank')
-    expect(() => parseCliArgs(['one', 'two'])).toThrow('received 2')
-    expect(() => parseCliArgs(['-p', 'task', 'positional'])).toThrow('mutually exclusive')
-    expect(() => parseCliArgs(['--output-format', 'xml', 'task'])).toThrow('unsupported output format')
-    expect(() => parseCliArgs(['-x', 'task'])).toThrow('Unknown option')
-  })
-})
-
-describe('runOneShot and executeCli', () => {
-  it('prints help and argument diagnostics without booting or contaminating stdout', async () => {
-    let booted = false
-    let stdout = ''
-    let stderr = ''
-    const runtime = {
-      boot: async (): Promise<Context> => { booted = true; throw new Error('unexpected') },
-      writeStdout: (chunk: string): void => { stdout += chunk },
-      writeStderr: (chunk: string): void => { stderr += chunk },
-    }
-    expect(await executeCli(['--help'], runtime)).toBe(0)
-    expect(stdout).toContain('Usage: dsh-cli-demo')
-    stdout = ''
-    expect(await executeCli([], runtime)).toBe(1)
-    expect(stdout).toBe('')
-    expect(stderr).toContain('received 0')
-    expect(booted).toBe(false)
-  })
-
-  it('leaves stdout empty for environment and boot failures and resolves the default config', async () => {
-    let bootPath = ''
-    let stderr = ''
-    const code = await executeCli(['task'], {
-      cwd: '/tmp/cli-work',
-      loadEnv: (_name, _dir, warn) => { warn('env warning\n') },
-      boot: async (_name, path) => { bootPath = path; throw 'boot exploded' },
-      writeStdout: () => { throw new Error('stdout must stay empty') },
-      writeStderr: (chunk) => { stderr += chunk },
-    })
-    expect(code).toBe(1)
-    expect(bootPath).toBe(resolve('/tmp/cli-work/cordis.yml'))
-    expect(stderr).toContain('env warning')
-    expect(stderr).toContain('boot exploded')
-  })
-
-  it('contains a thrown value whose inspection and coercion both fail', async () => {
-    const hostile = new Proxy({}, {
-      getPrototypeOf: () => { throw new Error('prototype trap escaped') },
-      get: (target, key, receiver) => {
-        if (key === Symbol.toPrimitive) throw new Error('coercion escaped')
-        return Reflect.get(target, key, receiver) as unknown
-      },
-    })
-    let stdout = ''
-    let stderr = ''
-    const code = await executeCli(['task'], {
-      boot: async () => { throw hostile },
-      loadEnv: () => {},
-      writeStdout: (chunk) => { stdout += chunk },
-      writeStderr: (chunk) => { stderr += chunk },
-    })
-    expect(code).toBe(1)
-    expect(stdout).toBe('')
-    expect(stderr).toBe('dsh-cli-demo: [unrenderable thrown value]\n')
-  })
-
-  it('interrupts Loader boot and contains every late boot outcome', async () => {
-    const abort = new AbortController()
-    const lateContext = new Context()
-    liveContexts.push(lateContext)
-    const boot = Promise.withResolvers<Context>()
-    const disposed = Promise.withResolvers<undefined>()
-    let disposeCalls = 0
-    let stderr = ''
-    const running = executeCli(['task'], {
-      signal: abort.signal,
-      boot: () => boot.promise,
-      loadEnv: () => {},
-      writeStdout: () => {},
-      writeStderr: (chunk) => { stderr += chunk },
-      dispose: async (ctx) => {
-        disposeCalls += 1
-        await ctx.fiber.dispose()
-        disposed.resolve(undefined)
-      },
-    })
-    abort.abort('received SIGTERM')
-    await expect(running).resolves.toBe(1)
-    expect(stderr).toContain('received SIGTERM')
-    expect(disposeCalls).toBe(0)
-    boot.resolve(lateContext)
-    await disposed.promise
-    expect(disposeCalls).toBe(1)
-
-    const rejectedBoot = Promise.withResolvers<Context>()
-    const rejectedAbort = new AbortController()
-    const rejected = executeCli(['task'], {
-      signal: rejectedAbort.signal,
-      boot: () => rejectedBoot.promise,
-      loadEnv: () => {},
-      writeStdout: () => {},
-      writeStderr: () => {},
-    })
-    rejectedAbort.abort('stop rejected boot')
-    await expect(rejected).resolves.toBe(1)
-    rejectedBoot.reject(new Error('late boot rejection'))
-    await Promise.resolve()
-
-    let ordinaryBootStderr = ''
-    const ordinaryBootFailure = await executeCli(['task'], {
-      signal: new AbortController().signal,
-      boot: async () => { throw new Error('ordinary boot failure') },
-      loadEnv: () => {},
-      writeStdout: () => {},
-      writeStderr: (chunk) => { ordinaryBootStderr += chunk },
-    })
-    expect(ordinaryBootFailure).toBe(1)
-    expect(ordinaryBootStderr).toContain('ordinary boot failure')
-
-    const failedCleanupBoot = Promise.withResolvers<Context>()
-    const failedCleanupAbort = new AbortController()
-    const cleanupFailure = Promise.withResolvers<undefined>()
-    const failedCleanupContext = new Context()
-    liveContexts.push(failedCleanupContext)
-    const failedCleanup = executeCli(['task'], {
-      signal: failedCleanupAbort.signal,
-      boot: () => failedCleanupBoot.promise,
-      loadEnv: () => {},
-      writeStdout: () => {},
-      writeStderr: (chunk) => {
-        if (chunk.includes('dispose after interrupted boot failed: late cleanup')) cleanupFailure.resolve(undefined)
-      },
-      dispose: async (ctx) => {
-        await ctx.fiber.dispose()
-        throw new Error('late cleanup')
-      },
-    })
-    failedCleanupAbort.abort('stop failed cleanup boot')
-    await expect(failedCleanup).resolves.toBe(1)
-    failedCleanupBoot.resolve(failedCleanupContext)
-    await cleanupFailure.promise
-  })
-
-  it('renders text, flushes a persisted fresh session, and disposes the context', async () => {
-    const { ctx, agent, persistenceRoot } = await harness([textResponse('final answer')])
-    const output = await invoke(ctx, ['task'])
-    expect(output).toEqual({ code: 0, stdout: 'final answer\n', stderr: '' })
-    expect(agent.status).toBe('idle')
-    const files = await readdir(persistenceRoot, { recursive: true })
-    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 }
-    const { ctx } = await harness([toolResponse(first), textResponse('done', second)])
-    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', output: 'done' })
-    expect(result.usage).toEqual({
-      inputTokens: 17,
-      outputTokens: 8,
-      cacheReadTokens: 6,
-      cacheWriteTokens: 1,
-      reasoningTokens: 6,
-    })
-  })
-
-  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)])
-
-    const result = await runOneShot(ctx, { task: 'task' })
-
-    expect(result.usage).toEqual({
-      inputTokens: 7,
-      outputTokens: 5,
-      reasoningTokens: 4,
-    })
-  })
-
-  it('keeps the prior text when a later assistant message has no text blocks', async () => {
-    const { ctx } = await harness([
-      toolResponse({ inputTokens: 1, outputTokens: 1 }),
-      reasoningResponse('reasoning only'),
-    ])
-    const result = await runOneShot(ctx, { task: 'task' })
-    expect(result.output).toBe('working')
-  })
-
-  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 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 ({ agent: 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', ({ agent: 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 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('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({ 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 () => {
-    const { ctx, agent } = await harness(['hang'])
-    const abort = new AbortController()
-    let started!: () => void
-    const running = new Promise<void>((resolveStarted) => { started = resolveStarted })
-    ctx.on('session/event', (session, event) => {
-      if (session === agent.session && event.type === 'assistant/chunk') started()
-    })
-    const outcome = invoke(ctx, ['--output-format', 'json', 'task'], { signal: abort.signal })
-    await running
-    abort.abort('received SIGINT')
-    const output = await outcome
-    expect(output.stdout).toBe('')
-    expect(output.code).toBe(1)
-    expect(output.stderr).toContain('received SIGINT')
-    expect(agent.status).toBe('idle')
-  })
-
-  it('contains stream-writer failures, cancels, flushes, and returns the output error', async () => {
-    const { ctx, agent } = await harness(['hang'])
-    await expect(runOneShot(ctx, {
-      task: 'task',
-      onEvent: () => { throw new Error('stream sink failed') },
-    })).rejects.toThrow('stream sink failed')
-    expect(agent.status).toBe('idle')
-  })
-
-  it('handles cancellation before submission, a missing main agent, and final-output failure', async () => {
-    const early = await harness([textResponse('unused')])
-    const fakeSignal = {
-      aborted: true,
-      reason: undefined,
-    } 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 })
-    expect(preBoot).toMatchObject({ code: 1, stdout: '' })
-    expect(preBoot.stderr).toContain('before boot completed')
-
-    const empty = new Context()
-    liveContexts.push(empty)
-    await expect(runOneShot(empty, { task: 'task' })).rejects.toThrow('exactly one top-level agent')
-
-    const final = await harness([textResponse('answer')])
-    const output = await invoke(final.ctx, ['task'], { failStdout: true })
-    expect(output.code).toBe(1)
-    expect(output.stdout).toBe('')
-    expect(output.stderr).toContain('stdout closed')
-    expect(final.agent.status).toBe('idle')
-
-    const disposal = await harness([textResponse('answer')])
-    const disposalOutput = await invoke(disposal.ctx, ['task'], { failDispose: true })
-    expect(disposalOutput).toMatchObject({ code: 1, stdout: 'answer\n' })
-    expect(disposalOutput.stderr).toContain('dispose exploded')
-  })
-
-  it('reports disposal failure alongside an earlier run failure', async () => {
-    const ctx = new Context()
-    liveContexts.push(ctx)
-    const output = await invoke(ctx, ['task'], { failDispose: true })
-    expect(output).toEqual({
-      code: 1,
-      stdout: '',
-      stderr: 'dsh-cli-demo: config must create exactly one top-level agent, found 0\n'
-        + 'dsh-cli-demo: dispose failed: dispose exploded\n',
-    })
-  })
-
-  it('cancels startup work and queued work before the correlated turn begins', async () => {
-    const startup = await harness(['hang'])
-    let started!: () => void
-    const running = new Promise<void>((resolveStarted) => { started = resolveStarted })
-    startup.ctx.on('session/event', (session, event) => {
-      if (session === startup.agent.session && event.type === 'assistant/chunk') started()
-    })
-    startup.agent.followup(createUserMessage({ content: [{ type: 'text', text: 'first' }], source: { kind: 'user' } }))
-    await running
-    const startupAbort = new AbortController()
-    const waiting = runOneShot(startup.ctx, { task: 'second', signal: startupAbort.signal })
-    startupAbort.abort('cancel startup')
-    await expect(waiting).rejects.toThrow('cancel startup')
-    await startup.agent.whenIdle()
-
-    const queued = await harness([textResponse('unused')])
-    const queuedAbort = new AbortController()
-    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()
-  })
-})
--- a/packages/examples/cli-demo/tsconfig.json
+++ b/packages/examples/cli-demo/tsconfig.json
@@ -1,47 +0,0 @@
-{
-  "extends": "../../../tsconfig.base.json",
-  "compilerOptions": {
-    "composite": true,
-    "rootDir": "src",
-    "outDir": "lib/types"
-  },
-  "include": ["src/**/*.ts"],
-  "references": [
-    {
-      "path": "../../../vendor/schemastery"
-    },
-    {
-      "path": "../../../vendor/cordis"
-    },
-    {
-      "path": "../../llm/llm"
-    },
-    {
-      "path": "../../core/session"
-    },
-    {
-      "path": "../../core/agent"
-    },
-    {
-      "path": "../../core/system-prompt"
-    },
-    {
-      "path": "../../core/tools"
-    },
-    {
-      "path": "../agent-spine-demo"
-    },
-    {
-      "path": "../../session-persistence/session-checkpoint-policy"
-    },
-    {
-      "path": "../../session-persistence/session-persistence-jsonl"
-    },
-    {
-      "path": "../../ui/app-boot"
-    },
-    {
-      "path": "../../support/invariants"
-    }
-  ]
-}
--- a/packages/examples/cli-demo/tsdown.config.ts
+++ b/packages/examples/cli-demo/tsdown.config.ts
@@ -1,13 +0,0 @@
-import { defineConfig } from 'tsdown'
-
-/** Builds the plugin and executable entries from declarations emitted by `tsc -b`. */
-export default defineConfig({
-  entry: ['lib/types/index.js', 'lib/types/invariant.js', 'lib/types/bin.js'],
-  outDir: 'lib',
-  format: ['esm'],
-  platform: 'node',
-  target: 'es2024',
-  fixedExtension: false,
-  dts: false,
-  clean: false,
-})
--- a/packages/goal/goal/tests/goal.e2e.ts
+++ b/packages/goal/goal/tests/goal.e2e.ts
@@ -6,7 +6,7 @@ import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import { decodeGoalChange } from '@deepseek-ai/dsh-goal'
 import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'

-const binScript = fileURLToPath(new URL('../../../examples/cli-demo/src/bin.ts', import.meta.url))
+const binScript = fileURLToPath(new URL('../../../../examples/headless-agent/tests/fixtures/headless-driver.ts', import.meta.url))
 const configPath = fileURLToPath(new URL(
  '../../../../examples/headless-agent/tests/fixtures/goal-domain/cordis.yml',
  import.meta.url,
@@ -30,8 +30,9 @@ describe('goal domain through a real cordis.yml and headless process', () => {
      label: 'goal-domain',
      tempDirPrefix: 'goal-domain-e2e-',
      binScript,
+      libBinScript: binScript,
      configPath,
-      binArgs: ['--config', configPath, '--output-format', 'json', 'prove the persisted goal domain'],
+      binArgs: [configPath, 'prove the persisted goal domain'],
      tsconfigPath: repoTsconfig,
      inspect: async (cwd) => {
        const logs = await jsonlFiles(join(cwd, '.sessions'))
@@ -41,7 +42,7 @@ describe('goal domain through a real cordis.yml and headless process', () => {
      },
    })
    expect(stderr).toBe('')
-    const result = JSON.parse(stdout) as Record<string, unknown>
+    const result = JSON.parse(stdout.trimEnd().split('\n').at(-1) ?? '') as Record<string, unknown>
    expect(result).toMatchObject({
      type: 'result',
    })
--- a/packages/host/apiproxy/README.i18n.yaml
+++ b/packages/host/apiproxy/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/host/apiproxy/README.md
-README.md: 5506cbef7b778a870e1e28c3f9fdf1713f89d65f
-README.zh.md: de31f653944097e9b47a966f56c418dc9fa9b1b9
+README.md: a3c9f214690144ec0f39a8690e4fd346f5e315e2
+README.zh.md: aeaf1b29e5a71674c9feedb30b67f9ce11c47340
--- a/packages/host/apiproxy/README.md
+++ b/packages/host/apiproxy/README.md
@@ -52,7 +52,7 @@ The `settings.*`, `credentials.*`, and `llm.*` domains are the configuration-pag

 ## Carrier layer (`/client` + root)

-`AbstractApiClient` holds every protocol invariant — rpcId minting, envelope wrap/unwrap, zod parsing, SSE frame decoding, unary timeout, microtask-batched envelope observation (`subscribeEnvelopes`) — while platform subclasses supply only the `doFetch` transport aspect. `InProcessApiClient` over `toFetchHandler(api)` is the isomorphic point: the full wire serialization/validation path with no network, used by `dsh -p` headless.
+`AbstractApiClient` holds every protocol invariant — rpcId minting, envelope wrap/unwrap, zod parsing, SSE frame decoding, unary timeout, microtask-batched envelope observation (`subscribeEnvelopes`) — while platform subclasses supply only the `doFetch` transport aspect. `InProcessApiClient` over `toFetchHandler(api)` is the isomorphic point: the full wire serialization/validation path with no network, used by `dsh run` headless.

 ## Model Experience

--- a/packages/host/apiproxy/README.zh.md
+++ b/packages/host/apiproxy/README.zh.md
@@ -52,7 +52,7 @@ Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.cr

 ## 载体层（`/client` + 根路径）

-`AbstractApiClient` 持有全部协议不变量：签发 rpcId、包装／解包信封、Zod 解析、SSE 帧解码、一元请求超时，以及按微任务批处理的信封观测（`subscribeEnvelopes`）；平台子类只提供 `doFetch` 传输环节。`InProcessApiClient` 以 `toFetchHandler(api)` 为基础，是同构接点：它运行完整的协议序列化与校验路径而不经过网络，供 `dsh -p` headless 模式使用。
+`AbstractApiClient` 持有全部协议不变量：签发 rpcId、包装／解包信封、Zod 解析、SSE 帧解码、一元请求超时，以及按微任务批处理的信封观测（`subscribeEnvelopes`）；平台子类只提供 `doFetch` 传输环节。`InProcessApiClient` 以 `toFetchHandler(api)` 为基础，是同构接点：它运行完整的协议序列化与校验路径而不经过网络，供 `dsh run` headless 模式使用。

 ## 模型体验

--- a/packages/support/loader-smoke/README.i18n.yaml
+++ b/packages/support/loader-smoke/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/support/loader-smoke/README.md
-README.md: 73610ce50ebac4c6fc7bb9135f7b41b347c60685
-README.zh.md: 9254cd1592d4bf3f119d350f04165228db87b1cf
+README.md: e5a33beb95f4e5940364cf309c8ea5fea60686f1
+README.zh.md: 1f3c6235175b3cfdcefec111eac39b2361b0e05b
--- a/packages/support/loader-smoke/README.md
+++ b/packages/support/loader-smoke/README.md
@@ -6,15 +6,17 @@ Shared subprocess harness for tests that boot an app and `cordis.yml` through th

 `runLoaderSmoke` accepts bin and config paths, optional complete bin arguments, environment overrides, stdin, pre-run setup, and pre-cleanup inspection. It owns the isolated cwd, DSH homes, diagnostics, deadline, termination, EOF, and cleanup; it returns both streams after a zero exit and rejects with both streams on failure.

+`runFixtureTurn` drives one task through exactly one configured root agent, forwards canonical events after that task reaches the durable inbox, flushes the session, and returns the final assistant text plus accumulated usage. Example-local drivers retain configuration, rendering, and assertion ownership.
+
 This is support-tier test infrastructure, not product API.

 ## Model Experience

-None, as this test-only harness boots example processes and inspects their streams without changing an assembled model request.
+None, as the test harness submits only the consuming test's ordinary user task and delegates prompt and tool composition to the loaded tree.

 #### KV Cache effect

-None; this package neither assembles nor sends a provider request.
+None beyond the loaded tree; the helper neither changes the request prefix nor retains state across runs.

 ## Known Limitations and Deferred Work

--- a/packages/support/loader-smoke/README.zh.md
+++ b/packages/support/loader-smoke/README.zh.md
@@ -6,15 +6,17 @@

 `runLoaderSmoke` 接受可执行文件路径和配置路径、可选的完整可执行文件参数、环境变量覆盖、标准输入、运行前准备和清理前检查。它负责隔离工作目录、DSH 主目录、诊断、截止时间、终止、EOF 和清理；进程以零状态退出后返回两个流，失败时则返回拒绝并附带两个流。

+`runFixtureTurn` 通过恰好一个已配置的根 agent（智能体）驱动一项任务，在该任务进入持久收件箱后转发规范事件，刷写会话，并返回最终 assistant 文本和累计用量。示例本地 driver 继续负责配置、渲染和断言。
+
 这是支持层测试基础设施，而非产品 API。

 ## 模型体验

-无。该测试专用 harness 启动示例进程并检查它们的流，不会改变组装后的模型请求。
+无，因为测试 harness 仅提交调用方测试的普通用户任务，并将提示词和工具组装交由已加载的插件树负责。

 #### KV Cache 影响

-无；该包既不组装也不发送提供方请求。
+除已加载树本身的影响外，无其他影响；该 helper 既不更改请求前缀，也不跨运行保留状态。

 ## 已知限制与暂缓事项

--- a/packages/support/loader-smoke/package.json
+++ b/packages/support/loader-smoke/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@deepseek-ai/dsh-loader-smoke",
-  "description": "Shared subprocess harness for keyless real-Loader example smoke tests",
+  "description": "Shared subprocess and direct-agent harness for keyless real-Loader example smoke tests",
  "version": "0.0.1",
  "private": true,
  "type": "module",
@@ -29,11 +29,17 @@
    "tsx": "^4.22.4"
  },
  "peerDependencies": {
+    "@deepseek-ai/dsh-agent": "^0.0.1",
    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
    "cordis": "^4.0.0-rc.6"
  },
  "devDependencies": {
+    "@deepseek-ai/dsh-agent": "workspace:^",
    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
    "cordis": "^4.0.0-rc.6"
  }
 }
--- a/packages/support/loader-smoke/src/agent-turn.ts
+++ b/packages/support/loader-smoke/src/agent-turn.ts
@@ -0,0 +1,100 @@
+/**
+ * Test-only direct-agent turn driver shared by assembled Loader fixtures.
+ * @module @deepseek-ai/dsh-loader-smoke/agent-turn
+ */
+
+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 } from '@deepseek-ai/dsh-session'
+
+/** Result envelope consumed only by snapshot and composition tests. */
+export interface FixtureTurnResult {
+  readonly type: 'result'
+  readonly sessionId: string
+  readonly output: string
+  readonly usage?: TokenUsage
+}
+
+/** Options for one fixture turn against exactly one configured root agent. */
+export interface FixtureTurnOptions {
+  readonly task: string
+  readonly onEvent?: (sessionId: string, event: SessionEvent) => void
+}
+
+function addUsage(total: TokenUsage | undefined, step: TokenUsage): TokenUsage {
+  const next: TokenUsage = {
+    inputTokens: (total?.inputTokens ?? 0) + step.inputTokens,
+    outputTokens: (total?.outputTokens ?? 0) + step.outputTokens,
+  }
+  for (const key of ['cacheReadTokens', 'cacheWriteTokens', 'reasoningTokens'] as const) {
+    if (total?.[key] !== undefined || step[key] !== undefined) next[key] = (total?.[key] ?? 0) + (step[key] ?? 0)
+  }
+  return next
+}
+
+function assistantText(event: Extract<SessionEvent, { type: 'assistant/message' }>): string | undefined {
+  const blocks = event.data.message.content.filter(block => block.type === 'text')
+  return blocks.length === 0 ? undefined : blocks.map(block => block.text).join('')
+}
+
+function onlyRootAgent(ctx: Context): Agent {
+  const agents = ctx.get('agents')?.roots() ?? []
+  const [agent] = agents
+  if (agent === undefined || agents.length !== 1) {
+    throw new Error(`fixture turn requires exactly one top-level agent, found ${agents.length}`)
+  }
+  return agent
+}
+
+/**
+ * Drive one task from its durable inbox receipt through whole-agent idle.
+ * @param ctx - settled Loader context with exactly one configured root agent.
+ * @param options - task and optional canonical-event observer.
+ * @returns the final assistant text and accumulated model usage.
+ */
+export async function runFixtureTurn(ctx: Context, options: FixtureTurnOptions): Promise<FixtureTurnResult> {
+  const agent = onlyRootAgent(ctx)
+  await agent.whenIdle()
+
+  const message = createUserMessage({
+    content: [{ type: 'text', text: options.task }],
+    source: { kind: 'user' },
+  })
+  let received = false
+  let output = ''
+  const usageByStep = new Map<string, TokenUsage>()
+  const disposeListener = ctx.on('session/event', (session, event) => {
+    if (session !== agent.session) return
+    if (!received) {
+      if (event.type !== 'agent/inbox/spliced'
+        || !event.data.inserted.some(inserted => inserted.id === message.id)) return
+      received = true
+    }
+    options.onEvent?.(session.id, event)
+    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') {
+      output = assistantText(event) ?? output
+      if (event.data.usage !== undefined) {
+        usageByStep.set(`${event.data.turn}/${event.data.step}`, event.data.usage)
+      }
+    }
+  })
+
+  try {
+    agent.followup(message)
+    await agent.whenIdle()
+  } finally {
+    disposeListener()
+  }
+  await ctx.sessions.flush(agent.session)
+  const usage = [...usageByStep.values()].reduce<TokenUsage | undefined>(addUsage, undefined)
+  return {
+    type: 'result',
+    sessionId: agent.session.id,
+    output,
+    ...usage === undefined ? {} : { usage },
+  }
+}
--- a/packages/support/loader-smoke/src/index.ts
+++ b/packages/support/loader-smoke/src/index.ts
@@ -16,6 +16,12 @@ import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { execa } from 'execa'

+export {
+  runFixtureTurn,
+  type FixtureTurnOptions,
+  type FixtureTurnResult,
+} from './agent-turn.ts'
+
 const DEFAULT_PROCESS_TIMEOUT_MS = 30_000

 /** Vitest deadline that leaves room for the subprocess-owned 30-second diagnostic timeout. */
--- a/packages/support/loader-smoke/tests/agent-turn.spec.ts
+++ b/packages/support/loader-smoke/tests/agent-turn.spec.ts
@@ -0,0 +1,160 @@
+import type { Context } from 'cordis'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+import { describe, expect, it, vi } from 'vitest'
+import { runFixtureTurn } from '../src/agent-turn.ts'
+
+type Listener = (session: unknown, event: SessionEvent) => void
+
+const event = (value: object): SessionEvent => value as unknown as SessionEvent
+
+function turnHarness(): {
+  readonly ctx: Context
+  readonly session: { readonly id: string }
+  readonly foreignSession: object
+  readonly emit: (session: unknown, value: object) => void
+  readonly setFollowup: (callback: (message: { readonly id: unknown }) => void) => void
+  readonly whenIdle: ReturnType<typeof vi.fn>
+  readonly disposeListener: ReturnType<typeof vi.fn>
+  readonly flush: ReturnType<typeof vi.fn>
+} {
+  const session = { id: 'fixture-session' }
+  const foreignSession = {}
+  let listener: Listener | undefined
+  let followup = (_message: { readonly id: unknown }): void => {}
+  const whenIdle = vi.fn(async () => {})
+  const disposeListener = vi.fn()
+  const flush = vi.fn(async () => {})
+  const agent = {
+    session,
+    whenIdle,
+    followup: vi.fn((message: { readonly id: unknown }) => { followup(message) }),
+  }
+  const ctx = {
+    get: (name: string) => name === 'agents' ? { roots: () => [agent] } : undefined,
+    on: (_name: string, callback: Listener) => {
+      listener = callback
+      return disposeListener
+    },
+    sessions: { flush },
+  } as unknown as Context
+  return {
+    ctx,
+    session,
+    foreignSession,
+    emit: (target, value) => { listener?.(target, event(value)) },
+    setFollowup: (callback) => { followup = callback },
+    whenIdle,
+    disposeListener,
+    flush,
+  }
+}
+
+describe('runFixtureTurn', () => {
+  it.each([
+    ['no agent registry', undefined, 0],
+    ['multiple roots', { roots: () => [{}, {}] }, 2],
+  ])('rejects %s', async (_label, registry, count) => {
+    const ctx = { get: () => registry } as unknown as Context
+    await expect(runFixtureTurn(ctx, { task: 'ignored' }))
+      .rejects.toThrow(`fixture turn requires exactly one top-level agent, found ${count}`)
+  })
+
+  it('observes only the owned interval and returns its final text and deduplicated usage', async () => {
+    const harness = turnHarness()
+    const observed: SessionEvent[] = []
+    harness.setFollowup((message) => {
+      harness.emit(harness.foreignSession, {
+        type: 'assistant/message', seq: 0, time: 0, data: { message: { content: [] } },
+      })
+      harness.emit(harness.session, {
+        type: 'step/start', seq: 0, time: 0, data: { turn: 1, step: 1 },
+      })
+      harness.emit(harness.session, {
+        type: 'agent/inbox/spliced', seq: 1, time: 1, data: { inserted: [{ id: 'other' }] },
+      })
+      harness.emit(harness.session, {
+        type: 'agent/inbox/spliced', seq: 2, time: 2, data: { inserted: [message] },
+      })
+      harness.emit(harness.session, {
+        type: 'assistant/chunk', seq: 3, time: 3,
+        data: { turn: 1, step: 1, chunk: { type: 'text-delta', text: 'partial' } },
+      })
+      harness.emit(harness.session, {
+        type: 'assistant/chunk', seq: 4, time: 4,
+        data: {
+          turn: 1,
+          step: 1,
+          chunk: { type: 'usage', usage: { inputTokens: 2, outputTokens: 3, reasoningTokens: 1 } },
+        },
+      })
+      harness.emit(harness.session, {
+        type: 'assistant/message', seq: 5, time: 5,
+        data: {
+          turn: 1,
+          step: 1,
+          message: { content: [{ type: 'text', text: 'final answer' }] },
+          usage: { inputTokens: 4, outputTokens: 5, cacheReadTokens: 6 },
+        },
+      })
+      harness.emit(harness.session, {
+        type: 'assistant/chunk', seq: 6, time: 6,
+        data: {
+          turn: 1,
+          step: 2,
+          chunk: { type: 'usage', usage: { inputTokens: 1, outputTokens: 2, cacheWriteTokens: 7, reasoningTokens: 2 } },
+        },
+      })
+      harness.emit(harness.session, {
+        type: 'assistant/message', seq: 7, time: 7,
+        data: { turn: 1, step: 2, message: { content: [{ type: 'tool-call' }] } },
+      })
+      harness.emit(harness.foreignSession, {
+        type: 'assistant/message', seq: 8, time: 8, data: { message: { content: [] } },
+      })
+    })
+
+    await expect(runFixtureTurn(harness.ctx, {
+      task: 'prove the fixture',
+      onEvent: (_sessionId, current) => { observed.push(current) },
+    })).resolves.toEqual({
+      type: 'result',
+      sessionId: 'fixture-session',
+      output: 'final answer',
+      usage: {
+        inputTokens: 5,
+        outputTokens: 7,
+        cacheReadTokens: 6,
+        cacheWriteTokens: 7,
+        reasoningTokens: 2,
+      },
+    })
+    expect(observed.map(current => current.seq)).toEqual([2, 3, 4, 5, 6, 7])
+    expect(harness.whenIdle).toHaveBeenCalledTimes(2)
+    expect(harness.flush).toHaveBeenCalledWith(harness.session)
+    expect(harness.disposeListener).toHaveBeenCalledOnce()
+  })
+
+  it('omits usage when the interval records none', async () => {
+    const harness = turnHarness()
+    harness.setFollowup((message) => {
+      harness.emit(harness.session, {
+        type: 'agent/inbox/spliced', seq: 0, time: 0, data: { inserted: [message] },
+      })
+    })
+
+    await expect(runFixtureTurn(harness.ctx, { task: 'no model step' })).resolves.toEqual({
+      type: 'result',
+      sessionId: 'fixture-session',
+      output: '',
+    })
+  })
+
+  it('always removes its listener when the turn fails', async () => {
+    const harness = turnHarness()
+    harness.whenIdle.mockResolvedValueOnce(undefined).mockRejectedValueOnce(new Error('turn failed'))
+
+    await expect(runFixtureTurn(harness.ctx, { task: 'fail' })).rejects.toThrow('turn failed')
+    expect(harness.disposeListener).toHaveBeenCalledOnce()
+    expect(harness.flush).not.toHaveBeenCalled()
+  })
+})
--- a/packages/support/loader-smoke/tests/example-launch.spec.ts
+++ b/packages/support/loader-smoke/tests/example-launch.spec.ts
@@ -5,7 +5,7 @@ import {
  resolveExampleMode,
 } from '@deepseek-ai/dsh-loader-smoke'

-const SRC_BIN = '/repo/packages/examples/cli-demo/src/bin.ts'
+const SRC_BIN = '/repo/packages/examples/acp-demo/src/bin.ts'
 const TSCONFIG = '/repo/tsconfig.json'

 const originalMode = process.env[EXAMPLE_MODE_ENV]
@@ -65,7 +65,7 @@ describe('resolveExampleLaunch', () => {
      env: { DSH_HOME: '/tmp/home' },
    })
    expect(args).not.toContain('--import')
-    expect(args).toContain('/repo/packages/examples/cli-demo/lib/bin.js')
+    expect(args).toContain('/repo/packages/examples/acp-demo/lib/bin.js')
    expect(args.slice(-2)).toEqual(['--config', './cordis.yml'])
    expect(env.TSX_TSCONFIG_PATH).toBeUndefined()
    expect(env.DSH_HOME).toBe('/tmp/home')
@@ -100,6 +100,6 @@ describe('resolveExampleLaunch', () => {
  it('defaults the mode from the environment', () => {
    process.env[EXAMPLE_MODE_ENV] = 'lib'
    const { args } = resolveExampleLaunch({ srcBin: SRC_BIN })
-    expect(args).toContain('/repo/packages/examples/cli-demo/lib/bin.js')
+    expect(args).toContain('/repo/packages/examples/acp-demo/lib/bin.js')
  })
 })
--- a/packages/support/loader-smoke/tsconfig.json
+++ b/packages/support/loader-smoke/tsconfig.json
@@ -8,6 +8,15 @@
    "src"
  ],
  "references": [
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../core/session"
+    },
    {
      "path": "../../support/invariants"
    }
--- a/packages/ui/app-boot/README.i18n.yaml
+++ b/packages/ui/app-boot/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/ui/app-boot/README.md
-README.md: 359f05a83b41db6db5ede40db7317a0fb15de43b
-README.zh.md: a916236e30b50cc884d9d5876f27fcb1aa6f0777
+README.md: c256b89288e3e384c1dd3e64629a06d7cfef31f6
+README.zh.md: 88d1c4ad0ced2f5a6440a1b64e34e738a842f938
--- a/packages/ui/app-boot/README.md
+++ b/packages/ui/app-boot/README.md
@@ -2,7 +2,7 @@

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

-Shared boot glue for the app bins ([`dsh`](../../../apps/cli/README.md), [`dsh-cli-demo`](../../examples/cli-demo/README.md), [`dsh-acp-demo`](../../examples/acp-demo/README.md)): each bin is a thin self-executing composition over these helpers, parameterized by its diagnostic prefix, so loader-failure behavior has one owner instead of drifting between published artifacts.
+Shared boot glue for the app bins ([`dsh`](../../../apps/cli/README.md) and [`dsh-acp-demo`](../../examples/acp-demo/README.md)): each bin is a thin self-executing composition over these helpers, parameterized by its diagnostic prefix, so loader-failure behavior has one owner instead of drifting between published artifacts.

 | Export | Role |
 |---|---|
--- a/packages/ui/app-boot/README.zh.md
+++ b/packages/ui/app-boot/README.zh.md
@@ -2,7 +2,7 @@

 [English](README.md) | 中文

-供 app bin（[`dsh`](../../../apps/cli/README.md)、[`dsh-cli-demo`](../../examples/cli-demo/README.md)、[`dsh-acp-demo`](../../examples/acp-demo/README.md)）共用的启动粘合层：每个 bin 都是在这些 helper 上构建的精简自执行组合，并以自身诊断前缀参数化。这样，Loader 故障行为只由一处负责，不会在已发布产物之间逐渐分化。
+供 app bin（[`dsh`](../../../apps/cli/README.md) 与 [`dsh-acp-demo`](../../examples/acp-demo/README.md)）共用的启动粘合层：每个 bin 都是在这些 helper 上构建的精简自执行组合，并以自身诊断前缀参数化。这样，Loader 故障行为只由一处负责，不会在已发布产物之间逐渐分化。

 | 导出 | 职责 |
 |---|---|
--- a/packages/ui/app-boot/src/index.ts
+++ b/packages/ui/app-boot/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Shared boot glue for the app bins (`dsh`, `dsh-cli-demo`, `dsh-acp-demo`): load the gitignored
+ * Shared boot glue for the app bins (`dsh`, `dsh-acp-demo`): load the gitignored
 * `.env`, install the fail-loud Loader guards, resolve the config path (snapshot-aware), load the
 * optional user patch layers from the Harness home (`~/.dsh`), expose its path resolver to
 * config expressions, and drive the Cordis Loader against a leaf `cordis.yml` until the tree settles.