Merge PR #340 fixes into codex/simplify-agent-identity-plumbing

# Conflicts: # docs/rfc/implemented/architecture/2026-07-15-agent-initiator-scope.i18n.yaml # docs/rfc/implemented/architecture/2026-07-15-agent-initiator-scope.md # docs/rfc/implemented/architecture/2026-07-15-agent-initiator-scope.zh.md
2026-08-15 21:04:50 +00:00 · 2026-07-19 15:27:02 +08:00
parent 7a9c2ef473 49bd666a26
commit 7a7cea1a05
71 changed files with 2666 additions and 88 deletions
--- a/.agents/skills/dsh-pre-push-checks/SKILL.md
+++ b/.agents/skills/dsh-pre-push-checks/SKILL.md
@@ -54,7 +54,7 @@ pnpm run test:snapshot
 Run built-bin smoke tests after `pnpm run build` when app packages, app boot, package runtime imports, bin entries, loader behavior, or published artifact paths change.

 ```sh
-pnpm exec vitest run --config vitest.e2e.config.ts packages/examples/stdio-demo/tests/built-bin.e2e.ts packages/examples/acp-demo/tests/built-bin.e2e.ts
+pnpm exec vitest run --config vitest.e2e.config.ts packages/examples/stdio-demo/tests/built-bin.e2e.ts packages/examples/cli-demo/tests/built-bin.e2e.ts packages/examples/acp-demo/tests/built-bin.e2e.ts
 ```

 Run real e2e when behavior depends on a real model/API, tool-use loop, ACP integration, prompt injection, or end-to-end agent UX. If `.env` is available, use it; do not print secrets.
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -28,7 +28,7 @@ packages/    @deepseek-ai/dsh-<pkg> workspaces at packages/<group>/<pkg>/
  hooks/       Claude Code / Codex hook bridges + shared wire-protocol library
  session-persistence/  persistence seam + JSONL/SQLite backends
  ui/          ACP/stdio/TUI/JSON-RPC bridges; boot, approval, interaction plugins
-  examples/    demo bundles (agent-spine + stdio/ACP/JSON-RPC bins) leaves load
+  examples/    demo bundles (agent-spine + stdio/CLI/ACP/JSON-RPC bins) leaves load
  support/     dev/test infrastructure packages
  util/        zero-dependency utilities
 python/      Python SDK and bundled runtime (see python/README.md)
@@ -47,7 +47,7 @@ pnpm install            # pnpm workspaces, node ^22.19 || >=24
 pnpm run test           # vitest unit tests
 pnpm run test:coverage  # THE gating test run: per-file 100% coverage on packages/*/*/src
 pnpm run test:e2e       # real-API tests; self-skip without DEEPSEEK_API_KEY
-pnpm run test:snapshot  # keyless ACP replay vs goldens; filter: -t <name>
+pnpm run test:snapshot  # keyless ACP/headless/TUI replay vs goldens; filter: -t <name>
 pnpm run test:snapshot:record  # re-record goldens (needs key)
 pnpm run typecheck
 pnpm run lint
@@ -58,6 +58,7 @@ pnpm run doc-sync       # all documentation gates; see the doc-sync script in pa
 pnpm run website:build  # VitePress build (doubles as the site's dead-link check)
 pnpm run demo:echo      # mock-model REPL, no key needed
 pnpm run demo:repl      # real REPL coding agent (needs DEEPSEEK_API_KEY)
+pnpm run demo:headless -- "task" # one-shot agent (needs DEEPSEEK_API_KEY)
 pnpm run demo:tui       # full-screen TUI coding agent (needs DEEPSEEK_API_KEY)
 pnpm run demo:cordis    # self-referential demo: the agent modifies its own runtime (needs key)
 pnpm run demo:acp       # ACP server agent (needs DEEPSEEK_API_KEY)
@@ -88,7 +89,7 @@ printf '%s\n' "$out" | grep -q '\[tool call\] echo({"text":"ci smoke"})'
 printf '%s\n' "$out" | grep -q '\[tool result\] ECHO: CI SMOKE'
 test -n "$(find .sessions -path '.sessions/cwd-*/main-session-*.jsonl' -type f -print -quit)"
 rm -rf .sessions
-pnpm exec vitest run --config vitest.e2e.config.ts packages/examples/stdio-demo/tests/built-bin.e2e.ts packages/examples/acp-demo/tests/built-bin.e2e.ts packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts packages/workflow/workflow-workerthread/tests/built-worker.e2e.ts packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts
+pnpm exec vitest run --config vitest.e2e.config.ts packages/examples/stdio-demo/tests/built-bin.e2e.ts packages/examples/cli-demo/tests/built-bin.e2e.ts packages/examples/acp-demo/tests/built-bin.e2e.ts packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts packages/workflow/workflow-workerthread/tests/built-worker.e2e.ts packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts
 ```

 `test:coverage`, not `test`, is the gate ([why](docs/testing.md)); report only commands actually run.
--- a/README.i18n.yaml
+++ b/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
-README.md: aaa129272ee9346cebe2d59774d742fbe21af80a
-README.zh.md: 42f2ed9b57bf008210042083977b7adbb7f1ab0e
+README.md: ef9a3a8832d1eaa35ec5f0fed1780ab27e8ff37c
+README.zh.md: a30d6db4b04f23559c36a7aba80b4feb2962a1c6
--- a/README.md
+++ b/README.md
@@ -14,6 +14,7 @@ pnpm run test          # vitest
 pnpm run demo:echo     # keyless mock-model REPL
 pnpm run demo:repl     # readline coding agent (needs DEEPSEEK_API_KEY)
 pnpm run demo:tui      # full-screen TUI coding agent (needs DEEPSEEK_API_KEY)
+pnpm run demo:headless -- "task" # one-shot coding agent (needs DEEPSEEK_API_KEY)
 pnpm run demo:cordis   # self-referential agent demo (needs DEEPSEEK_API_KEY)
 pnpm run demo:acp      # ACP server agent demo (needs DEEPSEEK_API_KEY)
 ```
--- a/README.zh.md
+++ b/README.zh.md
@@ -14,6 +14,7 @@ pnpm run test          # vitest
 pnpm run demo:echo     # keyless mock-model REPL
 pnpm run demo:repl     # readline coding agent (needs DEEPSEEK_API_KEY)
 pnpm run demo:tui      # full-screen TUI coding agent (needs DEEPSEEK_API_KEY)
+pnpm run demo:headless -- "task" # one-shot coding agent (needs DEEPSEEK_API_KEY)
 pnpm run demo:cordis   # self-referential agent demo (needs DEEPSEEK_API_KEY)
 pnpm run demo:acp      # ACP server agent demo (needs DEEPSEEK_API_KEY)
 ```
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -150,7 +150,7 @@ Some seams bend the template deliberately: LLM combines interface and consumer b

 ### Bundles And Apps

-`dsh-agent-spine-demo` bundles the default spine ([README](../packages/examples/agent-spine-demo/README.md)). `dsh-stdio-demo` adds a terminal front door that selects `dsh-tui` for interactive terminals and line-oriented `dsh-stdio` for pipes; `dsh-acp-demo` adds stdout-pure ACP over JSON-RPC ([ui/](../packages/ui/README.md)). `dsh-jsonrpc-agent` boots external `cordis.yml`; the Python SDK supplies its default only without an explicit config channel and drives `dsh-jsonrpc` over line-delimited JSON-RPC ([Python SDK](../python/README.md)). Deployments remain thin leaves with swappable backends and optional product tools ([examples/](../examples/AGENTS.md), [runnable wirings](cookbook/extension-cookbook.md#runnable-wirings), [graph atlas](graph-atlas.md)).
+`dsh-agent-spine-demo` bundles the default spine ([README](../packages/examples/agent-spine-demo/README.md)). `dsh-stdio-demo` adds a terminal front door that selects `dsh-tui` for interactive terminals and line-oriented `dsh-stdio` for pipes; `dsh-cli-demo` runs one persisted headless turn with format-pure stdout; and `dsh-acp-demo` adds stdout-pure ACP over JSON-RPC ([ui/](../packages/ui/README.md)). `dsh-jsonrpc-agent` boots external `cordis.yml`; the Python SDK supplies its default only without an explicit config channel and drives `dsh-jsonrpc` over line-delimited JSON-RPC ([Python SDK](../python/README.md)). Deployments remain thin leaves with swappable backends and optional product tools ([examples/](../examples/AGENTS.md), [runnable wirings](cookbook/extension-cookbook.md#runnable-wirings), [graph atlas](graph-atlas.md)).

 ### Where New Behavior Goes

--- a/docs/capability-seams.md
+++ b/docs/capability-seams.md
@@ -19,6 +19,7 @@ flowchart LR
  pkg_session["session"]
  svc_sessions["ctx.sessions<br/>In-memory session store"]
  pkg_agent["agent"]
+  pkg_cli_demo["cli-demo"]
  pkg_session_persistence["session-persistence"]
  pkg_session_query["session-query"]
  pkg_subagent_inprocess["subagent-inprocess"]
@@ -145,6 +146,7 @@ flowchart LR
  svc_agentLoop --> pkg_agent_spine_demo
  svc_agents --> pkg_acp
  svc_agents --> pkg_agent_loop
+  svc_agents --> pkg_cli_demo
  svc_agents --> pkg_invariants
  svc_agents --> pkg_stdio_demo
  svc_agents --> pkg_subagent_inprocess
@@ -168,6 +170,7 @@ flowchart LR
  svc_sessionPersistence --> pkg_tool_bash
  svc_sessions --> pkg_agent
  svc_sessions --> pkg_agent_loop
+  svc_sessions --> pkg_cli_demo
  svc_sessions --> pkg_invariants
  svc_sessions --> pkg_session_persistence
  svc_sessions --> pkg_session_query
@@ -205,14 +208,14 @@ flowchart LR
 | --- | --- | --- | --- | --- | --- | --- |
 | `ctx.llm` | `seam` | [`llm`](../packages/llm/llm) | [`llm-deepseek`](../packages/llm/llm-deepseek), [`llm-pi-ai`](../packages/llm/llm-pi-ai), [`llm-replay`](../packages/support/llm-replay) | [`agent-loop`](../packages/core/agent-loop), [`compact-basic`](../packages/compact/compact-basic) | - | Adapters register provider implementations; the loop and compaction call the provider-neutral stream service. |
 | `ctx.tokenMeter` | `core` | [`token-meter`](../packages/llm/token-meter) | - | [`compact-basic`](../packages/compact/compact-basic) | - | Owns isolated per-session replay folds; pressure consumers share immutable revisioned measurements. |
-| `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`invariants`](../packages/support/invariants) | - | Owns append-only Session instances and emits the durable session event feed. |
+| `ctx.sessions` | `core` | [`session`](../packages/core/session) | - | [`agent-loop`](../packages/core/agent-loop), [`agent`](../packages/core/agent), [`cli-demo`](../packages/examples/cli-demo), [`session-persistence`](../packages/session-persistence/session-persistence), [`session-query`](../packages/session-query/session-query), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`invariants`](../packages/support/invariants) | - | Owns append-only Session instances and emits the durable session event feed. |
 | `ctx.sessionPersistence` | `seam` | [`session-persistence`](../packages/session-persistence/session-persistence) | [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`session-persistence-sqlite`](../packages/session-persistence/session-persistence-sqlite) | [`agent-loop`](../packages/core/agent-loop), [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex), [`acp`](../packages/ui/acp), [`session-query`](../packages/session-query/session-query) | - | Backends persist the same SessionEvent vocabulary; apps choose a backend at composition time. |
 | `ctx.sessionQuery` | `seam` | [`session-query`](../packages/session-query/session-query) | - | - | - | Resolves live and optional persisted logs into one logical corpus for exact reads and relationship traces. |
 | `ctx.systemPrompt` | `core` | [`system-prompt`](../packages/core/system-prompt) | - | [`agent-loop`](../packages/core/agent-loop), [`tools`](../packages/core/tools), [`tool-fs`](../packages/fs/tool-fs), [`tool-web`](../packages/web/tool-web) | - | Collects prompt sections and model-facing tool schemas for each step. |
 | `ctx.tools` | `core` | [`tools`](../packages/core/tools) | - | [`agent-loop`](../packages/core/agent-loop), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tool-bash`](../packages/bash/tool-bash), [`tool-cordis`](../packages/cordis/tool-cordis), [`tool-fs`](../packages/fs/tool-fs), [`tool-skill`](../packages/skill/tool-skill), [`tool-subagent`](../packages/subagent/tool-subagent), [`tool-todo`](../packages/todo/tool-todo), [`tool-web`](../packages/web/tool-web), [`acp`](../packages/ui/acp) | - | Registers capabilities, owns Code Mode transport, and routes calls through pre-policy, monotonic guards, around dispatch, post-policy, and final-result observation. |
 | `ctx.userInteraction` | `seam` | [`user-interaction`](../packages/ui/user-interaction) | [`stdio-demo`](../packages/examples/stdio-demo), [`acp`](../packages/ui/acp) | [`tool-ask-user`](../packages/ui/tool-ask-user), [`stdio-demo`](../packages/examples/stdio-demo), [`acp`](../packages/ui/acp) | - | UI front doors provide the active human-answer provider; tool-ask-user pauses a tool call on the provider-neutral ask() promise. |
 | `ctx.skills` | `seam` | [`skill`](../packages/skill/skill) | [`skill-local`](../packages/skill/skill-local) | [`tool-skill`](../packages/skill/tool-skill) | - | Merges provider skill catalogs; tool-skill renders the session-prefix catalog and loads complete skill bodies. |
-| `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/ui/acp), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`stdio-demo`](../packages/examples/stdio-demo), [`invariants`](../packages/support/invariants) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. |
+| `ctx.agents` | `core` | [`agent`](../packages/core/agent) | - | [`agent-loop`](../packages/core/agent-loop), [`acp`](../packages/ui/acp), [`cli-demo`](../packages/examples/cli-demo), [`subagent-inprocess`](../packages/subagent/subagent-inprocess), [`stdio-demo`](../packages/examples/stdio-demo), [`invariants`](../packages/support/invariants) | - | Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation. |
 | `ctx.agentLoop` | `bundle` | [`agent-loop`](../packages/core/agent-loop) | - | [`agent-spine-demo`](../packages/examples/agent-spine-demo) | - | The one concrete loop plugin; extension packages depend on dsh-agent events and services, not on this package. |
 | `ctx.bash` | `seam` | [`bash`](../packages/bash/bash) | [`bash-local`](../packages/bash/bash-local), [`bash-sandbox`](../packages/bash/bash-sandbox) | [`tool-bash`](../packages/bash/tool-bash), [`hooks-claude`](../packages/hooks/hooks-claude), [`hooks-codex`](../packages/hooks/hooks-codex) | - | The model-facing bash tools and hook bridges consume this seam; sandboxed or remote executors replace bash-local without touching them. |
 | `ctx.bashEnv` | `core` | [`tool-bash`](../packages/bash/tool-bash) | - | - | - | Plugins declare effect-scoped DSH_* facts; tool-bash collects one trusted snapshot per execution and the executor rebuilds the namespace. |
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -206,6 +206,42 @@ Depends on: [`LocalConfig`](#deepseek-aidsh-bash-local) · [`SandboxMode`](core-

 Source: [`packages/bash/bash-sandbox/src/index.ts:27`](../packages/bash/bash-sandbox/src/index.ts)

+## `@deepseek-ai/dsh-cli-demo`
+
+```ts config-catalog
+/** 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
+  /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
+  persistenceRoot?: string
+  /** 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']
+}
+```
+
+Depends on: [`agentCore`](../packages/examples/agent-spine-demo/src/index.ts) · [`ToolsConfig`](#deepseek-aidsh-tools)
+
+Source: [`packages/examples/cli-demo/src/index.ts:22`](../packages/examples/cli-demo/src/index.ts)
+
 ## `@deepseek-ai/dsh-code-runtime-worker`

 ```ts config-catalog
--- a/docs/cookbook/extension-cookbook.i18n.yaml
+++ b/docs/cookbook/extension-cookbook.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
-extension-cookbook.md: d271ceee208e276d97188a6ebbe91e1e90a4219f
-extension-cookbook.zh.md: bdd2c5f0861aa55c6f0104764a34784e5e834d10
+extension-cookbook.md: 75cea09ad9dd1db36acdce7998cd7f04e1b97076
+extension-cookbook.zh.md: 6db3947b5414fb81f963aae79f908292df2f3440
--- a/docs/cookbook/extension-cookbook.md
+++ b/docs/cookbook/extension-cookbook.md
@@ -87,7 +87,7 @@ export function apply(ctx: Context) {

 ## Runnable wirings

-Five runnable leaves load their plugin trees from `cordis.yml`: [`examples/echo-agent`](../../examples/echo-agent) (mock model + echo tool, `pnpm run demo:echo`), [`examples/repl-agent`](../../examples/repl-agent) (DeepSeek V4 + coding tools through a line-oriented readline REPL, `pnpm run demo:repl`), [`examples/tui-agent`](../../examples/tui-agent) (the same coding composition through full-screen pi-tui, `pnpm run demo:tui`), [`examples/cordis-agent`](../../examples/cordis-agent) (self-inspection and dynamic plugin mounting, `pnpm run demo:cordis`), and [`examples/acp-agent`](../../examples/acp-agent) (an ACP server over JSON-RPC stdio, `pnpm run demo:acp`). The terminal leaves load [`@deepseek-ai/dsh-stdio-demo`](../../packages/examples/stdio-demo), the ACP leaf loads [`@deepseek-ai/dsh-acp-demo`](../../packages/examples/acp-demo), and both app packages share the spine through [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo).
+Six runnable leaves load their plugin trees from `cordis.yml`: [`examples/echo-agent`](../../examples/echo-agent) (mock model + echo tool, `pnpm run demo:echo`), [`examples/repl-agent`](../../examples/repl-agent) (DeepSeek V4 + coding tools through a line-oriented readline REPL, `pnpm run demo:repl`), [`examples/tui-agent`](../../examples/tui-agent) (the same coding composition through full-screen pi-tui, `pnpm run demo:tui`), [`examples/headless-agent`](../../examples/headless-agent) (the same capability class behind a one-shot task and DSH-native output, `pnpm run demo:headless -- "task"`), [`examples/cordis-agent`](../../examples/cordis-agent) (self-inspection and dynamic plugin mounting, `pnpm run demo:cordis`), and [`examples/acp-agent`](../../examples/acp-agent) (an ACP server over JSON-RPC stdio, `pnpm run demo:acp`). The terminal leaves load [`@deepseek-ai/dsh-stdio-demo`](../../packages/examples/stdio-demo), the headless leaf loads [`@deepseek-ai/dsh-cli-demo`](../../packages/examples/cli-demo), the ACP leaf loads [`@deepseek-ai/dsh-acp-demo`](../../packages/examples/acp-demo), and all three app packages share [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo).

 ## The feature → mechanism map

--- a/docs/cookbook/extension-cookbook.zh.md
+++ b/docs/cookbook/extension-cookbook.zh.md
@@ -87,7 +87,7 @@ export function apply(ctx: Context) {

 ## 可运行的组装示例

-五个可运行叶子从 `cordis.yml` 加载各自的插件树：[`examples/echo-agent`](../../examples/echo-agent)（mock 模型 + echo 工具，`pnpm run demo:echo`）、[`examples/repl-agent`](../../examples/repl-agent)（DeepSeek V4 + coding 工具，通过面向行的 readline REPL 交互，`pnpm run demo:repl`）、[`examples/tui-agent`](../../examples/tui-agent)（通过全屏 pi-tui 复用相同的 coding 组装，`pnpm run demo:tui`）、[`examples/cordis-agent`](../../examples/cordis-agent)（自我检查和动态插件挂载，`pnpm run demo:cordis`）与 [`examples/acp-agent`](../../examples/acp-agent)（通过 JSON-RPC stdio 暴露的 ACP 服务器，`pnpm run demo:acp`）。终端叶子加载 [`@deepseek-ai/dsh-stdio-demo`](../../packages/examples/stdio-demo)，ACP 叶子加载 [`@deepseek-ai/dsh-acp-demo`](../../packages/examples/acp-demo)，两个 app 包通过 [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo) 共享主干。
+六个可运行叶子从 `cordis.yml` 加载各自的插件树：[`examples/echo-agent`](../../examples/echo-agent)（mock 模型 + echo 工具，`pnpm run demo:echo`）、[`examples/repl-agent`](../../examples/repl-agent)（DeepSeek V4 + coding 工具，通过面向行的 readline REPL 交互，`pnpm run demo:repl`）、[`examples/tui-agent`](../../examples/tui-agent)（通过全屏 pi-tui 复用相同的 coding 组装，`pnpm run demo:tui`）、[`examples/headless-agent`](../../examples/headless-agent)（同类能力通过单次任务和 DSH 原生输出运行，`pnpm run demo:headless -- "task"`）、[`examples/cordis-agent`](../../examples/cordis-agent)（自我检查和动态插件挂载，`pnpm run demo:cordis`）与 [`examples/acp-agent`](../../examples/acp-agent)（通过 JSON-RPC stdio 暴露的 ACP 服务器，`pnpm run demo:acp`）。终端叶子加载 [`@deepseek-ai/dsh-stdio-demo`](../../packages/examples/stdio-demo)，headless 叶子加载 [`@deepseek-ai/dsh-cli-demo`](../../packages/examples/cli-demo)，ACP 叶子加载 [`@deepseek-ai/dsh-acp-demo`](../../packages/examples/acp-demo)，三个 app 包都通过 [`@deepseek-ai/dsh-agent-spine-demo`](../../packages/examples/agent-spine-demo) 共享主干。

 ## 功能→机制映射

--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -68,6 +68,8 @@ requireInitiator(): Agent
 /**
 * Run an operation with one exact Agent as its process-local initiator. The
 * exact synchronous value or Promise returned by the operation is preserved.
+ * If its inherited async chain starts an owning-fiber unload, the nested
+ * boundary lineage is excluded from the drain so teardown cannot wait on itself.
 * @param agent - initiating Agent to inherit; presence is neither liveness proof nor authorization.
 * @param operation - synchronous or asynchronous operation to invoke.
 * @returns the exact value returned by `operation`.
@@ -78,6 +80,8 @@ withInitiator<T>(agent: Agent, operation: () => T): T
 /**
 * Run an operation inside a boundary that hides any inherited initiating
 * Agent. The exact synchronous value or Promise is preserved.
+ * If its inherited async chain starts an owning-fiber unload, the nested
+ * boundary lineage is excluded from the drain so teardown cannot wait on itself.
 * @param operation - synchronous or asynchronous operation to invoke without an initiator.
 * @returns the exact value returned by `operation`.
 * @throws when the initiator scope is closing/disposed, or when `operation` throws.
@@ -198,7 +202,7 @@ roots(): Agent[]

 Types: [Agent](../core-data-structures/core.md)

-Source: [`packages/core/agent/src/index.ts:204`](../../packages/core/agent/src/index.ts)
+Source: [`packages/core/agent/src/index.ts:211`](../../packages/core/agent/src/index.ts)

 ## `ctx.approval` — `ApprovalService`

--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -28,7 +28,7 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `llm/stream` | `waterfall` | [`packages/llm/llm/src/index.ts:40`](../packages/llm/llm/src/index.ts) | [`llm`](../packages/llm/llm) (`waterfall`) | [`invariants`](../packages/support/invariants), [`llm-replay`](../packages/support/llm-replay) |
 | `session/created` | `emit` | [`packages/core/session/src/index.ts:47`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`invariants`](../packages/support/invariants), [`jsonrpc`](../packages/ui/jsonrpc), [`session-persistence`](../packages/session-persistence/session-persistence) |
 | `session/disposed` | `emit` | [`packages/core/session/src/index.ts:57`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`agent-loop`](../packages/core/agent-loop), [`session-persistence`](../packages/session-persistence/session-persistence) |
-| `session/event` | `emit` | [`packages/core/session/src/index.ts:69`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/ui/acp), [`invariants`](../packages/support/invariants), [`jsonrpc`](../packages/ui/jsonrpc), [`session-persistence`](../packages/session-persistence/session-persistence), [`stdio`](../packages/ui/stdio), [`token-meter`](../packages/llm/token-meter), [`tui`](../packages/ui/tui), [`workspace-context`](../packages/context/workspace-context) |
+| `session/event` | `emit` | [`packages/core/session/src/index.ts:69`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`acp`](../packages/ui/acp), [`cli-demo`](../packages/examples/cli-demo), [`invariants`](../packages/support/invariants), [`jsonrpc`](../packages/ui/jsonrpc), [`session-persistence`](../packages/session-persistence/session-persistence), [`stdio`](../packages/ui/stdio), [`token-meter`](../packages/llm/token-meter), [`tui`](../packages/ui/tui), [`workspace-context`](../packages/context/workspace-context) |
 | `session/flush` | `parallel` | [`packages/core/session/src/index.ts:79`](../packages/core/session/src/index.ts) | [`session`](../packages/core/session) (`events.dispatch`) | [`session-persistence`](../packages/session-persistence/session-persistence) |
 | `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:112`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude`](../packages/hooks/hooks-claude), [`jsonrpc`](../packages/ui/jsonrpc) |
 | `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:86`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`tool-subagent`](../packages/subagent/tool-subagent) |
@@ -53,5 +53,6 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | Event string | Dispatchers | Listeners |
 | --- | --- | --- |
 | `internal/dispatch` | - | [`invariants`](../packages/support/invariants) |
+| `internal/status` | - | [`agent`](../packages/core/agent) |

 Maintenance mode: generated: Cordis event declarations and producer/listener edges are resolved from the repository TypeScript Program.
--- a/docs/graph-atlas.md
+++ b/docs/graph-atlas.md
@@ -15,6 +15,7 @@ The process decision behind this index is recorded in [the documentation graph R
 | [echo-agent app composition](../examples/echo-agent/composition.md) | `hybrid generated` |
 | [repl-agent app composition](../examples/repl-agent/composition.md) | `hybrid generated` |
 | [tui-agent app composition](../examples/tui-agent/composition.md) | `hybrid generated` |
+| [headless-agent app composition](../examples/headless-agent/composition.md) | `hybrid generated` |
 | [cordis-agent app composition](../examples/cordis-agent/composition.md) | `hybrid generated` |
 | [acp-agent app composition](../examples/acp-agent/composition.md) | `hybrid generated` |
 | [event producer/consumer matrix](event-producer-consumer.md) | `hybrid generated` |
--- a/docs/module-graph.md
+++ b/docs/module-graph.md
@@ -123,6 +123,7 @@ flowchart TD
  subgraph group_examples["packages/examples"]
    pkg_acp_demo["acp-demo"]
    pkg_agent_spine_demo["agent-spine-demo"]
+    pkg_cli_demo["cli-demo"]
    pkg_jsonrpc_demo["jsonrpc-demo"]
    pkg_stdio_demo["stdio-demo"]
  end
@@ -420,6 +421,14 @@ flowchart TD
  pkg_acp_demo --> pkg_tools
  pkg_acp_demo --> pkg_user_interaction
  pkg_acp_demo --> pkg_workspace_context
+  pkg_cli_demo --> pkg_agent
+  pkg_cli_demo --> pkg_agent_spine_demo
+  pkg_cli_demo --> pkg_app_boot
+  pkg_cli_demo --> pkg_llm
+  pkg_cli_demo --> pkg_session
+  pkg_cli_demo --> pkg_session_persistence_jsonl
+  pkg_cli_demo --> pkg_tools
+  pkg_cli_demo --> pkg_workspace_context
  pkg_stdio_demo --> pkg_agent
  pkg_stdio_demo --> pkg_agent_loop
  pkg_stdio_demo --> pkg_agent_spine_demo
@@ -524,4 +533,5 @@ flowchart TD
 | [`subagent-fork`](../packages/subagent/subagent-fork) | `subagent` | [`agent`](../packages/core/agent), [`session`](../packages/core/session), [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
 | [`subagent-spawn`](../packages/subagent/subagent-spawn) | `subagent` | [`subagent`](../packages/subagent/subagent), [`subagent-inprocess`](../packages/subagent/subagent-inprocess) |
 | [`acp-demo`](../packages/examples/acp-demo) | `examples` | [`acp`](../packages/ui/acp), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tools`](../packages/core/tools), [`user-interaction`](../packages/ui/user-interaction), [`workspace-context`](../packages/context/workspace-context) |
+| [`cli-demo`](../packages/examples/cli-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`tools`](../packages/core/tools), [`workspace-context`](../packages/context/workspace-context) |
 | [`stdio-demo`](../packages/examples/stdio-demo) | `examples` | [`agent`](../packages/core/agent), [`agent-loop`](../packages/core/agent-loop), [`agent-spine-demo`](../packages/examples/agent-spine-demo), [`app-boot`](../packages/ui/app-boot), [`llm`](../packages/llm/llm), [`session`](../packages/core/session), [`session-persistence-jsonl`](../packages/session-persistence/session-persistence-jsonl), [`stdio`](../packages/ui/stdio), [`tool-ask-user`](../packages/ui/tool-ask-user), [`tools`](../packages/core/tools), [`tui`](../packages/ui/tui), [`user-interaction`](../packages/ui/user-interaction), [`workspace-context`](../packages/context/workspace-context) |
--- a/docs/rfc/implemented/architecture/2026-07-15-agent-initiator-scope.i18n.yaml
+++ b/docs/rfc/implemented/architecture/2026-07-15-agent-initiator-scope.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
-2026-07-15-agent-initiator-scope.md: ae4d558215f1df462e4ad8a8af75afceebddb275
-2026-07-15-agent-initiator-scope.zh.md: 2aec7c8a6ec340cc428f7995f128de5f5660e61c
+2026-07-15-agent-initiator-scope.md: adae5d943faa6df436014ef3657b56adfbc6ea60
+2026-07-15-agent-initiator-scope.zh.md: a494c561c99adad9d1c44159e112b7220ea8468f
--- a/docs/rfc/implemented/architecture/2026-07-15-agent-initiator-scope.md
+++ b/docs/rfc/implemented/architecture/2026-07-15-agent-initiator-scope.md
@@ -12,7 +12,7 @@ Deep process-local infrastructure sometimes needs a trusted initiating Agent bel

 ## Decision

-The mandatory `ctx.agents` service uses Node `AsyncLocalStorage` to carry the initiating Agent. It stores the exact `Agent` directly rather than introducing a one-field frame; the [core-data catalog](../../../core-data-structures/core.md#initiating-agent) identifies the carried type.
+The mandatory `ctx.agents` service uses Node `AsyncLocalStorage` to carry the initiating Agent. It stores the exact `Agent` directly rather than introducing a one-field frame; a separate private run token records nested boundary lineage only for teardown bookkeeping and carries no identity. The [core-data catalog](../../../core-data-structures/core.md#initiating-agent) identifies the carried type.

 `currentInitiator()` reads optionally, `requireInitiator()` throws `no initiating agent is active`, and `withInitiator(agent, operation)` preserves the operation's exact synchronous value or Promise. `withoutInitiator(operation)` establishes a clearing boundary for work that must not inherit an Agent. Session remains derived as `agent.session`; turn, step, tool call, `signal`, model, `cwd`, sandbox, and authorization stay with their existing owners.

@@ -20,7 +20,7 @@ The mandatory `ctx.agents` service uses Node `AsyncLocalStorage` to carry the in

 Ambient identity does not replace explicit contracts. `ToolExecution.agent`, `AssembleContext.agent`, `GenerateOptions.sessionId`, task ownership, parent/child requests, `ctx.agent`, `agentCtx.agent`, approval and hook subjects, `cwd` selection, cancellation, worker/process messages, persistence records, and wire identity remain explicit. A remote boundary materializes the identity it needs into its typed request because ALS is process-local.

-`AgentRegistry` owns an ordered initiator lifecycle. Teardown first rejects new boundaries; removing `ctx.agents` then drains injected dependents such as AgentLoop, and the registry waits for active returned-Promise boundaries before calling `AsyncLocalStorage.disable()`. `currentInitiator()` and `requireInitiator()` remain usable through a retained in-flight service reference while that drain runs; after disposal, initiator methods throw `agent initiator scope is disposed`. Root Context disposal may start sibling fiber teardown concurrently, so active-boundary counting remains necessary in addition to Cordis dependency ordering.
+`AgentRegistry` owns an ordered initiator lifecycle. Teardown first rejects new boundaries; removing `ctx.agents` then drains injected dependents such as AgentLoop, and the registry waits for active returned-Promise boundaries before calling `AsyncLocalStorage.disable()`. If a boundary's inherited async chain starts an owning Cordis fiber's unload, the private run-token lineage releases that nested boundary chain from the drain, which prevents teardown from waiting on itself while unrelated boundaries still drain. `currentInitiator()` and `requireInitiator()` remain usable through a retained in-flight service reference while the ordinary drain runs; after disposal, initiator methods throw `agent initiator scope is disposed`. Root Context disposal may start sibling fiber teardown concurrently, so active-boundary counting remains necessary in addition to Cordis dependency ordering.

 Initiator scope does not own detached work: registry drain tracks only the Promise returned by `withInitiator()` or `withoutInitiator()`. Asynchronous resources created inside a boundary inherit its store until they settle or ALS is disabled, so their owning seam must stop unreturned work explicitly. Agent-owned foreground work returns its lifetime and keeps its cancellation contract. Unrelated timers, queues, and deployment infrastructure start under `withoutInitiator(operation)`; queue, worker, process, and wire boundaries serialize identity rather than expecting ALS propagation.

@@ -30,7 +30,7 @@ This decision extends the [Agent registration-scope contract](2026-07-08-agent-s

 ## Verification

-Agent service tests pin optional and required reads, exact synchronous and cross-realm Promise identity, overlapping, nested, and cleared boundaries, restoration after throws or rejection, drain ordering, and retained-reference errors. AgentLoop integration pins concurrent and nested drivers, agentless calls, AgentRegistry restart, root teardown, and package-private loop and tool scheduling through the ambient lookup. Composition, module-graph, build, and runtime-closure checks keep `ctx.agents` wired through the default bundle, SDK spine, Python runtime closure, and direct AgentLoop harnesses without another provider.
+Agent service tests pin optional and required reads, exact synchronous and cross-realm Promise identity, intrinsic Promise settlement observation, overlapping, nested, and cleared boundaries, restoration after throws or rejection, ordinary and reentrant drain ordering, and retained-reference errors. AgentLoop integration pins concurrent and nested drivers, agentless calls, AgentRegistry restart, root teardown, and package-private loop and tool scheduling through the ambient lookup. Composition, module-graph, build, and runtime-closure checks keep `ctx.agents` wired through the default bundle, SDK spine, Python runtime closure, and direct AgentLoop harnesses without another provider.

 A test-double host-aware transport derives `X-Harness-Session-Id` internally and verifies that tool schema and logged arguments contain no identity field. The service deliberately does not drain async work omitted from the Promise returned by the boundary operation; that work remains subject to its owner's explicit stop contract.

--- a/docs/rfc/implemented/architecture/2026-07-15-agent-initiator-scope.zh.md
+++ b/docs/rfc/implemented/architecture/2026-07-15-agent-initiator-scope.zh.md
@@ -12,7 +12,7 @@ Harness 中存在两种有用但不同的上下文概念。Cordis `Context` 负

 ## 决策

-必需的 `ctx.agents` 服务使用 Node `AsyncLocalStorage` 携带发起 Agent。它直接存储同一个 `Agent`，不引入只有一个字段的帧；[核心数据目录](../../../core-data-structures/core.md#initiating-agent)标明了所携带的类型。
+必需的 `ctx.agents` 服务使用 Node `AsyncLocalStorage` 携带发起 Agent。它直接存储同一个 `Agent`，不引入只有一个字段的帧；另一个私有运行标记只记录嵌套边界的谱系，供 teardown 记账使用，不携带身份。[核心数据目录](../../../core-data-structures/core.md#initiating-agent)标明了所携带的类型。

 `currentInitiator()` 用于可选读取，`requireInitiator()` 抛出 `no initiating agent is active`，`withInitiator(agent, operation)` 保留操作返回的同步值或 Promise 本身。`withoutInitiator(operation)` 会建立清空边界，供不得继承 Agent 的工作使用。会话仍通过 `agent.session` 推导；轮次、步骤、工具调用、`signal`、模型、`cwd`、沙箱和授权继续由现有归属方管理。

@@ -20,7 +20,7 @@ Harness 中存在两种有用但不同的上下文概念。Cordis `Context` 负

 隐式身份不会取代显式契约。`ToolExecution.agent`、`AssembleContext.agent`、`GenerateOptions.sessionId`、任务归属、父子请求、`ctx.agent`、`agentCtx.agent`、审批与 hook 主体、`cwd` 选择、取消、worker 和进程消息、持久化记录及协议身份都保持显式传递。远程边界会把所需身份写入类型化请求，因为 ALS 只在进程内有效。

-`AgentRegistry` 管理一个有序的发起方生命周期。teardown 会先拒绝新边界；移除 `ctx.agents` 后，AgentLoop 等注入方开始排空，注册表随后等待活动的返回 Promise 边界，最后调用 `AsyncLocalStorage.disable()`。排空期间，进行中代码可通过保留的服务引用继续调用 `currentInitiator()` 和 `requireInitiator()`；dispose 后，发起方方法会抛出 `agent initiator scope is disposed`。根 Context dispose 可能并发启动同级 fiber 的 teardown，因此除 Cordis 依赖顺序外仍必须统计活动边界。
+`AgentRegistry` 管理一个有序的发起方生命周期。teardown 会先拒绝新边界；移除 `ctx.agents` 后，AgentLoop 等注入方开始排空，注册表随后等待活动的返回 Promise 边界，最后调用 `AsyncLocalStorage.disable()`。如果某个边界继承的异步调用链启动所属 Cordis fiber 的卸载，私有运行标记谱系会从排空范围中释放该嵌套边界链，从而避免 teardown 等待自身完成，同时继续排空无关边界。在普通排空期间，进行中代码可通过保留的服务引用继续调用 `currentInitiator()` 和 `requireInitiator()`；dispose 后，发起方方法会抛出 `agent initiator scope is disposed`。根 Context dispose 可能并发启动同级 fiber 的 teardown，因此除 Cordis 依赖顺序外仍必须统计活动边界。

 发起方作用域不负责管理脱离返回链的工作：注册表排空只跟踪 `withInitiator()` 或 `withoutInitiator()` 返回的 Promise。边界内创建的异步资源会继承其存储，直到自身结束或 ALS 被禁用；所属 seam 必须显式停止未纳入返回 Promise 的工作。Agent 所有前台工作会把完整生命周期纳入返回值，并保留显式取消契约。无关的定时器、队列和部署基础设施在 `withoutInitiator(operation)` 下启动；队列、worker、进程和协议边界必须序列化身份，不能期待 ALS 传播。

@@ -30,7 +30,7 @@ Harness 中存在两种有用但不同的上下文概念。Cordis `Context` 负

 ## 验证

-Agent 服务测试锁定可选与必需读取、同步值和跨 realm Promise 的引用身份、并发、嵌套及清空边界、同步抛错或 Promise 拒绝后的恢复、排空顺序及保留引用的错误。AgentLoop 集成测试锁定并发与嵌套驱动、无 Agent 调用、AgentRegistry 重启、根 Context 销毁，以及包内私有的循环和工具调度通过隐式查找完成。组合、模块图、构建及运行时闭包检查确保默认组合包、SDK 主干、Python 运行时闭包及直接 AgentLoop harness 通过 `ctx.agents` 完成接线，无需其他提供方。
+Agent 服务测试锁定可选与必需读取、同步值和跨 realm Promise 的引用身份、内建 Promise 结束状态观察、并发、嵌套及清空边界、同步抛错或 Promise 拒绝后的恢复、普通与重入排空顺序及保留引用的错误。AgentLoop 集成测试锁定并发与嵌套驱动、无 Agent 调用、AgentRegistry 重启、根 Context 销毁，以及包内私有的循环和工具调度通过隐式查找完成。组合、模块图、构建及运行时闭包检查确保默认组合包、SDK 主干、Python 运行时闭包及直接 AgentLoop harness 通过 `ctx.agents` 完成接线，无需其他提供方。

 测试替身形式的宿主感知传输层在内部推导 `X-Harness-Session-Id`，并验证工具 schema 与记录参数都不包含身份字段。服务有意不排空边界操作所返回 Promise 之外的异步工作；这类工作仍由所属方的显式停止契约管理。

--- a/docs/testing.md
+++ b/docs/testing.md
@@ -7,7 +7,7 @@ How this repo tests, tier by tier, and the rules that keep a green suite meaning
 - **Unit** (`pnpm run test`): vitest over `packages|examples/*/tests/**/*.spec.ts`, colocated with what they test. Every registry gets an HMR-safety test (dispose the contributing fiber, assert cleanup). Prefer edge cases, error paths, event ordering, concurrency races, and permanent contract regressions (see `packages/core/agent-loop/tests/contract-regressions.spec.ts`).
 - **Coverage gate** (`pnpm run test:coverage`): the gating run, per-file 100% on `packages/*/*/src`. An uncovered line is often dead code the gate is correctly flagging for deletion, not a missing test to bolt on. Line coverage is necessary, never sufficient — it proves lines ran, not that the feature works as shipped.
 - **Real-API e2e** (`pnpm run test:e2e`): with-key tests against live provider APIs — the DeepSeek model plus provider-specific smokes that gate on their own keys (`EXA_API_KEY`, `PERPLEXITY_API_KEY`, …); each suite self-skips without its key so keyless CI stays green ([real-API e2e RFC](rfc/implemented/testing/2026-06-19-real-api-e2e-ci.md)).
- **Snapshot** (`pnpm run test:snapshot`): transport-specific keyless goldens cover external presentation. ACP suites boot the real example subprocess, replay a recorded session, and diff normalized stdout plus the re-persisted log ([ACP snapshot RFC](rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md)). TUI completed journeys replay recorded primary/child JSONL through the real agent loop and tools before projecting ANSI into semantic terminal-state goldens; package-local snapshots retain transient renderer states, and a real PTY conversation covers the process boundary ([TUI snapshot RFC](rfc/implemented/testing/2026-07-18-tui-terminal-state-snapshots.md)). Use `pnpm run test:snapshot:record` when a model transcript must change and `pnpm run test:snapshot:refresh` when committed replay input remains correct; review every JSONL and golden diff. System-prompt/tool-schema content is pinned by ONE ACP scenario (`text-turn`) and tokenized in every other fixture, so a prompt or schema edit churns one committed line ([pinned-header RFC](rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)).
+- **Snapshot** (`pnpm run test:snapshot`): transport-specific keyless goldens cover external presentation. ACP suites boot the real example subprocess, replay a recorded session, and diff normalized JSON-RPC plus the re-persisted log ([ACP snapshot RFC](rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md)); the headless suite independently pins `stream-json` through its real one-shot subprocess. TUI completed journeys replay recorded primary/child JSONL through the real agent loop and tools before projecting ANSI into semantic terminal-state goldens; package-local snapshots retain transient renderer states, and a real PTY conversation covers the process boundary ([TUI snapshot RFC](rfc/implemented/testing/2026-07-18-tui-terminal-state-snapshots.md)). Use `pnpm run test:snapshot:record` when a model transcript must change and `pnpm run test:snapshot:refresh` when committed replay input remains correct; review every JSONL and golden diff. System-prompt/tool-schema content is pinned by one ACP scenario (`text-turn`) and tokenized in every other fixture, so a prompt or schema edit churns one committed line ([pinned-header RFC](rfc/implemented/testing/2026-07-06-pin-request-header-content-in-one-scenario.md)).

 ## The with-key policy: inference is cheap here

@@ -35,4 +35,4 @@ An e2e assertion re-runs the command or re-reads the file externally; a keyword

 ## When a snapshot test is required

-Any change affecting an editor-facing transcript or end-to-end agent UX adds or updates a scenario in the owning snapshot suite, or states in the PR why none applies. ACP surfaces use `examples/<name>/tests/snapshots/`, a scenario table over the [`dsh-acp-snapshot`](../packages/support/acp-snapshot/README.md) suite factory (`examples/acp-agent` is primary). Completed interactive-terminal journeys use JSONL-driven scenarios under `examples/tui-agent/tests/snapshots/`; transient presentation uses the package-local semantic matrix, with a PTY case when input, Loader selection, or terminal teardown changes. New capability seams, lifecycle shapes, or transcript surfaces name their coverage at every tier at plan time and verify the harness can express it — a harness gap is scheduled work, not a mid-build surprise.
+Any change affecting an editor-facing transcript, headless event stream, or end-to-end agent UX adds or updates a scenario in the owning snapshot suite, or states in the PR why none applies. ACP surfaces use `examples/<name>/tests/snapshots/`, a scenario table over the [`dsh-acp-snapshot`](../packages/support/acp-snapshot/README.md) suite factory (`examples/acp-agent` is primary); `examples/headless-agent` owns the `stream-json` snapshot and replay fixtures. Completed interactive-terminal journeys use JSONL-driven scenarios under `examples/tui-agent/tests/snapshots/`; transient presentation uses the package-local semantic matrix, with a PTY case when input, Loader selection, or terminal teardown changes. New capability seams, lifecycle shapes, or transcript surfaces name their coverage at every tier at plan time and verify the harness can express it — a harness gap is scheduled work, not a mid-build surprise.
--- a/examples/README.md
+++ b/examples/README.md
@@ -1,6 +1,6 @@
 # Examples

-Runnable demos (not workspaces) that showcase how the harness is wired. Each example is a **thin leaf**: a `cordis.yml` that picks the swappable backends (an LLM adapter, a bash executor), loads one app package, and may add optional product tools or demo-only mocks. The composition — the spine, the front-door cluster, and the boot glue — lives in the app packages ([`@deepseek-ai/dsh-stdio-demo`](../packages/examples/stdio-demo), [`@deepseek-ai/dsh-acp-demo`](../packages/examples/acp-demo)) and the [`@deepseek-ai/dsh-agent-spine-demo`](../packages/examples/agent-spine-demo) bundle they share. There is no `start.ts`; the `demo:*` scripts invoke each app package's `bin`.
+Runnable demos (not workspaces) that showcase how the harness is wired. Each example is a **thin leaf**: a `cordis.yml` that picks the swappable backends (an LLM adapter, a bash executor), loads one app package, and may add optional product tools or demo-only mocks. The composition — the spine, the front-door cluster, and the boot glue — lives in the app packages ([`@deepseek-ai/dsh-stdio-demo`](../packages/examples/stdio-demo), [`@deepseek-ai/dsh-cli-demo`](../packages/examples/cli-demo), [`@deepseek-ai/dsh-acp-demo`](../packages/examples/acp-demo)) and the [`@deepseek-ai/dsh-agent-spine-demo`](../packages/examples/agent-spine-demo) bundle they share. There is no `start.ts`; the `demo:*` scripts invoke each app package's `bin`.

 ## echo-agent

@@ -21,6 +21,12 @@ Run with: `pnpm run demo:repl` (needs `DEEPSEEK_API_KEY` in the environment or a

 Run the Code Mode overlay with `pnpm run demo:code-mode`, or pass `acp` for the ACP example. See the [Code Mode example](repl-agent/README.md#code-mode) for its composition and a sample task.

+## headless-agent
+
+A non-interactive agent demo that accepts one positional task, runs one complete model/tool turn on the `@deepseek-ai/dsh-cli-demo` app, persists a fresh session, prints `text`, `json`, or `stream-json`, and exits.
+
+Run with: `pnpm run demo:headless -- "task"` (needs `DEEPSEEK_API_KEY`). See [headless-agent/README.md](headless-agent/README.md) for the output contract, safety boundaries, and snapshot suite.
+
 ## tui-agent

 The full-screen terminal sibling of `repl-agent`: it reuses the same coding backends and tools while forcing the shared terminal app to `dsh-tui`. It is the home of TUI PTY and snapshot scenarios.
@@ -35,7 +41,7 @@ Run with: `pnpm run demo:cordis` (needs `DEEPSEEK_API_KEY`). See [cordis-agent/R

 ## acp-agent

-An agent demo exposed as an **Agent Client Protocol (ACP)** server over JSON-RPC stdio, via the [`@deepseek-ai/dsh-acp-demo`](../packages/examples/acp-demo) app — drive it from Zed or any other ACP client. Also the home of the keyless snapshot tests.
+An agent demo exposed as an **Agent Client Protocol (ACP)** server over JSON-RPC stdio, via the [`@deepseek-ai/dsh-acp-demo`](../packages/examples/acp-demo) app — drive it from Zed or any other ACP client. It owns the ACP keyless snapshot suite.

 Run with: `pnpm run demo:acp` (needs `DEEPSEEK_API_KEY`); `pnpm run demo:code-mode acp` boots the same server in Code Mode via the `code-mode.cordis.yml` overlay. See [acp-agent/README.md](acp-agent/README.md) for the Zed setup and the snapshot-test design.

--- a/examples/acp-agent/README.md
+++ b/examples/acp-agent/README.md
@@ -33,7 +33,7 @@ The editor sets each session's `cwd` to the project it opens, and bash uses that

 ## Snapshot tests (record-once / replay-deterministic)

-This example hosts the ACP snapshot suite. `dsh-llm-replay` reconstructs model streams from `assistant/chunk` events in each scenario's session JSONL, so replay is keyless. Recording runs the real agent and harvests that log; refresh keeps the committed transcript as mock input and rewrites current replay outputs. `replay.override.json` covers throw and hang cases that chunks cannot express, and an optional `workspace/` seeds files. The [snapshot RFC](../../docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md) owns the full design.
+This example hosts the ACP snapshot suite. It replays through `dsh-llm-replay`, which reconstructs model streams from `assistant/chunk` events in each scenario's session JSONL. Recording runs the real ACP agent and harvests its logs; refresh keeps the committed transcript as mock input and rewrites current replay outputs. `replay.override.json` covers throw and hang cases that chunks cannot express, and an optional `workspace/` seeds files. The [snapshot RFC](../../docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md) owns the ACP harness design.

 ## Permissions and sandboxing

--- a/examples/headless-agent/README.md
+++ b/examples/headless-agent/README.md
@@ -0,0 +1,24 @@
+# headless-agent
+
+Headless one-shot agent wiring: DeepSeek V4 + local bash and filesystem tools + subagent delegation + workflows + `todo_write` + JSONL persistence, with [`@deepseek-ai/dsh-cli-demo`](../../packages/examples/cli-demo) as the app front door.
+
+## Run it
+
+```sh
+# repo root .env (gitignored) or exported env:
+#   DEEPSEEK_API_KEY=sk-…
+#   DEEPSEEK_BASE_URL=https://…   # optional; defaults to the public API
+pnpm run demo:headless -- "fix the failing test in this workspace"
+pnpm run demo:headless --output-format json -- "summarize the implementation"
+pnpm run demo:headless --output-format stream-json -- "run the focused tests"
+```
+
+Exactly one nonblank positional task is required; quote tasks containing spaces. There is no `-p` flag. `text` prints the last text-bearing assistant message, `json` prints one DSH-native result record, and `stream-json` emits the top-level session's canonical task-turn events before that record. Child sessions surface only through parent tool events and results.
+
+Each invocation creates and persists a fresh session, runs all model and tool steps in one turn, flushes, disposes, and exits. This is non-interactive automation: there is no prompt, approval, resume, second turn, or stdin context. The configured tools can mutate the launch workspace, run commands, spawn child agents, and consume provider tokens.
+
+## Advanced and snapshot wiring
+
+[`advanced.cordis.yml`](advanced.cordis.yml) adds Code Mode and the Cordis tools to the shipped leaf. [`advanced.cordis.snapshot.yml`](advanced.cordis.snapshot.yml) replaces only the live LLM with replay. The tests under [`tests/`](tests/) own the keyless real-Loader smoke, key-gated world-verified smoke, and the `stream-json` replay snapshot with its parent and child session fixtures.
+
+The package-level [CLI contract](../../packages/examples/cli-demo/README.md) documents output records, exit status, cancellation, persistence, and model/token effects.
--- a/examples/headless-agent/advanced.cordis.snapshot.yml
+++ b/examples/headless-agent/advanced.cordis.snapshot.yml
@@ -0,0 +1,12 @@
+# Replay counterpart to advanced.cordis.yml; only the live model is replaced.
+- id: base
+  name: '@cordisjs/plugin-include'
+  config:
+    path: ./advanced.cordis.yml
+    patches:
+      - id: llm-deepseek
+        name: '@deepseek-ai/dsh-llm-deepseek'
+        disabled: true
+      - insert:
+          - id: llm-replay
+            name: '@deepseek-ai/dsh-llm-replay'
--- a/examples/headless-agent/advanced.cordis.yml
+++ b/examples/headless-agent/advanced.cordis.yml
@@ -0,0 +1,25 @@
+# Add Code Mode and Cordis tools to the headless spawn/workflow stack.
+- id: base
+  name: '@cordisjs/plugin-include'
+  config:
+    path: ./cordis.yml
+    patches:
+      - id: cli-agent
+        name: '@deepseek-ai/dsh-cli-demo'
+        config:
+          provider: deepseek
+          model: deepseek-v4-flash
+          persistenceRoot: './.sessions'
+          workspaceContext:
+            maxBytes: 65536
+          tools:
+            mode: both
+          persona: |
+            You are headless-agent, a coding assistant powered by the {{model}} model. Your working directory is {{cwd}}.
+
+            Verify your work by running the code or tests. Keep answers brief and factual.
+      - insert:
+          - id: code-runtime
+            name: '@deepseek-ai/dsh-code-runtime-worker'
+          - id: tool-cordis
+            name: '@deepseek-ai/dsh-tool-cordis'
--- a/examples/headless-agent/composition.md
+++ b/examples/headless-agent/composition.md
@@ -0,0 +1,70 @@
+<!-- Generated by scripts/gen-doc-graphs.ts - do not edit by hand.
+     Run `pnpm run gen-doc-graphs` to regenerate. -->
+
+# Headless Agent App Composition
+
+The headless demo combines the real DeepSeek adapter and coding capabilities with the one-shot app package, format-pure stdout, and one fresh persisted top-level session.
+
+```mermaid
+flowchart LR
+  cfg["examples/headless-agent<br/>cordis.yml"]
+  plugin_headless_llm_deepseek["llm-deepseek<br/>@deepseek-ai/dsh-llm-deepseek"]
+  cfg --> plugin_headless_llm_deepseek
+  plugin_headless_bash["bash<br/>@deepseek-ai/dsh-bash-local"]
+  cfg --> plugin_headless_bash
+  plugin_headless_cli_agent["cli-agent<br/>@deepseek-ai/dsh-cli-demo"]
+  cfg --> plugin_headless_cli_agent
+  plugin_headless_cli_agent --> bundle_agent_core["@deepseek-ai/dsh-agent-spine-demo"]
+  plugin_headless_cli_agent --> bundle_jsonl["@deepseek-ai/dsh-session-persistence-jsonl"]
+  plugin_headless_cli_agent --> frontdoor_cli["one-shot driver<br/>format-pure stdout<br/>fresh top-level agent"]
+  bundle_agent_core --> spine_llm["ctx.llm"]
+  bundle_agent_core --> spine_sessions["ctx.sessions"]
+  bundle_agent_core --> spine_tools["ctx.tools + tool-bash"]
+  bundle_agent_core --> spine_loop["ctx.agents + ctx.agentLoop"]
+  plugin_headless_compact_basic["compact-basic<br/>@deepseek-ai/dsh-compact-basic"]
+  cfg --> plugin_headless_compact_basic
+  plugin_headless_subagent["subagent<br/>@deepseek-ai/dsh-subagent"]
+  cfg --> plugin_headless_subagent
+  plugin_headless_subagent_spawn["subagent-spawn<br/>@deepseek-ai/dsh-subagent-spawn"]
+  cfg --> plugin_headless_subagent_spawn
+  plugin_headless_subagent_fork["subagent-fork<br/>@deepseek-ai/dsh-subagent-fork"]
+  cfg --> plugin_headless_subagent_fork
+  plugin_headless_tool_subagent["tool-subagent<br/>@deepseek-ai/dsh-tool-subagent"]
+  cfg --> plugin_headless_tool_subagent
+  plugin_headless_tool_subagent_fork["tool-subagent-fork<br/>@deepseek-ai/dsh-tool-subagent"]
+  cfg --> plugin_headless_tool_subagent_fork
+  plugin_headless_workflow_workerthread["workflow-workerthread<br/>@deepseek-ai/dsh-workflow-workerthread"]
+  cfg --> plugin_headless_workflow_workerthread
+  plugin_headless_tool_workflow["tool-workflow<br/>@deepseek-ai/dsh-tool-workflow"]
+  cfg --> plugin_headless_tool_workflow
+  plugin_headless_tool_todo["tool-todo<br/>@deepseek-ai/dsh-tool-todo"]
+  cfg --> plugin_headless_tool_todo
+  plugin_headless_fs_local["fs-local<br/>@deepseek-ai/dsh-fs-local"]
+  cfg --> plugin_headless_fs_local
+  plugin_headless_fs_policy["fs-policy<br/>@deepseek-ai/dsh-fs-policy"]
+  cfg --> plugin_headless_fs_policy
+  plugin_headless_tool_fs["tool-fs<br/>@deepseek-ai/dsh-tool-fs"]
+  cfg --> plugin_headless_tool_fs
+```
+
+| Plugin id | Package / module |
+| --- | --- |
+| `llm-deepseek` | `@deepseek-ai/dsh-llm-deepseek` |
+| `bash` | `@deepseek-ai/dsh-bash-local` |
+| `cli-agent` | `@deepseek-ai/dsh-cli-demo` |
+| `compact-basic` | `@deepseek-ai/dsh-compact-basic` |
+| `subagent` | `@deepseek-ai/dsh-subagent` |
+| `subagent-spawn` | `@deepseek-ai/dsh-subagent-spawn` |
+| `subagent-fork` | `@deepseek-ai/dsh-subagent-fork` |
+| `tool-subagent` | `@deepseek-ai/dsh-tool-subagent` |
+| `tool-subagent-fork` | `@deepseek-ai/dsh-tool-subagent` |
+| `workflow-workerthread` | `@deepseek-ai/dsh-workflow-workerthread` |
+| `tool-workflow` | `@deepseek-ai/dsh-tool-workflow` |
+| `tool-todo` | `@deepseek-ai/dsh-tool-todo` |
+| `fs-local` | `@deepseek-ai/dsh-fs-local` |
+| `fs-policy` | `@deepseek-ai/dsh-fs-policy` |
+| `tool-fs` | `@deepseek-ai/dsh-tool-fs` |
+
+Source config: [`examples/headless-agent/cordis.yml`](cordis.yml).
+
+Maintenance mode: hybrid: the leaf plugin list is parsed from its `cordis.yml`; app package expansion is curated from package source.
--- a/examples/headless-agent/cordis.yml
+++ b/examples/headless-agent/cordis.yml
@@ -0,0 +1,99 @@
+# One-shot coding agent with format-pure stdout. The app bin loads the
+# gitignored root `.env`; this file reads `DEEPSEEK_API_KEY` and optional
+# `DEEPSEEK_BASE_URL` through `!!js`.
+
+# The DeepSeek adapter. Swap to '@deepseek-ai/dsh-llm-pi-ai' for the pi-ai-backed
+# twin (same config shape; `reasoning: high` replaces thinking/reasoningEffort).
+- id: llm-deepseek
+  name: '@deepseek-ai/dsh-llm-deepseek'
+  config:
+    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    baseURL: !!js process.env.DEEPSEEK_BASE_URL
+    models:
+      - id: deepseek-v4-pro
+      - id: deepseek-v4-flash
+
+- id: bash
+  name: '@deepseek-ai/dsh-bash-local'
+  config:
+    timeoutMs: 60000
+
+# The app bundle pre-creates one fresh `main` agent per invocation.
+- id: cli-agent
+  name: '@deepseek-ai/dsh-cli-demo'
+  config:
+    provider: deepseek
+    model: deepseek-v4-flash
+    persistenceRoot: './.sessions'
+    workspaceContext:
+      maxBytes: 65536
+    persona: |
+      You are headless-agent, a coding assistant powered by the {{model}} model.
+
+      Verify your work by running the code or tests. Keep answers brief and
+      factual.
+
+# Summarize an older range when derived history approaches the context window.
+- id: compact-basic
+  name: '@deepseek-ai/dsh-compact-basic'
+  config:
+    contextWindow: 128000
+    thresholdRatio: 0.8
+    retainTokens: 20480
+    summarizationModel: ''
+    maxTokens: 8192
+    compactionRetries: 1
+
+# Expose fresh-child `spawn` and completed-prefix `fork` through independent
+# in-process backends.
+- id: subagent
+  name: '@deepseek-ai/dsh-subagent'
+
+- id: subagent-spawn
+  name: '@deepseek-ai/dsh-subagent-spawn'
+  config:
+    providerName: spawn
+
+- id: subagent-fork
+  name: '@deepseek-ai/dsh-subagent-fork'
+  config:
+    providerName: fork
+
+- id: tool-subagent
+  name: '@deepseek-ai/dsh-tool-subagent'
+  config:
+    provider: spawn
+    toolName: subagent
+
+- id: tool-subagent-fork
+  name: '@deepseek-ai/dsh-tool-subagent'
+  config:
+    provider: fork
+    toolName: subagent_fork
+
+# The worker-thread workflow engine fans a model-written JavaScript script's
+# `agent()` calls out through the spawn backend.
+- id: workflow-workerthread
+  name: '@deepseek-ai/dsh-workflow-workerthread'
+  config:
+    provider: spawn
+
+- id: tool-workflow
+  name: '@deepseek-ai/dsh-tool-workflow'
+
+# `todo_write` replaces the logged whole list.
+- id: tool-todo
+  name: '@deepseek-ai/dsh-tool-todo'
+
+# Policy loads before the model-facing filesystem tools so writes and edits
+# require an observed file. Relative paths resolve from the process cwd.
+- id: fs-local
+  name: '@deepseek-ai/dsh-fs-local'
+  config:
+    cwd: !!js process.cwd()
+
+- id: fs-policy
+  name: '@deepseek-ai/dsh-fs-policy'
+
+- id: tool-fs
+  name: '@deepseek-ai/dsh-tool-fs'
--- a/examples/headless-agent/package.json
+++ b/examples/headless-agent/package.json
@@ -0,0 +1,7 @@
+{
+  "name": "headless-agent-example",
+  "private": true,
+  "version": "0.0.1",
+  "type": "module",
+  "description": "Runnable demo: one complete headless coding-agent turn"
+}
--- a/examples/headless-agent/tests/fixtures/cli-mock-llm.ts
+++ b/examples/headless-agent/tests/fixtures/cli-mock-llm.ts
@@ -0,0 +1,37 @@
+import type { Context } from 'cordis'
+import { CallId, LlmAdapter, type GenerateOptions, type StreamChunk } from '@deepseek-ai/dsh-llm'
+
+/** Keyless headless-agent adapter: one real bash call followed by a final answer. */
+class CliMockAdapter extends LlmAdapter {
+  async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    const toolResult = options.messages.at(-1)?.content.find(block => block.type === 'tool-result')
+    if (toolResult === undefined) {
+      const args = JSON.stringify({ command: 'printf CLI_TOOL_ROUND_TRIP', description: 'Prove the CLI tool round trip.' })
+      yield { type: 'block-start', index: 0, blockType: 'tool-call' }
+      yield { type: 'tool-call-delta', index: 0, id: CallId('cli-smoke-call'), name: 'bash', argumentsDelta: args }
+      yield { type: 'block-end', index: 0, block: { type: 'tool-call', id: CallId('cli-smoke-call'), name: 'bash', arguments: args } }
+      yield { type: 'usage', usage: { inputTokens: 11, outputTokens: 3, cacheReadTokens: 2 } }
+      yield { type: 'finish', reason: { kind: 'tool-calls' } }
+      return
+    }
+
+    const toolText = toolResult.content
+      .filter(block => block.type === 'text')
+      .map(block => block.text)
+      .join('')
+    const reply = `CLI tool round trip complete: ${toolText.trim()}`
+    yield { type: 'block-start', index: 0, blockType: '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: 7, outputTokens: 5, reasoningTokens: 1 } }
+    yield { type: 'finish', reason: { kind: 'stop' } }
+  }
+}
+
+export const name = 'cli-mock-llm'
+export const inject = ['llm']
+
+/** Register the keyless `cli-mock` adapter. */
+export function apply(ctx: Context): void {
+  ctx.llm.registerAdapter(['cli-mock'], new CliMockAdapter())
+}
--- a/examples/headless-agent/tests/fixtures/cli.cordis.yml
+++ b/examples/headless-agent/tests/fixtures/cli.cordis.yml
@@ -0,0 +1,19 @@
+- id: cli-mock-llm
+  name: './cli-mock-llm.ts'
+
+- id: base
+  name: '@cordisjs/plugin-include'
+  config:
+    path: ../../cordis.yml
+    patches:
+      - id: llm-deepseek
+        name: '@deepseek-ai/dsh-llm-deepseek'
+        disabled: true
+      - id: cli-agent
+        name: '@deepseek-ai/dsh-cli-demo'
+        config:
+          provider: cli-mock
+          model: cli-mock
+          persistenceRoot: './.sessions'
+          workspaceContext: false
+          persona: 'Keyless headless-agent smoke.'
--- a/examples/headless-agent/tests/headless.snapshot.ts
+++ b/examples/headless-agent/tests/headless.snapshot.ts
@@ -0,0 +1,140 @@
+import { readFile, readdir, writeFile } from 'node:fs/promises'
+import { delimiter, dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  normalizeSessionLog,
+  normalizeStdout,
+  scrubRequestHeaders,
+  type NormalizeContext,
+} from '@deepseek-ai/dsh-acp-snapshot'
+import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
+import { describe, expect, it } from 'vitest'
+
+const snapshotsDir = join(dirname(fileURLToPath(import.meta.url)), 'snapshots')
+const scenarioDir = join(snapshotsDir, 'advanced-toolchain')
+const sessionFixture = join(scenarioDir, 'session.jsonl')
+const streamGolden = join(scenarioDir, 'stream-json.golden.jsonl')
+const configPath = fileURLToPath(new URL('../advanced.cordis.snapshot.yml', import.meta.url))
+const binScript = fileURLToPath(new URL('../../../packages/examples/cli-demo/src/bin.ts', import.meta.url))
+const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
+const refreshing = process.env.DSH_SNAPSHOT === 'refresh'
+
+interface JsonObject {
+  [key: string]: unknown
+}
+
+interface PersistedLog {
+  readonly content: string
+  readonly header: JsonObject
+}
+
+function parseJsonl(content: string): JsonObject[] {
+  return content.split('\n')
+    .filter(line => line.trim().length > 0)
+    .map(line => JSON.parse(line) as JsonObject)
+}
+
+function contextFromLogs(contents: readonly string[]): NormalizeContext {
+  const headers = contents.map(content => parseJsonl(content)[0])
+  return {
+    sessionIds: headers.flatMap(header => typeof header?.id === 'string' ? [header.id] : []),
+    cwd: typeof headers[0]?.cwd === 'string' ? headers[0].cwd : '\0no-cwd\0',
+  }
+}
+
+function normalizeHeadlessStream(rawStdout: string, cwd: string): string {
+  const records = parseJsonl(rawStdout)
+  if (records.length === 0) throw new Error('headless snapshot emitted no stream-json records')
+  const final = records.at(-1)
+  if (final?.type !== 'result') throw new Error('headless snapshot did not end with a result record')
+  if (records.slice(0, -1).some(record => record.type !== 'session_event')) {
+    throw new Error('headless snapshot emitted a non-event record before its result')
+  }
+
+  const sessionIds = [...new Set(records.flatMap(record => typeof record.sessionId === 'string' ? [record.sessionId] : []))]
+  if (sessionIds.length !== 1) throw new Error(`headless snapshot streamed ${sessionIds.length} main session ids`)
+  const context: NormalizeContext = { sessionIds, cwd }
+  const events = records.slice(0, -1).map((record) => {
+    if (record.event === null || typeof record.event !== 'object' || Array.isArray(record.event)) {
+      throw new Error('headless snapshot emitted an invalid session event')
+    }
+    return record.event as JsonObject
+  })
+  const normalizedEvents = parseJsonl(scrubRequestHeaders(normalizeSessionLog(
+    `${events.map(event => JSON.stringify(event)).join('\n')}\n`,
+    context,
+  )))
+  const normalizedRecords = records.map((record, index) => index < normalizedEvents.length
+    ? { ...record, event: normalizedEvents[index] }
+    : record)
+  return normalizeStdout(`${normalizedRecords.map(record => JSON.stringify(record)).join('\n')}\n`, context)
+}
+
+async function advancedPrompt(): Promise<string> {
+  const input = JSON.parse(await readFile(join(scenarioDir, 'input.json'), 'utf8')) as {
+    steps?: { op?: unknown; text?: unknown }[]
+  }
+  const prompt = input.steps?.find(step => step.op === 'prompt')?.text
+  if (typeof prompt !== 'string') throw new Error('advanced-toolchain input has no prompt step')
+  return prompt
+}
+
+async function persistedLogs(cwd: string): Promise<PersistedLog[]> {
+  const root = join(cwd, '.sessions')
+  const files = (await readdir(root, { recursive: true })).filter(file => file.endsWith('.jsonl'))
+  return Promise.all(files.map(async (file) => {
+    const content = await readFile(join(root, file), 'utf8')
+    return { content, header: parseJsonl(content)[0] ?? {} }
+  }))
+}
+
+describe('headless stream-json snapshots', () => {
+  it('replays the advanced toolchain through the one-shot app', async () => {
+    const prompt = await advancedPrompt()
+    const expectedSessions = await Promise.all([
+      sessionFixture,
+      join(scenarioDir, 'session.1.jsonl'),
+      join(scenarioDir, 'session.2.jsonl'),
+    ].map(file => readFile(file, 'utf8')))
+    let runCwd = ''
+    const result = await runLoaderSmoke({
+      label: 'advanced headless stream-json snapshot',
+      tempDirPrefix: 'headless-snapshot-advanced-',
+      binScript,
+      configPath,
+      binArgs: ['--config', configPath, '--output-format', 'stream-json', prompt],
+      tsconfigPath,
+      env: {
+        DSH_SNAPSHOT: 'replay',
+        DSH_SNAPSHOT_FILE: sessionFixture,
+        DSH_SNAPSHOT_CHILD_FILES: [join(scenarioDir, 'session.1.jsonl'), join(scenarioDir, 'session.2.jsonl')].join(delimiter),
+        NODE_OPTIONS: [process.env.NODE_OPTIONS, '--disable-warning=ExperimentalWarning'].filter(Boolean).join(' '),
+      },
+      prepare: (cwd) => { runCwd = cwd },
+      inspect: async (cwd) => {
+        const logs = await persistedLogs(cwd)
+        expect(logs).toHaveLength(3)
+        const parents = logs.filter(log => typeof log.header.parentSession !== 'string')
+        expect(parents).toHaveLength(1)
+        const parent = parents[0]
+        if (parent === undefined) throw new Error('headless snapshot did not persist its main session')
+        const children = logs.filter(log => typeof log.header.parentSession === 'string')
+          .sort((left, right) => Number(left.header.createdAt) - Number(right.header.createdAt))
+        const actualSessions = [parent, ...children]
+        const actualContext = contextFromLogs(actualSessions.map(log => log.content))
+        const expectedContext = contextFromLogs(expectedSessions)
+        for (const [index, actual] of actualSessions.entries()) {
+          const expected = expectedSessions[index]
+          if (expected === undefined) throw new Error(`headless snapshot has no fixture for persisted log ${index}`)
+          expect(scrubRequestHeaders(normalizeSessionLog(actual.content, actualContext)))
+            .toBe(scrubRequestHeaders(normalizeSessionLog(expected, expectedContext)))
+        }
+      },
+    })
+
+    expect(result.stderr).toBe('')
+    const normalized = normalizeHeadlessStream(result.stdout, runCwd)
+    if (refreshing) await writeFile(streamGolden, normalized)
+    expect(normalized).toBe(await readFile(streamGolden, 'utf8'))
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+})
--- a/examples/headless-agent/tests/keyless-smoke.e2e.ts
+++ b/examples/headless-agent/tests/keyless-smoke.e2e.ts
@@ -0,0 +1,43 @@
+import { readdir } from 'node:fs/promises'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
+import type { SessionEvent } from '@deepseek-ai/dsh-session'
+
+const binScript = fileURLToPath(new URL('../../../packages/examples/cli-demo/src/bin.ts', import.meta.url))
+const configPath = fileURLToPath(new URL('./fixtures/cli.cordis.yml', import.meta.url))
+const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
+
+describe('headless-agent keyless smoke', () => {
+  it('boots the real Loader tree, runs a real bash tool round trip, and persists the turn', async () => {
+    let persisted = false
+    const { stdout, stderr } = await runLoaderSmoke({
+      label: 'headless-agent',
+      tempDirPrefix: 'headless-agent-smoke-',
+      binScript,
+      configPath,
+      binArgs: ['--config', configPath, '--output-format', 'stream-json', 'prove the tool path'],
+      tsconfigPath,
+      inspect: async (cwd) => {
+        const files = await readdir(cwd, { recursive: true })
+        persisted = files.some(file => file.endsWith('.jsonl'))
+      },
+    })
+    const lines = stdout.trimEnd().split('\n').map(line => JSON.parse(line) as Record<string, unknown>)
+    const events = lines.slice(0, -1).map(line => line['event'] as SessionEvent)
+    const result = lines.at(-1)
+    expect(stderr).toBe('')
+    expect(events.some(event => event.type === 'tool/call' && event.data.name === 'bash')).toBe(true)
+    const toolResult = events.find(event => event.type === 'tool/result')
+    expect(JSON.stringify(toolResult)).toContain('CLI_TOOL_ROUND_TRIP')
+    expect(result).toMatchObject({
+      type: 'result',
+      success: true,
+      turn: 1,
+      reason: { kind: 'completed' },
+      usage: { inputTokens: 18, outputTokens: 8, cacheReadTokens: 2, reasoningTokens: 1 },
+    })
+    expect(String(result?.['result'])).toContain('CLI_TOOL_ROUND_TRIP')
+    expect(persisted).toBe(true)
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+})
--- a/examples/headless-agent/tests/real-model.e2e.ts
+++ b/examples/headless-agent/tests/real-model.e2e.ts
@@ -0,0 +1,33 @@
+import { readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { describe, expect, it } from 'vitest'
+import { runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
+
+const binScript = fileURLToPath(new URL('../../../packages/examples/cli-demo/src/bin.ts', import.meta.url))
+const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url))
+const tsconfigPath = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
+const hasKey = Boolean(process.env.DEEPSEEK_API_KEY)
+
+describe.skipIf(!hasKey)('headless-agent with real model', () => {
+  it('modifies a temporary workspace and verifies the file outside the agent', async () => {
+    let verified = ''
+    const { stdout } = await runLoaderSmoke({
+      label: 'headless-agent real model',
+      tempDirPrefix: 'headless-agent-real-',
+      binScript,
+      configPath,
+      binArgs: [
+        '--config',
+        configPath,
+        'Read task.txt, replace its complete contents with exactly "value=after" followed by a newline, read it again, and report briefly.',
+      ],
+      tsconfigPath,
+      processTimeoutMs: 120_000,
+      prepare: cwd => writeFile(join(cwd, 'task.txt'), 'value=before\n'),
+      inspect: async (cwd) => { verified = await readFile(join(cwd, 'task.txt'), 'utf8') },
+    })
+    expect(verified).toBe('value=after\n')
+    expect(stdout.trim().length).toBeGreaterThan(0)
+  }, 135_000)
+})
--- a/examples/headless-agent/tests/snapshots/advanced-toolchain/input.json
+++ b/examples/headless-agent/tests/snapshots/advanced-toolchain/input.json
@@ -0,0 +1,7 @@
+{
+  "steps": [
+    { "op": "initialize" },
+    { "op": "newSession" },
+    { "op": "prompt", "text": "Run this advanced flow exactly once: mount a no-op Cordis plugin named snapshot-marker; use run_code to inspect the live dynamic mounts through tools.cordis_inspect; delegate once to a direct spawn child; run one workflow that delegates to another spawn child; unmount dyn-1; then reply with exactly ADVANCED_HEADLESS_OK." }
+  ]
+}
--- a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl
+++ b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl
@@ -0,0 +1,13 @@
+{"type":"session","version":0,"id":"22222222-2222-4222-8222-222222222222","createdAt":1783950001000,"cwd":"/tmp/advanced-headless","parentSession":"11111111-1111-4111-8111-111111111111"}
+{"type":"turn/start","seq":0,"time":1783957884563,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
+{"type":"user/message","seq":1,"time":1783957884563,"data":{"content":[{"type":"text","text":"Reply with exactly DIRECT_CHILD_OK and nothing else."}],"source":{"kind":"user"}},"surfaceOp":"append"}
+{"type":"step/start","seq":2,"time":1783957884564,"data":{"turn":1,"step":1}}
+{"type":"request/header","seq":3,"time":1783957884564,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"assistant/chunk","seq":4,"time":1783950001005,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":5,"time":1783957884564,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"DIRECT_CHILD_OK"}}}
+{"type":"assistant/chunk","seq":6,"time":1783957884564,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"DIRECT_CHILD_OK"}}}}
+{"type":"assistant/chunk","seq":7,"time":1783957884564,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":8,"time":1783957884564,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":9,"time":1783957884564,"data":{"turn":1,"step":1,"content":[{"type":"text","text":"DIRECT_CHILD_OK"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[4,5,6,7,8],"surfaceOp":"append"}
+{"type":"step/end","seq":10,"time":1783957884564,"data":{"turn":1,"step":1}}
+{"type":"turn/end","seq":11,"time":1783957884564,"data":{"turn":1,"reason":{"kind":"completed"}}}
--- a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl
+++ b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl
@@ -0,0 +1,13 @@
+{"type":"session","version":0,"id":"33333333-3333-4333-8333-333333333333","createdAt":1783950002000,"cwd":"/tmp/advanced-headless","parentSession":"11111111-1111-4111-8111-111111111111"}
+{"type":"turn/start","seq":0,"time":1783957884700,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
+{"type":"user/message","seq":1,"time":1783957884700,"data":{"content":[{"type":"text","text":"Reply with exactly WORKFLOW_CHILD_OK and nothing else."}],"source":{"kind":"user"}},"surfaceOp":"append"}
+{"type":"step/start","seq":2,"time":1783957884700,"data":{"turn":1,"step":1}}
+{"type":"request/header","seq":3,"time":1783957884701,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"assistant/chunk","seq":4,"time":1783950002005,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":5,"time":1783957884701,"data":{"turn":1,"step":1,"chunk":{"type":"text-delta","index":0,"text":"WORKFLOW_CHILD_OK"}}}
+{"type":"assistant/chunk","seq":6,"time":1783957884701,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"WORKFLOW_CHILD_OK"}}}}
+{"type":"assistant/chunk","seq":7,"time":1783957884701,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":8,"time":1783957884701,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":9,"time":1783957884701,"data":{"turn":1,"step":1,"content":[{"type":"text","text":"WORKFLOW_CHILD_OK"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[4,5,6,7,8],"surfaceOp":"append"}
+{"type":"step/end","seq":10,"time":1783957884701,"data":{"turn":1,"step":1}}
+{"type":"turn/end","seq":11,"time":1783957884701,"data":{"turn":1,"reason":{"kind":"completed"}}}
--- a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl
+++ b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl
@@ -0,0 +1,64 @@
+{"type":"session","version":0,"id":"11111111-1111-4111-8111-111111111111","createdAt":1783950000000,"cwd":"/tmp/advanced-headless"}
+{"type":"turn/start","seq":0,"time":1783957884479,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
+{"type":"user/message","seq":1,"time":1783957884479,"data":{"content":[{"type":"text","text":"Run this advanced flow exactly once: mount a no-op Cordis plugin named snapshot-marker; use run_code to inspect the live dynamic mounts through tools.cordis_inspect; delegate once to a direct spawn child; run one workflow that delegates to another spawn child; unmount dyn-1; then reply with exactly ADVANCED_HEADLESS_OK."}],"source":{"kind":"user"}},"surfaceOp":"append"}
+{"type":"step/start","seq":2,"time":1783957884486,"data":{"turn":1,"step":1}}
+{"type":"request/header","seq":3,"time":1783957884486,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"assistant/chunk","seq":4,"time":1783950000005,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":5,"time":1783950000006,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-mount","name":"cordis_mount","argumentsDelta":"{\"code\":\"return { name: 'snapshot-marker', apply() {} }\"}"}}}
+{"type":"assistant/chunk","seq":6,"time":1783950000007,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-mount","name":"cordis_mount","arguments":"{\"code\":\"return { name: 'snapshot-marker', apply() {} }\"}"}}}}
+{"type":"assistant/chunk","seq":7,"time":1783950000008,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":8,"time":1783950000009,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":9,"time":1783957884487,"data":{"turn":1,"step":1,"content":[{"type":"tool-call","id":"advanced-mount","name":"cordis_mount","arguments":"{\"code\":\"return { name: 'snapshot-marker', apply() {} }\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[4,5,6,7,8],"surfaceOp":"append"}
+{"type":"tool/call","seq":10,"time":1783957884487,"data":{"turn":1,"step":1,"callId":"advanced-mount","name":"cordis_mount","arguments":"{\"code\":\"return { name: 'snapshot-marker', apply() {} }\"}"}}
+{"type":"tool/result","seq":11,"time":1783957884488,"data":{"turn":1,"step":1,"callId":"advanced-mount","content":[{"type":"text","text":"mounted dyn-1 (plugin \"snapshot-marker\", state: active)"}],"isError":false},"sourceEventSeqs":[10],"surfaceOp":"append"}
+{"type":"step/end","seq":12,"time":1783957884489,"data":{"turn":1,"step":1}}
+{"type":"step/start","seq":13,"time":1783957884489,"data":{"turn":1,"step":2}}
+{"type":"assistant/chunk","seq":14,"time":1783950000015,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":15,"time":1783950000016,"data":{"turn":1,"step":2,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-code","name":"run_code","argumentsDelta":"{\"code\":\"return await tools.cordis_inspect({ what: 'dynamic' })\"}"}}}
+{"type":"assistant/chunk","seq":16,"time":1783950000017,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-code","name":"run_code","arguments":"{\"code\":\"return await tools.cordis_inspect({ what: 'dynamic' })\"}"}}}}
+{"type":"assistant/chunk","seq":17,"time":1783950000018,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":18,"time":1783950000019,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":19,"time":1783957884490,"data":{"turn":1,"step":2,"content":[{"type":"tool-call","id":"advanced-code","name":"run_code","arguments":"{\"code\":\"return await tools.cordis_inspect({ what: 'dynamic' })\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[14,15,16,17,18],"surfaceOp":"append"}
+{"type":"tool/call","seq":20,"time":1783957884490,"data":{"turn":1,"step":2,"callId":"advanced-code","name":"run_code","arguments":"{\"code\":\"return await tools.cordis_inspect({ what: 'dynamic' })\"}"}}
+{"type":"tool/code-dispatch","seq":21,"time":1783957884560,"data":{"parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"dynamic"},"isError":false,"resultSummary":"## dynamic\n- dyn-1: snapshot-marker [active]"}}
+{"type":"tool/result","seq":22,"time":1783957884561,"data":{"turn":1,"step":2,"callId":"advanced-code","content":[{"type":"text","text":"## dynamic\n- dyn-1: snapshot-marker [active]"}],"isError":false,"meta":{"logs":[]}},"sourceEventSeqs":[20],"surfaceOp":"append"}
+{"type":"step/end","seq":23,"time":1783957884561,"data":{"turn":1,"step":2}}
+{"type":"step/start","seq":24,"time":1783957884562,"data":{"turn":1,"step":3}}
+{"type":"assistant/chunk","seq":25,"time":1783950000026,"data":{"turn":1,"step":3,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":26,"time":1783950000027,"data":{"turn":1,"step":3,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-direct-child","name":"subagent","argumentsDelta":"{\"description\":\"Check direct child\",\"prompt\":\"Reply with exactly DIRECT_CHILD_OK and nothing else.\"}"}}}
+{"type":"assistant/chunk","seq":27,"time":1783950000028,"data":{"turn":1,"step":3,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-direct-child","name":"subagent","arguments":"{\"description\":\"Check direct child\",\"prompt\":\"Reply with exactly DIRECT_CHILD_OK and nothing else.\"}"}}}}
+{"type":"assistant/chunk","seq":28,"time":1783950000029,"data":{"turn":1,"step":3,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":29,"time":1783950000030,"data":{"turn":1,"step":3,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":30,"time":1783957884562,"data":{"turn":1,"step":3,"content":[{"type":"tool-call","id":"advanced-direct-child","name":"subagent","arguments":"{\"description\":\"Check direct child\",\"prompt\":\"Reply with exactly DIRECT_CHILD_OK and nothing else.\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[25,26,27,28,29],"surfaceOp":"append"}
+{"type":"tool/call","seq":31,"time":1783957884562,"data":{"turn":1,"step":3,"callId":"advanced-direct-child","name":"subagent","arguments":"{\"description\":\"Check direct child\",\"prompt\":\"Reply with exactly DIRECT_CHILD_OK and nothing else.\"}"}}
+{"type":"tool/result","seq":32,"time":1783957884593,"data":{"turn":1,"step":3,"callId":"advanced-direct-child","content":[{"type":"text","text":"DIRECT_CHILD_OK"}],"isError":false},"sourceEventSeqs":[31],"surfaceOp":"append"}
+{"type":"step/end","seq":33,"time":1783957884593,"data":{"turn":1,"step":3}}
+{"type":"step/start","seq":34,"time":1783957884594,"data":{"turn":1,"step":4}}
+{"type":"assistant/chunk","seq":35,"time":1783957884594,"data":{"turn":1,"step":4,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":36,"time":1783957884594,"data":{"turn":1,"step":4,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-workflow","name":"workflow","argumentsDelta":"{\"script\":\"phase('Delegate')\\nconst reply = await agent('Reply with exactly WORKFLOW_CHILD_OK and nothing else.', { label: 'workflow-child' })\\nreturn { reply }\",\"meta\":{\"name\":\"advanced-headless-snapshot\",\"description\":\"exercise one workflow child through the headless agent\"}}"}}}
+{"type":"assistant/chunk","seq":37,"time":1783957884594,"data":{"turn":1,"step":4,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-workflow","name":"workflow","arguments":"{\"script\":\"phase('Delegate')\\nconst reply = await agent('Reply with exactly WORKFLOW_CHILD_OK and nothing else.', { label: 'workflow-child' })\\nreturn { reply }\",\"meta\":{\"name\":\"advanced-headless-snapshot\",\"description\":\"exercise one workflow child through the headless agent\"}}"}}}}
+{"type":"assistant/chunk","seq":38,"time":1783957884594,"data":{"turn":1,"step":4,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":39,"time":1783957884594,"data":{"turn":1,"step":4,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":40,"time":1783957884594,"data":{"turn":1,"step":4,"content":[{"type":"tool-call","id":"advanced-workflow","name":"workflow","arguments":"{\"script\":\"phase('Delegate')\\nconst reply = await agent('Reply with exactly WORKFLOW_CHILD_OK and nothing else.', { label: 'workflow-child' })\\nreturn { reply }\",\"meta\":{\"name\":\"advanced-headless-snapshot\",\"description\":\"exercise one workflow child through the headless agent\"}}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[35,36,37,38,39],"surfaceOp":"append"}
+{"type":"tool/call","seq":41,"time":1783957884594,"data":{"turn":1,"step":4,"callId":"advanced-workflow","name":"workflow","arguments":"{\"script\":\"phase('Delegate')\\nconst reply = await agent('Reply with exactly WORKFLOW_CHILD_OK and nothing else.', { label: 'workflow-child' })\\nreturn { reply }\",\"meta\":{\"name\":\"advanced-headless-snapshot\",\"description\":\"exercise one workflow child through the headless agent\"}}"}}
+{"type":"tool/result","seq":42,"time":1783957884717,"data":{"turn":1,"step":4,"callId":"advanced-workflow","content":[{"type":"text","text":"workflow \"advanced-headless-snapshot\" completed (1 agent).\nReturn value:\n{\n  \"reply\": \"WORKFLOW_CHILD_OK\"\n}"}],"isError":false},"sourceEventSeqs":[41],"surfaceOp":"append"}
+{"type":"step/end","seq":43,"time":1783957884718,"data":{"turn":1,"step":4}}
+{"type":"step/start","seq":44,"time":1783957884718,"data":{"turn":1,"step":5}}
+{"type":"assistant/chunk","seq":45,"time":1783957884719,"data":{"turn":1,"step":5,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":46,"time":1783957884719,"data":{"turn":1,"step":5,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-unmount","name":"cordis_unmount","argumentsDelta":"{\"id\":\"dyn-1\"}"}}}
+{"type":"assistant/chunk","seq":47,"time":1783957884719,"data":{"turn":1,"step":5,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-unmount","name":"cordis_unmount","arguments":"{\"id\":\"dyn-1\"}"}}}}
+{"type":"assistant/chunk","seq":48,"time":1783957884719,"data":{"turn":1,"step":5,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":49,"time":1783957884719,"data":{"turn":1,"step":5,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":50,"time":1783957884719,"data":{"turn":1,"step":5,"content":[{"type":"tool-call","id":"advanced-unmount","name":"cordis_unmount","arguments":"{\"id\":\"dyn-1\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[45,46,47,48,49],"surfaceOp":"append"}
+{"type":"tool/call","seq":51,"time":1783957884719,"data":{"turn":1,"step":5,"callId":"advanced-unmount","name":"cordis_unmount","arguments":"{\"id\":\"dyn-1\"}"}}
+{"type":"tool/result","seq":52,"time":1783957884719,"data":{"turn":1,"step":5,"callId":"advanced-unmount","content":[{"type":"text","text":"unmounted dyn-1 (plugin \"snapshot-marker\")"}],"isError":false},"sourceEventSeqs":[51],"surfaceOp":"append"}
+{"type":"step/end","seq":53,"time":1783957884719,"data":{"turn":1,"step":5}}
+{"type":"step/start","seq":54,"time":1783957884720,"data":{"turn":1,"step":6}}
+{"type":"assistant/chunk","seq":55,"time":1783957884720,"data":{"turn":1,"step":6,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":56,"time":1783957884720,"data":{"turn":1,"step":6,"chunk":{"type":"text-delta","index":0,"text":"ADVANCED_HEADLESS_OK"}}}
+{"type":"assistant/chunk","seq":57,"time":1783957884720,"data":{"turn":1,"step":6,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"ADVANCED_HEADLESS_OK"}}}}
+{"type":"assistant/chunk","seq":58,"time":1783957884720,"data":{"turn":1,"step":6,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":59,"time":1783957884720,"data":{"turn":1,"step":6,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":60,"time":1783957884720,"data":{"turn":1,"step":6,"content":[{"type":"text","text":"ADVANCED_HEADLESS_OK"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[55,56,57,58,59],"surfaceOp":"append"}
+{"type":"step/end","seq":61,"time":1783957884721,"data":{"turn":1,"step":6}}
+{"type":"turn/end","seq":62,"time":1783957884721,"data":{"turn":1,"reason":{"kind":"completed"}}}
--- a/examples/headless-agent/tests/snapshots/advanced-toolchain/stream-json.golden.jsonl
+++ b/examples/headless-agent/tests/snapshots/advanced-toolchain/stream-json.golden.jsonl
@@ -0,0 +1,64 @@
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"turn/start","seq":0,"time":0,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"user/message","seq":1,"time":0,"data":{"content":[{"type":"text","text":"Run this advanced flow exactly once: mount a no-op Cordis plugin named snapshot-marker; use run_code to inspect the live dynamic mounts through tools.cordis_inspect; delegate once to a direct spawn child; run one workflow that delegates to another spawn child; unmount dyn-1; then reply with exactly ADVANCED_HEADLESS_OK."}],"source":{"kind":"user"}},"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/start","seq":2,"time":0,"data":{"turn":1,"step":1}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"request/header","seq":3,"time":0,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":4,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":5,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-mount","name":"cordis_mount","argumentsDelta":"{\"code\":\"return { name: 'snapshot-marker', apply() {} }\"}"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":6,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-mount","name":"cordis_mount","arguments":"{\"code\":\"return { name: 'snapshot-marker', apply() {} }\"}"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":7,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":8,"time":0,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":9,"time":0,"data":{"turn":1,"step":1,"content":[{"type":"tool-call","id":"advanced-mount","name":"cordis_mount","arguments":"{\"code\":\"return { name: 'snapshot-marker', apply() {} }\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[4,5,6,7,8],"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/call","seq":10,"time":0,"data":{"turn":1,"step":1,"callId":"advanced-mount","name":"cordis_mount","arguments":"{\"code\":\"return { name: 'snapshot-marker', apply() {} }\"}"}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/result","seq":11,"time":0,"data":{"turn":1,"step":1,"callId":"advanced-mount","content":[{"type":"text","text":"mounted dyn-1 (plugin \"snapshot-marker\", state: active)"}],"isError":false},"sourceEventSeqs":[10],"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":12,"time":0,"data":{"turn":1,"step":1}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/start","seq":13,"time":0,"data":{"turn":1,"step":2}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":14,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":15,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-code","name":"run_code","argumentsDelta":"{\"code\":\"return await tools.cordis_inspect({ what: 'dynamic' })\"}"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":16,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-code","name":"run_code","arguments":"{\"code\":\"return await tools.cordis_inspect({ what: 'dynamic' })\"}"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":17,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":18,"time":0,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":19,"time":0,"data":{"turn":1,"step":2,"content":[{"type":"tool-call","id":"advanced-code","name":"run_code","arguments":"{\"code\":\"return await tools.cordis_inspect({ what: 'dynamic' })\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[14,15,16,17,18],"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/call","seq":20,"time":0,"data":{"turn":1,"step":2,"callId":"advanced-code","name":"run_code","arguments":"{\"code\":\"return await tools.cordis_inspect({ what: 'dynamic' })\"}"}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/code-dispatch","seq":21,"time":0,"data":{"parentCallId":"advanced-code","subCallId":"advanced-code:code:1","name":"cordis_inspect","arguments":{"what":"dynamic"},"isError":false,"resultSummary":"## dynamic\n- dyn-1: snapshot-marker [active]"}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/result","seq":22,"time":0,"data":{"turn":1,"step":2,"callId":"advanced-code","content":[{"type":"text","text":"## dynamic\n- dyn-1: snapshot-marker [active]"}],"isError":false,"meta":{"logs":[]}},"sourceEventSeqs":[20],"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":23,"time":0,"data":{"turn":1,"step":2}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/start","seq":24,"time":0,"data":{"turn":1,"step":3}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":25,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":26,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-direct-child","name":"subagent","argumentsDelta":"{\"description\":\"Check direct child\",\"prompt\":\"Reply with exactly DIRECT_CHILD_OK and nothing else.\"}"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":27,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-direct-child","name":"subagent","arguments":"{\"description\":\"Check direct child\",\"prompt\":\"Reply with exactly DIRECT_CHILD_OK and nothing else.\"}"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":28,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":29,"time":0,"data":{"turn":1,"step":3,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":30,"time":0,"data":{"turn":1,"step":3,"content":[{"type":"tool-call","id":"advanced-direct-child","name":"subagent","arguments":"{\"description\":\"Check direct child\",\"prompt\":\"Reply with exactly DIRECT_CHILD_OK and nothing else.\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[25,26,27,28,29],"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/call","seq":31,"time":0,"data":{"turn":1,"step":3,"callId":"advanced-direct-child","name":"subagent","arguments":"{\"description\":\"Check direct child\",\"prompt\":\"Reply with exactly DIRECT_CHILD_OK and nothing else.\"}"}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/result","seq":32,"time":0,"data":{"turn":1,"step":3,"callId":"advanced-direct-child","content":[{"type":"text","text":"DIRECT_CHILD_OK"}],"isError":false},"sourceEventSeqs":[31],"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":33,"time":0,"data":{"turn":1,"step":3}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/start","seq":34,"time":0,"data":{"turn":1,"step":4}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":35,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":36,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-workflow","name":"workflow","argumentsDelta":"{\"script\":\"phase('Delegate')\\nconst reply = await agent('Reply with exactly WORKFLOW_CHILD_OK and nothing else.', { label: 'workflow-child' })\\nreturn { reply }\",\"meta\":{\"name\":\"advanced-headless-snapshot\",\"description\":\"exercise one workflow child through the headless agent\"}}"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":37,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-workflow","name":"workflow","arguments":"{\"script\":\"phase('Delegate')\\nconst reply = await agent('Reply with exactly WORKFLOW_CHILD_OK and nothing else.', { label: 'workflow-child' })\\nreturn { reply }\",\"meta\":{\"name\":\"advanced-headless-snapshot\",\"description\":\"exercise one workflow child through the headless agent\"}}"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":38,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":39,"time":0,"data":{"turn":1,"step":4,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":40,"time":0,"data":{"turn":1,"step":4,"content":[{"type":"tool-call","id":"advanced-workflow","name":"workflow","arguments":"{\"script\":\"phase('Delegate')\\nconst reply = await agent('Reply with exactly WORKFLOW_CHILD_OK and nothing else.', { label: 'workflow-child' })\\nreturn { reply }\",\"meta\":{\"name\":\"advanced-headless-snapshot\",\"description\":\"exercise one workflow child through the headless agent\"}}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[35,36,37,38,39],"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/call","seq":41,"time":0,"data":{"turn":1,"step":4,"callId":"advanced-workflow","name":"workflow","arguments":"{\"script\":\"phase('Delegate')\\nconst reply = await agent('Reply with exactly WORKFLOW_CHILD_OK and nothing else.', { label: 'workflow-child' })\\nreturn { reply }\",\"meta\":{\"name\":\"advanced-headless-snapshot\",\"description\":\"exercise one workflow child through the headless agent\"}}"}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/result","seq":42,"time":0,"data":{"turn":1,"step":4,"callId":"advanced-workflow","content":[{"type":"text","text":"workflow \"advanced-headless-snapshot\" completed (1 agent).\nReturn value:\n{\n  \"reply\": \"WORKFLOW_CHILD_OK\"\n}"}],"isError":false},"sourceEventSeqs":[41],"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":43,"time":0,"data":{"turn":1,"step":4}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/start","seq":44,"time":0,"data":{"turn":1,"step":5}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":45,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":46,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"tool-call-delta","index":0,"id":"advanced-unmount","name":"cordis_unmount","argumentsDelta":"{\"id\":\"dyn-1\"}"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":47,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"advanced-unmount","name":"cordis_unmount","arguments":"{\"id\":\"dyn-1\"}"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":48,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":49,"time":0,"data":{"turn":1,"step":5,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":50,"time":0,"data":{"turn":1,"step":5,"content":[{"type":"tool-call","id":"advanced-unmount","name":"cordis_unmount","arguments":"{\"id\":\"dyn-1\"}"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[45,46,47,48,49],"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/call","seq":51,"time":0,"data":{"turn":1,"step":5,"callId":"advanced-unmount","name":"cordis_unmount","arguments":"{\"id\":\"dyn-1\"}"}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"tool/result","seq":52,"time":0,"data":{"turn":1,"step":5,"callId":"advanced-unmount","content":[{"type":"text","text":"unmounted dyn-1 (plugin \"snapshot-marker\")"}],"isError":false},"sourceEventSeqs":[51],"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":53,"time":0,"data":{"turn":1,"step":5}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/start","seq":54,"time":0,"data":{"turn":1,"step":6}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":55,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":56,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"text-delta","index":0,"text":"ADVANCED_HEADLESS_OK"}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":57,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"ADVANCED_HEADLESS_OK"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":58,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/chunk","seq":59,"time":0,"data":{"turn":1,"step":6,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"assistant/message","seq":60,"time":0,"data":{"turn":1,"step":6,"content":[{"type":"text","text":"ADVANCED_HEADLESS_OK"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[55,56,57,58,59],"surfaceOp":"append"}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"step/end","seq":61,"time":0,"data":{"turn":1,"step":6}}}
+{"type":"session_event","sessionId":"{{sessionId}}","event":{"type":"turn/end","seq":62,"time":0,"data":{"turn":1,"reason":{"kind":"completed"}}}}
+{"type":"result","success":true,"sessionId":"{{sessionId}}","turn":1,"result":"ADVANCED_HEADLESS_OK","reason":{"kind":"completed"},"usage":{"inputTokens":18,"outputTokens":18}}
--- a/examples/package.json
+++ b/examples/package.json
@@ -10,6 +10,7 @@
    "@deepseek-ai/dsh-acp-demo": "workspace:*",
    "@deepseek-ai/dsh-bash-local": "workspace:*",
    "@deepseek-ai/dsh-bash-sandbox": "workspace:*",
+    "@deepseek-ai/dsh-cli-demo": "workspace:*",
    "@deepseek-ai/dsh-code-runtime-worker": "workspace:*",
    "@deepseek-ai/dsh-compact-basic": "workspace:*",
    "@deepseek-ai/dsh-fs-local": "workspace:*",
--- a/examples/repl-agent/README.md
+++ b/examples/repl-agent/README.md
@@ -1,6 +1,6 @@
 # repl-agent

-The repl-agent wiring: DeepSeek V4 + the `read`/`write`/`edit` filesystem tools + the bash tool suite + subagent delegation + `todo_write` + readline chat + JSONL persistence, loaded from `cordis.yml`. The sibling [`tui-agent`](../tui-agent/README.md) fixes the same agent composition to the full-screen terminal front door.
+The repl-agent wiring: DeepSeek V4 + the `read`/`write`/`edit` filesystem tools + the bash tool suite + subagent delegation + workflows + `todo_write` + readline chat + JSONL persistence, loaded from `cordis.yml`. The sibling [`tui-agent`](../tui-agent/README.md) fixes the same agent composition to the full-screen terminal front door.

 ## Run it

@@ -52,6 +52,7 @@ This example is a thin leaf `cordis.yml`: it picks the swappable backends, loads
 | `stdio-agent` (`@deepseek-ai/dsh-stdio-demo`) | the app bundle: the agent-spine demo + JSONL persistence + the configured terminal channel + a pre-created `main` agent. This leaf fixes `ui.mode` to `readline`; `tui-agent` owns the corresponding TUI leaf |
 | `subagent`, `subagent-spawn`, `subagent-fork` | the subagent provider registry plus the two in-process backends: a fresh child and a child seeded with the parent's completed-turn prefix |
 | `tool-subagent`, `tool-subagent-fork` | two model-facing `dsh-tool-subagent` loads, each bound to a different provider and exposed under a distinct tool name (`subagent`, `subagent_fork`) |
+| `workflow-workerthread`, `tool-workflow` | the worker-thread workflow engine and its model-facing `workflow` tool, with child calls routed through the spawn backend |
 | `tool-todo` | the model-facing `todo_write` tool; writes the whole task list to the session log and renders as a persistent TUI plan or readline checklist |
 | `fs-local`, `fs-policy`, `tool-fs` | the filesystem stack: the local `ctx.fs` provider, the read-before-write/edit policy gate (on the `fs/*` event gate), and the model-facing `read`/`write`/`edit` tools. Relative paths resolve against the session workspace |

@@ -63,4 +64,4 @@ This example is a thin leaf `cordis.yml`: it picks the swappable backends, loads
 - `tests/compaction.e2e.ts` — the compaction smoke: a real multi-step bash task runs with a deliberately tiny context window so the auto-compaction listener fires MID-SESSION. Verifies the WORLD — a `compact/start…end` pair landed in the real log, the surface shrank (a replace node shadowed older nodes), and the agent still produced a correct final answer after compaction.
 - `tests/todo-write.e2e.ts` — a real model drives the real `todo_write` tool and the test verifies the resulting `todo/write` session event.

-These self-skip without `DEEPSEEK_API_KEY`. `tests/code-mode.e2e.ts` is the with-key Code Mode proof — a real model, a two-tool task, asserting the wire tool list was exactly `[run_code]`, the `tool/code-dispatch` events landed under the parent call, and the curated answer came back. The keyless boot smokes run in the default e2e gate: `tests/keyless-smoke.e2e.ts` (the full real tree, dummy key, no prompt → no model call) and `tests/code-mode-keyless-smoke.e2e.ts` (the same guard for the Code Mode overlay).
+These self-skip without `DEEPSEEK_API_KEY`. `tests/code-mode.e2e.ts` is the with-key Code Mode proof — a real model, a two-tool task, asserting the wire tool list was exactly `[run_code]`, the `tool/code-dispatch` events landed under the parent call, and the curated answer came back. The keyless Loader smokes run in the default e2e gate: `tests/keyless-smoke.e2e.ts` and `tests/code-mode-keyless-smoke.e2e.ts`.
--- a/knip.json
+++ b/knip.json
@@ -10,6 +10,7 @@
    "examples": {
      "entry": [
        "echo-agent/src/*.ts",
+        "headless-agent/tests/fixtures/cli-mock-llm.ts",
        "tui-agent/tests/fixtures/tui-scripted-llm.ts",
        "*/tests/**/*.e2e.ts",
        "*/tests/**/*.snapshot.ts"
@@ -114,6 +115,10 @@
      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
      "project": ["src/**/*.ts", "tests/**/*.ts"]
    },
+    "packages/examples/cli-demo": {
+      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
+      "project": ["src/**/*.ts", "tests/**/*.ts"]
+    },
    "packages/ui/stdio": {
      "entry": ["tests/**/*.spec.ts"],
      "project": ["src/**/*.ts", "tests/**/*.ts"]
--- a/package.json
+++ b/package.json
@@ -80,6 +80,7 @@
    "hygiene": "pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-cordis-config && pnpm run verify-node-next-types && pnpm run verify-runtime-closure",
    "demo:echo": "node --expose-internals --import tsx packages/examples/stdio-demo/src/bin.ts examples/echo-agent/cordis.yml",
    "demo:repl": "node --expose-internals --import tsx packages/examples/stdio-demo/src/bin.ts examples/repl-agent/cordis.yml",
+    "demo:headless": "node --expose-internals --import tsx packages/examples/cli-demo/src/bin.ts --config examples/headless-agent/cordis.yml",
    "demo:tui": "node --expose-internals --import tsx packages/examples/stdio-demo/src/bin.ts examples/tui-agent/cordis.yml",
    "demo:code-mode": "node scripts/demo-code-mode.mjs",
    "demo:cordis": "node --expose-internals --import tsx packages/examples/stdio-demo/src/bin.ts examples/cordis-agent/cordis.yml",
--- a/packages/README.md
+++ b/packages/README.md
@@ -31,8 +31,8 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 | [`session-query/`](session-query/README.md) | Session retrieval: logical corpus, bounded reads, lineage, and event relationships | Product — stable surface |
 | [`sdk/`](sdk/README.md) | Project SDK tooling | Product — stable surface |
 | [`ui/`](ui/README.md) | Editor/client integration surfaces: ACP bridge, JSON-RPC SDK server, user-approval/user-interaction seams, ask-user tool | Product — stable surface |
-| [`examples/`](examples/README.md) | Demo bundles (agent-spine + stdio/ACP/JSON-RPC bins) the leaves load | Support — example infra |
-| [`support/`](support/README.md) | Support infrastructure (testkits, invariants, replay, Loader smokes, subagent mock) | Support — lower compatibility expectations |
+| [`examples/`](examples/README.md) | Demo bundles (agent-spine + stdio/one-shot CLI/ACP/JSON-RPC bins) the leaves load | Support — example infra |
+| [`support/`](support/README.md) | Support infrastructure (testkits, invariants, replay, Loader smokes) | Support — lower compatibility expectations |
 | [`util/`](util/README.md) | Low-level zero-dependency utilities shared across groups (`Branded<B>`, Harness home/path helpers, timeout, retention) | Support — small, stable, harness-dep-free |

 Groups distinguish product API from support infrastructure. New packages join an existing group; a new group updates its README and this table.
--- a/packages/core/agent/README.md
+++ b/packages/core/agent/README.md
@@ -26,7 +26,7 @@ The scoped-registration surface: `Agent.ctx` is the agent's scope context (`dsh-
 - `ctx.agents.withInitiator(agent, operation)` — run with one exact Agent and preserve the operation's exact synchronous value or Promise.
 - `ctx.agents.withoutInitiator(operation)` — hide an inherited initiator for unrelated process-local work.

-The scope carries the `Agent` itself and is process-local. Ambient presence is neither liveness proof nor authorization; explicit Agent fields remain authoritative at service, worker, process, persistence, and wire boundaries. Teardown rejects new boundaries, lets injected dependents and returned-Promise boundaries drain, then disables the underlying `AsyncLocalStorage`; unreturned work remains owned by the subsystem that detached it. The [initiator-scope decision](../../../docs/rfc/implemented/architecture/2026-07-15-agent-initiator-scope.md) owns the detailed boundary and teardown contract.
+The scope carries the `Agent` itself and is process-local. Ambient presence is neither liveness proof nor authorization; explicit Agent fields remain authoritative at service, worker, process, persistence, and wire boundaries. Teardown rejects new boundaries, lets injected dependents and returned-Promise boundaries drain, then disables the underlying `AsyncLocalStorage`; unreturned work remains owned by the subsystem that detached it. If a boundary's inherited async chain starts an owning Cordis fiber's unload, that nested boundary chain is released from the drain so the unload cannot wait on itself; its continuations observe the disposed service after teardown. The [initiator-scope decision](../../../docs/rfc/implemented/architecture/2026-07-15-agent-initiator-scope.md) owns the detailed boundary and teardown contract.

 #### Factory seam (creation)

--- a/packages/core/agent/src/index.ts
+++ b/packages/core/agent/src/index.ts
@@ -5,7 +5,8 @@
 * @module @deepseek-ai/dsh-agent
 */

-import { Context, getTraceable, Service, symbols } from 'cordis'
+import { Context, FiberState, getTraceable, Service, symbols } from 'cordis'
+import type { Fiber } from 'cordis'
 import { AsyncLocalStorage } from 'node:async_hooks'
 import { isPromise } from 'node:util/types'
 import { scopeTarget } from '@deepseek-ai/dsh-scope'
@@ -190,6 +191,12 @@ interface AgentEntry {
  detachRequested: boolean
 }

+/** One tracked boundary plus its inherited nesting chain. */
+interface InitiatorRun {
+  active: boolean
+  readonly parent: InitiatorRun | undefined
+}
+
 /** Plain holder prevents Cordis from tracing the factory field before the caller context is known. */
 interface FactorySlot {
  readonly target: AgentFactory
@@ -205,6 +212,7 @@ export class AgentRegistry extends Service {
  private store = new Map<SessionId, AgentEntry>()
  private factory: FactorySlot | undefined
  private readonly initiators = new AsyncLocalStorage<Agent | undefined>()
+  private readonly initiatorRuns = new AsyncLocalStorage<InitiatorRun>()
  private initiatorState: 'active' | 'closing' | 'disposed' = 'active'
  private activeInitiatorRuns = 0
  private initiatorDrain: PromiseWithResolvers<void> | undefined
@@ -219,6 +227,11 @@ export class AgentRegistry extends Service {
    // accessor body never needs to resolve a scope itself. Effect-scoped:
    // unwinds with this service's fiber.
    ctx.accessor('agent', { get: () => undefined })
+    ctx.on('internal/status', (fiber) => {
+      if (fiber.state === FiberState.UNLOADING && this.hasLifecycleAncestor(fiber)) {
+        this.closeInitiators()
+      }
+    })
    ctx.effect(function* (this: AgentRegistry) {
      yield () => this.disposeInitiators()
      yield () => { this.closeInitiators() }
@@ -249,6 +262,8 @@ export class AgentRegistry extends Service {
  /**
   * Run an operation with one exact Agent as its process-local initiator. The
   * exact synchronous value or Promise returned by the operation is preserved.
+   * If its inherited async chain starts an owning-fiber unload, the nested
+   * boundary lineage is excluded from the drain so teardown cannot wait on itself.
   * @param agent - initiating Agent to inherit; presence is neither liveness proof nor authorization.
   * @param operation - synchronous or asynchronous operation to invoke.
   * @returns the exact value returned by `operation`.
@@ -261,6 +276,8 @@ export class AgentRegistry extends Service {
  /**
   * Run an operation inside a boundary that hides any inherited initiating
   * Agent. The exact synchronous value or Promise is preserved.
+   * If its inherited async chain starts an owning-fiber unload, the nested
+   * boundary lineage is excluded from the drain so teardown cannot wait on itself.
   * @param operation - synchronous or asynchronous operation to invoke without an initiator.
   * @returns the exact value returned by `operation`.
   * @throws when the initiator scope is closing/disposed, or when `operation` throws.
@@ -537,42 +554,77 @@ export class AgentRegistry extends Service {
  private disposeInitiators(): Promise<void> {
    return (this.initiatorDisposal ??= (async () => {
      this.closeInitiators()
+      this.releaseReentrantInitiatorRuns()
      if (this.activeInitiatorRuns !== 0) {
        this.initiatorDrain ??= Promise.withResolvers<void>()
        await this.initiatorDrain.promise
      }
      this.initiatorState = 'disposed'
      this.initiators.disable()
+      this.initiatorRuns.disable()
    })())
  }

  /** Establish one tracked initiator or clearing boundary. */
  private runWithInitiator<T>(agent: Agent | undefined, operation: () => T): T {
    if (this.initiatorState !== 'active') throw new Error(DISPOSED_INITIATOR_MESSAGE)
+    const run: InitiatorRun = {
+      active: true,
+      parent: this.initiatorRuns.getStore(),
+    }
    this.activeInitiatorRuns += 1
    let result: T
    try {
-      result = this.initiators.run(agent, operation)
+      result = this.initiatorRuns.run(run, () => this.initiators.run(agent, operation))
    } catch (error: unknown) {
-      this.releaseInitiatorRun()
+      this.releaseInitiatorRun(run)
      throw error
    }
    if (isPromise(result)) {
-      void result.then(
-        () => { this.releaseInitiatorRun() },
-        () => { this.releaseInitiatorRun() },
-      )
+      try {
+        void Promise.prototype.then.call(
+          result,
+          () => { this.releaseInitiatorRun(run) },
+          () => { this.releaseInitiatorRun(run) },
+        )
+      } catch {
+        // A branded Promise may expose a failing @@species. Observer setup did
+        // not attach, so preserve the exact return without leaking the run.
+        this.releaseInitiatorRun(run)
+      }
    } else {
-      this.releaseInitiatorRun()
+      this.releaseInitiatorRun(run)
    }
    return result
  }

+  /** Whether one unloading fiber owns this service's lifecycle. */
+  private hasLifecycleAncestor(candidate: Fiber): boolean {
+    let fiber = this.ctx.fiber
+    while (true) {
+      if (fiber === candidate) return true
+      const parent = fiber.parent.fiber
+      if (parent === fiber) return false
+      fiber = parent
+    }
+  }
+
  private assertInitiatorsReadable(): void {
    if (this.initiatorState === 'disposed') throw new Error(DISPOSED_INITIATOR_MESSAGE)
  }

-  private releaseInitiatorRun(): void {
+  /** Exclude the boundary chain that initiated this teardown from its own drain. */
+  private releaseReentrantInitiatorRuns(): void {
+    let run = this.initiatorRuns.getStore()
+    while (run !== undefined) {
+      this.releaseInitiatorRun(run)
+      run = run.parent
+    }
+  }
+
+  private releaseInitiatorRun(run: InitiatorRun): void {
+    if (!run.active) return
+    run.active = false
    this.activeInitiatorRuns -= 1
    if (this.activeInitiatorRuns !== 0) return
    this.initiatorDrain?.resolve()
--- a/packages/core/agent/tests/agent-initiator.spec.ts
+++ b/packages/core/agent/tests/agent-initiator.spec.ts
@@ -23,6 +23,17 @@ async function harness(): Promise<{
  }
 }

+/** Fail a lifecycle regression promptly instead of waiting for Vitest's suite timeout. */
+async function promptly<T>(task: Promise<T>): Promise<T> {
+  const timeout = Promise.withResolvers<never>()
+  const timer = setTimeout(() => { timeout.reject(new Error('initiator teardown did not settle promptly')) }, 1000)
+  try {
+    return await Promise.race([task, timeout.promise])
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
 describe('AgentRegistry initiator scope', () => {
  it('reports an absent initiator and requires an active boundary', async () => {
    const { service, dispose } = await harness()
@@ -52,6 +63,44 @@ describe('AgentRegistry initiator scope', () => {
    await dispose()
  })

+  it('tracks a branded Promise without calling its overridable then property', async () => {
+    const { service, dispose } = await harness()
+    const initiator = agent('overridden-then')
+    const release = Promise.withResolvers<boolean>()
+    void Object.defineProperty(release.promise, 'then', {
+      value: () => { throw new Error('overridden then called') },
+    })
+
+    const pending = service.withInitiator(initiator, () => release.promise)
+    expect(pending).toBe(release.promise)
+
+    let disposed = false
+    const disposal = dispose().then(() => { disposed = true })
+    await Promise.resolve()
+    expect(disposed).toBe(false)
+
+    release.resolve(true)
+    await new Promise<void>((resolve, reject) => {
+      void Promise.prototype.then.call(pending, resolve, reject)
+    })
+    await disposal
+    expect(disposed).toBe(true)
+  })
+
+  it('preserves a settled branded Promise when its species blocks observer construction', async () => {
+    const { service, dispose } = await harness()
+    const initiator = agent('invalid-species')
+    const promise = Promise.resolve()
+    const constructor = {}
+    Object.defineProperty(constructor, Symbol.species, {
+      get: () => { throw new Error('invalid species') },
+    })
+    void Object.defineProperty(promise, 'constructor', { value: constructor })
+
+    expect(service.withInitiator(initiator, () => promise)).toBe(promise)
+    await dispose()
+  })
+
  it('isolates overlapping initiators', async () => {
    const { service, dispose } = await harness()
    const a = agent('a')
@@ -160,4 +209,57 @@ describe('AgentRegistry initiator scope', () => {
    await disposal
    expect(disposed).toBe(true)
  })
+
+  it('does not self-deadlock when a boundary returns service disposal', async () => {
+    const { service, dispose } = await harness()
+    const initiator = agent('service-disposer')
+
+    const returned = service.withInitiator(initiator, dispose)
+    await promptly(returned)
+
+    expect(() => service.currentInitiator()).toThrow('agent initiator scope is disposed')
+  })
+
+  it('does not self-deadlock when nested boundaries return ancestor disposal', async () => {
+    const { ctx, service } = await harness()
+    const parent = agent('parent-disposer')
+    const child = agent('child-disposer')
+    let disposal: Promise<void> | undefined
+
+    const returned = service.withInitiator(parent, () => service.withInitiator(child, () => {
+      disposal = ctx.fiber.dispose()
+      return disposal
+    }))
+    expect(returned).toBe(disposal)
+
+    await promptly(returned)
+    expect(() => service.currentInitiator()).toThrow('agent initiator scope is disposed')
+  })
+
+  it('excludes an asynchronous teardown initiator while draining unrelated boundaries', async () => {
+    const { ctx, service } = await harness()
+    const initiator = agent('async-disposer')
+    const unrelated = agent('unrelated')
+    const release = Promise.withResolvers<boolean>()
+    const pending = service.withInitiator(unrelated, async () => {
+      await release.promise
+      expect(service.requireInitiator()).toBe(unrelated)
+    })
+
+    const returned = service.withInitiator(initiator, async () => {
+      await Promise.resolve()
+      await ctx.fiber.dispose()
+    })
+    let disposed = false
+    void returned.then(() => { disposed = true })
+    await Promise.resolve()
+    await Promise.resolve()
+    expect(disposed).toBe(false)
+
+    release.resolve(true)
+    await pending
+    await promptly(returned)
+
+    expect(() => service.currentInitiator()).toThrow('agent initiator scope is disposed')
+  })
 })
--- a/packages/examples/README.md
+++ b/packages/examples/README.md
@@ -6,10 +6,11 @@ Pre-composed plugin bundles a thin leaf `cordis.yml` loads instead of assembling
 |---|---|---|
 | `agent-spine-demo/` | `@deepseek-ai/dsh-agent-spine-demo` | The executor-less/UI-less agent spine as one bundle plugin (`timer` + `llm` + sessions + system-prompt + tools + skills + agents + invariants + `tool-bash` + workspace-context + `tool-skill` + `agent-loop`) |
 | `stdio-demo/` | `@deepseek-ai/dsh-stdio-demo` | Terminal chat app: the spine + JSONL persistence + TTY-selected `dsh-tui`/`dsh-stdio` front door + a pre-created `main` agent, with a boot `bin` |
+| `cli-demo/` | `@deepseek-ai/dsh-cli-demo` | Headless one-shot app: the spine + JSONL persistence + a pre-created `main` agent, with text and DSH-native JSON output |
 | `acp-demo/` | `@deepseek-ai/dsh-acp-demo` | ACP server app: the spine + JSONL persistence + the [`acp`](../ui/acp/README.md) bridge (no stdout logger), with a boot `bin` |
 | `jsonrpc-demo/` | `@deepseek-ai/dsh-jsonrpc-demo` | Bin-only runtime that boots an external `cordis.yml` for the stdio JSON-RPC SDK client |

-`agent-spine-demo` is the shared bundle; `stdio-demo` and `acp-demo` compose it with terminal and ACP front-door clusters and own their boot bins. `jsonrpc-demo` mounts no composition of its own — it boots whatever tree the deployment's `cordis.yml` names, and is what the Python SDK runtime launches.
+`agent-spine-demo` is the shared bundle; `stdio-demo`, `cli-demo`, and `acp-demo` compose it with terminal, headless one-shot, and ACP front doors and own their boot bins. `jsonrpc-demo` mounts no composition of its own — it boots whatever tree the deployment's `cordis.yml` names, and is what the Python SDK runtime launches.

 These are **not** product API. The spine pieces they bundle live in [`core/`](../core/README.md), the bridges/channels/boot-glue in [`ui/`](../ui/README.md), and the swappable backends (LLM adapter, bash executor) in their capability groups; a demo bundle just picks one concrete composition of them. Swap or fork one freely.

--- a/packages/examples/cli-demo/README.md
+++ b/packages/examples/cli-demo/README.md
@@ -0,0 +1,66 @@
+# @deepseek-ai/dsh-cli-demo
+
+Headless one-shot app and bin for running one agent task without a readline or editor client. It composes [`@deepseek-ai/dsh-agent-spine-demo`](../agent-spine-demo/README.md), JSONL persistence, and exactly one fresh top-level agent. The bin submits the task, waits for its durable turn ending, renders the selected output, disposes to quiescence, and exits.
+
+The package mounts no console logger, readline 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 |
+| `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 |
+| `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 with bare package specifiers require `node --expose-internals` or the Loader's optional native fallback. The root command supplies the Node flag.
+
+### Output formats
+
+- `text` writes the last assistant message containing text, followed by one newline.
+- `json` writes one DSH-native result record: `{ type: "result", success, sessionId, turn, result, reason, usage? }`. `usage` sums every model step in the task turn.
+- `stream-json` writes each canonical event from the top-level session's task turn as `{ type: "session_event", sessionId, event }`, then the same result record. Child-agent activity appears only through the parent tool events and results.
+
+Only `reason.kind === "completed"` exits successfully. Other durable turn endings still emit partial text or a result record, add a stderr diagnostic, and exit nonzero. Argument and boot failures leave stdout empty. SIGINT and SIGTERM cancel active work, await disposal, and exit 130 and 143 respectively.
+
+The task turn 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 task turn
+
+**What the model sees**: The positional task becomes one user message. Through `dsh-agent-spine-demo`, the top-level agent also receives configured workspace instructions and persona, the skill catalog, visible tool schemas, and retained tool results needed for later steps in the same turn.
+
+**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.
+
+## 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 task turn.
--- a/packages/examples/cli-demo/package.json
+++ b/packages/examples/cli-demo/package.json
@@ -0,0 +1,61 @@
+{
+  "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"
+    },
+    "./bin": {
+      "types": "./lib/types/bin.d.ts",
+      "default": "./lib/bin.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/bin.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "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-llm": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^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-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "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
@@ -0,0 +1,34 @@
+#!/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
@@ -0,0 +1,447 @@
+/**
+ * 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 type { TokenUsage } from '@deepseek-ai/dsh-llm'
+import type { SessionEvent, TurnEndReason } 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] <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 success: boolean
+  readonly sessionId: string
+  readonly turn: number
+  readonly result: string
+  readonly reason: TurnEndReason
+  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 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' },
+      },
+      allowPositionals: true,
+      strict: true,
+    })
+  } catch (error: unknown) {
+    throw new CliArgumentError(toError(error).message)
+  }
+
+  if (parsed.values.help === true) return { kind: 'help' }
+  if (parsed.positionals.length !== 1) {
+    throw new CliArgumentError(`expected exactly one positional task, received ${parsed.positionals.length}`)
+  }
+  // Cardinality was checked above, so index zero exists.
+  // eslint-disable-next-line @typescript-eslint/no-non-null-assertion
+  const task = 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.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(interruptionReason(signal))
+    throw new CliInterruptedError(interruptionReason(signal))
+  }
+  await new Promise<void>((resolve, reject) => {
+    const onAbort = (): void => {
+      agent.cancel(interruptionReason(signal))
+      reject(new CliInterruptedError(interruptionReason(signal)))
+    }
+    signal.addEventListener('abort', onAbort, { once: true })
+    void agent.whenIdle().then(resolve, reject).finally(() => {
+      signal.removeEventListener('abort', onAbort)
+    })
+  })
+}
+
+/**
+ * Run one message-triggered turn on the configured top-level agent, aggregate its
+ * final text and model usage, wait for idle plus an explicit persistence flush,
+ * and return its durable ending. Only the selected agent's task turn reaches
+ * `onEvent`; startup injections and unrelated sessions are ignored. The context
+ * must contain exactly one top-level agent. Signal abort cancels that agent; an
+ * abort before the correlated task turn rejects. An observer throw cancels the
+ * turn and is rethrown after the agent reaches idle and the session flushes.
+ * @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)
+
+  let targetTurn: number | undefined
+  let reason: TurnEndReason | undefined
+  let result = ''
+  let usage: TokenUsage | undefined
+  let outputError: Error | undefined
+  let resolveTurn!: () => void
+  let rejectTurn!: (error: Error) => void
+  let settled = false
+  const turnEnded = new Promise<void>((resolve, reject) => {
+    resolveTurn = resolve
+    rejectTurn = reject
+  })
+
+  const settleResolved = (): void => {
+    settled = true
+    resolveTurn()
+  }
+  const settleRejected = (error: Error): void => {
+    settled = true
+    rejectTurn(error)
+  }
+  const observe = (sessionId: string, event: SessionEvent): void => {
+    if (outputError !== undefined || options.onEvent === undefined) return
+    try {
+      options.onEvent(sessionId, event)
+    } catch (error: unknown) {
+      outputError = toError(error)
+      agent.cancel('stream output failed')
+    }
+  }
+
+  const disposeListener = ctx.on('session/event', (session, event) => {
+    if (session !== agent.session || settled) return
+    if (targetTurn === undefined) {
+      if (event.type !== 'turn/start' || event.data.trigger.kind !== 'message') return
+      targetTurn = event.data.turn
+    }
+    observe(session.id, event)
+    if (event.type === 'assistant/message' && event.data.turn === targetTurn) {
+      result = assistantText(event) ?? result
+      if (event.data.usage !== undefined) usage = addUsage(usage, event.data.usage)
+    }
+    if (event.type === 'turn/end' && event.data.turn === targetTurn) {
+      reason = event.data.reason
+      settleResolved()
+    }
+  })
+
+  const signal = options.signal
+  let onAbort: (() => void) | undefined
+  if (signal !== undefined) {
+    onAbort = (): void => {
+      agent.cancel(interruptionReason(signal))
+      if (targetTurn === undefined) settleRejected(new CliInterruptedError(interruptionReason(signal)))
+    }
+    signal.addEventListener('abort', onAbort, { once: true })
+    /* v8 ignore next -- closes the race between startup-idle completion and listener registration */
+    if (signal.aborted) onAbort()
+  }
+
+  try {
+    /* v8 ignore next -- skips send only when cancellation wins the listener-registration race above */
+    if (!settled) { // eslint-disable-line @typescript-eslint/no-unnecessary-condition
+      agent.send([{ type: 'text', text: options.task }])
+    }
+    await turnEnded
+  } finally {
+    if (onAbort !== undefined) signal?.removeEventListener('abort', onAbort)
+    disposeListener()
+    await agent.whenIdle()
+  }
+
+  /* v8 ignore next 3 -- turnEnded resolves only from the matching branch that assigns both values */
+  if (targetTurn === undefined || reason === undefined) {
+    throw new Error('task ended without a correlated turn/end event')
+  }
+  await ctx.sessions.flush(agent.session)
+  if (outputError !== undefined) throw outputError
+  return {
+    type: 'result',
+    success: reason.kind === 'completed',
+    sessionId: agent.session.id,
+    turn: targetTurn,
+    result,
+    reason,
+    ...usage === undefined ? {} : { usage },
+  }
+}
+
+function renderResult(outputFormat: OutputFormat, result: CliResult): string {
+  return outputFormat === 'text' ? `${result.result}\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.
+    // eslint-disable-next-line @typescript-eslint/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)
+  }
+}
+
+/**
+ * Render a non-completed turn reason for stderr.
+ * @param reason - durable turn ending to describe.
+ * @returns a concise diagnostic fragment.
+ */
+export function formatTurnFailure(reason: TurnEndReason): string {
+  switch (reason.kind) {
+    case 'completed': return 'completed'
+    case 'aborted': return reason.reason === undefined ? 'was aborted' : `was aborted: ${reason.reason}`
+    case 'error': return `failed at step ${reason.step}: ${reason.message}`
+    case 'disposed': return 'was disposed'
+    case 'max-tokens': return 'reached the model output-token limit'
+    case 'rejected': return `was rejected: ${reason.reason}`
+    case 'interrupted': return 'was interrupted during persistence recovery'
+    default: return `ended with ${JSON.stringify(reason)}`
+  }
+}
+
+/**
+ * Execute one CLI invocation. Argument and boot failures never write stdout;
+ * context disposal is awaited before return, and its failure does not replace
+ * 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 = result.success ? 0 : 1
+    if (!result.success) diagnostic = `${CLI_NAME}: turn ${result.turn} ${formatTurnFailure(result.reason)}\n`
+  } 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
@@ -0,0 +1,82 @@
+/**
+ * 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 from '@deepseek-ai/dsh-session-persistence-jsonl'
+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
+  /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
+  persistenceRoot?: string
+  /** 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),
+  persona: z.string(),
+  dshHome: z.string(),
+  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: 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 })
+}
--- a/packages/examples/cli-demo/tests/built-bin.e2e.ts
+++ b/packages/examples/cli-demo/tests/built-bin.e2e.ts
@@ -0,0 +1,177 @@
+import { spawn } from 'node:child_process'
+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 { fileURLToPath } from 'node:url'
+import { afterEach, describe, expect, it } from 'vitest'
+
+const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
+const cliBin = join(repoRoot, 'packages/examples/cli-demo/lib/bin.js')
+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', 'support/invariants', 'ui/app-boot',
+  'session-persistence/session-persistence', 'session-persistence/session-persistence-jsonl',
+  'context/workspace-context',
+]
+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.mjs'), [
+    "import { LlmAdapter } from '@deepseek-ai/dsh-llm'",
+    'class Mock extends LlmAdapter {',
+    '  async * stream(options) {',
+    "    const text = 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((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) { ctx.llm.registerAdapter(['built-cli-mock'], new Mock()) }",
+    '',
+  ].join('\n'))
+  await writeFile(join(dir, 'cordis.yml'), [
+    '- id: mock-llm',
+    "  name: './mock-llm.mjs'",
+    '- 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',
+    '',
+  ].join('\n'))
+  return dir
+}
+
+interface BinResult {
+  readonly code: number
+  readonly signal: NodeJS.Signals | null
+  readonly stdout: string
+  readonly stderr: string
+}
+
+function runBuiltBin(cwd: string, args: readonly string[], interrupt?: NodeJS.Signals): Promise<BinResult> {
+  return new Promise((resolveResult, reject) => {
+    const child = spawn(process.execPath, ['--expose-internals', cliBin, ...args], {
+      cwd,
+      env: { ...process.env, DSH_HOME: join(cwd, '.dsh'), DSH_AGENTS_HOME: join(cwd, '.agents') },
+      stdio: ['ignore', 'pipe', 'pipe'],
+    })
+    let stdout = ''
+    let stderr = ''
+    let interrupted = false
+    child.stdout.setEncoding('utf8')
+    child.stdout.on('data', (chunk: string) => {
+      stdout += chunk
+      if (interrupt !== undefined && !interrupted && stdout.includes('assistant/chunk')) {
+        interrupted = true
+        child.kill(interrupt)
+      }
+    })
+    child.stderr.setEncoding('utf8')
+    child.stderr.on('data', (chunk: string) => { stderr += chunk })
+    const timer = setTimeout(() => {
+      child.kill('SIGKILL')
+      reject(new Error(`built CLI did not exit. stdout:\n${stdout}\nstderr:\n${stderr}`))
+    }, 25_000)
+    child.once('error', (error) => { clearTimeout(timer); reject(error) })
+    child.once('exit', (code, signal) => {
+      clearTimeout(timer)
+      resolveResult({ code: code ?? -1, signal, stdout, 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', success: true, result: 'BUILT: json task', reason: { kind: 'completed' },
+      usage: { inputTokens: 4, outputTokens: 2 },
+    })
+
+    const stream = await runBuiltBin(consumer, ['--config', './cordis.yml', '--output-format', 'stream-json', 'stream task'])
+    const lines = stream.stdout.trimEnd().split('\n').map(line => JSON.parse(line) as Record<string, unknown>)
+    expect(lines[0]).toMatchObject({ type: 'session_event', event: { type: 'turn/start' } })
+    expect(lines.at(-1)).toMatchObject({ type: 'result', success: true, result: 'BUILT: stream task' })
+    const files = await readdir(join(consumer, '.sessions'), { recursive: true })
+    expect(files.filter(file => file.endsWith('.jsonl'))).toHaveLength(3)
+  }, 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).toContain(`received ${signal}`)
+    }, 30_000)
+  })
+})
--- a/packages/examples/cli-demo/tests/cli-demo.spec.ts
+++ b/packages/examples/cli-demo/tests/cli-demo.spec.ts
@@ -0,0 +1,159 @@
+import { mkdtemp } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import { agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
+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 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 })
+  contexts.push(ctx)
+  await ctx.plugin(cliDemo, config)
+  await new Promise(resolve => setTimeout(resolve, 80))
+  return ctx
+}
+
+async function composePrefix(ctx: Context): Promise<Message[]> {
+  const agent = { session: { header: { cwd: '/tmp' } } } as unknown as Agent
+  const empty: Message[] = []
+  return await agentEvents(ctx, agent).waterfall(
+    'agent/session-prefix', empty, new AbortController().signal,
+    () => Promise.resolve(empty),
+  )
+}
+
+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,
+      skills: await skillConfig(),
+      workspaceContext: false,
+    })
+    const [agent] = ctx.get('agents')?.roots() ?? []
+    expect(ctx.get('agentLoop')).toBeDefined()
+    expect(ctx.get('sessionPersistence')).toBeDefined()
+    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: {}, execute: async () => [] })
+    }
+    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 = {
+      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({
+      callId: CallId('cli-demo-task-config'),
+      name: 'task_output',
+      arguments: { task_id: id, wait: true },
+    })
+    expect(wait).toHaveBeenCalledWith(id, 7, undefined, undefined)
+  })
+
+  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
@@ -0,0 +1,474 @@
+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 { CallId, LlmAdapter, type GenerateOptions, type StreamChunk, type TokenUsage } from '@deepseek-ai/dsh-llm'
+import { SessionId, type SessionEvent, type TurnEndReason } from '@deepseek-ai/dsh-session'
+import { afterEach, describe, expect, it } from 'vitest'
+import * as cliDemo from '../src/index.ts'
+import {
+  executeCli,
+  formatTurnFailure,
+  parseCliArgs,
+  runOneShot,
+  type CliResult,
+} from '../src/cli.ts'
+
+type ScriptEntry = readonly StreamChunk[] | 'hang'
+
+class ScriptedAdapter extends LlmAdapter {
+  readonly requests: GenerateOptions[] = []
+  private cursor = 0
+
+  constructor(private readonly script: readonly ScriptEntry[]) {
+    super()
+  }
+
+  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 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 skillHome = await mkdtemp(join(tmpdir(), 'dsh-cli-runner-skills-'))
+  const ctx = new Context()
+  liveContexts.push(ctx)
+  await ctx.plugin(cliDemo, {
+    provider: 'mock',
+    model: 'mock',
+    persistenceRoot: root,
+    skills: { local: { dshHome: join(skillHome, '.dsh'), agentsHome: join(skillHome, '.agents') } },
+    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 } },
+    execute: async args => [{ type: 'text', text: `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(['--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(['one', 'two'])).toThrow('received 2')
+    expect(() => parseCliArgs(['--output-format', 'xml', 'task'])).toThrow('unsupported output format')
+    expect(() => parseCliArgs(['-p', '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('disposed')
+    const files = await readdir(persistenceRoot, { recursive: true })
+    expect(files.some(file => file.endsWith('.jsonl'))).toBe(true)
+  })
+
+  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', success: true, turn: 1, result: 'done', reason: { kind: 'completed' } })
+    expect(result.usage).toEqual({
+      inputTokens: 17,
+      outputTokens: 8,
+      cacheReadTokens: 6,
+      cacheWriteTokens: 1,
+      reasoningTokens: 6,
+    })
+  })
+
+  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.result).toBe('working')
+  })
+
+  it('streams only the correlated main message turn and then the result envelope', async () => {
+    const { ctx, agent } = await harness([textResponse('streamed')])
+    const other = ctx.sessions.create(SessionId('unrelated'))
+    let injected = false
+    ctx.on('agent/queued', (subject) => {
+      if (subject !== agent || injected) return
+      injected = true
+      agent.inject([{ type: 'text', text: 'startup injection' }], { source: { kind: 'plugin', plugin: 'test' } })
+      other.append('turn/start', { turn: 1, trigger: { kind: 'injection', source: { kind: 'plugin', plugin: 'test' } } })
+      other.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
+    })
+    const output = await invoke(ctx, ['--output-format', 'stream-json', 'task'])
+    const lines = output.stdout.trimEnd().split('\n').map(line => JSON.parse(line) as Record<string, unknown>)
+    const events = lines.slice(0, -1).map(line => line['event'] as SessionEvent)
+    expect(lines.at(-1)).toMatchObject({ type: 'result', success: true, turn: 2, result: 'streamed' })
+    expect(events[0]).toMatchObject({ type: 'turn/start', data: { turn: 2, trigger: { kind: 'message' } } })
+    expect(events.at(-1)).toMatchObject({ type: 'turn/end', data: { turn: 2 } })
+    expect(lines.slice(0, -1).every(line => line['sessionId'] === agent.session.id)).toBe(true)
+    expect(events.some(event => event.type === 'context/message')).toBe(false)
+  })
+
+  it('emits partial data and a diagnostic for non-completed turns', async () => {
+    const { ctx } = await harness([textResponse('partial', { inputTokens: 2, outputTokens: 3 }, 'max-tokens')])
+    const output = await invoke(ctx, ['--output-format', 'json', 'task'])
+    expect(JSON.parse(output.stdout)).toMatchObject({ success: false, result: 'partial', reason: { kind: 'max-tokens' } })
+    expect(output.code).toBe(1)
+    expect(output.stderr).toContain('output-token limit')
+  })
+
+  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(JSON.parse(output.stdout)).toMatchObject({ success: false, reason: { kind: 'aborted', reason: 'received SIGINT' } })
+    expect(output.code).toBe(1)
+    expect(output.stderr).toContain('was aborted: received SIGINT')
+    expect(agent.status).toBe('disposed')
+  })
+
+  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 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('disposed')
+
+    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.send([{ type: 'text', text: 'first' }])
+    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('agent/queued', (agent) => {
+      if (agent === queued.agent) queuedAbort.abort('cancel queued')
+    })
+    await expect(runOneShot(queued.ctx, { task: 'task', signal: queuedAbort.signal })).rejects.toThrow('cancel queued')
+    await queued.agent.whenIdle()
+  })
+})
+
+describe('formatTurnFailure', () => {
+  it('diagnoses every durable reason and preserves merge-extensible unknowns', () => {
+    const cases: [TurnEndReason, string][] = [
+      [{ kind: 'completed' }, 'completed'],
+      [{ kind: 'aborted' }, 'was aborted'],
+      [{ kind: 'aborted', reason: 'stop' }, 'was aborted: stop'],
+      [{ kind: 'error', step: 2, message: 'bad' }, 'failed at step 2: bad'],
+      [{ kind: 'disposed' }, 'was disposed'],
+      [{ kind: 'max-tokens' }, 'output-token limit'],
+      [{ kind: 'rejected', reason: 'policy' }, 'was rejected: policy'],
+      [{ kind: 'interrupted' }, 'persistence recovery'],
+    ]
+    for (const [reason, expected] of cases) expect(formatTurnFailure(reason)).toContain(expected)
+    expect(formatTurnFailure({ kind: 'extension' } as unknown as TurnEndReason)).toContain('extension')
+  })
+})
--- a/packages/examples/cli-demo/tsconfig.json
+++ b/packages/examples/cli-demo/tsconfig.json
@@ -0,0 +1,22 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "composite": true,
+    "rootDir": "src",
+    "outDir": "lib/types",
+    "tsBuildInfoFile": "../../../.typecheck/cli-demo.tsbuildinfo"
+  },
+  "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-persistence-jsonl" },
+    { "path": "../../ui/app-boot" }
+  ]
+}
--- a/packages/examples/cli-demo/tsdown.config.ts
+++ b/packages/examples/cli-demo/tsdown.config.ts
@@ -0,0 +1,13 @@
+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/bin.js'],
+  outDir: 'lib',
+  format: ['esm'],
+  platform: 'node',
+  target: 'es2024',
+  fixedExtension: false,
+  dts: false,
+  clean: false,
+})
--- a/packages/session-persistence/session-persistence-jsonl/README.md
+++ b/packages/session-persistence/session-persistence-jsonl/README.md
@@ -23,7 +23,7 @@ The JSONL durable session-persistence backend — a concrete `SessionPersistence

 ## Durability and crash semantics

- **Lazy materialization.** `create(meta)` writes nothing; on the first `append`, the backend writes and `fsync`s a temporary file, publishes it without overwrite via a hard link, then `fsync`s the directory. A created-but-never-appended session leaves nothing on disk and is absent from `list`.
+- **Lazy materialization.** `create(meta)` writes nothing; on the first `append`, the backend writes and `fsync`s a temporary file, publishes it without overwrite via a hard link, then `fsync`s the directory when the host supports it. A created-but-never-appended session leaves nothing on disk and is absent from `list`.
 - **Append-only.** Committed events (at or below a flushed `turn/end`) are never rewritten. Subsequent appends are line appends at EOF + `fsync`.
 - **Crash recovery — preserve valid tail work.** `load` keeps the contiguous valid prefix of an interrupted final turn. It truncates from the first unparsable or sequence-gapped uncommitted record, then appends the synthetic tool, step, and turn closers required by the shared [persistence contract](../../../docs/rfc/implemented/architecture/2026-06-14-session-persistence.md); the same defect at or before the last committed `turn/end` rejects.
 - **Contiguous-seq.** `append` rejects a batch whose first `seq` does not continue the stored log, and rejects non-JSON-serializable `event.data` naming the offending event type.
@@ -46,3 +46,4 @@ The plugin buffers frozen session events and drains them on flush or disposal. A
 - **Nothing deletes session files** — logs accumulate under `root` until removed externally (the seam has no deletion surface).
 - **Single-process assumption** — per-session serialization and the write cursor live in this process; two processes appending to the same `root` are not coordinated.
 - **Initial materialization requires hard-link support** — first append uses `link()` so same-id races fail instead of overwriting a committed log; a filesystem that cannot create hard links cannot host this backend.
+- **Windows cannot `fsync` directory handles through Node** — the backend tolerates only Windows `EPERM` from directory `fsync`; file-content `fsync` remains mandatory, but a crash can lose a newly published directory entry on a host without an equivalent directory-sync primitive.
--- a/packages/session-persistence/session-persistence-jsonl/src/index.ts
+++ b/packages/session-persistence/session-persistence-jsonl/src/index.ts
@@ -57,6 +57,9 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
  private root: string
  private coordinator: PersistenceCoordinator<number>

+  /** Runtime host platform used to decide whether directory sync is supported. */
+  readonly internals: { platform: NodeJS.Platform } = { platform: process.platform }
+
  constructor(ctx: Context, public config: Config) {
    super(ctx)
    // Resolve once so later process.cwd() changes cannot split one backend across roots.
@@ -208,11 +211,18 @@ export class SessionPersistenceJsonl extends SessionPersistence implements Persi
    }
  }

-  /** fsync a directory so a just-created or published entry inside it is crash-durable. */
+  /** fsync a directory when the host exposes that durability primitive. */
  private async syncDir(dir: string): Promise<void> {
    const handle = await open(dir, 'r')
    try {
-      await handle.sync()
+      try {
+        await handle.sync()
+      } catch (error: unknown) {
+        const code = (error as NodeJS.ErrnoException | null)?.code
+        // Node opens directories on Windows but its fsync binding rejects them.
+        // File-content fsync remains mandatory; only this unsupported primitive is skipped.
+        if (this.internals.platform !== 'win32' || code !== 'EPERM') throw error
+      }
    } finally {
      await handle.close()
    }
--- a/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts
+++ b/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts
@@ -1,6 +1,7 @@
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
-import { appendFile, mkdtemp, mkdir, rm, readFile, writeFile, readdir, stat } from 'node:fs/promises'
+import { appendFile, mkdtemp, mkdir, open, rm, readFile, writeFile, readdir, stat } from 'node:fs/promises'
+import type { FileHandle } from 'node:fs/promises'
 import { tmpdir } from 'node:os'
 import { isAbsolute, join, relative, resolve } from 'node:path'
 import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
@@ -40,9 +41,25 @@ async function freshRoot(): Promise<string> {
 }

 afterEach(async () => {
+  vi.restoreAllMocks()
  for (const d of dirs.splice(0)) await rm(d, { recursive: true, force: true })
 })

+async function rejectDirectorySync(code: string): Promise<void> {
+  const handle = await open(root, 'r')
+  const proto = Object.getPrototypeOf(handle) as { sync: () => Promise<void> }
+  await handle.close()
+  const realSync = proto.sync
+  vi.spyOn(proto, 'sync').mockImplementation(async function (this: FileHandle) {
+    if ((await this.stat()).isDirectory()) {
+      const error = new Error(`simulated directory fsync ${code}`) as NodeJS.ErrnoException
+      error.code = code
+      throw error
+    }
+    return realSync.call(this)
+  })
+}
+
 function appendClosedTurn(session: Session): void {
  session.append('turn/start', { turn: 1, trigger: { kind: 'message', source: { kind: 'user' } } })
  session.append('user/message', {
@@ -336,6 +353,28 @@ describe('SessionPersistenceJsonl: durability and crash semantics', () => {
    expect(loaded.events.map(e => e.seq)).toEqual([0, 1, 2, 3, 4, 5, 6, 7])
  })

+  it('keeps file fsync mandatory while tolerating unsupported Windows directory fsync', async () => {
+    await rejectDirectorySync('EPERM')
+    const backend = ctx.sessionPersistence as SessionPersistenceJsonl
+    backend.internals.platform = 'win32'
+    const m = meta('windows-directory-sync')
+    await ctx.sessionPersistence.create(m)
+    await expect(ctx.sessionPersistence.append(m.id, oneTurnLog())).resolves.toBeUndefined()
+    expect((await ctx.sessionPersistence.load(m.id)).events).toEqual(oneTurnLog())
+  })
+
+  it.each([
+    ['linux', 'EPERM'],
+    ['win32', 'EIO'],
+  ] as const)('surfaces directory fsync errors on %s with %s', async (platform, code) => {
+    await rejectDirectorySync(code)
+    const backend = ctx.sessionPersistence as SessionPersistenceJsonl
+    backend.internals.platform = platform
+    const m = meta(`directory-sync-${platform}-${code}`)
+    await ctx.sessionPersistence.create(m)
+    await expect(ctx.sessionPersistence.append(m.id, oneTurnLog())).rejects.toMatchObject({ code })
+  })
+
  it('load returns a meta copy: mutating it does not corrupt backend pathing', async () => {
    const m = meta('meta-copy', '/proj')
    await ctx.sessionPersistence.create(m)
--- a/packages/support/llm-replay/README.md
+++ b/packages/support/llm-replay/README.md
@@ -2,7 +2,7 @@

 A replay LLM plugin for keyless snapshot tests. It yields model streams reconstructed from a recorded **session JSONL** fixture, so a test can boot the real agent against a fixed model transcript with no API key. With `providers` configured it registers a replay-only adapter whose catalog is visible to clients such as ACP editors; without `providers` it installs the catch-all `llm/stream` waterfall used by tests that do not need discovery.

-Its consumer is the ACP snapshot harness in `examples/acp-agent`, which loads this plugin (via `cordis.snapshot.yml`) in place of a real LLM adapter. The package exists so its derive/parse/replay logic falls under the per-file 100% coverage gate on `packages/*/src` (the same logic, while it lived under `examples/`, was outside the gate).
+Its consumers are the ACP snapshot harness in `examples/acp-agent` and the `stream-json` snapshot in `examples/headless-agent`; each loads this plugin in place of a real LLM adapter. Keeping derivation and replay here places that logic under the per-file 100% coverage gate on `packages/*/src`.

 ## How the fixture works

--- a/packages/support/loader-smoke/README.md
+++ b/packages/support/loader-smoke/README.md
@@ -2,7 +2,7 @@

 Shared subprocess harness for tests that boot an app and `cordis.yml` through the Cordis Loader. `resolveExampleLaunch` selects local `src` mode (tsx and root tsconfig paths) or CI `lib` mode (plain Node and package exports) from an explicit mode or `DSH_EXAMPLE_MODE`.

-`runLoaderSmoke` owns the isolated cwd, DSH homes, stdin, diagnostics, deadline, termination, and cleanup. It returns both streams after a zero exit and rejects with both streams on failure.
+`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.

 This is support-tier test infrastructure, not product API.

--- a/packages/support/loader-smoke/src/index.ts
+++ b/packages/support/loader-smoke/src/index.ts
@@ -1,14 +1,12 @@
 /**
 * Shared subprocess harness for keyless example smokes that boot a real
- * `cordis.yml` through the stdio-agent bin and Cordis Loader.
+ * `cordis.yml` through an app bin and Cordis Loader.
 *
 * It also owns the mode-aware launch resolver every example subprocess harness shares
 * ({@link resolveExampleLaunch}): booting an example bin from TypeScript source under `tsx` (the
 * zero-build dev path, resolving `@deepseek-ai/dsh-*` / `@cordisjs/*` through the tsconfig `paths`
 * map) or from built `lib/` under plain Node (resolving bare packages through real `exports`, as an
 * installed consumer does, while Node type-strips relative example-local TypeScript plugins).
- * Consolidating that spawn glue here retires the copies in the ACP snapshot harness and the example
- * e2e drivers (the `TODO(acp-test-harness)`).
 *
 * @module @deepseek-ai/dsh-loader-smoke
 */
@@ -126,12 +124,14 @@ export interface LoaderSmokeOptions {
  readonly label: string
  /** Prefix for the isolated temporary process cwd. */
  readonly tempDirPrefix: string
-  /** Absolute stdio-agent bin SOURCE path (`<pkg>/src/bin.ts`); the `lib` bin is derived from it. */
+  /** Absolute app-bin source path (`<pkg>/src/bin.ts`); the `lib` bin is derived from it. */
  readonly binScript: string
  /** Explicit plain-Node entry for `lib` mode; intended for test fixtures outside a package `src/` tree. */
  readonly libBinScript?: string | undefined
-  /** Absolute real Loader config path. */
+  /** Absolute real Loader config path, passed as the sole bin argument by default. */
  readonly configPath: string
+  /** Complete argv after the bin path; overrides the default `[configPath]`. */
+  readonly binArgs?: readonly string[]
  /** Absolute repo tsconfig path used for unbuilt workspace-package resolution (required in `src` mode). */
  readonly tsconfigPath: string
  /** Boot from source via tsx (`src`) or built lib via plain Node (`lib`); defaults to the environment's mode. */
@@ -142,6 +142,10 @@ export interface LoaderSmokeOptions {
  readonly stdinLines?: readonly string[]
  /** Process deadline override for harness tests. */
  readonly processTimeoutMs?: number
+  /** Optional world-state setup run in the isolated cwd before process start. */
+  readonly prepare?: (cwd: string) => Promise<void> | void
+  /** Optional world-state assertion run in the isolated cwd before cleanup. */
+  readonly inspect?: (cwd: string) => Promise<void> | void
 }

 /** Captured output from a Loader smoke that exited successfully. */
@@ -162,17 +166,18 @@ export interface LoaderSmokeResult {
 export async function runLoaderSmoke(options: LoaderSmokeOptions): Promise<LoaderSmokeResult> {
  const cwd = await mkdtemp(join(tmpdir(), options.tempDirPrefix))
  const processTimeoutMs = options.processTimeoutMs ?? DEFAULT_PROCESS_TIMEOUT_MS
-  const launch = resolveExampleLaunch({
-    srcBin: options.binScript,
-    libBin: options.libBinScript,
-    configArgs: [options.configPath],
-    ...options.mode !== undefined ? { mode: options.mode } : {},
-    tsconfigPath: options.tsconfigPath,
-    exposeInternals: true,
-    env: { DSH_HOME: join(cwd, '.dsh'), DSH_AGENTS_HOME: join(cwd, '.agents'), ...options.env },
-  })
  try {
-    return await new Promise((resolve, reject) => {
+    await options.prepare?.(cwd)
+    const launch = resolveExampleLaunch({
+      srcBin: options.binScript,
+      libBin: options.libBinScript,
+      configArgs: options.binArgs ?? [options.configPath],
+      ...options.mode !== undefined ? { mode: options.mode } : {},
+      tsconfigPath: options.tsconfigPath,
+      exposeInternals: true,
+      env: { DSH_HOME: join(cwd, '.dsh'), DSH_AGENTS_HOME: join(cwd, '.agents'), ...options.env },
+    })
+    const result = await new Promise<LoaderSmokeResult>((resolve, reject) => {
      const child = spawn(launch.command, launch.args, {
        cwd,
        env: { ...process.env, ...launch.env },
@@ -217,6 +222,8 @@ export async function runLoaderSmoke(options: LoaderSmokeOptions): Promise<Loade

      child.stdin.end((options.stdinLines ?? []).map(line => `${line}\n`).join(''))
    })
+    await options.inspect?.(cwd)
+    return result
  } finally {
    await rm(cwd, { recursive: true, force: true })
  }
--- a/packages/support/loader-smoke/tests/fixtures/success.ts
+++ b/packages/support/loader-smoke/tests/fixtures/success.ts
@@ -6,6 +6,7 @@ process.stdin.on('data', (chunk: string) => { input += chunk })
 process.stdin.on('end', () => {
  console.log(JSON.stringify({
    configPath: process.argv[2],
+    args: process.argv.slice(2),
    cwd: process.cwd(),
    dshHome: process.env.DSH_HOME,
    agentsHome: process.env.DSH_AGENTS_HOME,
--- a/packages/support/loader-smoke/tests/loader-smoke.spec.ts
+++ b/packages/support/loader-smoke/tests/loader-smoke.spec.ts
@@ -1,4 +1,6 @@
 import { existsSync } from 'node:fs'
+import { readFile, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { describe, expect, it } from 'vitest'
 import { LOADER_SMOKE_TEST_TIMEOUT_MS, runLoaderSmoke } from '@deepseek-ai/dsh-loader-smoke'
@@ -22,6 +24,7 @@ describe('runLoaderSmoke', () => {
    })
    const output = JSON.parse(result.stdout) as {
      configPath: string
+      args: string[]
      cwd: string
      dshHome: string
      agentsHome: string
@@ -30,6 +33,7 @@ describe('runLoaderSmoke', () => {
    }
    expect(output).toMatchObject({
      configPath,
+      args: [configPath],
      marker: 'present',
      input: 'one\ntwo\n',
    })
@@ -39,6 +43,30 @@ describe('runLoaderSmoke', () => {
    expect(existsSync(output.cwd)).toBe(false)
  }, LOADER_SMOKE_TEST_TIMEOUT_MS)

+  it('passes an arbitrary bin argv and inspects world state before cleanup', async () => {
+    let inspected = ''
+    let marker = ''
+    const result = await runLoaderSmoke({
+      label: 'argv fixture',
+      tempDirPrefix: 'loader-smoke-argv-',
+      binScript: fixture('success'),
+      libBinScript: fixture('success'),
+      configPath,
+      binArgs: ['--config', configPath, '--output-format', 'json', 'task with spaces'],
+      tsconfigPath,
+      prepare: cwd => writeFile(join(cwd, 'marker.txt'), 'prepared'),
+      inspect: async (cwd) => {
+        inspected = cwd
+        marker = await readFile(join(cwd, 'marker.txt'), 'utf8')
+      },
+    })
+    const output = JSON.parse(result.stdout) as { args: string[]; cwd: string }
+    expect(output.args).toEqual(['--config', configPath, '--output-format', 'json', 'task with spaces'])
+    expect(canonicalTempPath(inspected)).toBe(canonicalTempPath(output.cwd))
+    expect(marker).toBe('prepared')
+    expect(existsSync(inspected)).toBe(false)
+  }, LOADER_SMOKE_TEST_TIMEOUT_MS)
+
  it('rejects a non-zero exit with captured diagnostics', async () => {
    await expect(runLoaderSmoke({
      label: 'failure fixture',
--- a/pnpm-lock.yaml
+++ b/pnpm-lock.yaml
@@ -107,6 +107,9 @@ importers:
      '@deepseek-ai/dsh-bash-sandbox':
        specifier: workspace:*
        version: link:../packages/bash/bash-sandbox
+      '@deepseek-ai/dsh-cli-demo':
+        specifier: workspace:*
+        version: link:../packages/examples/cli-demo
      '@deepseek-ai/dsh-code-runtime-worker':
        specifier: workspace:*
        version: link:../packages/code-runtime/code-runtime-worker
@@ -738,6 +741,48 @@ importers:
        specifier: ^4.0.0-rc.7
        version: 4.0.0-rc.7(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.5)

+  packages/examples/cli-demo:
+    devDependencies:
+      '@cordisjs/plugin-include':
+        specifier: workspace:^
+        version: link:../../../vendor/include
+      '@cordisjs/plugin-loader':
+        specifier: workspace:^
+        version: link:../../../vendor/loader
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-agent-spine-demo':
+        specifier: workspace:^
+        version: link:../agent-spine-demo
+      '@deepseek-ai/dsh-app-boot':
+        specifier: workspace:^
+        version: link:../../ui/app-boot
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../../core/session
+      '@deepseek-ai/dsh-session-persistence-jsonl':
+        specifier: workspace:^
+        version: link:../../session-persistence/session-persistence-jsonl
+      '@deepseek-ai/dsh-system-prompt':
+        specifier: workspace:^
+        version: link:../../core/system-prompt
+      '@deepseek-ai/dsh-tools':
+        specifier: workspace:^
+        version: link:../../core/tools
+      '@deepseek-ai/dsh-workspace-context':
+        specifier: workspace:^
+        version: link:../../context/workspace-context
+      cordis:
+        specifier: ^4.0.0-rc.7
+        version: 4.0.0-rc.7(@cordisjs/plugin-include@vendor+include)(@cordisjs/plugin-loader@vendor+loader)
+      schemastery:
+        specifier: ^3.17.0
+        version: 3.18.0
+
  packages/examples/jsonrpc-demo:
    dependencies:
      '@deepseek-ai/dsh-app-boot':
--- a/scripts/gen-doc-graphs.ts
+++ b/scripts/gen-doc-graphs.ts
@@ -100,7 +100,7 @@ const SERVICE_ROLES: ServiceRole[] = [
    pkg: 'session',
    title: 'In-memory session store',
    mode: 'core',
-    consumers: ['agent-loop', 'agent', 'session-persistence', 'session-query', 'subagent-inprocess', 'invariants'],
+    consumers: ['agent-loop', 'agent', 'cli-demo', 'session-persistence', 'session-query', 'subagent-inprocess', 'invariants'],
    note: 'Owns append-only Session instances and emits the durable session event feed.',
  },
  {
@@ -158,7 +158,7 @@ const SERVICE_ROLES: ServiceRole[] = [
    pkg: 'agent',
    title: 'Agent service',
    mode: 'core',
-    consumers: ['agent-loop', 'acp', 'subagent-inprocess', 'stdio-demo', 'invariants'],
+    consumers: ['agent-loop', 'acp', 'cli-demo', 'subagent-inprocess', 'stdio-demo', 'invariants'],
    note: 'Owns live Agent handles, the create/resume factory seam, and process-local initiator propagation.',
  },
  {
@@ -442,6 +442,14 @@ const APP_EXAMPLES = [
    config: 'examples/tui-agent/cordis.yml',
    summary: 'The TUI agent reuses the repl-agent backend and tool composition while fixing the shared terminal app to the full-screen dsh-tui front door.',
  },
+  {
+    id: 'headless',
+    rel: 'examples/headless-agent/composition.md',
+    title: 'Headless Agent App Composition',
+    label: 'examples/headless-agent',
+    config: 'examples/headless-agent/cordis.yml',
+    summary: 'The headless demo combines the real DeepSeek adapter and coding capabilities with the one-shot app package, format-pure stdout, and one fresh persisted top-level session.',
+  },
  {
    id: 'cordis',
    rel: 'examples/cordis-agent/composition.md',
@@ -474,6 +482,8 @@ function renderAppExpansion(lines: string[], appNode: string, pluginName: string
        ? '@deepseek-ai/dsh-stdio<br/>pre-created main agent'
        : 'dsh-tui (TTY) / dsh-stdio (pipes)<br/>pre-created main agent'
    lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'stdio')}["${frontDoor}"]`)
+  } else if (pluginName === '@deepseek-ai/dsh-cli-demo') {
+    lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'cli')}["one-shot driver<br/>format-pure stdout<br/>fresh top-level agent"]`)
  } else if (pluginName === '@deepseek-ai/dsh-acp-demo') {
    lines.push(`  ${appNode} --> ${nodeId('frontdoor', 'acp')}["@deepseek-ai/dsh-acp<br/>JSON-RPC stdio bridge<br/>sessions created by client"]`)
  }
@@ -500,7 +510,7 @@ function renderAppComposition(example: AppExample): string {
    const pluginNode = nodeId(`plugin_${example.id}`, plugin.id)
    lines.push(`  ${pluginNode}["${escLabel(plugin.id)}<br/>${escLabel(plugin.name)}"]`)
    lines.push(`  cfg --> ${pluginNode}`)
-    if (plugin.name === '@deepseek-ai/dsh-stdio-demo' || plugin.name === '@deepseek-ai/dsh-acp-demo') {
+    if (plugin.name === '@deepseek-ai/dsh-stdio-demo' || plugin.name === '@deepseek-ai/dsh-cli-demo' || plugin.name === '@deepseek-ai/dsh-acp-demo') {
      renderAppExpansion(lines, pluginNode, plugin.name, example.id)
    }
  }
@@ -991,6 +1001,7 @@ function renderIndex(docs: GraphDoc[]): string {
    'docs/capability-seams.md': 'capability seams and core services',
    'examples/echo-agent/composition.md': 'echo-agent app composition',
    'examples/repl-agent/composition.md': 'repl-agent app composition',
+    'examples/headless-agent/composition.md': 'headless-agent app composition',
    'examples/tui-agent/composition.md': 'tui-agent app composition',
    'examples/cordis-agent/composition.md': 'cordis-agent app composition',
    'examples/acp-agent/composition.md': 'acp-agent app composition',
@@ -1003,6 +1014,7 @@ function renderIndex(docs: GraphDoc[]): string {
    'docs/capability-seams.md': 'hybrid generated',
    'examples/echo-agent/composition.md': 'hybrid generated',
    'examples/repl-agent/composition.md': 'hybrid generated',
+    'examples/headless-agent/composition.md': 'hybrid generated',
    'examples/tui-agent/composition.md': 'hybrid generated',
    'examples/cordis-agent/composition.md': 'hybrid generated',
    'examples/acp-agent/composition.md': 'hybrid generated',
--- a/scripts/run-gates.ts
+++ b/scripts/run-gates.ts
@@ -399,6 +399,7 @@ function builtBinSmokeGate(): Gate {
    '--config',
    'vitest.e2e.config.ts',
    'packages/examples/stdio-demo/tests/built-bin.e2e.ts',
+    'packages/examples/cli-demo/tests/built-bin.e2e.ts',
    'packages/examples/acp-demo/tests/built-bin.e2e.ts',
    'packages/ui/jsonrpc/tests/built-scope-carrier.e2e.ts',
    // The worker-entry packages' built bundles: the only automated proof
--- a/tsconfig.build.json
+++ b/tsconfig.build.json
@@ -37,6 +37,7 @@
    { "path": "./packages/context/workspace-context" },
    { "path": "./packages/core/agent-loop" },
    { "path": "./packages/examples/agent-spine-demo" },
+    { "path": "./packages/examples/cli-demo" },
    { "path": "./packages/bash/bash" },
    { "path": "./packages/code-runtime/code-runtime" },
    { "path": "./packages/code-runtime/code-runtime-worker" },
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -48,6 +48,7 @@
    { "path": "./packages/context/workspace-context" },
    { "path": "./packages/core/agent-loop" },
    { "path": "./packages/examples/agent-spine-demo" },
+    { "path": "./packages/examples/cli-demo" },
    { "path": "./packages/bash/bash" },
    { "path": "./packages/code-runtime/code-runtime" },
    { "path": "./packages/code-runtime/code-runtime-worker" },
--- a/vitest.snapshot.config.ts
+++ b/vitest.snapshot.config.ts
@@ -20,10 +20,10 @@ const snapshotMaxConcurrency = positiveIntFromEnv(
  Math.min(DEFAULT_SNAPSHOT_MAX_CONCURRENCY, availableParallelism()),
 )

-// Replay is the keyless default: boot the real ACP subprocess from recorded model scripts and diff
-// normalized transcript plus persisted-log goldens. `record` calls the real API and updates fixtures
-// and goldens; `refresh` replays committed scripts and updates only current goldens. Replay/refresh
-// never load `.env`; only record reads a key from the environment or gitignored root `.env`.
+// Replay is the keyless default: boot real example subprocesses from recorded model scripts and diff
+// normalized protocol or transcript output plus persisted-log goldens. `record` calls the real API
+// and updates fixtures and goldens; `refresh` replays committed scripts and updates current goldens.
+// Replay/refresh never load `.env`; only record reads a key from the environment or root `.env`.
 if (process.env.DSH_SNAPSHOT === 'record') {
  try {
    process.loadEnvFile(new URL('.env', import.meta.url).pathname)
--- a/website/zh-CN/api/harness/agents.md
+++ b/website/zh-CN/api/harness/agents.md
@@ -6,7 +6,7 @@

 Agent service (`ctx.agents`): tracks live agents and carries the initiating Agent through one process-local asynchronous driver chain. Agent *creation* is provided by whichever plugin implements the AgentFactory (`@deepseek-ai/dsh-agent-loop`), registered via setFactory.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L204)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L211)

 ### ctx.agents.currentInitiator()

@@ -18,7 +18,7 @@ Read the Agent that initiated the inherited asynchronous driver chain.

 **Returns** the inherited Agent, or `undefined` outside a driver and inside an explicit clearing boundary.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L233)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L246)

 ### ctx.agents.requireInitiator()

@@ -30,7 +30,7 @@ Read the initiating Agent and fail when no driver boundary is active.

 **Returns** the inherited Agent.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L243)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L256)

 ### ctx.agents.withInitiator(agent, operation)

@@ -38,14 +38,14 @@ Read the initiating Agent and fail when no driver boundary is active.
 withInitiator<T>(agent: Agent, operation: () => T): T
 ```

-Run an operation with one exact Agent as its process-local initiator. The exact synchronous value or Promise returned by the operation is preserved.
+Run an operation with one exact Agent as its process-local initiator. The exact synchronous value or Promise returned by the operation is preserved. If its inherited async chain starts an owning-fiber unload, the nested boundary lineage is excluded from the drain so teardown cannot wait on itself.

 - `agent` — initiating Agent to inherit; presence is neither liveness proof nor authorization.
 - `operation` — synchronous or asynchronous operation to invoke.

 **Returns** the exact value returned by `operation`.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L257)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L272)

 ### ctx.agents.withoutInitiator(operation)

@@ -53,13 +53,13 @@ Run an operation with one exact Agent as its process-local initiator. The exact
 withoutInitiator<T>(operation: () => T): T
 ```

-Run an operation inside a boundary that hides any inherited initiating Agent. The exact synchronous value or Promise is preserved.
+Run an operation inside a boundary that hides any inherited initiating Agent. The exact synchronous value or Promise is preserved. If its inherited async chain starts an owning-fiber unload, the nested boundary lineage is excluded from the drain so teardown cannot wait on itself.

 - `operation` — synchronous or asynchronous operation to invoke without an initiator.

 **Returns** the exact value returned by `operation`.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L268)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L285)

 ### ctx.agents.setFactory(factory)

@@ -73,7 +73,7 @@ Register the agent-creation factory (the loop calls this on construction, effect

 **Returns** the disposer that clears the factory slot. The exact Cordis effect disposer (single-shot): composite (generator) effects may yield it directly — exact identity nests the teardown in order.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L284)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L301)

 ### ctx.agents.create(options)

@@ -87,7 +87,7 @@ Create and publish a new agent through the registered factory. Distinct from reg

 **Returns** the handle after setup, rollback-covered publication, and loop start complete.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L317)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L334)

 ### ctx.agents.resume(options)

@@ -101,7 +101,7 @@ Load a persisted session and resume an agent on it through the registered factor

 **Returns** the handle after setup, rollback-covered publication, and loop start complete.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L336)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L353)

 ### ctx.agents.register(agent)

@@ -115,7 +115,7 @@ Register a live agent. Throws if an agent with the same id is already registered

 **Returns** the EXACT Cordis effect disposer (single-shot; a repeat call returns undefined without awaiting an in-flight teardown). Exact identity is load-bearing: a composite (generator) effect that owns a teardown ORDER — the agent factory's lifecycle chain — must yield THIS function so Cordis nests the unregistration at that yield position; yielding a wrapper would leave it disposing as a concurrent sibling on owner unload, unregistering the agent (and emitting `agent/disposed`) while its final turn is still draining.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L362)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L379)

 ### ctx.agents.enter(agent, owner)

@@ -130,7 +130,7 @@ Insert an already-constructed agent without announcing it. This is the advanced

 **Returns** an idempotent closure that removes this exact entry and emits `agent/disposed` with listener failures contained. When called from a synchronous `agent/created` listener, removal and disposal wait until that creation dispatch unwinds.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L386)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L403)

 ### ctx.agents.announce(agent)

@@ -142,7 +142,7 @@ Announce an agent previously inserted with enter.

 - `agent` — the live inserted agent to announce.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L461)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L478)

 ### ctx.agents.get(id)

@@ -156,7 +156,7 @@ Look up a live agent.

 **Returns** the agent, or undefined when no live agent has that id.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L495)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L512)

 ### ctx.agents.isOwnedBy(id, owner)

@@ -171,7 +171,7 @@ Test whether a live agent was created through one exact parent agent's scoped co

 **Returns** true only while the exact child entry is live under that owner.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L507)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L524)

 ### ctx.agents.list()

@@ -183,7 +183,7 @@ All live agents, in registration order.

 **Returns** a fresh array; mutating it does not affect the registry.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L515)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L532)

 ### ctx.agents.roots()

@@ -195,4 +195,4 @@ All live top-level agents in registration order. A top-level agent was created w

 **Returns** a fresh array; mutating it does not affect the registry.

-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L525)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L542)