diff --git a/.agents/skills/dsh-pre-push-checks/SKILL.md b/.agents/skills/dsh-pre-push-checks/SKILL.md
index 4ce005ee79..433aa38942 100644
--- 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.
diff --git a/AGENTS.md b/AGENTS.md
index 38799b8e96..efaa29bbac 100644
--- 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.
diff --git a/README.i18n.yaml b/README.i18n.yaml
index 19c4ccf72d..64e212ff3a 100644
--- 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
diff --git a/README.md b/README.md
index aaa129272e..ef9a3a8832 100644
--- 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)
 ```
diff --git a/README.zh.md b/README.zh.md
index 42f2ed9b57..a30d6db4b0 100644
--- 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)
 ```
diff --git a/docs/AGENTS.md b/docs/AGENTS.md
index dc06018c16..f7635c659b 100644
--- a/docs/AGENTS.md
+++ b/docs/AGENTS.md
@@ -27,7 +27,7 @@ Placement: bugs → postmortems; rationale → RFCs; procedures → cookbooks; t
 - **Document current state, not change history.** Avoid "previously/now/no longer", PRs, commits, and stack positions in durable prose; name the live mechanism. Put change stories in commits, PRs, RFCs, or postmortems.
 - **Write an RFC in the same PR for decisions a maintainer may reasonably revisit.** Mechanical or self-evident changes need none ([when to write one](rfc/README.md)).
 - **One physical line per paragraph** (`verify-md-wrap`): use editor soft-wrap. Code blocks, tables, and list structure keep their formatting; code comments stay under the linter's column limit.
-- **Fenced `ts` blocks must compile** (`doc-typecheck`); a pasted type declaration and its original JSDoc are fenced ` ```ts type-equiv ` and registered in the manifest so neither can drift ([mechanics](development.md#documenting-types-verbatim-ts-type-equiv)).
+- **Fenced `ts` blocks must compile** (`doc-typecheck`); a pasted type declaration and its original JSDoc use ` ```ts type-equiv `, while a body-stripped public class declaration uses ` ```ts public-api `; register either in the manifest so neither can drift ([mechanics](development.md#documenting-types-verbatim-ts-type-equiv)).
 - **The [core-data-structures catalog](core-data-structures/core.md) updates in the same change** that reshapes a documented type. `verify-type-equiv` catches drifted pastes, not never-documented new types ([what counts as core](core-data-structures/core.md#what-counts-as-core)).
 - **Bilingual pairs update together**: editing either side obligates the counterpart and a re-record in the same change ([i18n contract](i18n/README.md)).
 - **Comments and JSDoc state complete contracts, not reasoning transcripts.** Preserve behavior, conditions, timing, modality, exceptions, consequences, and non-obvious orientation; delete implementation narration, test walkthroughs, review analysis, and code restatement. Keep the local contract and link to its owning rationale. Use [dsh-prose-standard](../.agents/skills/dsh-prose-standard/SKILL.md) for required coverage, decision rules, and examples.
diff --git a/docs/architecture.md b/docs/architecture.md
index 5ef170d51e..c181e4b951 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -16,7 +16,7 @@ A harness is one [Cordis](cordis-primer.md) context. Packages contribute service
 | `ctx.sessions` | `dsh-session` | in-memory event-sourced sessions |
 | `ctx.systemPrompt` | `dsh-system-prompt` | ordered prompt sections, tool schemas, and prompt variables |
 | `ctx.tools` | `dsh-tools` | tool registry and [execution pipeline](tool-execution-pipeline.md) |
-| `ctx.agents` | `dsh-agent` | live agent registry, public `Agent` handle, `agent/*` events |
+| `ctx.agents` | `dsh-agent` | live agents, creation delegation, `agent/*` events, and process-local initiating Agent scope |
 | `ctx.agentLoop` | `dsh-agent-loop` | concrete `Agent` driver |
 
 ### Capability Services
@@ -118,6 +118,10 @@ Every session event is turn-enclosed. Reloading preserves an interrupted tail an
 
 Every live agent owns a scoped `agent.ctx`. Its registrations shadow globals, receive only that agent's dispatches, and unwind with it; async effects such as background-task cleanup are awaited. `CreateAgentOptions.setup(agentCtx)` composes the scope before publication. Typed resolvers derive carrier checks from merged `Events` signatures and `scopeTarget` ([semantic-gates RFC](rfc/implemented/process/2026-07-14-typescript-program-backed-semantic-gates.md)). See the [agent-scope RFC](rfc/implemented/architecture/2026-07-08-agent-scope-contexts.md) and [subagent composition controls](rfc/implemented/feature/2026-07-12-subagent-persona-tool-filter-and-depth.md).
 
+### Initiating Agent Scope
+
+`AgentLoop` runs each driver inside `ctx.agents.withInitiator()`; private code derives `agent.session`, while other identities stay explicit ([decision](rfc/implemented/architecture/2026-07-15-agent-initiator-scope.md)).
+
 ## State
 
 ### Session Log
@@ -146,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
 
diff --git a/docs/capability-seams.md b/docs/capability-seams.md
index 03239998b8..c119b79c18 100644
--- 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"]
@@ -48,7 +49,7 @@ flowchart LR
   pkg_skill["skill"]
   svc_skills["ctx.skills<br/>Skill provider registry"]
   pkg_skill_local["skill-local"]
-  svc_agents["ctx.agents<br/>Agent registry"]
+  svc_agents["ctx.agents<br/>Agent service"]
   svc_agentLoop["ctx.agentLoop<br/>Concrete loop driver"]
   pkg_agent_spine_demo["agent-spine-demo"]
   pkg_bash["bash"]
@@ -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 and the create/resume factory seam. |
+| `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. |
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index f77334b442..c3b185d13e 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -99,7 +99,7 @@ export interface Config {
 }
 ```
 
-Depends on: [`AgentOptions`](../packages/core/agent/src/index.ts) · [`SessionId`](../packages/core/session/src/index.ts)
+Depends on: [`AgentOptions`](core-data-structures/core.md) · [`SessionId`](core-data-structures/core.md)
 
 Source: [`packages/core/agent-loop/src/index.ts:369`](../packages/core/agent-loop/src/index.ts)
 
@@ -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
@@ -1108,7 +1144,7 @@ export interface Config {
 }
 ```
 
-Depends on: [`AgentOptions`](../packages/core/agent/src/index.ts)
+Depends on: [`AgentOptions`](core-data-structures/core.md)
 
 Source: [`packages/subagent/tool-subagent/src/index.ts:23`](../packages/subagent/tool-subagent/src/index.ts)
 
diff --git a/docs/cookbook/extension-cookbook.i18n.yaml b/docs/cookbook/extension-cookbook.i18n.yaml
index 3829d4eca7..9a2aec30a5 100644
--- 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
diff --git a/docs/cookbook/extension-cookbook.md b/docs/cookbook/extension-cookbook.md
index d271ceee20..75cea09ad9 100644
--- 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
 
diff --git a/docs/cookbook/extension-cookbook.zh.md b/docs/cookbook/extension-cookbook.zh.md
index bdd2c5f086..6db3947b54 100644
--- 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) 共享主干。
 
 ## 功能→机制映射
 
diff --git a/docs/cordis-catalog/events.md b/docs/cordis-catalog/events.md
index 12f877ad48..f522790fd0 100644
--- a/docs/cordis-catalog/events.md
+++ b/docs/cordis-catalog/events.md
@@ -31,7 +31,7 @@ A fully configured agent and live session were published. Setup is composition-o
 'agent/created'(this: Scoped<Agent>, agent: Agent): void
 ```
 
-Types: [Agent](../core-data-structures/core.md)
+Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
 Source: [`packages/core/agent/src/types.ts:141`](../../packages/core/agent/src/types.ts)
 
@@ -51,7 +51,7 @@ An agent left the registry; AgentLoop emits this after driver quiescence but bef
 'agent/disposed'(this: Scoped<Agent>, agent: Agent): void
 ```
 
-Types: [Agent](../core-data-structures/core.md)
+Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
 Source: [`packages/core/agent/src/types.ts:150`](../../packages/core/agent/src/types.ts)
 
@@ -73,7 +73,7 @@ A step or turn errored. The loop reports a failure here (plus the logger) even w
 'agent/error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: Error): void
 ```
 
-Types: [Agent](../core-data-structures/core.md)
+Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
 Source: [`packages/core/agent/src/types.ts:285`](../../packages/core/agent/src/types.ts)
 
@@ -101,7 +101,7 @@ Awaited serial checkpoint for session-surface mutation after prompt assembly and
 'agent/pre-step'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal): Promise<void> | void
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md)
+Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
 Source: [`packages/core/agent/src/types.ts:204`](../../packages/core/agent/src/types.ts)
 
@@ -122,7 +122,7 @@ Allow, rewrite, or block one drained prompt before it becomes a user message. Ca
 'agent/prompt-submit'(this: Scoped<Agent>, agent: Agent, content: ContentBlock[], source: MessageSource, next: () => Promise<PromptDecision>): Promise<PromptDecision>
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md)
+Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md) · [PromptDecision](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
 Source: [`packages/core/agent/src/types.ts:214`](../../packages/core/agent/src/types.ts)
 
@@ -143,7 +143,7 @@ Detached, frozen content entered the agent's inbox. Source defaults have already
 'agent/queued'(this: Scoped<Agent>, agent: Agent, content: ContentBlock[], info: { source: MessageSource; steering: boolean }): void
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md)
+Types: [Agent](../core-data-structures/core.md) · [ContentBlock](../core-data-structures/core.md) · [MessageSource](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
 Source: [`packages/core/agent/src/types.ts:169`](../../packages/core/agent/src/types.ts)
 
@@ -166,7 +166,7 @@ Replace the frozen call configuration. Model-visible content must use logged cha
 'agent/request'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, config: LlmCallConfig, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [LlmCallConfig](../core-data-structures/core.md)
+Types: [Agent](../core-data-structures/core.md) · [LlmCallConfig](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
 Source: [`packages/core/agent/src/types.ts:226`](../../packages/core/agent/src/types.ts)
 
@@ -192,7 +192,7 @@ Compose request-only messages placed before derived history. The frozen result i
 'agent/session-prefix'(this: Scoped<Agent>, agent: Agent, prefix: Message[], signal: AbortSignal, next: () => Promise<Message[]>): Promise<Message[]>
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md)
+Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
 Source: [`packages/core/agent/src/types.ts:241`](../../packages/core/agent/src/types.ts)
 
@@ -214,7 +214,7 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to
 'agent/session-start'(this: Scoped<Agent>, agent: Agent, source: SessionStartSource): void
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [SessionStartSource](../core-data-structures/core.md)
+Types: [Agent](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md) · [SessionStartSource](../core-data-structures/core.md)
 
 Source: [`packages/core/agent/src/types.ts:182`](../../packages/core/agent/src/types.ts)
 
@@ -234,7 +234,7 @@ Agent status changed (`idle` ⇄ `running`, or → `disposed`). `send()` does no
 'agent/status'(this: Scoped<Agent>, agent: Agent, status: AgentStatus): void
 ```
 
-Types: [Agent](../core-data-structures/core.md)
+Types: [Agent](../core-data-structures/core.md) · [AgentStatus](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
 Source: [`packages/core/agent/src/types.ts:159`](../../packages/core/agent/src/types.ts)
 
@@ -256,7 +256,7 @@ Waterfall: post-process the assembled assistant Message before tool dispatch (va
 'agent/step-result'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, message: Message, next: () => Promise<Message>): Promise<Message>
 ```
 
-Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md)
+Types: [Agent](../core-data-structures/core.md) · [Message](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
 Source: [`packages/core/agent/src/types.ts:252`](../../packages/core/agent/src/types.ts)
 
@@ -277,7 +277,7 @@ Override whether the turn continues. The default continues after tool calls or s
 'agent/turn-continuation'(this: Scoped<Agent>, agent: Agent, turn: number, defaultDecision: ContinuationDecision, next: () => Promise<ContinuationDecision>): Promise<ContinuationDecision>
 ```
 
-Types: [Agent](../core-data-structures/core.md)
+Types: [Agent](../core-data-structures/core.md) · [ContinuationDecision](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
 Source: [`packages/core/agent/src/types.ts:262`](../../packages/core/agent/src/types.ts)
 
@@ -298,7 +298,7 @@ Monotonic terminal-stop checkpoint after continuation and steering are folded; a
 'agent/turn-stop'(this: Scoped<Agent>, agent: Agent, turn: number): ContinuationStop | undefined
 ```
 
-Types: [Agent](../core-data-structures/core.md)
+Types: [Agent](../core-data-structures/core.md) · [ContinuationStop](../core-data-structures/core.md) · [Scoped](../core-data-structures/scope.md)
 
 Source: [`packages/core/agent/src/types.ts:272`](../../packages/core/agent/src/types.ts)
 
@@ -321,6 +321,8 @@ A declarative agent entry failed before it could publish a live agent. Consumers
 'agent-loop/config-start-failed'(sessionId: SessionId, error: unknown): void
 ```
 
+Types: [SessionId](../core-data-structures/core.md)
+
 Source: [`packages/core/agent-loop/src/index.ts:362`](../../packages/core/agent-loop/src/index.ts)
 
 ## `approval/*`
@@ -340,7 +342,7 @@ Ask composed answerers for one decision. Return an outcome to claim the request
 'approval/request'(this: Scoped<ApprovalService>, req: ApprovalRequest, next: () => Promise<ApprovalOutcome>): Promise<ApprovalOutcome>
 ```
 
-Types: [ApprovalOutcome](../core-data-structures/approval.md) · [ApprovalRequest](../core-data-structures/approval.md)
+Types: [ApprovalOutcome](../core-data-structures/approval.md) · [ApprovalRequest](../core-data-structures/approval.md) · [ApprovalService](../core-data-structures/approval.md) · [Scoped](../core-data-structures/scope.md)
 
 Source: [`packages/ui/user-approval/src/index.ts:31`](../../packages/ui/user-approval/src/index.ts)
 
@@ -426,7 +428,7 @@ Waterfall around every streaming model call (retry, replay, routing). Bound to t
 'llm/stream'(this: LlmService, options: GenerateOptions, next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>
 ```
 
-Types: [GenerateOptions](../core-data-structures/core.md) · [StreamChunk](../core-data-structures/llm-streaming.md)
+Types: [GenerateOptions](../core-data-structures/core.md) · [LlmService](../core-data-structures/llm-streaming.md) · [StreamChunk](../core-data-structures/llm-streaming.md)
 
 Source: [`packages/llm/llm/src/index.ts:40`](../../packages/llm/llm/src/index.ts)
 
@@ -451,6 +453,8 @@ Creation announcement during session publication. A synchronous throw vetoes and
 'session/created'(this: Scoped<Session>, session: Session): void
 ```
 
+Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md)
+
 Source: [`packages/core/session/src/index.ts:47`](../../packages/core/session/src/index.ts)
 
 ### `session/disposed` — emit
@@ -470,6 +474,8 @@ Emitted once when an announced session leaves the store, including publication r
 'session/disposed'(this: Scoped<Session>, session: Session): void
 ```
 
+Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md)
+
 Source: [`packages/core/session/src/index.ts:57`](../../packages/core/session/src/index.ts)
 
 ### `session/event` — emit
@@ -491,7 +497,7 @@ Post-commit, fire-and-forget append feed. The listener snapshot resolves before
 'session/event'(this: Scoped<Session>, session: Session, event: SessionEvent): void
 ```
 
-Types: [SessionEvent](../core-data-structures/core.md)
+Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md) · [SessionEvent](../core-data-structures/core.md)
 
 Source: [`packages/core/session/src/index.ts:69`](../../packages/core/session/src/index.ts)
 
@@ -512,6 +518,8 @@ Awaited parallel durability checkpoint: every listener runs and the caller await
 'session/flush'(this: Scoped<Session>, session: Session): Promise<void> | void
 ```
 
+Types: [Scoped](../core-data-structures/scope.md) · [Session](../core-data-structures/session.md)
+
 Source: [`packages/core/session/src/index.ts:79`](../../packages/core/session/src/index.ts)
 
 ## `subagent/*`
@@ -532,6 +540,8 @@ A ready child settled. Scope-filtered dispatch uses the same delegating parent c
 'subagent/end'(this: Scoped<SubagentService>, info: SubagentRunEndInfo): void
 ```
 
+Types: [Scoped](../core-data-structures/scope.md) · [SubagentService](../core-data-structures/subagent.md)
+
 Source: [`packages/subagent/subagent/src/index.ts:112`](../../packages/subagent/subagent/src/index.ts)
 
 ### `subagent/provider-added` — emit
@@ -547,6 +557,8 @@ A provider became resolvable in the registry.
 'subagent/provider-added'(provider: SubagentProvider): void
 ```
 
+Types: [SubagentProvider](../core-data-structures/subagent.md)
+
 Source: [`packages/subagent/subagent/src/index.ts:86`](../../packages/subagent/subagent/src/index.ts)
 
 ### `subagent/provider-removed` — emit
@@ -582,6 +594,8 @@ A provider established a ready child. For in-process providers, `ctx.agents.get(
 'subagent/start'(this: Scoped<SubagentService>, info: SubagentRunInfo): void
 ```
 
+Types: [Scoped](../core-data-structures/scope.md) · [SubagentService](../core-data-structures/subagent.md)
+
 Source: [`packages/subagent/subagent/src/index.ts:103`](../../packages/subagent/subagent/src/index.ts)
 
 ## `system-prompt/*`
@@ -602,6 +616,8 @@ Expert waterfall over the assembled sections, tools, and variables. Scope-filter
 'system-prompt/assemble'(this: Scoped<SystemPrompt>, assembly: PromptAssembly, context: AssembleContext, next: () => Promise<PromptAssembly>): Promise<PromptAssembly>
 ```
 
+Types: [AssembleContext](../core-data-structures/system-prompt.md) · [Scoped](../core-data-structures/scope.md) · [SystemPrompt](../core-data-structures/system-prompt.md)
+
 Source: [`packages/core/system-prompt/src/index.ts:27`](../../packages/core/system-prompt/src/index.ts)
 
 ### `system-prompt/change` — emit
@@ -656,7 +672,7 @@ Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns a nor
 'tools/execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, next: () => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>
 ```
 
-Types: [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md)
+Types: [Scoped](../core-data-structures/scope.md) · [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) · [ToolRegistry](../core-data-structures/tools.md)
 
 Source: [`packages/core/tools/src/index.ts:89`](../../packages/core/tools/src/index.ts)
 
@@ -676,7 +692,7 @@ Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts
 'tools/post-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, result: Readonly<ToolExecutionResult>, next: () => Promise<PostToolDecision>): Promise<PostToolDecision>
 ```
 
-Types: [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md)
+Types: [PostToolDecision](../core-data-structures/tools.md) · [Scoped](../core-data-structures/scope.md) · [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) · [ToolRegistry](../core-data-structures/tools.md)
 
 Source: [`packages/core/tools/src/index.ts:98`](../../packages/core/tools/src/index.ts)
 
@@ -695,7 +711,7 @@ Allow, deny, or ask before dispatch. `next()` delegates to allow; missing approv
 'tools/pre-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision>
 ```
 
-Types: [ToolExecution](../core-data-structures/tools.md)
+Types: [PreToolDecision](../core-data-structures/tools.md) · [Scoped](../core-data-structures/scope.md) · [ToolExecution](../core-data-structures/tools.md) · [ToolRegistry](../core-data-structures/tools.md)
 
 Source: [`packages/core/tools/src/index.ts:80`](../../packages/core/tools/src/index.ts)
 
@@ -714,7 +730,7 @@ Observe the frozen, lossless-JSON final outcome. Listener failures are contained
 'tools/result'(this: Scoped<ToolRegistry>, exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): undefined
 ```
 
-Types: [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md)
+Types: [Scoped](../core-data-structures/scope.md) · [ToolExecution](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) · [ToolRegistry](../core-data-structures/tools.md)
 
 Source: [`packages/core/tools/src/index.ts:106`](../../packages/core/tools/src/index.ts)
 
@@ -738,6 +754,8 @@ One `agent()` call settled (clean result, child failure, or run cancellation). P
 'workflow/agent-end'(info: WorkflowRunInfo, agent: WorkflowAgentEndInfo): void
 ```
 
+Types: [WorkflowRunInfo](../core-data-structures/workflow.md)
+
 Source: [`packages/workflow/workflow/src/index.ts:81`](../../packages/workflow/workflow/src/index.ts)
 
 ### `workflow/agent-start` — emit
@@ -757,6 +775,8 @@ One `agent()` call established a ready child run. Paired with Events['workflow/a
 'workflow/agent-start'(info: WorkflowRunInfo, agent: WorkflowAgentInfo): void
 ```
 
+Types: [WorkflowRunInfo](../core-data-structures/workflow.md)
+
 Source: [`packages/workflow/workflow/src/index.ts:70`](../../packages/workflow/workflow/src/index.ts)
 
 ### `workflow/end` — emit
@@ -776,6 +796,8 @@ A workflow run settled (any stop reason). Fired when WorkflowRun.result resolves
 'workflow/end'(info: WorkflowRunInfo, result: WorkflowResultInfo): void
 ```
 
+Types: [WorkflowRunInfo](../core-data-structures/workflow.md)
+
 Source: [`packages/workflow/workflow/src/index.ts:91`](../../packages/workflow/workflow/src/index.ts)
 
 ### `workflow/log` — emit
@@ -792,6 +814,8 @@ The script emitted a narration line (a `log(message)` call).
 'workflow/log'(info: WorkflowRunInfo, message: string): void
 ```
 
+Types: [WorkflowRunInfo](../core-data-structures/workflow.md)
+
 Source: [`packages/workflow/workflow/src/index.ts:60`](../../packages/workflow/workflow/src/index.ts)
 
 ### `workflow/phase` — emit
@@ -809,6 +833,8 @@ The script entered a phase (a `phase(title)` call) — progress grouping for obs
 'workflow/phase'(info: WorkflowRunInfo, title: string): void
 ```
 
+Types: [WorkflowRunInfo](../core-data-structures/workflow.md)
+
 Source: [`packages/workflow/workflow/src/index.ts:53`](../../packages/workflow/workflow/src/index.ts)
 
 ### `workflow/start` — emit
@@ -825,6 +851,8 @@ A workflow run started — the script's meta block validated, the body about to
 'workflow/start'(info: WorkflowRunInfo): void
 ```
 
+Types: [WorkflowRunInfo](../core-data-structures/workflow.md)
+
 Source: [`packages/workflow/workflow/src/index.ts:45`](../../packages/workflow/workflow/src/index.ts)
 
 ## Inherited events (cordis core + loader/hmr/timer)
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index 78ec4c82c0..267c2f0caa 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -42,15 +42,66 @@ async createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<Agent
 async resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandle>
 ```
 
-Types: [Agent](../core-data-structures/core.md)
+Types: [Agent](../core-data-structures/core.md) · [AgentOptions](../core-data-structures/core.md) · [SessionHeader](../core-data-structures/persistence.md) · [SessionId](../core-data-structures/core.md)
 
 Source: [`packages/core/agent-loop/src/index.ts:407`](../../packages/core/agent-loop/src/index.ts)
 
 ## `ctx.agents` — `AgentRegistry`
 
-Agent registry (`ctx.agents`): tracks live agents so UI, hook, and orchestrator plugins can find them without depending on the concrete loop package. Agent *creation* is provided by whichever plugin implements the AgentFactory (`@deepseek-ai/dsh-agent-loop`), registered via setFactory.
+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.
+
+Initiator methods provide same-process causal attribution only. Ambient presence is neither liveness proof nor authorization; subjects and owners remain explicit, as does identity at worker, process, persistence, and wire boundaries. Returned Promise boundaries drain during teardown, except a nested lineage that starts an owning-fiber unload is excluded from its own drain.
 
 ```ts cordis-catalog
+/**
+ * Read the Agent that initiated the inherited asynchronous driver chain.
+ * Use this optional form for logging, tracing, metrics, or host attribution
+ * that also supports agentless calls. When a parent creates a child, setup
+ * reports the causal parent while `agentCtx.agent` identifies the child.
+ * @returns the inherited Agent, or `undefined` outside an initiator boundary
+ *   and inside an explicit clearing boundary.
+ * @throws when this service instance has been disposed.
+ */
+currentInitiator(): Agent | undefined
+
+/**
+ * Read the initiating Agent and fail when no initiator boundary is active.
+ * Use this for private helpers contractually below a driver, or for a
+ * deployment-owned outbound request whose contract forbids agentless calls.
+ * Generic or direct-call seams use optional lookup or explicit request fields.
+ * @returns the inherited Agent.
+ * @throws when no initiator is active or this service instance has been disposed.
+ */
+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.
+ * Custom drivers and test harnesses wrap their complete returned foreground
+ * lifetime.
+ * A queue or wire receiver may establish this boundary only after validating
+ * explicit identity and resolving the exact live Agent; this method does neither.
+ * Detached work remains owned by the subsystem that starts it.
+ * @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`.
+ * @throws when the initiator scope is closing/disposed, or when `operation` throws.
+ */
+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.
+ * Use this while creating lazy shared timers, queue pumps, pool maintenance,
+ * watchers, or exporters so they do not inherit the first Agent that happens
+ * to initialize them. It clears only initiator attribution, not explicit
+ * fields, and does not own or drain detached resources.
+ * @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.
+ */
+withoutInitiator<T>(operation: () => T): T
+
 /**
  * Register the agent-creation factory (the loop calls this on construction,
  * effect-scoped). A traced Cordis service is canonicalized to its concrete
@@ -163,9 +214,9 @@ list(): Agent[]
 roots(): Agent[]
 ```
 
-Types: [Agent](../core-data-structures/core.md)
+Types: [Agent](../core-data-structures/core.md) · [SessionId](../core-data-structures/core.md)
 
-Source: [`packages/core/agent/src/index.ts:201`](../../packages/core/agent/src/index.ts)
+Source: [`packages/core/agent/src/index.ts:217`](../../packages/core/agent/src/index.ts)
 
 ## `ctx.approval` — `ApprovalService`
 
@@ -233,7 +284,7 @@ abstract run(spec: BashExecSpec): Promise<BashRunResult>
 abstract start(spec: BashExecSpec): BashProcess
 ```
 
-Types: [BashExecRequest](../core-data-structures/bash.md) · [BashExecSpec](../core-data-structures/bash.md) · [BashRunResult](../core-data-structures/bash.md)
+Types: [BashExecRequest](../core-data-structures/bash.md) · [BashExecSpec](../core-data-structures/bash.md) · [BashProcess](../core-data-structures/bash.md) · [BashRunResult](../core-data-structures/bash.md)
 
 Source: [`packages/bash/bash/src/index.ts:49`](../../packages/bash/bash/src/index.ts)
 
@@ -264,7 +315,7 @@ collect(execution: ToolExecution): DshEnvironment
 list(): BashEnvVariableInfo[]
 ```
 
-Types: [ToolExecution](../core-data-structures/tools.md)
+Types: [DshEnvironment](../core-data-structures/bash.md) · [ToolExecution](../core-data-structures/tools.md)
 
 Source: [`packages/bash/tool-bash/src/index.ts:102`](../../packages/bash/tool-bash/src/index.ts)
 
@@ -331,7 +382,7 @@ abstract compactIfNeeded( agent: CompactAgentContext, fullSystemPrompt: string,
 abstract compactRegion( start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>
 ```
 
-Types: [Message](../core-data-structures/core.md)
+Types: [CompactionResult](../core-data-structures/compaction.md) · [Message](../core-data-structures/core.md)
 
 Source: [`packages/compact/compact/src/index.ts:38`](../../packages/compact/compact/src/index.ts)
 
@@ -427,7 +478,7 @@ abstract writeText(target: FsTarget, content: string, expected?: FsWriteIntent,
 abstract editText(target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal): Promise<FsEditOutcome>
 ```
 
-Types: [FsEditOutcome](../core-data-structures/filesystem.md) · [FsEditRequest](../core-data-structures/filesystem.md) · [FsInfo](../core-data-structures/filesystem.md) · [FsTarget](../core-data-structures/filesystem.md) · [FsVersion](../core-data-structures/filesystem.md) · [FsWriteIntent](../core-data-structures/filesystem.md) · [FsWriteOutcome](../core-data-structures/filesystem.md)
+Types: [FsDirEntry](../core-data-structures/filesystem.md) · [FsEditOutcome](../core-data-structures/filesystem.md) · [FsEditRequest](../core-data-structures/filesystem.md) · [FsInfo](../core-data-structures/filesystem.md) · [FsPathInfo](../core-data-structures/filesystem.md) · [FsTarget](../core-data-structures/filesystem.md) · [FsVersion](../core-data-structures/filesystem.md) · [FsWriteIntent](../core-data-structures/filesystem.md) · [FsWriteOutcome](../core-data-structures/filesystem.md)
 
 Source: [`packages/fs/fs/src/index.ts:80`](../../packages/fs/fs/src/index.ts)
 
@@ -472,7 +523,7 @@ async listModels(provider: string): Promise<LlmModelInfo[]>
 stream(options: GenerateOptions): AsyncIterable<StreamChunk>
 ```
 
-Types: [GenerateOptions](../core-data-structures/core.md) · [StreamChunk](../core-data-structures/llm-streaming.md)
+Types: [GenerateOptions](../core-data-structures/core.md) · [LlmAdapter](../core-data-structures/llm-streaming.md) · [LlmModelInfo](../core-data-structures/core.md) · [LlmProviderInfo](../core-data-structures/core.md) · [StreamChunk](../core-data-structures/llm-streaming.md)
 
 Source: [`packages/llm/llm/src/index.ts:94`](../../packages/llm/llm/src/index.ts)
 
@@ -516,7 +567,7 @@ optionOf(name: string): PresetOption
 set(session: Session, name: string): void
 ```
 
-Types: [SessionEvent](../core-data-structures/core.md)
+Types: [Session](../core-data-structures/session.md) · [SessionEvent](../core-data-structures/core.md)
 
 Source: [`packages/ui/permission/src/index.ts:94`](../../packages/ui/permission/src/index.ts)
 
@@ -594,7 +645,7 @@ abstract load(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEven
 abstract list(): Promise<SessionHeader[]>
 ```
 
-Types: [SessionEvent](../core-data-structures/core.md)
+Types: [SessionEvent](../core-data-structures/core.md) · [SessionHeader](../core-data-structures/persistence.md) · [SessionId](../core-data-structures/core.md) · [SessionLocation](../core-data-structures/persistence.md)
 
 Source: [`packages/session-persistence/session-persistence/src/index.ts:42`](../../packages/session-persistence/session-persistence/src/index.ts)
 
@@ -640,6 +691,8 @@ async traceEvent(request: SessionEventTraceRequest): Promise<SessionEventTrace>
 async readEvent(request: SessionEventReadRequest): Promise<SessionEventWindow>
 ```
 
+Types: [SessionEventReadRequest](../core-data-structures/session-query.md) · [SessionEventRecord](../core-data-structures/session-query.md) · [SessionEventTrace](../core-data-structures/session-query.md) · [SessionEventTraceRequest](../core-data-structures/session-query.md) · [SessionEventWindow](../core-data-structures/session-query.md) · [SessionId](../core-data-structures/core.md) · [SessionLineageTrace](../core-data-structures/session-query.md) · [SessionRecord](../core-data-structures/session-query.md)
+
 Source: [`packages/session-query/session-query/src/index.ts:38`](../../packages/session-query/session-query/src/index.ts)
 
 ## `ctx.sessions` — `SessionStore`
@@ -765,6 +818,8 @@ list(): Session[]
 fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session
 ```
 
+Types: [CreateSessionOptions](../core-data-structures/persistence.md) · [Session](../core-data-structures/session.md) · [SessionId](../core-data-structures/core.md)
+
 Source: [`packages/core/session/src/index.ts:577`](../../packages/core/session/src/index.ts)
 
 ## `ctx.skills` — `SkillService`
@@ -811,6 +866,8 @@ async list(options: SkillLookupOptions = {}): Promise<SkillSummary[]>
 async get(name: string, options: SkillLookupOptions = {}): Promise<SkillDefinition | undefined>
 ```
 
+Types: [SkillDefinition](../core-data-structures/skills.md) · [SkillLookupOptions](../core-data-structures/skills.md) · [SkillProvider](../core-data-structures/skills.md) · [SkillRegistration](../core-data-structures/skills.md) · [SkillSummary](../core-data-structures/skills.md)
+
 Source: [`packages/skill/skill/src/index.ts:141`](../../packages/skill/skill/src/index.ts)
 
 ## `ctx.spillStore` — `SpillStore` (abstract seam)
@@ -832,6 +889,8 @@ Semantics every implementation must honor:
 abstract saveText(input: SaveTextSpill): Promise<SpillRef>
 ```
 
+Types: [SaveTextSpill](../core-data-structures/spill.md) · [SpillRef](../core-data-structures/spill.md)
+
 Source: [`packages/spill/spill/src/index.ts:45`](../../packages/spill/spill/src/index.ts)
 
 ## `ctx.subagents` — `SubagentService`
@@ -873,6 +932,8 @@ list(): string[]
 async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>
 ```
 
+Types: [SubagentProvider](../core-data-structures/subagent.md) · [SubagentRun](../core-data-structures/subagent.md) · [SubagentStartRequest](../core-data-structures/subagent.md)
+
 Source: [`packages/subagent/subagent/src/index.ts:153`](../../packages/subagent/subagent/src/index.ts)
 
 ## `ctx.systemPrompt` — `SystemPrompt`
@@ -919,6 +980,8 @@ variable(name: string, provider: (context: AssembleContext) => string | undefine
 async assemble(context: AssembleContext = {}): Promise<PromptAssembly>
 ```
 
+Types: [AssembleContext](../core-data-structures/system-prompt.md) · [PromptSection](../core-data-structures/system-prompt.md) · [ToolProviderResult](../core-data-structures/system-prompt.md)
+
 Source: [`packages/core/system-prompt/src/index.ts:209`](../../packages/core/system-prompt/src/index.ts)
 
 ## `ctx.tasks` — `TaskService`
@@ -1006,7 +1069,7 @@ onTaskDone(listener: TaskDoneListener): () => void
 attachSurface(name: string): () => void
 ```
 
-Types: [Agent](../core-data-structures/core.md)
+Types: [Agent](../core-data-structures/core.md) · [TaskDoneListener](../core-data-structures/tasks.md) · [TaskId](../core-data-structures/tasks.md) · [TaskRead](../core-data-structures/tasks.md) · [TaskSnapshot](../core-data-structures/tasks.md) · [TaskStart](../core-data-structures/tasks.md)
 
 Source: [`packages/tasks/tasks/src/index.ts:76`](../../packages/tasks/tasks/src/index.ts)
 
@@ -1041,7 +1104,7 @@ measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement
 estimateMessage(message: Message): number
 ```
 
-Types: [Message](../core-data-structures/core.md)
+Types: [EpochHeader](../core-data-structures/session.md) · [Message](../core-data-structures/core.md) · [Session](../core-data-structures/session.md) · [TokenMeasurement](../core-data-structures/token-meter.md)
 
 Source: [`packages/llm/token-meter/src/index.ts:106`](../../packages/llm/token-meter/src/index.ts)
 
@@ -1119,7 +1182,7 @@ executionMode(exec: ToolExecutionInput): ToolExecutionMode
 async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>
 ```
 
-Types: [ToolDefinition](../core-data-structures/tools.md) · [ToolExecutionInput](../core-data-structures/tools.md) · [ToolExecutionMode](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md)
+Types: [ScopeKey](../core-data-structures/scope.md) · [ToolDefinition](../core-data-structures/tools.md) · [ToolExecutionInput](../core-data-structures/tools.md) · [ToolExecutionMode](../core-data-structures/tools.md) · [ToolExecutionResult](../core-data-structures/tools.md) · [ToolGuard](../core-data-structures/tools.md) · [ToolRestriction](../core-data-structures/tools.md) · [ToolSchema](../core-data-structures/tools.md)
 
 Source: [`packages/core/tools/src/index.ts:438`](../../packages/core/tools/src/index.ts)
 
@@ -1145,6 +1208,8 @@ registerProvider(provider: UserInteractionProvider): () => void
 async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>
 ```
 
+Types: [AskUserQuestionAnswer](../core-data-structures/user-interaction.md) · [AskUserQuestionRequest](../core-data-structures/user-interaction.md) · [UserInteractionProvider](../core-data-structures/user-interaction.md)
+
 Source: [`packages/ui/user-interaction/src/index.ts:82`](../../packages/ui/user-interaction/src/index.ts)
 
 ## `ctx.web` — `WebService`
@@ -1201,6 +1266,8 @@ async search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearch
 async fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>
 ```
 
+Types: [WebFetchProvider](../core-data-structures/web.md) · [WebFetchRequest](../core-data-structures/web.md) · [WebFetchResult](../core-data-structures/web.md) · [WebSearchProvider](../core-data-structures/web.md) · [WebSearchRequest](../core-data-structures/web.md) · [WebSearchResult](../core-data-structures/web.md)
+
 Source: [`packages/web/web/src/index.ts:74`](../../packages/web/web/src/index.ts)
 
 ## `ctx.workflows` — `WorkflowService` (abstract seam)
@@ -1217,6 +1284,8 @@ Workflow execution seam. Invalid requests throw before publication; a live run i
 abstract start(request: WorkflowStartRequest): WorkflowRun
 ```
 
+Types: [WorkflowRun](../core-data-structures/workflow.md) · [WorkflowStartRequest](../core-data-structures/workflow.md)
+
 Source: [`packages/workflow/workflow/src/index.ts:159`](../../packages/workflow/workflow/src/index.ts)
 
 ## Inherited `ctx` members (cordis core + loader/hmr/timer)
diff --git a/docs/core-data-structures/core.md b/docs/core-data-structures/core.md
index dfb59b3ac6..06781b60a5 100644
--- a/docs/core-data-structures/core.md
+++ b/docs/core-data-structures/core.md
@@ -36,9 +36,7 @@ Everything else is documented on a **sub-page**, not here. The rule that draws t
 | [spill.md](spill.md) | the spill storage seam: `SaveTextSpill`, `SpillOwner`/`SpillSource`, `SpillRef`, the branded `SpillLocator` |
 | [workflow.md](workflow.md) | the workflow seam: `WorkflowStartRequest`, `WorkflowMeta`, `WorkflowRun`/`Result`, the `workflow/*` event payloads, `WorkflowError` fatality |
 
-> Type declarations and their JSDoc on this page are pasted **verbatim** from source and drift-checked by `pnpm run verify-type-equiv` (see [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)).
-
-FIXME(catalog-verbs): the drift gate covers only the nouns (the pasted type shapes); every method surface on these pages is hand-written prose. core-data-structures should probably also generate the *verbs* — the public methods of the cataloged classes — so a signature change cannot silently outdate the catalog.
+> Type declarations and their JSDoc on these pages are source-equivalent and drift-checked by `pnpm run verify-type-equiv` (see [development.md](../development.md#documenting-types-verbatim-ts-type-equiv)). Ordinary blocks preserve complete declarations; `public-api` blocks preserve body-stripped public class declarations. Cordis services use the generated [service catalog](../cordis-catalog/services.md).
 
 ## The `…Map → derived-union` pattern
 
@@ -403,6 +401,10 @@ interface Agent {
 
 The [event taxonomy](../architecture.md#event) owns the `agent/*` lifecycle, checkpoint, and waterfall contracts. Turn and step boundaries are durable session events rather than agent emits.
 
+## Initiating Agent
+
+The process-local initiator carried by `ctx.agents` is the exact `Agent` above, not a separate frame or copied identity. Ambient presence is neither liveness proof nor authorization; the [initiator-scope decision](../rfc/implemented/architecture/2026-07-15-agent-initiator-scope.md) owns its lifetime and boundary rules.
+
 ## Interception decisions
 
 Each `agent/*` interception waterfall returns a small, seam-specific typed union — the unified Decision idiom (the tool seams' `PreToolDecision`/`PostToolDecision` in [tools.md](tools.md) follow the same shape). A CC/Codex hook bridge maps its `permissionDecision`/`decision`/`continue`/`additionalContext` fields onto these; a native plugin returns them directly. Prompt and post-tool decisions share one model-facing context shape, `HookContext`, which is `inject()`ed as a `context/message` and therefore carries a REQUIRED `source` (a missing source would default to `{kind:'user'}` and mislabel plugin context as a user prompt). Its optional `envelope` selects the canonical context tag or caller-owned raw framing, while JSON `meta` persists plugin state without exposing it to the model. Both decisions carry `additionalContexts[]` so every entry preserves its own provenance, framing, and metadata. Continuation reasons are steering messages instead and deliberately use the narrower content/source shape.
diff --git a/docs/core-data-structures/llm-streaming.md b/docs/core-data-structures/llm-streaming.md
index 0ef9ae02f7..ce8c1bf074 100644
--- a/docs/core-data-structures/llm-streaming.md
+++ b/docs/core-data-structures/llm-streaming.md
@@ -91,10 +91,79 @@ interface TokenUsage {
 
 `BlockAssembler` ([`packages/llm/llm/src/assembler.ts`](../../packages/llm/llm/src/assembler.ts)) is the single shared implementation that folds a `StreamChunk` stream back into `ContentBlock`s, usage, finish reason, and replay state. The loop logs the raw chunks while feeding the same chunks through an assembler, then stores the assembled assistant content with its provider/model provenance. A consumer that needs the assembled result without re-implementing the fold uses this.
 
+```ts public-api
+/**
+ * Incrementally assembles raw {@link StreamChunk}s into complete
+ * {@link ContentBlock}s and a final assistant {@link Message}.
+ *
+ * The agent loop feeds it while logging raw chunks for replay fidelity, then
+ * reads `blocks()` / `message()` / `usage` / `finish` once the stream ends.
+ *
+ * Tolerant of delta-only protocols (no block-start/end); deltas arriving for
+ * an index already closed by `block-end` are ignored (malformed stream) so a
+ * misbehaving adapter cannot grow memory or corrupt a completed block.
+ */
+declare class BlockAssembler {
+  /**
+   * Feed one chunk into the assembly state.
+   * @param chunk - the next raw chunk, in stream order.
+   */
+  push(chunk: StreamChunk): void;
+  /**
+   * Assemble all blocks seen so far, in stream order.
+   * @returns one block per seen index; an open block assembles from its
+   *   accumulated deltas (an unknown block type never closed by `block-end` throws).
+   */
+  blocks(): ContentBlock[];
+  /** Usage from the `usage` chunk; undefined until one arrives. */
+  get usage(): TokenUsage | undefined;
+  /** Finish reason from the `finish` chunk; `{kind: 'stop'}` when the stream ended without one. */
+  get finish(): FinishReason;
+  /** Adapter-private replay state from the terminal finish chunk, if any. */
+  get replayState(): unknown;
+  /**
+   * The assembled assistant message.
+   * @returns an assistant-role message over `blocks()` (same open-block assembly rules).
+   */
+  message(): Message;
+}
+```
+
 ## The seam
 
 `LlmAdapter` is the provider seam: subclass, implement `stream()`, and register one adapter instance with `ctx.llm.registerAdapter(providers, adapter)`. `GenerateOptions.provider` selects the registered adapter; `GenerateOptions.model` is passed to that adapter and need not be registered at lifecycle start. Duplicate provider routes fail atomically. Optional `providerInfo()` and asynchronous `listModels()` methods feed `LlmService.listProviders()` / `listModels()` with detached selector metadata. That catalog is advisory rather than a request whitelist: the adapter remains authoritative and may accept unlisted model ids. Adapter lookup happens at the terminal continuation of the `llm/stream` waterfall, so a listener may short-circuit the call or route a mutable one-shot request before lookup. The `block-start` / `block-end` `index` correlation and the assembler together mean an adapter only has to emit well-formed chunks — block reassembly is not each adapter's problem. The consumer surface (`ctx.llm.stream()`) and the `llm/stream` waterfall are described in [architecture.md § Content blocks and streaming](../architecture.md#content-blocks-and-streaming-dsh-llm).
 
+```ts public-api
+/**
+ * Provider-wire adapter for the harness message and stream vocabulary. Register implementations
+ * with `ctx.llm.registerAdapter(providers, adapter)`. Every provider HTTP request must include
+ * `attributionHeaders()`; prove that at the wire or library header-hook boundary. The hand-rolled
+ * DeepSeek and pi-ai adapters intentionally exercise this contract through different internals.
+ */
+declare abstract class LlmAdapter {
+  /**
+   * Describe one provider route owned by this adapter.
+   * @param provider - a route passed to `registerAdapter()` for this instance.
+   * @returns detached display metadata whose id must equal `provider`.
+   */
+  providerInfo(provider: string): LlmProviderInfo;
+  /**
+   * List models this adapter can currently advertise for one owned provider.
+   * The result is advisory: an adapter may accept unlisted model ids, and
+   * consumers must not turn absence into request rejection.
+   * @param _provider - one provider route owned by this adapter.
+   * @returns discoverable models in adapter-preferred order.
+   */
+  listModels(_provider: string): Promise<readonly LlmModelInfo[]>;
+  /**
+   * Stream one model call as raw chunks. The only required method.
+   * @param options - the fully-assembled request; implementations must honor `options.signal`.
+   * @returns the chunk stream, obeying the adapter contract documented on `StreamChunk`.
+   */
+  abstract stream(options: GenerateOptions): AsyncIterable<StreamChunk>;
+}
+```
+
 `ContentBlockType` (the key set the `index`-correlated blocks carry) derives from `ContentBlockMap`:
 
 ```ts type-equiv
diff --git a/docs/core-data-structures/session.md b/docs/core-data-structures/session.md
index 3d3fca045a..3668191fb2 100644
--- a/docs/core-data-structures/session.md
+++ b/docs/core-data-structures/session.md
@@ -305,6 +305,126 @@ interface SurfaceFoldResult {
 }
 ```
 
+## `Session` public API
+
+The body-stripped declaration keeps the plain class's public constructor, state accessors, append boundary, and history projections synchronized with source. Store operations remain in the generated [`ctx.sessions` service catalog](../cordis-catalog/services.md#ctxsessions--sessionstore).
+
+```ts public-api
+/**
+ * An event-sourced session: an append-only log of {@link SessionEvent}s.
+ *
+ * Plain class (not a Service) — create instances via `ctx.sessions.create()`.
+ * Seeding with an existing event log replays/forks a session.
+ */
+declare class Session {
+  /** The ordered surface over this session's event log. */
+  get surface(): SessionSurface;
+  /**
+   * Detached, deep-frozen creation metadata (format version, cwd, lineage,
+   * seed boundary). Supplied by the store via `ctx.sessions.create()`. When a
+   * `Session` is constructed bare (tests, ad-hoc replay), a minimal header is
+   * synthesized (stamped with the current {@link SESSION_FORMAT_VERSION}) so
+   * `session.header` is always present. Kept out of the event log — it is a
+   * storage concern, not replayable conversation state.
+   */
+  readonly header: SessionHeader;
+  /** The session identity, derived from its durable header's single copy. */
+  get id(): SessionId;
+  constructor(id: SessionId, seed?: readonly SessionEvent[], header?: SessionHeader);
+  /**
+   * An immutable snapshot of the append-only event log. The snapshot is reused
+   * until the next append; a previously returned array does not grow later.
+   * Events and their nested data are deep-frozen at acceptance, so neither a
+   * cast nor ordinary JavaScript can rewrite durable history.
+   */
+  get events(): readonly SessionEvent[];
+  /** The next event's sequence number — always the log length (the `seq = log.length` contiguity contract). */
+  get seq(): number;
+  /**
+   * Append one typed event to the log and synchronously notify observers via
+   * the store-owned, module-private publication hooks. The hot path never blocks
+   * on I/O — persistence plugins buffer asynchronously. Once the event enters
+   * the log, the append is committed: observer failures are logged and
+   * contained per listener, so they do not change the return value or prevent
+   * later listeners from observing the same accepted event.
+   *
+   * @param type - The event type (key of {@link SessionEventMap}).
+   * @param data - The event payload; must be JSON-serializable.
+   * @param opts - Surface metadata: `surfaceOp` controls how the event enters
+   *   the ordered surface; `sourceEventSeqs` records provenance (the seq
+   *   numbers of events this one derives from). REQUIRED for
+   *   {@link SurfaceEventType} events (every message-producing event must
+   *   declare how it joins the surface, the sole source of derived history) and
+   *   rejected by the compiler for non-surface types like `turn/start` or
+   *   `assistant/chunk`.
+   * @returns the logged event — its assigned `seq`/`time` plus the SNAPSHOT of
+   *   `data` that entered the log, so reading `event.data` back sees the logged
+   *   value, never the caller's still-mutable input.
+   * @throws if `data` or surface metadata is not losslessly JSON-serializable
+   *   (BigInt, function, symbol, undefined, negative zero, non-finite number,
+   *   circular reference, sparse array, or an exotic object such as
+   *   Map/Set/Date/class instance), or when the candidate violates the
+   *   canonical surface contract (marker shape and eligibility, unique
+   *   earlier provenance, positional replacement validity, and complete
+   *   shadowed-node coverage). One recursive pass reads, validates, and
+   *   copies each nested value once, so a stateful getter cannot supply one value
+   *   to validation and another to storage. The event log is the durable source
+   *   of truth, so a bad event fails at the append site rather than later during
+   *   a backend flush. A synchronous internal dispatch validation failure or an
+   *   append reentered while this acceptance/publication boundary is open also
+   *   rejects before the log changes.
+   */
+  append<T extends SessionEventType>(
+    type: T,
+    data: SessionEventMap[T],
+    ...opts: T extends SurfaceEventType ? [opts: SurfaceIntent] : []
+  ): SessionEvent<T>;
+  /**
+   * The {@link EpochHeader} in force after the log's last header event — the
+   * header the NEXT request will be compared against — or undefined before
+   * the first `request/header` snapshot. The live, incrementally-maintained
+   * form of `foldRequestHeader(session.events)`: each header event is folded
+   * once, when first seen, so a per-step read costs O(new events).
+   * @returns the folded header, or undefined when no header event exists yet.
+   */
+  requestHeader(): EpochHeader | undefined;
+  /**
+   * Derive the LLM message history by walking the ordered sequences of
+   * message-producing events maintained by `surfaceOp` markers. The
+   * surface is the single source of derived history: every message-producing
+   * append records its `surfaceOp`, so a raw event with no marker (a chunk, a
+   * turn boundary) is correctly absent, and a compaction `replace` deletes the
+   * shadowed nodes from the derivation. The projection rules are
+   * {@link deriveEventMessage}, folded per node.
+   *
+   * CACHED: each surface node is projected exactly once, when first seen — a
+   * call costs O(new nodes), and a surface rewrite (a `replace`;
+   * {@link SessionSurface.replaceGeneration}) rebuilds. The returned array is
+   * a fresh snapshot per call (later appends never grow an array a caller
+   * already holds); the `Message` objects in it are SHARED and **deep-frozen**.
+   * Their content reuses the already frozen durable event data, so the cache
+   * needs no second deep clone and consumers still cannot mutate the log.
+   * @returns a fresh array of the shared, frozen derived history.
+   */
+  deriveMessages(): Message[];
+  /**
+   * Project a single event into the LLM message it derives to, or null when
+   * it produces none — a non-surface event (chunk, boundary, log-only record)
+   * or an empty-content assistant/message (which exists only to host usage).
+   * The per-node pure function {@link deriveMessages} folds over the surface;
+   * an external reconstructor (or the dev invariant) folds the same function
+   * over a log prefix's surface to rebuild the exact messages any request was
+   * built from (the reconstructability RFC). The returned message wrapper is
+   * fresh; its content reuses the logged event's already deep-frozen durable
+   * data, so changing the wrapper cannot rewrite the log and changing content
+   * throws.
+   * @param event - the event to project.
+   * @returns the derived message, or null when the event produces none.
+   */
+  deriveEventMessage(event: SessionEvent): Message | null;
+}
+```
+
 ## Derived history: `deriveMessages()` and `deriveEventMessage()`
 
 `Session.deriveMessages()` projects the event log into the `Message[]` the model sees — cached (each surface node projected once, when first seen; a surface rewrite rebuilds) and frozen (a fresh array per call over shared, deep-frozen messages, so mutating logged history through a projection is unrepresentable). `deriveEventMessage(event)` is the per-node pure function the fold applies — public so external reconstructors and the dev invariant project a log prefix with exactly the same rules and cannot disagree with the cache. The projection rules:
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index 692113eb2a..d7f82d7e92 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.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
-development.md: 452f4e82beaeacb23aa6bc3e7a60c0f2b1e2c95e
-development.zh.md: 2285482726c43aa02d31c7d2094e2058de1d3863
+development.md: a3268164cd06fb8bf66f52391bc42c2dc3ca9396
+development.zh.md: f8f29c64aa6e49e3ed6d7ef12df2a4911c9182b0
diff --git a/docs/development.md b/docs/development.md
index 452f4e82be..a3268164cd 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -145,13 +145,13 @@ Pick the tag that matches the urgency so anyone scanning the code can tell a rel
 
 ## Documenting types verbatim (`ts type-equiv`)
 
-The [core data structures](core-data-structures/core.md) docs paste real type declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:
+The [core data structures](core-data-structures/core.md) docs paste source-equivalent declarations together with their original JSDoc so a reader sees the exact shape and source contract. To keep a paste from drifting when source changes, fence it as ` ```ts type-equiv ` (instead of ` ```ts `) and register it in `scripts/type-equiv.manifest.json` with the source file and symbol it mirrors:
 
 ```json
 { "doc": "docs/core-data-structures/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }
 ```
 
-`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate also enforces a 1:1 correspondence: every `ts type-equiv` block has exactly one manifest entry and vice-versa, so a block can't go silently unchecked and a stale entry can't linger. `doc-typecheck` skips `ts type-equiv` blocks (they aren't standalone-compilable) and excludes them from its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a block, update the manifest in the same change.
+`pnpm run verify-type-equiv` (part of `doc-sync`) then extracts that symbol's declaration and attached JSDoc from source via the TypeScript parser and asserts the block matches both. For a class whose implementation bodies do not belong in the catalog, use ` ```ts public-api ` and set `"projection": "public-api"`; the checked projection retains the public fields, constructor, accessors, methods, and original class/member JSDoc while omitting bodies and private or protected members. Comparison ignores whitespace and non-JSDoc comments but requires every original JSDoc comment, including member documentation, so readers see the source contract beside the exact shape. The gate also enforces a 1:1 correspondence by document, symbol, and projection, so a block can't go silently unchecked and a stale entry can't linger. `doc-typecheck` skips both fence kinds (they aren't standalone-compilable) and excludes them from its opt-out ratio. When you change a documented declaration or its JSDoc, the gate fails until you update the paste; when you add or remove a block, update the manifest in the same change.
 
 ## Architecture context
 
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 2285482726..f8f29c64aa 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -145,13 +145,13 @@ pnpm run demo:acp
 
 ## 逐字记录类型（`ts type-equiv`）
 
-[核心数据结构](core-data-structures/core.md)文档会把真实类型声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：
+[核心数据结构](core-data-structures/core.md)文档会把与源码等价的声明及其原始 JSDoc 一并粘贴，让读者看到确切形状和源码契约。为防止粘贴内容在源码变化时漂移，请将其围栏为 ` ```ts type-equiv `（而不是 ` ```ts `），并在 `scripts/type-equiv.manifest.json` 中登记它镜像的源文件和符号：
 
 ```json
 { "doc": "docs/core-data-structures/session.md", "symbol": "SessionEvent", "source": "packages/core/session/src/types.ts" }
 ```
 
-`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁还强制 1:1 对应：每个 `ts type-equiv` 块恰好有一条 manifest 条目，反之亦然；因此不会有块被静默漏检，也不会有陈旧条目滞留。`doc-typecheck` 跳过 `ts type-equiv` 块（它们不能独立编译），并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个块时，请在同一个变更里更新 manifest。
+`pnpm run verify-type-equiv`（`doc-sync` 的一环）随后通过 TypeScript 解析器从源码提取该符号的声明及其附带的 JSDoc，并断言代码块同时匹配两者。对于不应把实现体写进目录的类，请使用 ` ```ts public-api ` 并设置 `"projection": "public-api"`；门禁检查的投影会保留公共字段、构造函数、访问器、方法以及类和成员的原始 JSDoc，同时省略实现体和私有或受保护成员。比对会忽略空白和非 JSDoc 注释，但要求保留每条原始 JSDoc（包括成员文档），让读者同时看到源码契约和确切形状。该门禁还按文档、符号和投影强制 1:1 对应，因此不会有块被静默漏检，也不会有陈旧条目滞留。`doc-typecheck` 跳过两种围栏（它们不能独立编译），并将其排除在 opt-out 比例之外。当你改动一个已记录的类型声明或其 JSDoc 时，门禁会失败直到你更新粘贴内容；当你增删一个块时，请在同一个变更里更新 manifest。
 
 ## 架构上下文
 
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index abea24e3a5..78f878106c 100644
--- 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.
diff --git a/docs/graph-atlas.md b/docs/graph-atlas.md
index 987d8ad7a5..0e6401fdc0 100644
--- 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` |
diff --git a/docs/module-graph.md b/docs/module-graph.md
index edb6034216..0886877f0e 100644
--- 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) |
diff --git a/docs/rfc/INDEX.md b/docs/rfc/INDEX.md
index 26518db3e4..d56f085809 100644
--- a/docs/rfc/INDEX.md
+++ b/docs/rfc/INDEX.md
@@ -164,6 +164,7 @@ Generated by `pnpm run gen-rfc-index` from the RFC tree — never edit by hand;
 | [Single-file executable SDK runtime distribution (single-exe)](implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md) | 2026-07-10 |
 | [Agent-scope runtime design and correctness](implemented/architecture/2026-07-12-agent-scope-runtime-design.md) | 2026-07-12 |
 | [Provider-routed LLM adapters and a generic pi-ai backend](implemented/architecture/2026-07-14-provider-routed-llm-adapters.md) | 2026-07-14 |
+| [Initiating Agent scope over AsyncLocalStorage](implemented/architecture/2026-07-15-agent-initiator-scope.md) | 2026-07-15 |
 | [Advisory LLM catalogs and per-session ACP model selection](implemented/architecture/2026-07-15-llm-model-catalog-and-acp-selection.md) | 2026-07-15 |
 | [Replay token meter service](implemented/architecture/2026-07-15-replay-token-meter-service.md) | 2026-07-15 |
 
diff --git 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
new file mode 100644
index 0000000000..52128ea344
--- /dev/null
+++ b/docs/rfc/implemented/architecture/2026-07-15-agent-initiator-scope.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write
+2026-07-15-agent-initiator-scope.md: a9df15beb8744216e020c259934db9fdf8b28b79
+2026-07-15-agent-initiator-scope.zh.md: 4198f066ef27042bda0d12fbcaf86f143482d596
diff --git a/docs/rfc/implemented/architecture/2026-07-15-agent-initiator-scope.md b/docs/rfc/implemented/architecture/2026-07-15-agent-initiator-scope.md
new file mode 100644
index 0000000000..a9df15beb8
--- /dev/null
+++ b/docs/rfc/implemented/architecture/2026-07-15-agent-initiator-scope.md
@@ -0,0 +1,65 @@
+# RFC: Initiating Agent scope over AsyncLocalStorage
+
+Status: implemented
+
+English | [中文](2026-07-15-agent-initiator-scope.zh.md)
+
+## Problem
+
+The harness has two useful but different notions of context. A Cordis `Context` selects services, registration ownership, and lifetime; `agent.ctx` is the flat registration scope owned by one live Agent. Agent and Session identity instead describe the subject of an asynchronous operation. Changing a root `ctx.agent` to mean “whichever Agent is running” would conflate those meanings and fail when one process drives Agents concurrently.
+
+Deep process-local infrastructure sometimes needs a trusted initiating Agent below explicit loop, tool, and request parameters—for example, a host-aware transport, tracing helper, logger, or gateway client. Requiring every private helper to forward `agent` adds repetition, while a process-global mutable slot is incorrect across `await`. Model-visible arguments are unsuitable because a model must not choose a trusted Session or routing header. The carrier belongs to the Agent service rather than optional model-visible context.
+
+## 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; 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.
+
+`AgentLoop` already injects `ctx.agents` and wraps each concrete driver's complete `runLoop` lifetime in `agents.withInitiator(agent, ...)`. Its package-private loop, turn, step, and tool-call orchestration entries recover the exact Agent from `ctx.agents`, derive `agent.session` once, and let operation-local helpers capture it instead of forwarding the concrete driver or `Session` through shallow interfaces. A leaf helper keeps a narrow `Session` parameter when that is its actual interface rather than accepting a broader `Context` only for an ambient lookup.
+
+Concurrent drivers receive independent stores. A child driver's continuations carry the child, while the caller resumes in its prior store as soon as `withInitiator()` returns; active-run tracking keeps the returned Promise in the teardown drain until it settles. Creation, persistence load, and unpublished `setup(agentCtx)` remain outside the child's driver boundary: creation initiated by a parent runs under the parent identity, while `agentCtx.agent` explicitly identifies the child.
+
+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()`. 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.
+
+A host-aware transport may derive a deployment-owned header such as `X-Harness-Session-Id` from `ctx.agents.requireInitiator().session.id`; the header is absent from model-visible schema and arguments. No production MCP or Web transport adopts such a header in this decision. A test-double transport proves the trusted boundary without assigning host routing policy to an existing provider-neutral seam.
+
+This decision extends the [Agent registration-scope contract](2026-07-08-agent-scope-contexts.md) and its [runtime design](2026-07-12-agent-scope-runtime-design.md); it does not change their static `agent.ctx` meaning.
+
+## Verification
+
+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.
+
+## Alternatives considered
+
+**Pass Agent through every function.** Public, worker, process, persistence, and wire boundaries continue to do this, but requiring every process-local private helper to carry Agent adds repetitive forwarding without improving trust. ALS is confined to the asynchronous chain inside those explicit boundaries.
+
+**Make `ctx.agent` dynamic.** `ctx.agent` already means the static Agent associated with an Agent-scoped Cordis context. Changing the root meaning would mix registration and execution scopes and make concurrent behavior surprising.
+
+**Add a separate `ctx.agentExecution` service.** The carrier has no independent backend, configuration, or identity type: it stores the same `Agent` that `ctx.agents` already owns, and AgentLoop already depends on that service. A second mandatory provider would add package, composition, lifecycle, generated-catalog, and test-harness wiring without separating a real capability.
+
+**Store a named or complete runtime frame.** A one-field `{ agent }` frame only wraps the value, while Agent, Session, inbox, cancellation, turn, step, tool execution, and persistence already have authoritative owners. Adding more fields would create stale snapshots and another lifecycle; carrying `Agent` directly keeps the boundary named by its methods without duplicating state.
+
+**Include a step `AbortSignal`, `cwd`, sandbox, or authorization.** Their lifetimes and authority do not match the driver boundary, and their existing seams already pass them explicitly. Adding a control capability requires a separate decision and nested lifecycle contract.
+
+**Use a process-global `currentAgent`.** Concurrent Agents and subagents overwrite one another across awaited continuations, so a mutable global is correct only under a serialization guarantee the harness does not make.
+
+**Derive identity from model-visible arguments.** Model or user input cannot be trusted to select Session, tenant, or sandbox routing.
+
+**Add routing identity to every capability seam.** That spreads hosting concerns through provider-neutral APIs. A host-aware implementation owns its transport header while public boundaries remain explicit.
+
+## Consequences
+
+Deep infrastructure gains one trusted process-local initiating Agent without widening existing tool and capability requests. Concurrent and nested drivers isolate automatically, AgentLoop gains no additional mandatory service, and HMR/root disposal reaches quiescence before ALS is disabled.
+
+The dependency is implicit in function signatures and carries a capability-bearing Agent object. Consumers must restrict it to cross-cutting infrastructure, treat ambient presence as neither liveness nor authorization, and retain explicit cancellation and ownership checks. ALS also has an always-on propagation cost and does not cross worker, process, HTTP, or durable queue boundaries.
+
+The teardown design deliberately accepts Node's [Stability 1 (Experimental)](https://nodejs.org/api/async_context.html#asynclocalstoragedisable) `AsyncLocalStorage.disable()` dependency. Node requires `disable()` before an ALS instance can be garbage-collected, which matters when HMR replaces AgentRegistry-owned instances; the service state guard prevents a later boundary from re-entering the instance after disposal.
+
+The scope deliberately carries only the Agent, omitting turn, step, `signal`, `cwd`, sandbox, and authorization. A real consumer that cannot use existing explicit fields must justify any refinement separately; a stale copied field may at most mislabel telemetry, never grant control.
diff --git 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
new file mode 100644
index 0000000000..4198f066ef
--- /dev/null
+++ b/docs/rfc/implemented/architecture/2026-07-15-agent-initiator-scope.zh.md
@@ -0,0 +1,65 @@
+# RFC: 基于 AsyncLocalStorage 的发起 Agent 作用域
+
+Status: implemented
+
+[English](2026-07-15-agent-initiator-scope.md) | 中文
+
+## 问题
+
+Harness 中存在两种有用但不同的上下文概念。Cordis `Context` 负责选择服务、注册归属和生命周期；`agent.ctx` 是一个存活 Agent 所拥有的扁平注册作用域。Agent 与会话身份描述的则是异步操作主体。若把根 `ctx.agent` 改成「当前正在运行的 Agent」，就会混淆这两种含义，并在单进程并发驱动多个 Agent 时失效。
+
+进程内深层基础设施有时需要在显式传递的循环、工具及请求参数之下获取可信的发起 Agent，例如宿主感知传输层、追踪辅助函数、日志器或网关客户端。要求每个私有辅助函数都转发 `agent` 会造成重复，而进程级可变槽会在跨 `await` 时发生并发错误。模型可见参数也不适用，因为模型不得选择可信的会话或路由请求头。该载体归 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`、沙箱和授权继续由现有归属方管理。
+
+`AgentLoop` 已经注入 `ctx.agents`，并用 `agents.withInitiator(agent, ...)` 包裹每个具体驱动的完整 `runLoop` 生命周期。循环、轮次、步骤和工具调用的包内私有入口从 `ctx.agents` 恢复同一个 Agent，一次推导 `agent.session`，再由操作内辅助函数捕获该值，避免在浅层接口中转发具体驱动或 `Session`。若 `Session` 本身就是底层辅助函数的实际接口，该函数会保留狭窄的 `Session` 参数，而不会只为隐式查找而接收更宽泛的 `Context`。
+
+因此，并发驱动使用彼此独立的存储。子驱动的异步延续携带子 Agent；`withInitiator()` 返回后，调用方立即恢复之前的存储，而活动运行计数仍持续跟踪返回的 Promise，直到其结束。创建、持久化加载和尚未发布的 `setup(agentCtx)` 位于子驱动边界之外：由父 Agent 发起的创建使用父身份，而 `agentCtx.agent` 显式标识子 Agent。
+
+隐式身份不会取代显式契约。`ToolExecution.agent`、`AssembleContext.agent`、`GenerateOptions.sessionId`、任务归属、父子请求、`ctx.agent`、`agentCtx.agent`、审批与 hook 主体、`cwd` 选择、取消、worker 和进程消息、持久化记录及协议身份都保持显式传递。远程边界会把所需身份写入类型化请求，因为 ALS 只在进程内有效。
+
+`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 传播。
+
+宿主感知的传输层可以从 `ctx.agents.requireInitiator().session.id` 推导由部署方拥有的 `X-Harness-Session-Id` 等请求头；模型可见 schema 和参数中不包含该请求头。本决策不让现有生产 MCP 或 Web 传输层采用此请求头。测试替身传输层用于证明可信边界，而不会把宿主路由策略分配给现有的提供方无关 seam。
+
+本决策扩展 [Agent 注册作用域契约](2026-07-08-agent-scope-contexts.md)及其[运行时设计](2026-07-12-agent-scope-runtime-design.md)，不会改变其中 `agent.ctx` 的静态含义。
+
+## 验证
+
+Agent 服务测试锁定可选与必需读取、同步值和跨 realm Promise 的引用身份、内建 Promise 结束状态观察、并发、嵌套及清空边界、同步抛错或 Promise 拒绝后的恢复、普通与重入排空顺序及保留引用的错误。AgentLoop 集成测试锁定并发与嵌套驱动、无 Agent 调用、AgentRegistry 重启、根 Context 销毁，以及包内私有的循环和工具调度通过隐式查找完成。组合、模块图、构建及运行时闭包检查确保默认组合包、SDK 主干、Python 运行时闭包及直接 AgentLoop harness 通过 `ctx.agents` 完成接线，无需其他提供方。
+
+测试替身形式的宿主感知传输层在内部推导 `X-Harness-Session-Id`，并验证工具 schema 与记录参数都不包含身份字段。服务有意不排空边界操作所返回 Promise 之外的异步工作；这类工作仍由所属方的显式停止契约管理。
+
+## 考虑过的替代方案
+
+**在每个函数中传递 Agent。** 公开、worker、进程、持久化和协议边界继续显式传递，但要求每个进程内私有辅助函数都携带 Agent 只会造成重复转发，不会提高可信度。ALS 仅限于这些显式边界内部的异步调用链。
+
+**让 `ctx.agent` 变成动态值。** `ctx.agent` 已经表示与 Agent 作用域 Cordis 上下文静态关联的 Agent。改变根上下文的含义会混合注册作用域与执行作用域，并让并发行为变得意外。
+
+**新增独立的 `ctx.agentExecution` 服务。** 该载体没有独立后端、配置或身份类型：它存储的是 `ctx.agents` 已经管理的同一个 `Agent`，而 AgentLoop 本就依赖该服务。第二个必需提供方会增加包、组合、生命周期、生成目录及测试 harness 接线，却没有拆出真实能力。
+
+**保存命名帧或完整运行时帧。** 只有一个字段的 `{ agent }` 帧只是包装该值，而 Agent、会话、inbox、取消、轮次、步骤、工具执行和持久化已经有各自的真源。增加更多字段会产生陈旧快照和另一套生命周期；直接携带 `Agent`，由方法名标识边界，无需重复保存状态。
+
+**包含步骤级 `AbortSignal`、`cwd`、沙箱或授权。** 它们的生命周期及权限范围与驱动边界不一致，而且现有 seam 已经显式传递这些值。新增控制能力需要独立决策和嵌套生命周期契约。
+
+**使用进程级 `currentAgent`。** 并发 Agent 和 subagent 会在异步延续执行之间相互覆盖，因此可变全局值只在 Harness 不具备的串行保证下才正确。
+
+**从模型可见参数推导身份。** 不能信任模型或用户输入来选择会话、租户或沙箱路由。
+
+**给每个能力 seam 增加路由身份。** 这会把宿主关注点扩散到提供方无关 API。宿主感知实现拥有其传输请求头，而公开边界继续显式传递身份。
+
+## 后果
+
+深层基础设施可以获得一个可信的进程内发起 Agent，而无需加宽现有工具和能力请求。并发及嵌套驱动会自动隔离，AgentLoop 不增加新的必需服务，HMR 或根 Context dispose 会在禁用 ALS 前完成排空。
+
+该依赖不会出现在函数签名中，并且携带一个具有控制能力的 Agent 对象。消费方必须将其限制在横切基础设施中，把隐式存在视为既不证明存活、也不授予权限，并保留显式取消和归属检查。ALS 还有常驻传播成本，也无法跨越 worker、进程、HTTP 或持久化队列边界。
+
+该销毁设计有意依赖 Node 的 [Stability 1（实验性）](https://nodejs.org/api/async_context.html#asynclocalstoragedisable) API `AsyncLocalStorage.disable()`。Node 要求在 ALS 实例可被垃圾回收前调用 `disable()`，这对 HMR 替换 AgentRegistry 所拥有的实例尤为重要；服务状态守卫会阻止 dispose 后通过后续边界重新进入该实例。
+
+该作用域有意只携带 Agent，省略轮次、步骤、`signal`、`cwd`、沙箱和授权。若真实消费方无法使用现有显式字段，必须另行论证扩展；陈旧字段最多只能误标遥测数据，绝不能授予控制权。
diff --git a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
index 4d592af42b..94d11ee931 100644
--- a/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
+++ b/docs/rfc/implemented/feature/2026-07-08-self-referential-cordis-toolset.md
@@ -18,11 +18,11 @@ The vm isolates accidental global pollution, and the context façade hides frame
 
 | Tool | Contract |
 |---|---|
-| `cordis_inspect` | Read-only report over the live runtime, one Markdown section per `what` value (omit `what` for all sections). Never mutates. |
+| `cordis_inspect` | Read-only report over the live runtime, one Markdown section per `what` value (omit `what` for all sections). An exact `name` with `what: "api"` or `what: "events"` narrows to one source-documented target. Never mutates. |
 | `cordis_mount` | Evaluates `code` (the body of an async JavaScript function) in a `node:vm` sandbox; the code must `return` a cordis plugin, which is mounted as a child of the `cordis-dynamic` group fiber and tracked under a fresh id (`dyn-1`, `dyn-2`, …). |
 | `cordis_unmount` | Disposes one dynamic mount by id and returns only after disposal reaches quiescence — every registration the plugin made is unwound, not merely requested to stop. |
 
-`cordis_inspect` sections: `services` (every provided ctx service and the owning fiber, non-active owners flagged), `plugins` (a flat list of every loaded plugin with its lifecycle state, from `ctx.registry` — what capabilities are loaded, deliberately not the tree shape), `tools` (what the model can call), `dynamic` (the mount table: id, name, state, provided services, awaited services), `api` (live service signatures + the type shapes they reference, from the generated catalog), and `events` (harness events with dispatch mode and signature). The model-facing tool descriptions carry the operational rules the model needs at call time; [the generated tool catalog](../../../tool-catalog.md) is their exhaustive rendering.
+`cordis_inspect` sections: `services` (every provided ctx service and the owning fiber, non-active owners flagged), `plugins` (a flat list of every loaded plugin with its lifecycle state, from `ctx.registry` — what capabilities are loaded, deliberately not the tree shape), `tools` (what the model can call), `dynamic` (the mount table: id, name, state, provided services, awaited services), `api` (live service signatures + the type shapes they reference, from the generated catalog), and `events` (harness events with dispatch mode and signature). Broad `api` and `events` reports omit full JSDoc to stay compact; an exact `name` returns one service or event with its original method/declaration JSDoc. A name is invalid with other sections, unknown targets fail, and an API target must be live. The model-facing tool descriptions carry the operational rules the model needs at call time; [the generated tool catalog](../../../tool-catalog.md) is their exhaustive rendering.
 
 ### Sandbox semantics
 
@@ -44,9 +44,9 @@ Mounts relate to each other through ordinary cordis service semantics, with thei
 
 ### The generated API catalog
 
-`cordis_inspect` serves API and event data from a generated catalog rather than a duplicated table. The generator reuses the Cordis catalog AST scan and emits service summaries, signatures, event modes, referenced type declarations, and the inherited context surface. Ambiguous type names are omitted and oversized declarations are marked as truncated.
+`cordis_inspect` serves API and event data from a generated catalog rather than a duplicated table. The generator reuses the Cordis catalog AST scan and emits service summaries, signatures, original service-method and event JSDoc, event modes, referenced type declarations, and the inherited context surface. Ambiguous type names are omitted and oversized declarations are marked as truncated.
 
-Freshness is gated like every generated artifact: `pnpm run verify-cordis-api` (in `doc-sync`) regenerates in memory and fails on any diff, so a JSDoc edit that changes a public signature cannot ship without regenerating the catalog the model reads. At runtime the inspect tool intersects the catalog with the live runtime rather than dumping it: live catalogued services render summary + signatures, live services without a catalog entry (mount-provided ones) render name + owning fiber, catalogued services with no live provider are listed tersely, and the referenced type shapes follow.
+Freshness is gated like every generated artifact: `pnpm run verify-cordis-api` (in `doc-sync`) regenerates in memory and fails on any diff, so a JSDoc or public-signature edit cannot ship without regenerating the catalog the model reads. At runtime the inspect tool intersects the catalog with the live runtime rather than dumping it: broad reports render live catalogued services as summary + signatures, live services without a catalog entry (mount-provided ones) as name + owning fiber, catalogued services with no live provider tersely, and then the referenced type shapes. Exact-name reports render one live service or event with the original JSDoc immediately before each signature; keeping that detail opt-in avoids charging its token cost on exploratory listings.
 
 ### Configuration, rendering, and observability
 
diff --git a/docs/rfc/implemented/process/2026-06-20-core-data-structures-catalog.md b/docs/rfc/implemented/process/2026-06-20-core-data-structures-catalog.md
index bf70879c71..47dc370d22 100644
--- a/docs/rfc/implemented/process/2026-06-20-core-data-structures-catalog.md
+++ b/docs/rfc/implemented/process/2026-06-20-core-data-structures-catalog.md
@@ -29,8 +29,8 @@ The rule that settled the remaining cases: ***the type you write, hold, or recei
 
 The durability requirement was specific: the doc shows the **literal** current type declaration and original JSDoc (so a reader sees the real shape and source contract, not a paraphrase) **and** is mechanically guaranteed to match source. The repo already compiles fenced ` ```ts ` blocks (`doc-typecheck`), but a real typechecked block needs import noise and proves only *assignability* — a renamed field or changed JSDoc can pass. So:
 
-- Type declarations and their JSDoc are pasted verbatim into a dedicated ` ```ts type-equiv ` fence. `doc-typecheck` recognizes the fence and skips it (a bare definition is not standalone-compilable), and **excludes it from the opt-out ratio** — it is a separately-checked category, not an unchecked sketch.
-- A new `scripts/verify-type-equiv.ts` extracts each block via the TypeScript parser and asserts that its declaration structure and every JSDoc comment match the declared symbol, ignoring only formatting whitespace and non-JSDoc comments. This is chosen over a compiled `_Check` assertion because source names and documentation identity, not assignability, are the properties the catalog preserves.
+- Complete type declarations and their JSDoc are pasted verbatim into a dedicated ` ```ts type-equiv ` fence. A concise ` ```ts public-api ` fence carries the source-equivalent ambient projection for a class whose implementation bodies do not belong in the catalog. `doc-typecheck` recognizes both and skips them (the bare declarations are not standalone-compilable), and **excludes them from the opt-out ratio** — they are a separately-checked category, not unchecked sketches.
+- A new `scripts/verify-type-equiv.ts` extracts each block via the TypeScript parser and asserts that its declaration structure and every JSDoc comment match the declared symbol, ignoring only formatting whitespace and non-JSDoc comments. Ordinary blocks retain the complete declaration. A `public-api` projection retains a class's public fields, constructor, accessors, and methods with their original JSDoc while removing implementation bodies and private or protected members. This is chosen over a compiled `_Check` assertion because source names and documentation identity, not assignability, are the properties the catalog preserves.
 - Provenance lives in a central `scripts/type-equiv.manifest.json` (`{ doc, symbol, source }` entries), **not** in directive comments in the prose. The script enforces a **1:1 correspondence**: every type-equiv block has exactly one manifest entry and vice versa, so a block can never be silently unchecked and an entry can never rot.
 - Wired into `doc-sync`, so it runs in the same lefthook pre-push and CI paths as the other doc gates.
 
@@ -52,7 +52,7 @@ The spine-vs-seam rule was tested against `BashExecRequest`, tool schemas and de
 
 ## Consequences
 
-- The vocabulary now has a single home that **cannot silently drift**: a field rename in source fails `verify-type-equiv` in the pre-push hook and CI until the paste is refreshed.
+- The vocabulary now has a single home that **cannot silently drift**: a field or public class-member change in source fails `verify-type-equiv` in the pre-push hook and CI until the paste is refreshed. Cordis service methods remain owned by the generated services catalog rather than being duplicated here.
 - The spine-vs-seam line is a reusable scoping tool, not a one-off: the same "the thing you write/hold/receive is core; the machinery that types/renders/persists it is a detail" rule is what later scoped the events/services catalog's harness-vs-inherited tiering.
 - The `ts type-equiv` fence is a third doc-block category alongside ` ```ts ` (compiled) and ` ```ts ignore-check ` (sketch). A later sibling added a fourth, ` ```ts cordis-catalog ` (generated signature), reusing the same skip-and-exclude treatment.
 - Adding or reshaping a core type now carries a documentation obligation the author must honor (the gate cannot detect a missing *new* type), backstopped by the `dsh-code-review` checklist.
diff --git a/docs/rfc/implemented/process/2026-06-20-generated-cordis-catalog.md b/docs/rfc/implemented/process/2026-06-20-generated-cordis-catalog.md
index c4c57d36d6..879f8de701 100644
--- a/docs/rfc/implemented/process/2026-06-20-generated-cordis-catalog.md
+++ b/docs/rfc/implemented/process/2026-06-20-generated-cordis-catalog.md
@@ -20,7 +20,7 @@ Specific choices:
 
 - **`@mode` tag, cross-checked.** Each harness event's JSDoc carries an explicit `@mode emit|waterfall|parallel|serial` tag; the generator hard-errors on a missing tag. Where the signature shape is conclusive — a trailing `next: () => …` parameter is structurally a waterfall — it asserts the tag agrees and hard-errors on a contradiction. The emit/parallel/serial distinction is not structurally visible (`session/flush` returns `Promise<void> | void` with no `next`, as does the ordered `agent/pre-step` checkpoint), so it is trusted from the tag. The authoring rule lives in [AGENTS.md](../../../../AGENTS.md).
 - **Tiered scope.** The harness tier (the 8 `@deepseek-ai/dsh-*` services + their events) is rendered in full from source. The inherited tier (cordis-core `ctx.on/emit/effect/provide/…` + the `internal/*` events + loader/hmr/timer) is pinned vendor source a plugin also sees; it is rendered tersely (name + one-line + source pointer) from a curated table in the generator, NOT walked from the vendor AST — the cordis-core `Context` mixes true ctx members with non-service fields (`root`, `baseUrl`, `logger`), and the vendor surface changes only on a deliberate vendor sync.
-- **Cross-links to the data-structure catalog.** A type name in a signature (`GenerateOptions`, `StreamChunk`, `ToolDefinition`, …) links to the core-data-structures page that documents it. The map is a small hand-curated const in the generator — NOT `type-equiv.manifest.json`, which documents the `…Map` symbols while signatures reference the derived union names, and lists a few symbols on two pages.
+- **Cross-links to the data-structure catalog.** Every repository-owned type name in a signature (`GenerateOptions`, `StreamChunk`, `ToolDefinition`, …) links to its primary core-data-structures page through a curated map. The AST walk is fail-closed: each parameter, generic constraint/default, and return-type reference must be mapped, be the signature's own type parameter, be a named TypeScript/Cordis foundation type, or carry a named exception with its non-catalog documentation owner. Violations aggregate with source pointers and name the appropriate owning lists. The map does NOT reuse `type-equiv.manifest.json`, which documents `…Map` symbols while signatures reference derived union names and lists some symbols on multiple pages.
 - **A dedicated fence.** Signature blocks use a ` ```ts cordis-catalog ` info string and place the original event or public-method JSDoc immediately before its declaration. `doc-typecheck` recognizes and skips the bare fragments, excluding them from the opt-out ratio — the same treatment `type-equiv` blocks get.
 
 This **supersedes the event-taxonomy half** of [doc-sync enforcement](2026-06-11-doc-sync-enforcement.md): `verify-event-taxonomy` and its `docs/architecture.md` table are retired (the architecture.md heading stays, its body now points at the catalog; the Service-map role table stays as curated prose). doc-typecheck, verify-md-wrap, verify-md-links, and verify-type-equiv are unchanged.
@@ -29,11 +29,11 @@ This **supersedes the event-taxonomy half** of [doc-sync enforcement](2026-06-11
 
 - **Verify-don't-generate, as the retired taxonomy check did** — reversed *for this surface only*: the data here is mechanically complete, so generation is strictly stronger (full signatures, cannot drift, catches undocumented events) than a name-set check of a hand-maintained table.
 - **Walking the vendor AST for the inherited tier** — rejected for the curated table: the cordis-core `Context` mixes true ctx members with non-service fields, and the pinned vendor surface changes only on a deliberate sync.
-- **Reusing `type-equiv.manifest.json` as the signature cross-link map** — rejected for a small hand-curated const: the manifest documents the `…Map` symbols while signatures reference the derived union names, and it lists a few symbols on two pages.
+- **Reusing `type-equiv.manifest.json` as the signature cross-link map** — rejected for a complete curated const plus fail-closed coverage: the manifest documents `…Map` symbols while signatures reference derived union names, and it lists some symbols on multiple pages. The explicit map makes each rendered destination and each non-catalog exception a reviewable decision.
 
 ## Consequences
 
-- The catalog cannot drift: a source change that the committed file doesn't reflect fails `verify-cordis-catalog` in the pre-push hook and CI. A new event with no `@mode` tag, or a tag that contradicts its signature, fails the generator outright.
+- The catalog cannot drift: a source change that the committed file doesn't reflect fails `verify-cordis-catalog` in the pre-push hook and CI. A new event with no `@mode` tag, a tag that contradicts its signature, or an unclassified signature type fails the generator outright.
 - Event and service-method contracts have a single home — the JSDoc at the declaration. The catalog repeats that original JSDoc inside its generated signature block and uses its description portion as entry prose, so thin source documentation yields a thin catalog entry.
 - The inherited tier is hand-summarized, so a vendor sync that adds/renames a cordis-core event or `ctx` member needs a matching edit to the curated table in `gen-cordis-catalog.ts`. This is the deliberate cost of not walking pinned vendor source; it changes rarely and is called out in the generator.
 - `verify-event-taxonomy.ts` is deleted and the `docs/architecture.md` event table is gone; anyone who linked to a specific table row now lands on the generated catalog instead.
diff --git a/docs/testing.md b/docs/testing.md
index ab34b0af51..cd3b1aa9e8 100644
--- 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.
diff --git a/docs/tool-catalog.md b/docs/tool-catalog.md
index 3dacb56902..dfb97deef3 100644
--- a/docs/tool-catalog.md
+++ b/docs/tool-catalog.md
@@ -169,7 +169,7 @@ The bash tool is the model-facing consumer of the bash executor seam. A `run_in_
 
 ### `cordis_inspect`
 
-Inspect the live cordis runtime that is running THIS agent. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (a flat list of the loaded plugins with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Omit `what` to get all six sections.
+Inspect the live cordis runtime that is running THIS agent. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (a flat list of the loaded plugins with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Omit `what` to get all six sections. With `what:"api"` or `what:"events"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.
 
 ```json
 {
@@ -186,6 +186,10 @@ Inspect the live cordis runtime that is running THIS agent. Read-only. Sections:
         "api",
         "events"
       ]
+    },
+    "name": {
+      "type": "string",
+      "description": "Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."
     }
   }
 }
diff --git a/examples/README.md b/examples/README.md
index 17aa65bb8e..abeee1d97e 100644
--- 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.
 
diff --git a/examples/acp-agent/README.md b/examples/acp-agent/README.md
index 5424be6ab3..000017dd90 100644
--- 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
 
diff --git a/examples/acp-agent/tests/acp.snapshot.ts b/examples/acp-agent/tests/acp.snapshot.ts
index 124117afef..8f749923ef 100644
--- a/examples/acp-agent/tests/acp.snapshot.ts
+++ b/examples/acp-agent/tests/acp.snapshot.ts
@@ -122,6 +122,13 @@ const SCENARIOS: Scenario[] = [
     headerClass: 'advanced',
     configPath: ADVANCED_CONFIG,
   },
+  {
+    name: 'cordis-inspect-jsdoc',
+    hasModelTurn: true,
+    recorded: false,
+    headerClass: 'advanced',
+    configPath: ADVANCED_CONFIG,
+  },
   // Prompt-submit blocks are authored keylessly: they persist a rejected turn
   // and hook events without starting a model step, so their logs still compare.
   { name: 'hook-cc-promptsubmit-block', hasModelTurn: false, comparesLog: true, recorded: false },
diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.golden.md b/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.golden.md
index fb5b48c70c..b8acef973c 100644
--- a/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.golden.md
+++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/system-prompt.golden.md
@@ -44,10 +44,12 @@ declare const tools: {
     /** Required with sandbox_permissions: one sentence for the user explaining why this exact command needs the wider access. */
     justification?: string;
   }): Promise<string>;
-  /** Inspect the live cordis runtime that is running THIS agent. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (a flat list of the loaded plugins with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Omit `what` to get all six sections. */
+  /** Inspect the live cordis runtime that is running THIS agent. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (a flat list of the loaded plugins with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Omit `what` to get all six sections. With `what:"api"` or `what:"events"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc. */
   cordis_inspect(args: {
     /** Limit the report to one section. Omit for all sections. */
     what?: "services" | "plugins" | "tools" | "dynamic" | "api" | "events";
+    /** Exact service key or event name whose original JSDoc to include; valid only with what:"api" or what:"events". */
+    name?: string;
   }): Promise<string>;
   /** Mount a NEW cordis plugin into the live runtime that is running THIS agent (self-modification). `code` runs as the body of an async JavaScript function in an isolated sandbox and MUST `return` a plugin. Two forms: FUNCTION form `return (ctx) => { … }` — declares no inject, so it can register tools, listen to events, and provide services, but reaching ANY service (e.g. ctx.bash) throws; use it only when you need no services. OBJECT form `return { name?, inject: ['bash', 'llm', …], apply(ctx) { … } }` — declares dependencies, and cordis activates the plugin only after the services exist; PREFER this form. You may reach ONLY the services you list in inject: an undeclared service throws even if it exists, because an undeclared dependency would not be cleaned up if its provider is unmounted. BEFORE calling a service from your code, read cordis_inspect what:"api" — it lists method signatures AND the type shapes of their arguments/returns (do not guess a field's type; e.g. a bash run's stdout is an object, not a string). Inside `apply`, use the standard cordis API: `ctx.on(event, listener)` to observe events (see cordis_inspect what:"events"), or call `harness.registerTool(ctx, harness.defineTool({ name, description, parameters: { text: { type: 'string', required: true } }, async execute(args) { … } }))` to give yourself a new tool — it becomes callable on your NEXT step. Tool parameters: each key IS a property — { type: 'string'|'number'|'boolean'|'object'|'array', required?: true, description?, enum?, items?, properties? }; a JSON-Schema-style { type: 'object', properties, required: […] } wrapper and type 'integer' are also accepted and normalized. A tool's `execute` MUST return an ARRAY of content blocks, e.g. `return [{ type: 'text', text: someString }]` — never a bare string. Mounts can COMPOSE: one plugin may `ctx.provide('name', value)` a service and another may declare `inject: ['name']` to consume it — the consumer stays pending until the provider exists and returns to pending when the provider is unmounted. Everything registered inside `apply` is cleaned up automatically on unmount. Sandbox globals: `console` (tagged `[cordis:<id>]`, writes through to the harness terminal), `harness.defineTool`, `harness.registerTool`, `btoa`, `atob`, `TextEncoder`, `TextDecoder`. Node APIs are DISABLED — do filesystem/network/timer work through the cordis services, never Node built-ins: `require`, `setTimeout`/`setInterval`, and `fetch` throw redirect errors; `process` and `Buffer` are undefined. Instead use inject: ['fs'] + ctx.fs for files, inject: ['web'] + ctx.web for HTTP, inject: ['bash'] + ctx.bash for processes, and inject: ['timer'] + ctx.setTimeout/ctx.setInterval for timing (fiber effects, auto-cleaned on unmount) — cordis_inspect what:"api" shows what THIS runtime provides. Write PLAIN JavaScript, not TypeScript (no `as`, no type annotations). Cautions: (1) waterfall events (e.g. tools/pre-execute) hand the listener a trailing `next` callback which MUST be called — returning without `next()` VETOES the call; prefer plain notification events unless you intend to intercept. (2) Never await something that only resolves after the current turn (your code runs INSIDE a tool call of that turn — it would deadlock). (3) Your `ctx` is a restricted façade: you can register tools, observe events, provide/consume services, and use timers, but framework internals (ctx.root, ctx.fiber, ctx.extend, ctx.plugin, …) are withheld. It is not a security boundary though — the services you inject (e.g. ctx.bash) reach the real runtime. */
   cordis_mount(args: {
diff --git a/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.golden.json b/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.golden.json
index 57e78b6345..978819fa1f 100644
--- a/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.golden.json
+++ b/examples/acp-agent/tests/snapshots/advanced-toolchain/tool-schemas.golden.json
@@ -47,7 +47,7 @@
     },
     {
       "name": "cordis_inspect",
-      "description": "Inspect the live cordis runtime that is running THIS agent. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (a flat list of the loaded plugins with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Omit `what` to get all six sections.",
+      "description": "Inspect the live cordis runtime that is running THIS agent. Read-only. Sections: `services` (every provided ctx service and the plugin fiber that owns it), `plugins` (a flat list of the loaded plugins with their lifecycle states), `tools` (the model-facing tools currently registered, i.e. what you can call), `dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), `api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), `events` (every harness event with its dispatch mode and exact signature — pick listener targets here). Omit `what` to get all six sections. With `what:\"api\"` or `what:\"events\"`, pass an exact `name` to narrow to one service/event and include its original source JSDoc.",
       "parameters": {
         "type": "object",
         "properties": {
@@ -62,6 +62,10 @@
               "api",
               "events"
             ]
+          },
+          "name": {
+            "type": "string",
+            "description": "Exact service key or event name whose original JSDoc to include; valid only with what:\"api\" or what:\"events\"."
           }
         }
       }
diff --git a/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/input.json b/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/input.json
new file mode 100644
index 0000000000..62df391622
--- /dev/null
+++ b/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/input.json
@@ -0,0 +1,7 @@
+{
+  "steps": [
+    { "op": "initialize" },
+    { "op": "newSession" },
+    { "op": "prompt", "text": "Inspect the exact tools service API and tools/pre-execute event with cordis_inspect, then reply with exactly CORDIS_INSPECT_JSDOC_OK." }
+  ]
+}
diff --git a/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl b/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
new file mode 100644
index 0000000000..94ea8a8fec
--- /dev/null
+++ b/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/session.jsonl
@@ -0,0 +1,33 @@
+{"type":"session","version":0,"id":"22222222-2222-4222-8222-222222222222","createdAt":1783951000000,"cwd":"/tmp/cordis-inspect-jsdoc"}
+{"type":"turn/start","seq":0,"time":1784449176717,"data":{"turn":1,"trigger":{"kind":"message","source":{"kind":"user"}}}}
+{"type":"user/message","seq":1,"time":1784449176718,"data":{"content":[{"type":"text","text":"Inspect the exact tools service API and tools/pre-execute event with cordis_inspect, then reply with exactly CORDIS_INSPECT_JSDOC_OK."}],"source":{"kind":"user"}},"surfaceOp":"append"}
+{"type":"step/start","seq":2,"time":1784449176720,"data":{"turn":1,"step":1}}
+{"type":"request/header","seq":3,"time":1784449176720,"data":{"header":{"config":{"provider":"deepseek","model":"deepseek-v4-flash"},"system":"{{system}}","tools":"{{tools}}"},"reason":"initial"}}
+{"type":"assistant/chunk","seq":4,"time":1783951000005,"data":{"turn":1,"step":1,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":5,"time":1783951000006,"data":{"turn":1,"step":1,"chunk":{"type":"tool-call-delta","index":0,"id":"inspect-tools-api","name":"cordis_inspect","argumentsDelta":"{\"what\":\"api\",\"name\":\"tools\"}"}}}
+{"type":"assistant/chunk","seq":6,"time":1783951000007,"data":{"turn":1,"step":1,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"inspect-tools-api","name":"cordis_inspect","arguments":"{\"what\":\"api\",\"name\":\"tools\"}"}}}}
+{"type":"assistant/chunk","seq":7,"time":1783951000008,"data":{"turn":1,"step":1,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":8,"time":1783951000009,"data":{"turn":1,"step":1,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":9,"time":1784449176722,"data":{"turn":1,"step":1,"content":[{"type":"tool-call","id":"inspect-tools-api","name":"cordis_inspect","arguments":"{\"what\":\"api\",\"name\":\"tools\"}"}],"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":1784449176722,"data":{"turn":1,"step":1,"callId":"inspect-tools-api","name":"cordis_inspect","arguments":"{\"what\":\"api\",\"name\":\"tools\"}"}}
+{"type":"tool/result","seq":11,"time":1784449176732,"data":{"turn":1,"step":1,"callId":"inspect-tools-api","content":[{"type":"text","text":"## api\n- tools — Tool registry and execution pipeline.\n    /**\n     * Register globally or in the calling agent scope. Scoped tools shadow\n     * globals; duplicates within one layer and the reserved `run_code` name fail.\n     * @param definition - the tool schema, execution, and optional presentation functions.\n     * @returns the exact disposer that unregisters the tool.\n     */\n    register(definition: ToolDefinition): () => void\n    /**\n     * Restrict global tools for the calling agent scope. Empty filters, unknown\n     * names, scope-local names, and reserved transport names fail. Restrictions\n     * intersect; scoped registrations remain visible.\n     * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).\n     * @returns the exact disposer that lifts this restriction.\n     */\n    restrict(filter: ToolRestriction): () => void\n    /**\n     * Register a monotonic guard after the extensible `tools/pre-execute`\n     * waterfall. A plain-context guard applies globally; one registered through\n     * `agent.ctx` applies only to that agent. Any matching guard may deny by\n     * returning a reason, while no guard can force-allow a call another guard\n     * denied. The exact effect disposer is returned for ordered ownership and\n     * HMR cleanup.\n     * @param guard - synchronous check; a returned string denies the execution.\n     * @returns the exact disposer that unregisters the guard.\n     */\n    guard(guard: ToolGuard): () => void\n    /**\n     * Look up a tool as one scope sees it (scoped\n     * shadows global; a restricted-away global reads as absent). Presenters pass\n     * the calling agent so the rendered card matches the definition that\n     * actually executed.\n     * @param name - the tool name as registered.\n     * @param scope - the viewing scope (the agent); omitted = the global view.\n     * @returns the definition the scope resolves, or undefined when none is visible.\n     */\n    get(name: string, scope?: ScopeKey): ToolDefinition | undefined\n    /**\n     * Project visible definitions onto the allowlisted model-facing schema fields,\n     * excluding execution and presentation callbacks.\n     * @param scope - the viewing scope (the agent); omitted = the global view.\n     * @returns one deep-cloned schema per visible tool.\n     */\n    schemas(scope?: ScopeKey): ToolSchema[]\n    /**\n     * Classify a pending call through the caller's visible tool definition. Only\n     * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or\n     * throwing classifiers are exclusive.\n     * @param exec - call name, parsed arguments, and optional agent scope.\n     * @returns the fail-closed scheduling mode.\n     */\n    executionMode(exec: ToolExecutionInput): ToolExecutionMode\n    /**\n     * Execute through pre-policy, guards, around-dispatch, post-policy, and final\n     * notification. Tool and listener failures resolve as materialized error\n     * results; an invisible tool reports `UNKNOWN_TOOL`. The returned outcome is\n     * the same lossless, frozen snapshot final observers receive.\n     * @param exec - the typed same-process call input. The registry assigns its\n     *   correlation token before policy begins.\n     * @returns the materialized final result.\n     */\n    async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>\ntype shapes (referenced by the signatures above — read these before assuming a field is a string):\n    export interface Agent {\n        readonly id: SessionId;\n        readonly options: AgentOptions;\n        readonly session: Session;\n        readonly status: AgentStatus;\n        readonly ctx: Context;\n        send(content: ContentBlock[], options?: SendOptions): void;\n        steer(content: ContentBlock[], options?: SendOptions): void;\n        inject(content: ContentBlock[], options?: InjectOptions): void;\n        cancel(reason?: string): void;\n        whenIdle(): Promise<void>;\n    }\n    export interface AgentOptions {\n        provider?: string;\n        model?: string;\n    }\n    export type AgentStatus = 'idle' | 'running' | 'disposed';\n    export type Branded<B extends string> = string & {\n        readonly [BRAND]: B;\n    };\n    export type CallId = Branded<'CallId'>;\n    export type ContextEnvelope = 'context' | 'raw';\n    export interface DiffCallView {\n        card: 'diff';\n        title: string;\n        diffs: FileDiff[];\n        locations?: FileLocation[];\n    }\n    export interface DiffResultView {\n        card: 'diff';\n        title?: string;\n        diffs: FileDiff[];\n    }\n    export interface FileDiff {\n        path: string;\n        oldText: string | null;\n        newText: string;\n    }\n    export interface FileLocation {\n        path: string;\n        line?: number;\n    }\n    export interface GenericCallView {\n        card: 'generic';\n        title: string;\n        kind?: ToolCallKind;\n        rawInput?: unknown;\n        content?: ContentBlock[];\n        locations?: FileLocation[];\n    }\n    export interface GenericResultView {\n        card: 'generic';\n        title?: string;\n        content?: ContentBlock[];\n    }\n    export interface HookContext {\n        content: ContentBlock[];\n        source: MessageSource;\n        envelope?: ContextEnvelope;\n        meta?: JsonValue;\n    }\n    export interface InjectOptions extends SendOptions {\n        envelope?: ContextEnvelope;\n        meta?: JsonValue;\n    }\n    export type JsonValue = null | boolean | number | string | JsonValue[] | {\n        [key: string]: JsonValue;\n    };\n    export type MessageSource = MessageSourceMap[keyof MessageSourceMap];\n    export interface MessageSourceMap {\n        user: {\n            kind: 'user';\n        };\n        plugin: {\n            kind: 'plugin';\n            plugin: string;\n        };\n    }\n    export type ScopeKey = object;\n    export interface SendOptions {\n        source?: MessageSource;\n    }\n    export type SessionId = Branded<'SessionId'>;\n    export interface TerminalCallView {\n        card: 'terminal';\n        title: string;\n        description?: string;\n        cwd?: string;\n    }\n    export interface TerminalResultView {\n        card: 'terminal';\n        title?: string;\n        output?: string;\n        exitCode?: number;\n        signal?: string;\n    }\n    export type ToolCallKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other';\n    export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;\n    export interface ToolDefinition extends ToolSchema {\n        execute(args: unknown, exec: ToolRunContext): Promise<ToolExecuteReturn>;\n        timeoutMs?: number;\n        isConcurrencySafe?(args: unknown): boolean;\n        presentCall?(args: unknown): ToolCallView | undefined;\n        presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n    }\n    export interface ToolErrorInfo {\n        name: string;\n        code: string;\n    }\n    export type ToolExecuteReturn = ContentBlock[] | {\n        content: ContentBlock[];\n        meta?: unknown;\n    };\n    export interface ToolExecution extends ToolExecutionInput {\n        readonly token: ToolExecutionToken;\n    }\n    export interface ToolExecutionInput {\n        readonly callId: CallId;\n        readonly name: string;\n        readonly arguments: unknown;\n        readonly agent?: Agent;\n        readonly parent?: ToolExecutionToken;\n        signal?: AbortSignal;\n    }\n    export type ToolExecutionMode = {\n        kind: 'parallel';\n    } | {\n        kind: 'exclusive';\n    };\n    export interface ToolExecutionResult {\n        content: ContentBlock[];\n        isError: boolean;\n        error?: ToolErrorInfo;\n        additionalContexts?: HookContext[];\n        meta?: unknown;\n    }\n    export type ToolExecutionToken = symbol & {\n        readonly [toolExecutionTokenBrand]: true;\n    };\n    export type ToolGuard = (execution: Readonly<ToolExecution>) => string | undefined;\n    export interface ToolRestriction {\n        readonly allow?: readonly string[];\n        readonly deny?: readonly string[];\n    }\n    export interface ToolResult {\n        content: ContentBlock[];\n        isError: boolean;\n        meta?: unknown;\n    }\n    export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView;\n    export interface ToolRunContext extends ToolExecution {\n        deferContext(context: HookContext): void;\n    }\n    export interface ToolSchema {\n        name: string;\n        description: string;\n        parameters: Record<string, unknown>;\n    }"}],"isError":false},"sourceEventSeqs":[10],"surfaceOp":"append"}
+{"type":"step/end","seq":12,"time":1784449176732,"data":{"turn":1,"step":1}}
+{"type":"step/start","seq":13,"time":1784449176733,"data":{"turn":1,"step":2}}
+{"type":"assistant/chunk","seq":14,"time":1783951000015,"data":{"turn":1,"step":2,"chunk":{"type":"block-start","index":0,"blockType":"tool-call"}}}
+{"type":"assistant/chunk","seq":15,"time":1784449176734,"data":{"turn":1,"step":2,"chunk":{"type":"tool-call-delta","index":0,"id":"inspect-tools-event","name":"cordis_inspect","argumentsDelta":"{\"what\":\"events\",\"name\":\"tools/pre-execute\"}"}}}
+{"type":"assistant/chunk","seq":16,"time":1784449176734,"data":{"turn":1,"step":2,"chunk":{"type":"block-end","index":0,"block":{"type":"tool-call","id":"inspect-tools-event","name":"cordis_inspect","arguments":"{\"what\":\"events\",\"name\":\"tools/pre-execute\"}"}}}}
+{"type":"assistant/chunk","seq":17,"time":1784449176734,"data":{"turn":1,"step":2,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":18,"time":1784449176734,"data":{"turn":1,"step":2,"chunk":{"type":"finish","reason":{"kind":"tool-calls"}}}}
+{"type":"assistant/message","seq":19,"time":1784449176734,"data":{"turn":1,"step":2,"content":[{"type":"tool-call","id":"inspect-tools-event","name":"cordis_inspect","arguments":"{\"what\":\"events\",\"name\":\"tools/pre-execute\"}"}],"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":1784449176734,"data":{"turn":1,"step":2,"callId":"inspect-tools-event","name":"cordis_inspect","arguments":"{\"what\":\"events\",\"name\":\"tools/pre-execute\"}"}}
+{"type":"tool/result","seq":21,"time":1784449176734,"data":{"turn":1,"step":2,"callId":"inspect-tools-event","content":[{"type":"text","text":"## events\n- tools/pre-execute [waterfall] — Allow, deny, or ask before dispatch.\n    /**\n     * Allow, deny, or ask before dispatch. `next()` delegates to allow; missing\n     * approval support turns `ask` into denial.\n     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.\n     * @param exec - the pending call (name, parsed arguments, caller agent).\n     * @mode waterfall\n     */\n    'tools/pre-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision>\nwaterfall listeners receive a trailing next() and MUST call it to delegate — returning without next() vetoes the chain."}],"isError":false},"sourceEventSeqs":[20],"surfaceOp":"append"}
+{"type":"step/end","seq":22,"time":1784449176734,"data":{"turn":1,"step":2}}
+{"type":"step/start","seq":23,"time":1784449176735,"data":{"turn":1,"step":3}}
+{"type":"assistant/chunk","seq":24,"time":1784449176735,"data":{"turn":1,"step":3,"chunk":{"type":"block-start","index":0,"blockType":"text"}}}
+{"type":"assistant/chunk","seq":25,"time":1784449176735,"data":{"turn":1,"step":3,"chunk":{"type":"text-delta","index":0,"text":"CORDIS_INSPECT_JSDOC_OK"}}}
+{"type":"assistant/chunk","seq":26,"time":1784449176735,"data":{"turn":1,"step":3,"chunk":{"type":"block-end","index":0,"block":{"type":"text","text":"CORDIS_INSPECT_JSDOC_OK"}}}}
+{"type":"assistant/chunk","seq":27,"time":1784449176735,"data":{"turn":1,"step":3,"chunk":{"type":"usage","usage":{"inputTokens":3,"outputTokens":3}}}}
+{"type":"assistant/chunk","seq":28,"time":1784449176735,"data":{"turn":1,"step":3,"chunk":{"type":"finish","reason":{"kind":"stop"}}}}
+{"type":"assistant/message","seq":29,"time":1784449176735,"data":{"turn":1,"step":3,"content":[{"type":"text","text":"CORDIS_INSPECT_JSDOC_OK"}],"provenance":{"provider":"deepseek","model":"deepseek-v4-flash"},"usage":{"inputTokens":3,"outputTokens":3}},"sourceEventSeqs":[24,25,26,27,28],"surfaceOp":"append"}
+{"type":"step/end","seq":30,"time":1784449176735,"data":{"turn":1,"step":3}}
+{"type":"turn/end","seq":31,"time":1784449176735,"data":{"turn":1,"reason":{"kind":"completed"}}}
diff --git a/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/stdout.golden.jsonl b/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/stdout.golden.jsonl
new file mode 100644
index 0000000000..321c5499a2
--- /dev/null
+++ b/examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/stdout.golden.jsonl
@@ -0,0 +1,8 @@
+{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":1,"agentInfo":{"name":"deepseek-harness-acp","version":"0.0.1"},"agentCapabilities":{"loadSession":true,"promptCapabilities":{"image":false,"audio":false,"embeddedContext":false}},"authMethods":[]}}
+{"jsonrpc":"2.0","id":2,"result":{"sessionId":"{{sessionId}}","configOptions":[{"id":"model","name":"Model","description":"Sets this session's provider and model.","category":"model","type":"select","currentValue":"[\"deepseek\",\"deepseek-v4-flash\"]","options":[{"value":"[\"deepseek\",\"deepseek-v4-flash\"]","name":"deepseek-v4-flash"},{"value":"[\"deepseek\",\"deepseek-v4-pro\"]","name":"deepseek-v4-pro"}]},{"id":"permission","name":"Permissions","description":"The session permission preset: each choice bundles a sandbox mode and an approval policy.","category":"mode","type":"select","currentValue":"danger-full-access","options":[{"value":"workspace-write","name":"workspace-write","description":"Write inside the workspace and permitted temporary directories; wider retries require approval."},{"value":"danger-full-access","name":"danger-full-access","description":"Full file access without approval prompts."}]}]}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"inspect-tools-api","title":"Inspect cordis runtime: api: tools","kind":"read","status":"in_progress"}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"inspect-tools-api","status":"completed","content":[{"type":"content","content":{"type":"text","text":"## api\n- tools — Tool registry and execution pipeline.\n    /**\n     * Register globally or in the calling agent scope. Scoped tools shadow\n     * globals; duplicates within one layer and the reserved `run_code` name fail.\n     * @param definition - the tool schema, execution, and optional presentation functions.\n     * @returns the exact disposer that unregisters the tool.\n     */\n    register(definition: ToolDefinition): () => void\n    /**\n     * Restrict global tools for the calling agent scope. Empty filters, unknown\n     * names, scope-local names, and reserved transport names fail. Restrictions\n     * intersect; scoped registrations remain visible.\n     * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).\n     * @returns the exact disposer that lifts this restriction.\n     */\n    restrict(filter: ToolRestriction): () => void\n    /**\n     * Register a monotonic guard after the extensible `tools/pre-execute`\n     * waterfall. A plain-context guard applies globally; one registered through\n     * `agent.ctx` applies only to that agent. Any matching guard may deny by\n     * returning a reason, while no guard can force-allow a call another guard\n     * denied. The exact effect disposer is returned for ordered ownership and\n     * HMR cleanup.\n     * @param guard - synchronous check; a returned string denies the execution.\n     * @returns the exact disposer that unregisters the guard.\n     */\n    guard(guard: ToolGuard): () => void\n    /**\n     * Look up a tool as one scope sees it (scoped\n     * shadows global; a restricted-away global reads as absent). Presenters pass\n     * the calling agent so the rendered card matches the definition that\n     * actually executed.\n     * @param name - the tool name as registered.\n     * @param scope - the viewing scope (the agent); omitted = the global view.\n     * @returns the definition the scope resolves, or undefined when none is visible.\n     */\n    get(name: string, scope?: ScopeKey): ToolDefinition | undefined\n    /**\n     * Project visible definitions onto the allowlisted model-facing schema fields,\n     * excluding execution and presentation callbacks.\n     * @param scope - the viewing scope (the agent); omitted = the global view.\n     * @returns one deep-cloned schema per visible tool.\n     */\n    schemas(scope?: ScopeKey): ToolSchema[]\n    /**\n     * Classify a pending call through the caller's visible tool definition. Only\n     * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or\n     * throwing classifiers are exclusive.\n     * @param exec - call name, parsed arguments, and optional agent scope.\n     * @returns the fail-closed scheduling mode.\n     */\n    executionMode(exec: ToolExecutionInput): ToolExecutionMode\n    /**\n     * Execute through pre-policy, guards, around-dispatch, post-policy, and final\n     * notification. Tool and listener failures resolve as materialized error\n     * results; an invisible tool reports `UNKNOWN_TOOL`. The returned outcome is\n     * the same lossless, frozen snapshot final observers receive.\n     * @param exec - the typed same-process call input. The registry assigns its\n     *   correlation token before policy begins.\n     * @returns the materialized final result.\n     */\n    async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>\ntype shapes (referenced by the signatures above — read these before assuming a field is a string):\n    export interface Agent {\n        readonly id: SessionId;\n        readonly options: AgentOptions;\n        readonly session: Session;\n        readonly status: AgentStatus;\n        readonly ctx: Context;\n        send(content: ContentBlock[], options?: SendOptions): void;\n        steer(content: ContentBlock[], options?: SendOptions): void;\n        inject(content: ContentBlock[], options?: InjectOptions): void;\n        cancel(reason?: string): void;\n        whenIdle(): Promise<void>;\n    }\n    export interface AgentOptions {\n        provider?: string;\n        model?: string;\n    }\n    export type AgentStatus = 'idle' | 'running' | 'disposed';\n    export type Branded<B extends string> = string & {\n        readonly [BRAND]: B;\n    };\n    export type CallId = Branded<'CallId'>;\n    export type ContextEnvelope = 'context' | 'raw';\n    export interface DiffCallView {\n        card: 'diff';\n        title: string;\n        diffs: FileDiff[];\n        locations?: FileLocation[];\n    }\n    export interface DiffResultView {\n        card: 'diff';\n        title?: string;\n        diffs: FileDiff[];\n    }\n    export interface FileDiff {\n        path: string;\n        oldText: string | null;\n        newText: string;\n    }\n    export interface FileLocation {\n        path: string;\n        line?: number;\n    }\n    export interface GenericCallView {\n        card: 'generic';\n        title: string;\n        kind?: ToolCallKind;\n        rawInput?: unknown;\n        content?: ContentBlock[];\n        locations?: FileLocation[];\n    }\n    export interface GenericResultView {\n        card: 'generic';\n        title?: string;\n        content?: ContentBlock[];\n    }\n    export interface HookContext {\n        content: ContentBlock[];\n        source: MessageSource;\n        envelope?: ContextEnvelope;\n        meta?: JsonValue;\n    }\n    export interface InjectOptions extends SendOptions {\n        envelope?: ContextEnvelope;\n        meta?: JsonValue;\n    }\n    export type JsonValue = null | boolean | number | string | JsonValue[] | {\n        [key: string]: JsonValue;\n    };\n    export type MessageSource = MessageSourceMap[keyof MessageSourceMap];\n    export interface MessageSourceMap {\n        user: {\n            kind: 'user';\n        };\n        plugin: {\n            kind: 'plugin';\n            plugin: string;\n        };\n    }\n    export type ScopeKey = object;\n    export interface SendOptions {\n        source?: MessageSource;\n    }\n    export type SessionId = Branded<'SessionId'>;\n    export interface TerminalCallView {\n        card: 'terminal';\n        title: string;\n        description?: string;\n        cwd?: string;\n    }\n    export interface TerminalResultView {\n        card: 'terminal';\n        title?: string;\n        output?: string;\n        exitCode?: number;\n        signal?: string;\n    }\n    export type ToolCallKind = 'read' | 'edit' | 'delete' | 'move' | 'search' | 'execute' | 'fetch' | 'other';\n    export type ToolCallView = GenericCallView | TerminalCallView | DiffCallView;\n    export interface ToolDefinition extends ToolSchema {\n        execute(args: unknown, exec: ToolRunContext): Promise<ToolExecuteReturn>;\n        timeoutMs?: number;\n        isConcurrencySafe?(args: unknown): boolean;\n        presentCall?(args: unknown): ToolCallView | undefined;\n        presentResult?(args: unknown, result: ToolResult): ToolResultView | undefined;\n    }\n    export interface ToolErrorInfo {\n        name: string;\n        code: string;\n    }\n    export type ToolExecuteReturn = ContentBlock[] | {\n        content: ContentBlock[];\n        meta?: unknown;\n    };\n    export interface ToolExecution extends ToolExecutionInput {\n        readonly token: ToolExecutionToken;\n    }\n    export interface ToolExecutionInput {\n        readonly callId: CallId;\n        readonly name: string;\n        readonly arguments: unknown;\n        readonly agent?: Agent;\n        readonly parent?: ToolExecutionToken;\n        signal?: AbortSignal;\n    }\n    export type ToolExecutionMode = {\n        kind: 'parallel';\n    } | {\n        kind: 'exclusive';\n    };\n    export interface ToolExecutionResult {\n        content: ContentBlock[];\n        isError: boolean;\n        error?: ToolErrorInfo;\n        additionalContexts?: HookContext[];\n        meta?: unknown;\n    }\n    export type ToolExecutionToken = symbol & {\n        readonly [toolExecutionTokenBrand]: true;\n    };\n    export type ToolGuard = (execution: Readonly<ToolExecution>) => string | undefined;\n    export interface ToolRestriction {\n        readonly allow?: readonly string[];\n        readonly deny?: readonly string[];\n    }\n    export interface ToolResult {\n        content: ContentBlock[];\n        isError: boolean;\n        meta?: unknown;\n    }\n    export type ToolResultView = GenericResultView | TerminalResultView | DiffResultView;\n    export interface ToolRunContext extends ToolExecution {\n        deferContext(context: HookContext): void;\n    }\n    export interface ToolSchema {\n        name: string;\n        description: string;\n        parameters: Record<string, unknown>;\n    }"}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call","toolCallId":"inspect-tools-event","title":"Inspect cordis runtime: events: tools/pre-execute","kind":"read","status":"in_progress"}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"tool_call_update","toolCallId":"inspect-tools-event","status":"completed","content":[{"type":"content","content":{"type":"text","text":"## events\n- tools/pre-execute [waterfall] — Allow, deny, or ask before dispatch.\n    /**\n     * Allow, deny, or ask before dispatch. `next()` delegates to allow; missing\n     * approval support turns `ask` into denial.\n     * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.\n     * @param exec - the pending call (name, parsed arguments, caller agent).\n     * @mode waterfall\n     */\n    'tools/pre-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision>\nwaterfall listeners receive a trailing next() and MUST call it to delegate — returning without next() vetoes the chain."}}]}}}
+{"jsonrpc":"2.0","method":"session/update","params":{"sessionId":"{{sessionId}}","update":{"sessionUpdate":"agent_message_chunk","content":{"type":"text","text":"CORDIS_INSPECT_JSDOC_OK"}}}}
+{"jsonrpc":"2.0","id":3,"result":{"stopReason":"end_turn"}}
diff --git a/examples/headless-agent/README.md b/examples/headless-agent/README.md
new file mode 100644
index 0000000000..285263146f
--- /dev/null
+++ 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.
diff --git a/examples/headless-agent/advanced.cordis.snapshot.yml b/examples/headless-agent/advanced.cordis.snapshot.yml
new file mode 100644
index 0000000000..48541a1054
--- /dev/null
+++ 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'
diff --git a/examples/headless-agent/advanced.cordis.yml b/examples/headless-agent/advanced.cordis.yml
new file mode 100644
index 0000000000..862a2f769b
--- /dev/null
+++ 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'
diff --git a/examples/headless-agent/composition.md b/examples/headless-agent/composition.md
new file mode 100644
index 0000000000..9533af28d3
--- /dev/null
+++ 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.
diff --git a/examples/headless-agent/cordis.yml b/examples/headless-agent/cordis.yml
new file mode 100644
index 0000000000..7f48c529c4
--- /dev/null
+++ 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'
diff --git a/examples/headless-agent/package.json b/examples/headless-agent/package.json
new file mode 100644
index 0000000000..c331af0f05
--- /dev/null
+++ 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"
+}
diff --git a/examples/headless-agent/tests/fixtures/cli-mock-llm.ts b/examples/headless-agent/tests/fixtures/cli-mock-llm.ts
new file mode 100644
index 0000000000..5238e67374
--- /dev/null
+++ 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())
+}
diff --git a/examples/headless-agent/tests/fixtures/cli.cordis.yml b/examples/headless-agent/tests/fixtures/cli.cordis.yml
new file mode 100644
index 0000000000..91941c108a
--- /dev/null
+++ 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.'
diff --git a/examples/headless-agent/tests/headless.snapshot.ts b/examples/headless-agent/tests/headless.snapshot.ts
new file mode 100644
index 0000000000..ff27347246
--- /dev/null
+++ 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)
+})
diff --git a/examples/headless-agent/tests/keyless-smoke.e2e.ts b/examples/headless-agent/tests/keyless-smoke.e2e.ts
new file mode 100644
index 0000000000..57b8660c03
--- /dev/null
+++ 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)
+})
diff --git a/examples/headless-agent/tests/real-model.e2e.ts b/examples/headless-agent/tests/real-model.e2e.ts
new file mode 100644
index 0000000000..653f5ab624
--- /dev/null
+++ 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)
+})
diff --git a/examples/headless-agent/tests/snapshots/advanced-toolchain/input.json b/examples/headless-agent/tests/snapshots/advanced-toolchain/input.json
new file mode 100644
index 0000000000..41072a211a
--- /dev/null
+++ 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." }
+  ]
+}
diff --git a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.1.jsonl
new file mode 100644
index 0000000000..b4e8cd6340
--- /dev/null
+++ 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"}}}
diff --git a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.2.jsonl
new file mode 100644
index 0000000000..d8d2e59e6e
--- /dev/null
+++ 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"}}}
diff --git a/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl b/examples/headless-agent/tests/snapshots/advanced-toolchain/session.jsonl
new file mode 100644
index 0000000000..e3849110ce
--- /dev/null
+++ 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"}}}
diff --git a/examples/headless-agent/tests/snapshots/advanced-toolchain/stream-json.golden.jsonl b/examples/headless-agent/tests/snapshots/advanced-toolchain/stream-json.golden.jsonl
new file mode 100644
index 0000000000..44577f1fe0
--- /dev/null
+++ 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}}
diff --git a/examples/package.json b/examples/package.json
index 8d77731a05..76349b2ea4 100644
--- 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:*",
diff --git a/examples/repl-agent/README.md b/examples/repl-agent/README.md
index 2e559d129a..7145873e9a 100644
--- 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`.
diff --git a/knip.json b/knip.json
index 0187d8e128..2c3465ab38 100644
--- 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"]
diff --git a/package.json b/package.json
index 19f6d15005..e736e3f8d1 100644
--- 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",
diff --git a/packages/AGENTS.md b/packages/AGENTS.md
index 766a188105..9ab0327cf9 100644
--- a/packages/AGENTS.md
+++ b/packages/AGENTS.md
@@ -6,6 +6,7 @@ These package-specific rules supplement the repo-wide [conventions](../AGENTS.md
 - **Optional services use `ctx.get(name)`.** Reserve `ctx.<name>` for declared injections; the property proxy is topology-sensitive, while strict `ctx.get` reads the global service store ([postmortem](../docs/postmortem/0001-acp-default-export-drops-inject.md)).
 - **Product-visible plugins require a non-unit REAL-composition test.** Hand-built `ctx.plugin(...)` suites are insufficient. Boot test-only `cordis.yml` through the Loader and app/process; mock only external/nondeterministic boundaries and assert model-visible, durable, or user-visible output. Keep opt-ins out of shipped defaults. [Policy](../docs/testing.md).
 - **Typed same-process service and plugin calls are contracts, not serialization boundaries.** Prefer readonly borrowed values; materialize or defensively validate only at parser/config, queued, model/tool JSON, durable/file, worker, process, or wire boundaries.
+- **Initiator-owned private chains derive, then capture.** Under `ctx.agents.withInitiator()`, recover the Agent at each orchestration entry, derive `agent.session`, and let operation-local helpers close over it. Keep `Agent` and `Session` explicit at lifecycle, session-log, service, authority, worker/process, persistence, and wire interfaces; do not widen a leaf helper from `Session` to `Context` merely to hide a parameter ([rationale](../docs/rfc/implemented/architecture/2026-07-15-agent-initiator-scope.md)).
 - **Represent one asynchronous operation with one lifecycle controller or transaction.** Separate readiness, cancellation, disposal, reservation, or sentinel state requires an independent owner or settlement boundary; otherwise fold it while preserving rollback, callback containment, and quiescence.
 
 Naming notes:
diff --git a/packages/README.md b/packages/README.md
index 6c83abfc91..61a1e994c8 100644
--- a/packages/README.md
+++ b/packages/README.md
@@ -8,7 +8,7 @@ Packages live at `packages/<group>/<pkg>/`; groups are containers, while names r
 
 | Group | Role | Release expectation |
 |---|---|---|
-| [`core/`](core/README.md) | Product API spine: session, system-prompt, tools, agent, and the concrete loop | Product — stable surface |
+| [`core/`](core/README.md) | Product API spine: sessions, prompts, tools, agent services, and the concrete loop | Product — stable surface |
 | [`llm/`](llm/README.md) | LLM capability family: the abstract service + provider adapters | Product — stable surface |
 | [`bash/`](bash/README.md) | Bash capability family: the executor seam, a local impl, and the model-facing tool | Product — stable surface |
 | [`code-runtime/`](code-runtime/README.md) | Code-execution capability family: the abstract runtime seam for model-written programs + a worker-thread backend | Product — stable surface |
@@ -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.
diff --git a/packages/cordis/tool-cordis/README.md b/packages/cordis/tool-cordis/README.md
index fdc4e51e6b..c43e2fcc4d 100644
--- a/packages/cordis/tool-cordis/README.md
+++ b/packages/cordis/tool-cordis/README.md
@@ -4,7 +4,7 @@ The self-referential cordis toolset: three model-facing tools over the live runt
 
 ## What it does
 
-- `cordis_inspect` — read-only report over the runtime: services, the loaded-plugin list, registered tools, the dynamic-mount table, and the catalog-backed `api` / `events` references.
+- `cordis_inspect` — read-only report over the runtime: services, the loaded-plugin list, registered tools, the dynamic-mount table, and the catalog-backed `api` / `events` references. An exact `name` with `what: "api"` or `what: "events"` narrows the report and adds the original source JSDoc.
 - `cordis_mount` — evaluates model-written JavaScript (the body of an async function) in a `node:vm` sandbox; the code must `return` a cordis plugin, which is mounted under the `cordis-dynamic` group fiber and tracked as `dyn-<n>`.
 - `cordis_unmount` — disposes one mount by id, returning only after quiescence.
 
@@ -22,7 +22,7 @@ The sandbox isolates globals but is not a security boundary. Node globals are ab
 
 ## The generated API catalog
 
-`src/api-catalog.ts` is generated by `scripts/gen-cordis-api.ts` from the same AST walk as [docs/cordis-catalog](../../../docs/cordis-catalog/services.md) and freshness-gated by `pnpm run verify-cordis-api` (in `doc-sync`) — never edit it by hand. `cordis_inspect` intersects it with the live service store at call time.
+`src/api-catalog.ts` is generated by `scripts/gen-cordis-api.ts` from the same AST walk as [docs/cordis-catalog](../../../docs/cordis-catalog/services.md) and freshness-gated by `pnpm run verify-cordis-api` (in `doc-sync`) — never edit it by hand. `cordis_inspect` intersects it with the live service store at call time. Broad `api` / `events` reports render summaries and signatures only; an exact `name` opts into the retained method/event JSDoc, and unknown or non-running service targets fail loud.
 
 ## Rendering
 
@@ -42,7 +42,7 @@ Namespace plugin: named exports `name` / `inject` / `Config` / `apply`, no defau
 
 ### Tool-call history and results
 
-**What the model sees**: Inspect joins selected sections exactly as `## <section>` then a newline and the data-dependent body, with one blank line between sections. Mount returns `mounted <id> (plugin "<name>", state: <state>)`, optionally inserting ` — waiting for service(s): <names> (activates when provided)` before the closing parenthesis. Unmount returns `unmounted <id> (plugin "<name>")`; an unknown id becomes `Error: no dynamic plugin with id "<id>" (list mounts with cordis_inspect what:"dynamic")`. The submitted mount program remains in the assistant tool-call history.
+**What the model sees**: Inspect joins selected sections exactly as `## <section>` then a newline and the data-dependent body, with one blank line between sections. Its broad API/event reports omit JSDoc; `name` with `what: "api"` or `what: "events"` returns one exact target with its original JSDoc. Mount returns `mounted <id> (plugin "<name>", state: <state>)`, optionally inserting ` — waiting for service(s): <names> (activates when provided)` before the closing parenthesis. Unmount returns `unmounted <id> (plugin "<name>")`; an unknown id becomes `Error: no dynamic plugin with id "<id>" (list mounts with cordis_inspect what:"dynamic")`. The submitted mount program remains in the assistant tool-call history.
 
 **Token effect**: Inspect output and mount code are data-dependent and resent until compaction; lifecycle acknowledgements are small.
 
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index 7a02519b02..4813f91e1b 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -4,22 +4,30 @@
  * `pnpm run verify-cordis-api` in doc-sync).
  *
  * The machine-readable cordis API catalog `cordis_inspect` serves to the
- * model: harness services (summary + public method signatures), harness
- * events (mode + signature), and the inherited `ctx` surface. Produced by
+ * model: harness services (summary + public method signatures/JSDoc),
+ * harness events (mode + signature/JSDoc), and the inherited `ctx` surface. Produced by
  * the same AST walk as docs/cordis-catalog, so this data and the rendered
  * docs cannot diverge.
  *
  * @module @deepseek-ai/dsh-tool-cordis/api-catalog
  */
 
-/** One harness `ctx.<key>` service: its one-line summary and public method signatures. */
+/** One public service method and its source-owned contract. */
+export interface ServiceApiMethod {
+  /** Public method signature with its body stripped. */
+  signature: string
+  /** Original method JSDoc, with only container indentation removed. */
+  jsDoc: string
+}
+
+/** One harness `ctx.<key>` service: its one-line summary and public methods. */
 export interface ServiceApiEntry {
   /** The `ctx.<key>` name, e.g. `tools`. */
   key: string
   /** First sentence of the service class JSDoc. */
   summary: string
-  /** Public method signatures, bodies stripped, in source order. */
-  methods: readonly string[]
+  /** Public methods, bodies stripped, in source order. */
+  methods: readonly ServiceApiMethod[]
 }
 
 /** One harness event: its dispatch mode, exact signature, and one-line summary. */
@@ -30,6 +38,8 @@ export interface EventApiEntry {
   mode: string
   /** The exact listener signature, whitespace-normalized. */
   signature: string
+  /** Original event JSDoc, with only container indentation removed. */
+  jsDoc: string
   /** First sentence of the event JSDoc. */
   summary: string
 }
@@ -56,239 +66,540 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
     key: 'agentLoop',
     summary: 'Concrete agent factory and driver service.',
     methods: [
-      'create(id: SessionId, options: AgentOptions = {}, meta: Pick<SessionHeader, \'cwd\'> = {}): Agent',
-      'async createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle>',
-      'async resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandle>',
+      {
+        signature: 'create(id: SessionId, options: AgentOptions = {}, meta: Pick<SessionHeader, \'cwd\'> = {}): Agent',
+        jsDoc: '/**\n * Create an agent and session under one caller-supplied identity, owned by\n * the accessing fiber. Constructor-driven config calls mint a fresh combined\n * id before entering this boundary.\n * @param id - shared agent/session identity.\n * @param options - concrete loop options.\n * @param meta - optional fresh-session workspace metadata.\n * @returns the published running agent.\n */',
+      },
+      {
+        signature: 'async createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle>',
+        jsDoc: '/**\n * Create an owned agent on a caller-supplied session id.\n * @param ownerCtx - caller context that structurally owns the transaction.\n * @param options - identities, session seed/metadata, loop options, setup, and cancellation.\n * @returns the published handle.\n */',
+      },
+      {
+        signature: 'async resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandle>',
+        jsDoc: '/**\n * Resume an owned agent from the configured persistence service.\n * @param ownerCtx - caller context that owns load, setup, and the live lifecycle.\n * @param options - persisted identity, loop options, setup, and cancellation.\n * @returns the published handle.\n */',
+      },
     ],
   },
   {
     key: 'agents',
-    summary: 'Agent registry (`ctx.agents`): tracks live agents so UI, hook, and orchestrator plugins can find them without depending on the concrete loop package.',
+    summary: 'Agent service (`ctx.agents`): tracks live agents and carries the initiating Agent through one process-local asynchronous driver chain.',
     methods: [
-      'setFactory(factory: AgentFactory): () => void',
-      'async create(options: CreateAgentOptions): Promise<AgentHandle>',
-      'async resume(options: ResumeAgentOptions): Promise<AgentHandle>',
-      'register(agent: Agent): () => void',
-      'enter(agent: Agent, owner: Agent | undefined): () => void',
-      'announce(agent: Agent): void',
-      'get(id: SessionId): Agent | undefined',
-      'isOwnedBy(id: SessionId, owner: Agent): boolean',
-      'list(): Agent[]',
-      'roots(): Agent[]',
+      {
+        signature: 'currentInitiator(): Agent | undefined',
+        jsDoc: '/**\n * Read the Agent that initiated the inherited asynchronous driver chain.\n * Use this optional form for logging, tracing, metrics, or host attribution\n * that also supports agentless calls. When a parent creates a child, setup\n * reports the causal parent while `agentCtx.agent` identifies the child.\n * @returns the inherited Agent, or `undefined` outside an initiator boundary\n *   and inside an explicit clearing boundary.\n * @throws when this service instance has been disposed.\n */',
+      },
+      {
+        signature: 'requireInitiator(): Agent',
+        jsDoc: '/**\n * Read the initiating Agent and fail when no initiator boundary is active.\n * Use this for private helpers contractually below a driver, or for a\n * deployment-owned outbound request whose contract forbids agentless calls.\n * Generic or direct-call seams use optional lookup or explicit request fields.\n * @returns the inherited Agent.\n * @throws when no initiator is active or this service instance has been disposed.\n */',
+      },
+      {
+        signature: 'withInitiator<T>(agent: Agent, operation: () => T): T',
+        jsDoc: '/**\n * Run an operation with one exact Agent as its process-local initiator. The\n * exact synchronous value or Promise returned by the operation is preserved.\n * Custom drivers and test harnesses wrap their complete returned foreground\n * lifetime.\n * A queue or wire receiver may establish this boundary only after validating\n * explicit identity and resolving the exact live Agent; this method does neither.\n * Detached work remains owned by the subsystem that starts it.\n * @param agent - initiating Agent to inherit; presence is neither liveness proof nor authorization.\n * @param operation - synchronous or asynchronous operation to invoke.\n * @returns the exact value returned by `operation`.\n * @throws when the initiator scope is closing/disposed, or when `operation` throws.\n */',
+      },
+      {
+        signature: 'withoutInitiator<T>(operation: () => T): T',
+        jsDoc: '/**\n * Run an operation inside a boundary that hides any inherited initiating\n * Agent. The exact synchronous value or Promise is preserved.\n * Use this while creating lazy shared timers, queue pumps, pool maintenance,\n * watchers, or exporters so they do not inherit the first Agent that happens\n * to initialize them. It clears only initiator attribution, not explicit\n * fields, and does not own or drain detached resources.\n * @param operation - synchronous or asynchronous operation to invoke without an initiator.\n * @returns the exact value returned by `operation`.\n * @throws when the initiator scope is closing/disposed, or when `operation` throws.\n */',
+      },
+      {
+        signature: 'setFactory(factory: AgentFactory): () => void',
+        jsDoc: '/**\n * Register the agent-creation factory (the loop calls this on construction,\n * effect-scoped). A traced Cordis service is canonicalized to its concrete\n * target; each create/resume call is then traced through that caller\'s\n * context so ownership follows the caller without stacking proxy layers.\n * Throws if a factory is already registered. Returns the disposer; on\n * dispose the factory slot is cleared.\n * @param factory - the loop-owned factory {@link create}/{@link resume} delegate to.\n * @returns the disposer that clears the factory slot. The exact\n *   Cordis effect disposer (single-shot): composite (generator) effects may\n *   yield it directly — exact identity nests the teardown in order.\n */',
+      },
+      {
+        signature: 'async create(options: CreateAgentOptions): Promise<AgentHandle>',
+        jsDoc: '/**\n * Create and publish a new agent through the registered factory.\n * Distinct from {@link register} (which records an already-constructed\n * agent): this constructs the agent and its session. Rejects if no factory is\n * registered or creation/setup fails. The resolved {@link AgentHandle} lets\n * the owner tear down exactly this agent.\n * @param options - shared identity, session seed/metadata, and agent options.\n * @returns the handle after setup, rollback-covered publication, and loop start complete.\n */',
+      },
+      {
+        signature: 'async resume(options: ResumeAgentOptions): Promise<AgentHandle>',
+        jsDoc: '/**\n * Load a persisted session and resume an agent on it through the registered\n * factory. Rejects if no factory is registered; the factory rejects if\n * session persistence is not configured or persistence/setup fails.\n * @param options - persisted identity, configuration, and optional setup.\n * @returns the handle after setup, rollback-covered publication, and loop start complete.\n */',
+      },
+      {
+        signature: 'register(agent: Agent): () => void',
+        jsDoc: '/**\n * Register a live agent. Throws if an agent with the same id is already\n * registered. Emits `agent/created` on registration and `agent/disposed`\n * when the calling fiber is disposed — both with the agent\'s scope carrier\n * (`scopeTarget(agent, agent)`): the subject is the agent in hand, so the\n * emits are scope-filtered regardless of which context invoked `register`\n * (calling through `agent.ctx` scopes EFFECTS; dispatch scoping always\n * requires passing the carrier). Returns the disposer.\n * @param agent - the already-constructed agent to record in the store.\n * @returns the EXACT Cordis effect disposer (single-shot; a repeat call\n *   returns undefined without awaiting an in-flight teardown). Exact\n *   identity is load-bearing: a composite (generator) effect that owns a\n *   teardown ORDER — the agent factory\'s lifecycle chain — must yield THIS\n *   function so Cordis nests the unregistration at that yield position;\n *   yielding a wrapper would leave it disposing as a concurrent sibling on\n *   owner unload, unregistering the agent (and emitting `agent/disposed`)\n *   while its final turn is still draining.\n */',
+      },
+      {
+        signature: 'enter(agent: Agent, owner: Agent | undefined): () => void',
+        jsDoc: '/**\n * Insert an already-constructed agent without announcing it. This is the\n * advanced ordered-lifecycle primitive used by the async agent factory: it\n * first completes setup while the agent is unpublished, then assigns the\n * returned detach closure into its pre-installed composite teardown before\n * calling {@link announce}. Ordinary callers use {@link register}.\n * @param agent - the prepared, unpublished agent.\n * @param owner - live agent whose scoped context created this agent, or\n *   undefined for a top-level runtime root. This is runtime ownership, not\n *   the resumed session\'s durable parent lineage.\n * @returns an idempotent closure that removes this exact entry and emits\n *   `agent/disposed` with listener failures contained. When called from a\n *   synchronous `agent/created` listener, removal and disposal wait until\n *   that creation dispatch unwinds.\n */',
+      },
+      {
+        signature: 'announce(agent: Agent): void',
+        jsDoc: '/**\n * Announce an agent previously inserted with {@link enter}.\n * @param agent - the live inserted agent to announce.\n * @throws if `agent` is not the exact live registry entry for its id, or its\n *   creation announcement already began (including a reentrant call from a\n *   creation listener).\n */',
+      },
+      {
+        signature: 'get(id: SessionId): Agent | undefined',
+        jsDoc: '/**\n * Look up a live agent.\n * @param id - the shared agent/session id to look up.\n * @returns the agent, or undefined when no live agent has that id.\n */',
+      },
+      {
+        signature: 'isOwnedBy(id: SessionId, owner: Agent): boolean',
+        jsDoc: '/**\n * Test whether a live agent was created through one exact parent agent\'s\n * scoped context. Runtime ownership is independent of durable session\n * lineage and remains unambiguous when unrelated providers reuse an id.\n * @param id - the candidate child agent\'s shared agent/session id.\n * @param owner - the expected runtime creator agent.\n * @returns true only while the exact child entry is live under that owner.\n */',
+      },
+      {
+        signature: 'list(): Agent[]',
+        jsDoc: '/**\n * All live agents, in registration order.\n * @returns a fresh array; mutating it does not affect the registry.\n */',
+      },
+      {
+        signature: 'roots(): Agent[]',
+        jsDoc: '/**\n * All live top-level agents in registration order. A top-level agent was\n * created without an owning agent context; durable session lineage does not\n * affect this runtime relation, so a resumed fork may still be a root.\n * @returns a fresh array; mutating it does not affect the registry.\n */',
+      },
     ],
   },
   {
     key: 'approval',
     summary: 'Approval service that applies session policy before answerers and logs every ask/outcome pair to the requesting session.',
     methods: [
-      'async request(req: ApprovalRequest): Promise<ApprovalOutcome>',
+      {
+        signature: 'async request(req: ApprovalRequest): Promise<ApprovalOutcome>',
+        jsDoc: '/**\n * Ask the composed answerers to decide one readonly same-process request.\n * The service borrows the request, agent, session, and live signal directly.\n * The request requires an open turn because the audit pair must be enclosed\n * by the durable log\'s commit/replay boundary; an idle ask rejects before\n * appending anything. The answerer phase always produces an outcome: an\n * aborted signal yields `\'cancelled\'`, a missing or throwing answerer yields\n * `\'unavailable\'` (fail closed), and a rogue non-vocabulary return value is\n * normalized to `\'unavailable\'`. A failure that prevents either audit append\n * from committing still rejects because returning an unlogged decision would\n * violate the pair. Session contains post-commit observer failures, so an\n * authoritative append cannot reject the request or suppress its matching\n * audit event.\n * @param req - the pending decision (agent, tool identity, reason, signal).\n * @returns the closed outcome; `\'allowed-once\'` is the only grant.\n * @throws when no turn is open or either audit event fails before the session\n *   append commit point.\n */',
+      },
     ],
   },
   {
     key: 'bash',
     summary: 'Abstract bash execution service.',
     methods: [
-      'abstract resolve(request: BashExecRequest): BashExecSpec',
-      'abstract run(spec: BashExecSpec): Promise<BashRunResult>',
-      'abstract start(spec: BashExecSpec): BashProcess',
+      {
+        signature: 'abstract resolve(request: BashExecRequest): BashExecSpec',
+        jsDoc: '/**\n * Apply implementation-owned defaults and caps to a request before execution.\n * @param request - the caller\'s request; omitted fields get this\n *   implementation\'s defaults, capped fields are clamped.\n * @returns the fully-specified spec to hand to {@link run}/{@link start}.\n */',
+      },
+      {
+        signature: 'abstract run(spec: BashExecSpec): Promise<BashRunResult>',
+        jsDoc: '/**\n * Run a command in the foreground; resolves when it finishes.\n * @param spec - a resolved spec from {@link resolve}, never a raw request.\n * @returns the outcome; nonzero exits, timeout kills, and abort kills\n *   resolve with a descriptive result rather than reject.\n */',
+      },
+      {
+        signature: 'abstract start(spec: BashExecSpec): BashProcess',
+        jsDoc: '/**\n * Start a background process and return its handle immediately.\n * @param spec - a resolved spec from {@link resolve}, never a raw request.\n * @returns the live process handle (reads, kill, quiescence promise).\n */',
+      },
     ],
   },
   {
     key: 'bashEnv',
     summary: 'Registry (`ctx.bashEnv`) for trusted, per-execution `DSH_*` variables.',
     methods: [
-      'register(contributor: BashEnvContributor): () => void',
-      'collect(execution: ToolExecution): DshEnvironment',
-      'list(): BashEnvVariableInfo[]',
+      {
+        signature: 'register(contributor: BashEnvContributor): () => void',
+        jsDoc: '/**\n * Register one environment contributor. Names and keys are unique; built-in\n * keys are reserved. Registration is disposed with the calling plugin fiber.\n * @param contributor - declared key ownership and per-execution resolver.\n * @returns the disposer that unregisters the contribution.\n */',
+      },
+      {
+        signature: 'collect(execution: ToolExecution): DshEnvironment',
+        jsDoc: '/**\n * Build the trusted `DSH_*` snapshot for one bash tool execution.\n * @param execution - the current tool execution.\n * @returns an immutable environment overlay containing built-ins and current contributions.\n */',
+      },
+      {
+        signature: 'list(): BashEnvVariableInfo[]',
+        jsDoc: '/**\n * Enumerate plugin-contributed variables without executing their resolvers.\n * @returns declarations sorted by environment variable name.\n */',
+      },
     ],
   },
   {
     key: 'codeRuntime',
     summary: 'Registers one `ctx.codeRuntime` implementation.',
     methods: [
-      'abstract run(request: CodeRunRequest): Promise<CodeRunResult>',
+      {
+        signature: 'abstract run(request: CodeRunRequest): Promise<CodeRunResult>',
+        jsDoc: '/**\n * Execute one program against the request\'s bindings and capture what it\n * emitted. See the class doc for the resolution contract (error is a result\n * field; rejection means seam misuse only).\n * @param request - the program, its bindings, and the abort signal; the\n *   request carries everything the runtime acts on, with no hidden defaults.\n * @returns the run\'s outcome: completion value (when transferable), the\n *   ordered log capture, and the failure (if any).\n */',
+      },
     ],
   },
   {
     key: 'compact',
     summary: 'Abstract compaction service.',
     methods: [
-      'abstract compactIfNeeded( agent: CompactAgentContext, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal, ): Promise<CompactionResult | null>',
-      'abstract compactRegion( start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>',
+      {
+        signature: 'abstract compactIfNeeded( agent: CompactAgentContext, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal, ): Promise<CompactionResult | null>',
+        jsDoc: '/**\n * Check token pressure and compact if the conversation is too large.\n * Estimate the next request, including its session prefix, derived history,\n * and system prompt. Above threshold, compact a head-anchored range ending at\n * a balanced tool boundary and reconsolidate any prior automatic checkpoint.\n * Return `null` when no compaction is needed or an open tail leaves no safe\n * cutoff. A single oversized retained unit or prefix cannot be repaired here.\n *\n * @param agent - agent context owning the session surface and model options.\n * @param fullSystemPrompt - assembled system prompt, counted toward the estimate.\n * @param sessionPrefix - the instance\'s composed session prefix, counted toward the\n *   estimate.\n * @param signal - cancellation signal; model-backed implementations must forward it.\n * @returns the compaction result, or `null` if no compaction was needed.\n */',
+      },
+      {
+        signature: 'abstract compactRegion( start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>',
+        jsDoc: '/**\n * Forcibly compact a range of surface nodes into a single summary node.\n * `start` and `end` name an inclusive span by surface position, not numeric seq\n * order; replacements can make visible seqs non-monotonic. Both edges must be\n * balanced so assistant tool calls remain paired with their results. A model-\n * backed implementation forwards cancellation and rejects active, missing,\n * reversed, or unbalanced ranges. The target session is `agent.session`.\n * Use {@link toolPairingBalancedBefore} and {@link toolPairingBalancedAfter}\n * for the edge checks.\n *\n * @param start - first surface seq, inclusive.\n * @param end - last surface seq, inclusive.\n * @param agent - context whose session is mutated and whose routing options guide summarization.\n * @param signal - optional cancellation; model-backed implementations must forward it.\n * @throws when compaction is active or the range is missing, reversed, or unbalanced.\n * @returns the appended event seqs, summary, replaced range, and token accounting.\n */',
+      },
     ],
   },
   {
     key: 'fs',
     summary: 'Abstract filesystem provider.',
     methods: [
-      'abstract resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget>',
-      'abstract stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>',
-      'abstract lstat(path: string, opts?: { cwd?: string }, signal?: AbortSignal): Promise<FsPathInfo | undefined>',
-      'abstract readText(target: FsTarget, signal?: AbortSignal): Promise<string>',
-      'abstract streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>',
-      'abstract listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>',
-      'abstract writeText(target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal): Promise<FsWriteOutcome>',
-      'abstract editText(target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal): Promise<FsEditOutcome>',
+      {
+        signature: 'abstract resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget>',
+        jsDoc: '/**\n * Resolve a model/plugin-supplied path into a stable {@link FsTarget}. May perform I/O (a\n * remote/sandboxed backend may need a round-trip to map a path to a stable identity), hence\n * async even though the local backend only normalizes + realpaths.\n *\n * @param path - the path to resolve; relative paths resolve against `opts.cwd`.\n * @param opts - optional cwd override and cancellation signal.\n * @returns the stable target; the same file yields the same `targetKey`.\n */',
+      },
+      {
+        signature: 'abstract stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>',
+        jsDoc: '/**\n * Return target metadata, or `undefined` when the target does not exist.\n * @param target - the resolved target to stat.\n * @param signal - aborts the metadata round-trip.\n * @returns metadata only, never content; undefined for an absent target.\n */',
+      },
+      {
+        signature: 'abstract lstat(path: string, opts?: { cwd?: string }, signal?: AbortSignal): Promise<FsPathInfo | undefined>',
+        jsDoc: '/**\n * Return path metadata without following the final path component when it is a\n * symbolic link. This is intentionally path-shaped, not target-shaped:\n * {@link resolve} follows symlinks to produce the stable identity used by\n * normal reads/writes, while `lstat` lets a consumer reject the path itself\n * before that follow happens.\n *\n * `opts.cwd` follows {@link resolve}\'s cwd rules. `undefined` means the path is\n * absent.\n * @param path - the path to inspect; relative paths resolve against `opts.cwd`.\n * @param opts - `cwd` overrides the backend\'s default base for relative paths.\n * @param signal - aborts the metadata round-trip.\n * @returns metadata only, never content; undefined for an absent path.\n */',
+      },
+      {
+        signature: 'abstract readText(target: FsTarget, signal?: AbortSignal): Promise<string>',
+        jsDoc: '/**\n * Read the whole regular text file as a single decoded string.\n * @param target - the resolved target to read.\n * @param signal - aborts the read.\n * @returns the full decoded UTF-8 content.\n */',
+      },
+      {
+        signature: 'abstract streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>',
+        jsDoc: '/**\n * Stream the whole regular text file as decoded text chunks (same text\n * semantics as {@link readText}, for large files). The backend owns\n * cross-chunk UTF-8 decoding and binary rejection so the policy layer never\n * touches raw bytes.\n * @param target - the resolved target to read.\n * @param signal - aborts the stream, including between chunks.\n * @returns the chunk iterable, decoded and validated like {@link readText}.\n */',
+      },
+      {
+        signature: 'abstract listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>',
+        jsDoc: '/**\n * List direct children of a directory in stable name order. Returns resolved\n * child targets plus cheap metadata only; never reads file contents.\n * @param target - the resolved directory target.\n * @param signal - aborts the listing.\n * @returns one entry per direct child, in stable name order.\n */',
+      },
+      {
+        signature: 'abstract writeText(target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal): Promise<FsWriteOutcome>',
+        jsDoc: '/**\n * Atomically create or replace UTF-8 text. `expected` guards intent and\n * staleness; omission allows unconditional overwrite.\n * @param target - the resolved target to write.\n * @param content - the full new file content.\n * @param expected - the write intent guarding the write; omit for unconditional.\n * @param signal - aborts before the atomic rename takes effect.\n * @returns the outcome, including the version the write produced.\n */',
+      },
+      {
+        signature: 'abstract editText(target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal): Promise<FsEditOutcome>',
+        jsDoc: '/**\n * Atomically edit literal text. When supplied, the version guard is checked\n * before matching so stale content reports `FS_STALE_VERSION`; omission edits\n * the current content without a freshness precondition.\n * @param target - the resolved target to edit.\n * @param edit - the literal search/replace request.\n * @param expected - the version guard; omit for an unconditional edit.\n * @param signal - aborts before the atomic rename takes effect.\n * @returns the outcome, including the version the edit produced.\n */',
+      },
     ],
   },
   {
     key: 'llm',
     summary: 'The abstract `llm` service: an adapter registry plus a streaming model-call surface, interceptable via the `llm/stream` waterfall.',
     methods: [
-      'registerAdapter(providers: string[], adapter: LlmAdapter): () => void',
-      'listProviders(): LlmProviderInfo[]',
-      'async listModels(provider: string): Promise<LlmModelInfo[]>',
-      'stream(options: GenerateOptions): AsyncIterable<StreamChunk>',
+      {
+        signature: 'registerAdapter(providers: string[], adapter: LlmAdapter): () => void',
+        jsDoc: '/**\n * Register an adapter for the given provider routes. Throws `LlmError` with code\n * `DUPLICATE_ADAPTER` if any provider already has an adapter (all-or-nothing).\n * Disposed with the fiber.\n * @param providers - every provider route this adapter should serve.\n * @param adapter - the adapter that streams calls for those providers.\n * @returns the disposer that unregisters all of them.\n */',
+      },
+      {
+        signature: 'listProviders(): LlmProviderInfo[]',
+        jsDoc: '/**\n * Describe provider routes with a registered adapter.\n * @returns detached provider metadata in registration order.\n */',
+      },
+      {
+        signature: 'async listModels(provider: string): Promise<LlmModelInfo[]>',
+        jsDoc: '/**\n * Discover models advertised by one registered provider. Catalog membership\n * is advisory and never changes routing or request validation.\n * @param provider - registered provider route to inspect.\n * @returns detached model metadata in adapter-preferred order.\n */',
+      },
+      {
+        signature: 'stream(options: GenerateOptions): AsyncIterable<StreamChunk>',
+        jsDoc: '/**\n * Stream one model call as raw chunks (token-level deltas). Throws\n * `LlmError` with code `NO_ADAPTER` if no adapter is registered for\n * `options.provider`. Replay state is retained only when the same adapter\n * instance owns its historical provider and the target provider. Dispatches\n * through the `llm/stream` waterfall.\n * @param options - the full request; `options.provider` selects the adapter.\n * @returns the chunk stream, possibly wrapped by `llm/stream` listeners.\n */',
+      },
     ],
   },
   {
     key: 'permission',
     summary: 'Owns the deployment\'s permission presets and their write path.',
     methods: [
-      'current(events: readonly SessionEvent[]): string',
-      'resolve(name: string): PresetSpec',
-      'optionOf(name: string): PresetOption',
-      'set(session: Session, name: string): void',
+      {
+        signature: 'current(events: readonly SessionEvent[]): string',
+        jsDoc: '/**\n * Resolve the preset matching the effective knob values. A still-matching\n * last selection wins shared-bundle ties; otherwise the first table match\n * wins, or {@link CUSTOM_PRESET} when no entry matches.\n * @param events - the session\'s events in log order.\n * @returns the effective preset name, or `custom` when nothing matches.\n */',
+      },
+      {
+        signature: 'resolve(name: string): PresetSpec',
+        jsDoc: '/**\n * Resolve a preset\'s knob bundle.\n * @param name - the preset name to resolve.\n * @returns the configured bundle.\n * @throws when `name` is not in the table.\n */',
+      },
+      {
+        signature: 'optionOf(name: string): PresetOption',
+        jsDoc: '/**\n * Build the client option for a table entry or {@link CUSTOM_PRESET}. A\n * missing label falls back to the table key.\n * @param name - a table key, or `custom`.\n * @returns the option a client renders.\n * @throws when `name` is neither a table key nor `custom`.\n */',
+      },
+      {
+        signature: 'set(session: Session, name: string): void',
+        jsDoc: '/**\n * Record a changed preset, then update each changed knob through its own\n * setter. Selecting the effective preset again appends nothing.\n * @param session - the session the switch belongs to.\n * @param name - the preset to switch to; unknown names throw.\n */',
+      },
     ],
   },
   {
     key: 'sandbox',
     summary: 'Abstract process-sandbox service.',
     methods: [
-      'abstract confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv',
+      {
+        signature: 'abstract confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv',
+        jsDoc: '/**\n * Wrap `argv` so it executes confined under `policy` on this host; the\n * caller spawns the returned argv in place of its own.\n * @param argv - the exact argv the caller is about to spawn (program plus\n *   arguments), NOT a shell string — a shell-shaped consumer passes\n *   `[\'bash\', \'-c\', command]`.\n * @param policy - the file-effect policy this execution runs under,\n *   carried per call (see {@link SandboxPolicy}).\n * @returns the argv to spawn instead, plus the enforcement completeness\n *   the selected backend achieves for it.\n */',
+      },
     ],
   },
   {
     key: 'sessionPersistence',
     summary: 'Durable append-only session storage.',
     methods: [
-      'abstract locate(meta: SessionHeader): SessionLocation | undefined',
-      'abstract create(meta: SessionHeader): Promise<void>',
-      'abstract append(id: SessionId, events: readonly SessionEvent[]): Promise<void>',
-      'abstract load(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }>',
-      'abstract list(): Promise<SessionHeader[]>',
+      {
+        signature: 'abstract locate(meta: SessionHeader): SessionLocation | undefined',
+        jsDoc: '/**\n * Resolve this backend\'s independent local artifact for a session without\n * reading, creating, flushing, or otherwise materializing it. Backends such\n * as SQLite that do not own one artifact per session return `undefined`.\n * @param meta - the immutable session header whose artifact is requested.\n * @returns the backend-specific absolute location, when one exists.\n */',
+      },
+      {
+        signature: 'abstract create(meta: SessionHeader): Promise<void>',
+        jsDoc: '/**\n * Register a new session\'s metadata. A backend MAY defer the physical write\n * until the first {@link append} (lazy materialization), in which case a\n * created-but-never-appended session is absent from {@link list}\n * — abandoned sessions leave nothing behind.\n * @param meta - the immutable header (id, version, cwd, lineage) to record.\n */',
+      },
+      {
+        signature: 'abstract append(id: SessionId, events: readonly SessionEvent[]): Promise<void>',
+        jsDoc: '/**\n * Durably persist a batch of events (called from the write-behind drain at\n * the `session/flush` checkpoint). Honors the append-only and contiguous-seq\n * contracts: the first event\'s `seq` MUST equal the stored next-seq (after\n * `load` has durably closed any interrupted turn). Rejects non-JSON-\n * serializable `event.data` with an error naming the offending event type.\n * @param id - the session the batch belongs to.\n * @param events - the contiguous batch to persist, in seq order.\n */',
+      },
+      {
+        signature: 'abstract load(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }>',
+        jsDoc: '/**\n * Load a header and balanced contiguous log. A complete interrupted final\n * turn is preserved and durably closed with missing tool errors plus any open\n * step and turn boundaries; only a torn final record is discarded. Unknown\n * versions and corruption in the committed prefix reject.\n * @param id - the persisted session to reload.\n * @returns the header and a log ending on a balanced `turn/end`.\n */',
+      },
+      {
+        signature: 'abstract list(): Promise<SessionHeader[]>',
+        jsDoc: '/**\n * Lightweight listing from metadata, without a full-log parse.\n * @returns one header per materialized session.\n */',
+      },
     ],
   },
   {
     key: 'sessionQuery',
     summary: 'Live-preferred logical-corpus exact-read and relationship-tracing service.',
     methods: [
-      'listSessions(): Promise<SessionRecord[]>',
-      'async listEvents(sessionId: SessionId): Promise<SessionEventRecord[]>',
-      'async traceSession(sessionId: SessionId): Promise<SessionLineageTrace>',
-      'async traceEvent(request: SessionEventTraceRequest): Promise<SessionEventTrace>',
-      'async readEvent(request: SessionEventReadRequest): Promise<SessionEventWindow>',
+      {
+        signature: 'listSessions(): Promise<SessionRecord[]>',
+        jsDoc: '/**\n * List the complete logical corpus using live-preferred records.\n * @returns deterministic newest-first cloned session records.\n */',
+      },
+      {
+        signature: 'async listEvents(sessionId: SessionId): Promise<SessionEventRecord[]>',
+        jsDoc: '/**\n * List lightweight raw-log event records for one logical session.\n * @param sessionId - live-preferred session id to read.\n * @returns event records in ascending seq order.\n */',
+      },
+      {
+        signature: 'async traceSession(sessionId: SessionId): Promise<SessionLineageTrace>',
+        jsDoc: '/**\n * Trace known ancestry and descendants from one corpus observation.\n * @param sessionId - logical session id to trace.\n * @returns a complete lineage or an explicit unresolved parent boundary.\n * @throws when corpus resolution fails, the target is absent, or its known ancestry cycles.\n */',
+      },
+      {
+        signature: 'async traceEvent(request: SessionEventTraceRequest): Promise<SessionEventTrace>',
+        jsDoc: '/**\n * Trace one event\'s direct positional and provenance relationships.\n * @param request - target session id and event seq.\n * @returns direct links plus the target\'s positional replacement chain.\n * @throws when source resolution fails, the target is absent, or surface/provenance validation fails.\n */',
+      },
+      {
+        signature: 'async readEvent(request: SessionEventReadRequest): Promise<SessionEventWindow>',
+        jsDoc: '/**\n * Read one full event plus a bounded raw-log context window.\n * @param request - target session/seq and context sizes.\n * @returns cloned target and neighboring events.\n */',
+      },
     ],
   },
   {
     key: 'sessions',
     summary: 'In-memory session store (`ctx.sessions`).',
     methods: [
-      'create(id?: SessionId, options?: CreateSessionOptions): Session',
-      'prepare(id?: SessionId, options?: CreateSessionOptions): Session',
-      'enter(session: Session): () => void',
-      'announce(session: Session): void',
-      'async flush(session: Session): Promise<void>',
-      'get(id: SessionId): Session | undefined',
-      'list(): Session[]',
-      'fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session',
+      {
+        signature: 'create(id?: SessionId, options?: CreateSessionOptions): Session',
+        jsDoc: '/**\n * Create a session owned by the calling fiber: disposing that fiber stops\n * event notification and removes the session from the store. `options.seed`\n * populates the session with a copy of those events (replay/fork);\n * `options.meta` attaches creation metadata (validated absolute `cwd`,\n * `parentSession` lineage) as the immutable {@link SessionHeader} (the store\n * fills `version`/`id`/`createdAt`).\n *\n * For an agent whose session must be torn down IN ORDER with its loop (so the\n * loop\'s final flush is captured before the store attachment ends), do NOT use this\n * — fold the session lifecycle into the agent\'s own effect via\n * {@link prepare} + {@link enter} + {@link announce} (see\n * `dsh-agent-loop`\'s creation transaction).\n *\n * @param id - the session id; omitted, the store mints `session-<n>`.\n * @param options - seed events and/or creation metadata for the header.\n * @returns the live session, already entered and announced.\n * @throws if a session with `id` already exists, metadata is not a plain\n *   lossless-JSON record with valid scalar fields, or `meta.cwd` is a\n *   non-absolute path (storage backends key directories off it).\n */',
+      },
+      {
+        signature: 'prepare(id?: SessionId, options?: CreateSessionOptions): Session',
+        jsDoc: '/**\n * Build a session WITHOUT entering it into the store — validate the id/cwd and\n * construct the {@link Session} (with its immutable {@link SessionHeader}).\n * Pairs with {@link enter} + {@link announce}: a caller that owns a composite\n * `ctx.effect` (the agent factory) folds the session lifecycle into that ONE\n * effect so a fiber unload tears the session + agent down as a single ORDERED\n * chain rather than as racing sibling effects — which would remove the publication hooks\n * before the loop\'s closing `session/flush`, dropping the closing events.\n *\n * @param id - the session id; omitted, the store mints `session-<n>`.\n * @param options - seed events and/or creation metadata for the header.\n * @returns the constructed session, NOT yet in the store.\n * @throws if a session with `id` already exists, metadata is not a plain\n *   lossless-JSON record with valid scalar fields, or `meta.cwd` is a\n *   non-absolute path.\n */',
+      },
+      {
+        signature: 'enter(session: Session): () => void',
+        jsDoc: '/**\n * Enter a {@link prepare}d session into the store: install the module-private\n * append publication hooks and add it to the store. Returns the DETACH\n * disposer (hooks + store removal). Does NOT emit `session/created` —\n * the caller yields this disposer inside its effect and THEN calls\n * {@link announce}, so a throwing `session/created` listener rolls the attach\n * back instead of leaking it.\n *\n * Re-checks the id for a duplicate: `prepare` and `enter` are public\n * cross-package primitives and a caller may interleave arbitrary work (or\n * another create) between them, so a stale prepared session must NOT overwrite\n * a live store entry of the same id — its detach disposer would later delete\n * the REAL session. The {@link create} convenience and the agent factory call\n * the two back-to-back so they never trip this, but the public seam cannot\n * assume that.\n *\n * @param session - a {@link prepare}d session not yet in the store.\n * @returns the detach disposer (publication hooks + store removal). When called from\n *   a synchronous `session/created` listener, removal and disposal wait until\n *   that creation dispatch unwinds.\n * @throws if a session with this id is already in the store.\n */',
+      },
+      {
+        signature: 'announce(session: Session): void',
+        jsDoc: '/** Emit `session/created` exactly once for an {@link enter}ed session (with\n * the carrier {@link enter} captured). Separate from {@link enter} so the\n * caller can yield the detach disposer first (rollback safety — see\n * {@link enter}).\n * @param session - the entered session to announce to listeners.\n * @throws if the session is not live or its announcement already began,\n *   including a reentrant call from a creation listener. */',
+      },
+      {
+        signature: 'async flush(session: Session): Promise<void>',
+        jsDoc: '/**\n * Dispatch the awaited `session/flush` durability checkpoint for `session`,\n * with the carrier captured at {@link enter}. THE flush entry point: the\n * store owns the carrier, so callers (the loop\'s turn-end checkpoint, idle\n * injection, teardown drains) must come through here rather than dispatch a\n * raw `ctx.parallel(\'session/flush\', …)` — one owner, one spelling, and the\n * scoped-dispatch invariant can pin it.\n * @param session - the session whose buffered events must reach durable storage.\n * @returns resolves when every flush listener has settled; after all settle,\n *   rejects with the first registered listener failure if any listener failed.\n */',
+      },
+      {
+        signature: 'get(id: SessionId): Session | undefined',
+        jsDoc: '/**\n * Look up a live session.\n * @param id - the session id to look up.\n * @returns the session, or undefined when no live session has that id.\n */',
+      },
+      {
+        signature: 'list(): Session[]',
+        jsDoc: '/**\n * All live sessions, in creation order.\n * @returns a fresh array; mutating it does not affect the store.\n */',
+      },
+      {
+        signature: 'fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session',
+        jsDoc: '/**\n * Create a live child session from a turn-enclosed prefix of a live source.\n * `boundary` is an inclusive source event seq; omitted means the source\'s\n * current last event. A non-empty selected slice must end at `turn/end`.\n *\n * @param source - Live source session object or id.\n * @param boundary - Inclusive source event seq to fork through; omitted means\n *   the source\'s current last event, and omitted on an empty source forks an\n *   empty child.\n * @param childSessionId - Optional child session id; omitted delegates to\n *   `SessionStore`\'s id policy.\n * @returns The created live child session.\n */',
+      },
     ],
   },
   {
     key: 'skills',
     summary: 'Registry of skill providers.',
     methods: [
-      'registerProvider(provider: SkillProvider): () => void',
-      'register(skill: SkillRegistration): () => void',
-      'async list(options: SkillLookupOptions = {}): Promise<SkillSummary[]>',
-      'async get(name: string, options: SkillLookupOptions = {}): Promise<SkillDefinition | undefined>',
+      {
+        signature: 'registerProvider(provider: SkillProvider): () => void',
+        jsDoc: '/**\n * Register a borrowed same-process provider synchronously during plugin apply. Duplicate and\n * reserved names throw; remote initialization belongs in `list()`. Fiber disposal unregisters\n * the provider and invalidates catalog caches.\n * @param provider - the provider to register by `provider.name`.\n * @returns the exact Cordis effect disposer that unregisters this provider;\n *   composite effects may yield it directly to preserve teardown ordering.\n */',
+      },
+      {
+        signature: 'register(skill: SkillRegistration): () => void',
+        jsDoc: '/**\n * Register a borrowed readonly runtime skill. Project entries outrank runtime entries, which\n * outrank user entries. Same-name runtime entries are first-wins; a duplicate logs a warning and\n * receives a no-op disposer so it cannot remove the winner.\n * @param skill - the complete skill definition to expose for discovery.\n * @returns the exact Cordis effect disposer, preserving composite teardown order and invalidating caches.\n */',
+      },
+      {
+        signature: 'async list(options: SkillLookupOptions = {}): Promise<SkillSummary[]>',
+        jsDoc: '/**\n * List model-invocable skill summaries for a workspace. Lookup options and\n * provider candidates are readonly same-process values borrowed throughout\n * discovery.\n * @param options - lookup options; `cwd` selects project roots and `signal` cancels discovery.\n * @returns sorted summaries, excluding skills disabled for model invocation.\n */',
+      },
+      {
+        signature: 'async get(name: string, options: SkillLookupOptions = {}): Promise<SkillDefinition | undefined>',
+        jsDoc: '/**\n * Load and validate the winning candidate, passing its opaque discovery locator back to the\n * provider. Cancellation is rechecked after selection, including cache hits, and raced against\n * loading so an uncooperative provider cannot hang the caller.\n * @param name - kebab-case skill name.\n * @param options - lookup options; `cwd` selects workspace-sensitive skills and `signal` cancels work.\n * @returns the full skill, including body content, or `undefined`.\n */',
+      },
     ],
   },
   {
     key: 'spillStore',
     summary: 'Abstract spill storage service.',
     methods: [
-      'abstract saveText(input: SaveTextSpill): Promise<SpillRef>',
+      {
+        signature: 'abstract saveText(input: SaveTextSpill): Promise<SpillRef>',
+        jsDoc: '/**\n * Persist `input.content` to a session-scoped spill artifact.\n * @param input - the owner, provenance, suggested name, and full text to save.\n * @returns the saved artifact\'s {@link SpillRef}; rejects on a storage failure.\n */',
+      },
     ],
   },
   {
     key: 'subagents',
     summary: 'Named provider registry and capability-checked start surface.',
     methods: [
-      'registerProvider(provider: SubagentProvider): () => void',
-      'getProvider(name: string): SubagentProvider | undefined',
-      'list(): string[]',
-      'async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>',
+      {
+        signature: 'registerProvider(provider: SubagentProvider): () => void',
+        jsDoc: '/**\n * Register a provider under its name. Registration is effect-scoped and HMR\n * safe; removing a provider blocks new starts but does not revoke runs that\n * were already returned to their holders.\n * @param provider - the trusted provider implementation.\n * @returns the exact Cordis effect disposer.\n */',
+      },
+      {
+        signature: 'getProvider(name: string): SubagentProvider | undefined',
+        jsDoc: '/**\n * Look up a provider by name.\n * @param name - the provider name.\n * @returns the provider, or undefined when absent.\n */',
+      },
+      {
+        signature: 'list(): string[]',
+        jsDoc: '/**\n * List registered provider names in insertion order.\n * @returns the registered names.\n */',
+      },
+      {
+        signature: 'async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>',
+        jsDoc: '/**\n * Establish a ready child on the named provider. Capability and semantic\n * checks run before delegation. Provider ownership lasts until its promise\n * fulfills; a rejection therefore has no run for the caller to dispose and\n * emits no run lifecycle events.\n * @param name - the provider to use.\n * @param request - child prompt, parent, signal, and optional capabilities.\n * @returns the ready holder-owned run.\n */',
+      },
     ],
   },
   {
     key: 'systemPrompt',
     summary: 'Registry service for the prompt inputs assembled before each model step.',
     methods: [
-      'section(section: PromptSection): () => void',
-      'tools(provider: (context: AssembleContext) => ToolProviderResult): () => void',
-      'variable(name: string, provider: (context: AssembleContext) => string | undefined): () => void',
-      'async assemble(context: AssembleContext = {}): Promise<PromptAssembly>',
+      {
+        signature: 'section(section: PromptSection): () => void',
+        jsDoc: '/**\n * Register an ordered prompt section in the calling context\'s scope. A scoped\n * section shadows a global section with the same name; duplicates within one\n * layer and non-finite orders throw. Registration and disposal emit\n * `system-prompt/change`.\n * @param section - the section to register.\n * @returns the exact Cordis effect disposer.\n */',
+      },
+      {
+        signature: 'tools(provider: (context: AssembleContext) => ToolProviderResult): () => void',
+        jsDoc: '/**\n * Register a tool-schema provider in the calling context\'s scope. Global and\n * matching scoped providers both contribute; returning the reserved\n * {@link TOOL_ORDER_REST} name makes assembly fail.\n * @param provider - evaluated for each assembly with its context.\n * @returns the exact Cordis effect disposer.\n */',
+      },
+      {
+        signature: 'variable(name: string, provider: (context: AssembleContext) => string | undefined): () => void',
+        jsDoc: '/**\n * Register a prompt variable in the calling context\'s scope. Scoped values\n * shadow globals; invalid or duplicate names throw. A provider may return\n * `undefined`, but rendering a section that references that value then fails.\n * @param name - the `[a-z][a-z0-9_]*` reference name.\n * @param provider - evaluated for each assembly.\n * @returns the exact Cordis effect disposer.\n */',
+      },
+      {
+        signature: 'async assemble(context: AssembleContext = {}): Promise<PromptAssembly>',
+        jsDoc: '/**\n * Assemble global and scoped providers, detach tool parameters, apply\n * canonical ordering, then run the assembly waterfall. Scoped sections and\n * variables shadow globals; the returned waterfall value is authoritative.\n * @param context - the optional scope and plugin-defined assembly fields.\n * @returns the authoritative post-waterfall assembly.\n */',
+      },
     ],
   },
   {
     key: 'tasks',
     summary: 'The `tasks` service: the runtime-global background task registry.',
     methods: [
-      'start(spec: TaskStart): TaskId',
-      'list(caller?: Agent): TaskSnapshot[]',
-      'get(id: TaskId, caller?: Agent): TaskSnapshot',
-      'read(id: TaskId, caller?: Agent): TaskRead',
-      'kill(id: TaskId, caller?: Agent, reason?: string): \'requested\' | \'already-finished\'',
-      'async wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<TaskSnapshot>',
-      'onTaskDone(listener: TaskDoneListener): () => void',
-      'attachSurface(name: string): () => void',
+      {
+        signature: 'start(spec: TaskStart): TaskId',
+        jsDoc: '/**\n * Preflight access, validation, and owner cleanup before starting and\n * atomically registering work. A throwing starter leaves nothing registered;\n * after it returns, registration cannot fail. Settlement records the outcome,\n * notifies listeners, and releases waiters.\n * @param spec - task identity, owner, and synchronous starter.\n * @returns the registry-issued `<kind>-N` id.\n */',
+      },
+      {
+        signature: 'list(caller?: Agent): TaskSnapshot[]',
+        jsDoc: '/**\n * List caller-owned and unowned tasks in registration order without exposing\n * another session\'s labels.\n * @param caller - reading agent; a non-agent caller sees only unowned tasks.\n * @returns fresh snapshots.\n */',
+      },
+      {
+        signature: 'get(id: TaskId, caller?: Agent): TaskSnapshot',
+        jsDoc: '/**\n * Return a non-consuming snapshot without changing its read cursor or notice\n * state. Throws for an unknown or foreign task.\n * @param id - task to look up.\n * @param caller - reading agent checked against the owner.\n * @returns a fresh snapshot.\n */',
+      },
+      {
+        signature: 'read(id: TaskId, caller?: Agent): TaskRead',
+        jsDoc: '/**\n * Read the next stream delta, or the idempotent final output after settlement.\n * A terminal read marks the task reported. Throws for an unknown or foreign\n * task.\n * @param id - task to read.\n * @param caller - reading agent checked against the owner.\n * @returns output text and the post-read snapshot.\n */',
+      },
+      {
+        signature: 'kill(id: TaskId, caller?: Agent, reason?: string): \'requested\' | \'already-finished\'',
+        jsDoc: '/**\n * Request cancellation, then mark the task stopping and reported. A producer\n * throw propagates without changing task state. Throws for an unknown or\n * foreign task.\n * @param id - task to cancel.\n * @param caller - killing agent checked against the owner.\n * @param reason - logged reason forwarded to the producer.\n * @returns `requested` for live work, otherwise `already-finished`.\n */',
+      },
+      {
+        signature: 'async wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<TaskSnapshot>',
+        jsDoc: '/**\n * Wait for settlement or timeout without cancelling the task. Caller abort\n * rejects only while the task is live; after settlement it returns the\n * terminal snapshot so a notice suppressed for this waiter is still delivered.\n * Timed-out and aborted waits detach their resolvers. Throws for invalid,\n * unknown, or foreign input.\n * @param id - task to wait for.\n * @param timeoutMs - positive finite wait bound in milliseconds.\n * @param caller - waiting agent checked against the owner.\n * @param signal - optional cancellation of the wait itself.\n * @returns snapshot at settlement or timeout.\n */',
+      },
+      {
+        signature: 'onTaskDone(listener: TaskDoneListener): () => void',
+        jsDoc: '/**\n * Register an effect-scoped completion listener. Each listener is contained;\n * returned promises are observed but not awaited. No listener runs after\n * service disposal.\n * @param listener - receives each terminal snapshot and its exact owner.\n * @returns disposer that unregisters the listener.\n */',
+      },
+      {
+        signature: 'attachSurface(name: string): () => void',
+        jsDoc: '/**\n * Attach an effect-scoped surface that can read and stop tasks. {@link start}\n * refuses work while none is attached.\n * @param name - diagnostic label; duplicate names remain independent.\n * @returns disposer that detaches this surface.\n */',
+      },
     ],
   },
   {
     key: 'tokenMeter',
     summary: 'Replay owner for one service-wide estimator and isolated per-session folds.',
     methods: [
-      'measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement',
-      'estimateMessage(message: Message): number',
+      {
+        signature: 'measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement',
+        jsDoc: '/**\n * Measure current request pressure and surface through the durable tail.\n *\n * Provider usage is reused only when the latest successful call\'s canonical\n * request envelope matches `requestHeader` and its total is no lower than\n * that call\'s full heuristic anchor; otherwise the complete envelope and\n * surface are heuristically repriced.\n *\n * `requestHeader` affects request pressure only; surface fields always\n * describe the current session surface. Every call clones those positional\n * nodes, so measurement is O(surface).\n *\n * @param session - session to replay through its current durable tail.\n * @param requestHeader - optional effective request envelope replacing the latest logged header.\n * @returns a detached deeply immutable pressure and surface measurement.\n */',
+      },
+      {
+        signature: 'estimateMessage(message: Message): number',
+        jsDoc: '/**\n * Heuristically price one model-visible message.\n * @param message - message to price without mutation.\n * @returns content and role-framing tokens under the fixed service heuristic.\n */',
+      },
     ],
   },
   {
     key: 'tools',
     summary: 'Tool registry and execution pipeline.',
     methods: [
-      'register(definition: ToolDefinition): () => void',
-      'restrict(filter: ToolRestriction): () => void',
-      'guard(guard: ToolGuard): () => void',
-      'get(name: string, scope?: ScopeKey): ToolDefinition | undefined',
-      'schemas(scope?: ScopeKey): ToolSchema[]',
-      'executionMode(exec: ToolExecutionInput): ToolExecutionMode',
-      'async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>',
+      {
+        signature: 'register(definition: ToolDefinition): () => void',
+        jsDoc: '/**\n * Register globally or in the calling agent scope. Scoped tools shadow\n * globals; duplicates within one layer and the reserved `run_code` name fail.\n * @param definition - the tool schema, execution, and optional presentation functions.\n * @returns the exact disposer that unregisters the tool.\n */',
+      },
+      {
+        signature: 'restrict(filter: ToolRestriction): () => void',
+        jsDoc: '/**\n * Restrict global tools for the calling agent scope. Empty filters, unknown\n * names, scope-local names, and reserved transport names fail. Restrictions\n * intersect; scoped registrations remain visible.\n * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).\n * @returns the exact disposer that lifts this restriction.\n */',
+      },
+      {
+        signature: 'guard(guard: ToolGuard): () => void',
+        jsDoc: '/**\n * Register a monotonic guard after the extensible `tools/pre-execute`\n * waterfall. A plain-context guard applies globally; one registered through\n * `agent.ctx` applies only to that agent. Any matching guard may deny by\n * returning a reason, while no guard can force-allow a call another guard\n * denied. The exact effect disposer is returned for ordered ownership and\n * HMR cleanup.\n * @param guard - synchronous check; a returned string denies the execution.\n * @returns the exact disposer that unregisters the guard.\n */',
+      },
+      {
+        signature: 'get(name: string, scope?: ScopeKey): ToolDefinition | undefined',
+        jsDoc: '/**\n * Look up a tool as one scope sees it (scoped\n * shadows global; a restricted-away global reads as absent). Presenters pass\n * the calling agent so the rendered card matches the definition that\n * actually executed.\n * @param name - the tool name as registered.\n * @param scope - the viewing scope (the agent); omitted = the global view.\n * @returns the definition the scope resolves, or undefined when none is visible.\n */',
+      },
+      {
+        signature: 'schemas(scope?: ScopeKey): ToolSchema[]',
+        jsDoc: '/**\n * Project visible definitions onto the allowlisted model-facing schema fields,\n * excluding execution and presentation callbacks.\n * @param scope - the viewing scope (the agent); omitted = the global view.\n * @returns one deep-cloned schema per visible tool.\n */',
+      },
+      {
+        signature: 'executionMode(exec: ToolExecutionInput): ToolExecutionMode',
+        jsDoc: '/**\n * Classify a pending call through the caller\'s visible tool definition. Only\n * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or\n * throwing classifiers are exclusive.\n * @param exec - call name, parsed arguments, and optional agent scope.\n * @returns the fail-closed scheduling mode.\n */',
+      },
+      {
+        signature: 'async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>',
+        jsDoc: '/**\n * Execute through pre-policy, guards, around-dispatch, post-policy, and final\n * notification. Tool and listener failures resolve as materialized error\n * results; an invisible tool reports `UNKNOWN_TOOL`. The returned outcome is\n * the same lossless, frozen snapshot final observers receive.\n * @param exec - the typed same-process call input. The registry assigns its\n *   correlation token before policy begins.\n * @returns the materialized final result.\n */',
+      },
     ],
   },
   {
     key: 'userInteraction',
     summary: '`ctx.userInteraction`: one active UI provider plus an `ask()` surface.',
     methods: [
-      'registerProvider(provider: UserInteractionProvider): () => void',
-      'async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>',
+      {
+        signature: 'registerProvider(provider: UserInteractionProvider): () => void',
+        jsDoc: '/**\n * Register the UI provider. Only one provider may be active in a context.\n *\n * @param provider UI-side implementation that collects answers.\n * @returns Disposer that unregisters this provider.\n */',
+      },
+      {
+        signature: 'async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>',
+        jsDoc: '/**\n * Ask the active UI provider and wait for the user\'s answer.\n *\n * @param request Questions, owner agent, and abort signal.\n * @returns The answer chosen or typed by the human.\n */',
+      },
     ],
   },
   {
     key: 'web',
     summary: 'The web access service.',
     methods: [
-      'registerSearchProvider(provider: WebSearchProvider): () => void',
-      'registerFetchProvider(provider: WebFetchProvider): () => void',
-      'async search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>',
-      'async fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>',
+      {
+        signature: 'registerSearchProvider(provider: WebSearchProvider): () => void',
+        jsDoc: '/**\n * Register a search provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`\n * if its id is already registered for search. Returns a disposer; disposed\n * with the calling fiber.\n * @param provider - the provider; its `id` is the registry key.\n * @returns the disposer that unregisters the provider.\n */',
+      },
+      {
+        signature: 'registerFetchProvider(provider: WebFetchProvider): () => void',
+        jsDoc: '/**\n * Register a fetch provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`\n * if its id is already registered for fetch. Returns a disposer; disposed\n * with the calling fiber.\n * @param provider - the provider; its `id` is the registry key.\n * @returns the disposer that unregisters the provider.\n */',
+      },
+      {
+        signature: 'async search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>',
+        jsDoc: '/**\n * Run one search through the selected provider. Resolves the provider at call\n * time with the selection rules above; throws {@link WebError} when the\n * capability cannot run. The seam enforces `request.maxResults` on the result:\n * if the provider over-returns, `sources[]` is truncated and `truncated` set.\n * @param request - the query plus result-shaping options.\n * @param signal - optional cancellation signal forwarded to the provider.\n * @returns the provider\'s results, capped to `request.maxResults`.\n */',
+      },
+      {
+        signature: 'async fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>',
+        jsDoc: '/**\n * Retrieve one URL through the selected provider. Resolves the provider at\n * call time with the selection rules above; throws {@link WebError} when the\n * capability cannot run. A non-2xx response is a result, not a throw.\n * @param request - the URL plus retrieval options.\n * @param signal - optional cancellation signal forwarded to the provider.\n * @returns the retrieval outcome; non-2xx responses resolve descriptively.\n */',
+      },
     ],
   },
   {
     key: 'workflows',
     summary: 'Workflow execution seam.',
     methods: [
-      'abstract start(request: WorkflowStartRequest): WorkflowRun',
+      {
+        signature: 'abstract start(request: WorkflowStartRequest): WorkflowRun',
+        jsDoc: '/**\n * Parse and execute a workflow script.\n * @param request - the script, its `args`, the parent agent, and an\n *   optional cancel signal.\n * @returns the live run; its `result` resolves when the script settles.\n */',
+      },
     ],
   },
 ]
@@ -299,240 +610,280 @@ export const EVENT_API: readonly EventApiEntry[] = [
     name: 'agent-loop/config-start-failed',
     mode: 'emit',
     signature: '\'agent-loop/config-start-failed\'(sessionId: SessionId, error: unknown): void',
+    jsDoc: '/**\n * A declarative agent entry failed before it could publish a live agent.\n * Consumers that buffer work for the configured identity use this\n * transient signal to reject that work instead of waiting forever. Normal\n * factory teardown suppresses failures from the cancelled startup attempt.\n * @param sessionId - exact shared agent/session identity that failed startup.\n * @param error - persistence, setup, or publication failure.\n * @mode emit\n */',
     summary: 'A declarative agent entry failed before it could publish a live agent.',
   },
   {
     name: 'agent/created',
     mode: 'emit',
     signature: '\'agent/created\'(this: Scoped<Agent>, agent: Agent): void',
+    jsDoc: '/**\n * A fully configured agent and live session were published. Setup is\n * composition-only; `agent/session-start` is the first startup-driving seam.\n * Synchronous listener failure vetoes publication, while returned-promise\n * rejection is reported. Detach requested during dispatch waits until every\n * creation listener has observed the stable entry.\n * @param agent - the newly registered agent with its live session and completed setup.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
     summary: 'A fully configured agent and live session were published.',
   },
   {
     name: 'agent/disposed',
     mode: 'emit',
     signature: '\'agent/disposed\'(this: Scoped<Agent>, agent: Agent): void',
+    jsDoc: '/**\n * An agent left the registry; AgentLoop emits this after driver quiescence\n * but before session detachment and scoped-registration unwind. Custom\n * registry users own their driver-ordering contract.\n * @param agent - the exact agent removed from the registry.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
     summary: 'An agent left the registry; AgentLoop emits this after driver quiescence but before session detachment and scoped-registration unwind.',
   },
   {
     name: 'agent/error',
     mode: 'emit',
     signature: '\'agent/error\'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: Error): void',
+    jsDoc: '/**\n * A step or turn errored. The loop reports a failure here (plus the logger)\n * even when the error has no in-turn position for a session `error` event.\n * @param agent - the agent whose turn errored.\n * @param turn - the turn in which the failure surfaced.\n * @param step - the step at which the failure surfaced.\n * @param error - the failure, verbatim.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
     summary: 'A step or turn errored.',
   },
   {
     name: 'agent/pre-step',
     mode: 'serial',
     signature: '\'agent/pre-step\'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal): Promise<void> | void',
+    jsDoc: '/**\n * Awaited serial checkpoint for session-surface mutation after prompt\n * assembly and before `step/start`; appends land outside the pending step.\n * The loop derives history once afterward, so compaction records and\n * replacements are included without rewriting an assembled request. The\n * prompt and prefix are the exact pressure inputs for that request, and\n * `signal` cancels listener work.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @param agent - the agent opening the step.\n * @param turn - the open turn number.\n * @param step - the pending step number.\n * @param fullSystemPrompt - the assembled prompt.\n * @param sessionPrefix - the frozen request prefix.\n * @param signal - the turn abort signal.\n * @mode serial\n */',
     summary: 'Awaited serial checkpoint for session-surface mutation after prompt assembly and before `step/start`; appends land outside the pending step.',
   },
   {
     name: 'agent/prompt-submit',
     mode: 'waterfall',
     signature: '\'agent/prompt-submit\'(this: Scoped<Agent>, agent: Agent, content: ContentBlock[], source: MessageSource, next: () => Promise<PromptDecision>): Promise<PromptDecision>',
+    jsDoc: '/**\n * Allow, rewrite, or block one drained prompt before it becomes a user\n * message. Call `next()` for the unchanged default.\n * @param agent - the agent draining its inbox.\n * @param content - the drained message\'s blocks, as queued.\n * @param source - the message\'s resolved source.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode waterfall\n */',
     summary: 'Allow, rewrite, or block one drained prompt before it becomes a user message.',
   },
   {
     name: 'agent/queued',
     mode: 'emit',
     signature: '\'agent/queued\'(this: Scoped<Agent>, agent: Agent, content: ContentBlock[], info: { source: MessageSource; steering: boolean }): void',
+    jsDoc: '/**\n * Detached, frozen content entered the agent\'s inbox. Source defaults have\n * already been applied, so these are the exact values retained for the log.\n * @param agent - the agent whose inbox received the message.\n * @param content - the accepted content blocks retained by the inbox.\n * @param info - the accepted source plus whether it entered as steering.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
     summary: 'Detached, frozen content entered the agent\'s inbox.',
   },
   {
     name: 'agent/request',
     mode: 'waterfall',
     signature: '\'agent/request\'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, config: LlmCallConfig, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>',
+    jsDoc: '/**\n * Replace the frozen call configuration. Model-visible content must use\n * logged channels; this seam cannot mutate messages. Injection here joins\n * the next request because the current step boundary is already fixed.\n * @param agent - the agent making the model call.\n * @param turn - the open turn number.\n * @param step - the step whose request this is.\n * @param config - the config the loop would use (frozen); return a replacement to switch.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode waterfall\n */',
     summary: 'Replace the frozen call configuration.',
   },
   {
     name: 'agent/session-prefix',
     mode: 'waterfall',
     signature: '\'agent/session-prefix\'(this: Scoped<Agent>, agent: Agent, prefix: Message[], signal: AbortSignal, next: () => Promise<Message[]>): Promise<Message[]>',
+    jsDoc: '/**\n * Compose request-only messages placed before derived history. The frozen\n * result is computed once per loop instance, logged on its anchoring request\n * header, and reused so the provider prefix remains stable. Interrupted\n * composition is discarded. Composition precedes the first `agent/pre-step`\n * and request boundary, so listener appends join the current request and\n * pressure accounting sees the composed prefix. Changing context belongs in\n * history; contributors should prepend to `await next()` to preserve registration order.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @param agent - the agent whose session prefix is being composed.\n * @param prefix - the frozen seed; return an extended replacement.\n * @param signal - aborts composition when the step is torn down.\n * @mode waterfall\n */',
     summary: 'Compose request-only messages placed before derived history.',
   },
   {
     name: 'agent/session-start',
     mode: 'emit',
     signature: '\'agent/session-start\'(this: Scoped<Agent>, agent: Agent, source: SessionStartSource): void',
+    jsDoc: '/**\n * The session lifecycle began, once before the first turn. Use\n * `agent.inject()` to seed model-facing context. This is a notification, not\n * a veto; disposal requested by a lifecycle owner is rechecked before the\n * driver starts.\n * @param agent - the agent whose session lifecycle began.\n * @param source - why the session started (fresh startup, resume, …).\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
     summary: 'The session lifecycle began, once before the first turn.',
   },
   {
     name: 'agent/status',
     mode: 'emit',
     signature: '\'agent/status\'(this: Scoped<Agent>, agent: Agent, status: AgentStatus): void',
+    jsDoc: '/**\n * Agent status changed (`idle` ⇄ `running`, or → `disposed`). `send()` does\n * not enter `running` synchronously; drive lifecycle from this event.\n * @param agent - the agent whose status flipped.\n * @param status - the status just entered (the transition\'s destination).\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode emit\n */',
     summary: 'Agent status changed (`idle` ⇄ `running`, or → `disposed`).',
   },
   {
     name: 'agent/step-result',
     mode: 'waterfall',
     signature: '\'agent/step-result\'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, message: Message, next: () => Promise<Message>): Promise<Message>',
+    jsDoc: '/**\n * Waterfall: post-process the assembled assistant {@link Message} before\n * tool dispatch (validation, content rewriting, …).\n * @param agent - the agent that received the step\'s response.\n * @param turn - the open turn number.\n * @param step - the step that produced the message.\n * @param message - the assistant message as assembled from the stream.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode waterfall\n */',
     summary: 'Waterfall: post-process the assembled assistant Message before tool dispatch (validation, content rewriting, …).',
   },
   {
     name: 'agent/turn-continuation',
     mode: 'waterfall',
     signature: '\'agent/turn-continuation\'(this: Scoped<Agent>, agent: Agent, turn: number, defaultDecision: ContinuationDecision, next: () => Promise<ContinuationDecision>): Promise<ContinuationDecision>',
+    jsDoc: '/**\n * Override whether the turn continues. The default continues after tool\n * calls or steering and stops otherwise; a continue reason becomes steering.\n * @param agent - the agent deciding whether to run another step.\n * @param turn - the turn being continued or stopped.\n * @param defaultDecision - what the loop would do absent an override.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode waterfall\n */',
     summary: 'Override whether the turn continues.',
   },
   {
     name: 'agent/turn-stop',
     mode: 'serial',
     signature: '\'agent/turn-stop\'(this: Scoped<Agent>, agent: Agent, turn: number): ContinuationStop | undefined',
+    jsDoc: '/**\n * Monotonic terminal-stop checkpoint after continuation and steering are\n * folded; a stop remains authoritative through turn close and flush:\n * steering queued in that window is discarded, while ordinary sends survive.\n * @param agent - the agent whose composed continuation outcome may be stopped.\n * @param turn - the turn at its terminal-stop checkpoint.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @mode serial\n */',
     summary: 'Monotonic terminal-stop checkpoint after continuation and steering are folded; a stop remains authoritative through turn close and flush: steering queued in that window is discarded, while ordinary sends survive.',
   },
   {
     name: 'approval/request',
     mode: 'waterfall',
     signature: '\'approval/request\'(this: Scoped<ApprovalService>, req: ApprovalRequest, next: () => Promise<ApprovalOutcome>): Promise<ApprovalOutcome>',
+    jsDoc: '/**\n * Ask composed answerers for one decision. Return an outcome to claim the\n * request or call `next()`; failure yields the fail-closed default.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.\n * @param req - the pending decision (agent, tool identity, reason, signal).\n * @mode waterfall\n */',
     summary: 'Ask composed answerers for one decision.',
   },
   {
     name: 'fs/edit-intent',
     mode: 'waterfall',
     signature: '\'fs/edit-intent\'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>',
+    jsDoc: '/**\n * Single-slot decision for the next {@link FileSystem.editText}. Calling\n * `next()` yields an unconditional edit; the first returned guard wins.\n * @param target - the resolved target about to be edited.\n * @param actor - the opaque tool-execution context the decider keys off.\n * @mode waterfall\n */',
     summary: 'Single-slot decision for the next FileSystem.editText.',
   },
   {
     name: 'fs/observed',
     mode: 'emit',
     signature: '\'fs/observed\'(target: FsTarget, version: FsVersion, actor: object | undefined): void',
+    jsDoc: '/**\n * Record a successful observation. Listeners must be synchronous recorders:\n * throws fail the tool call and returned promises are not awaited.\n * @param target - the target that was read/written/edited.\n * @param version - the version the actor now holds as its observation.\n * @param actor - the observing tool-execution context; undefined records nothing useful.\n * @mode emit\n */',
     summary: 'Record a successful observation.',
   },
   {
     name: 'fs/write-intent',
     mode: 'waterfall',
     signature: '\'fs/write-intent\'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>): Promise<FsWriteIntent | undefined>',
+    jsDoc: '/**\n * Single-slot decision for the next {@link FileSystem.writeText}. Calling\n * `next()` yields the bare provider\'s unconditional write; the first listener\n * that returns an intent owns the decision rather than composing with peers.\n * @param target - the resolved target about to be written.\n * @param actor - the opaque tool-execution context the decider keys off.\n * @mode waterfall\n */',
     summary: 'Single-slot decision for the next FileSystem.writeText.',
   },
   {
     name: 'llm/stream',
     mode: 'waterfall',
     signature: '\'llm/stream\'(this: LlmService, options: GenerateOptions, next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>',
+    jsDoc: '/**\n * Waterfall around every streaming model call (retry, replay, routing).\n * Bound to the {@link LlmService}; call `next()` to reach the resolved\n * adapter\'s stream, or yield your own chunks to short-circuit.\n * @param options - the full request. A LOOP-built request arrives\n *   deep-frozen (mutation throws): its content is a pure function of the\n *   session log (the reconstructability RFC), so listeners read it, never\n *   rewrite it. A hand-built one-shot (compaction summarize) is the\n *   caller\'s own object and stays mutable here.\n * @mode waterfall\n */',
     summary: 'Waterfall around every streaming model call (retry, replay, routing).',
   },
   {
     name: 'session/created',
     mode: 'emit',
     signature: '\'session/created\'(this: Scoped<Session>, session: Session): void',
+    jsDoc: '/**\n * Creation announcement during session publication. A synchronous throw vetoes and rolls\n * back with a paired disposal; detach requested during dispatch is deferred.\n * A returned-promise rejection is logged but cannot retroactively veto this\n * synchronous boundary.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners\n * receive only sessions entered through that agent\'s context.\n * @param session - the session just entered and announced.\n * @dshScopeScan unsupported\n * @mode emit\n */',
     summary: 'Creation announcement during session publication.',
   },
   {
     name: 'session/disposed',
     mode: 'emit',
     signature: '\'session/disposed\'(this: Scoped<Session>, session: Session): void',
+    jsDoc: '/**\n * Emitted once when an announced session leaves the store, including\n * publication rollback, but never for an entry whose creation announcement\n * did not begin. Listener failures are logged and contained.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the owner scope.\n * @param session - the session that is no longer live in the store.\n * @dshScopeScan unsupported\n * @mode emit\n */',
     summary: 'Emitted once when an announced session leaves the store, including publication rollback, but never for an entry whose creation announcement did not begin.',
   },
   {
     name: 'session/event',
     mode: 'emit',
     signature: '\'session/event\'(this: Scoped<Session>, session: Session, event: SessionEvent): void',
+    jsDoc: '/**\n * Post-commit, fire-and-forget append feed. The listener snapshot resolves\n * before the log push, but callbacks run after it; observer failures are\n * logged and contained without making the committed append fail.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners\n * receive only events from sessions entered through that agent\'s context.\n * @param session - the session whose log grew.\n * @param event - the appended event, exactly as recorded.\n * @dshScopeScan unsupported\n * @mode emit\n */',
     summary: 'Post-commit, fire-and-forget append feed.',
   },
   {
     name: 'session/flush',
     mode: 'parallel',
     signature: '\'session/flush\'(this: Scoped<Session>, session: Session): Promise<void> | void',
+    jsDoc: '/**\n * Awaited parallel durability checkpoint: every listener runs and the\n * caller awaits all of them, with no waterfall veto. Dispatch through\n * {@link SessionStore.flush}. Scope-filtered dispatch\n * (`@deepseek-ai/dsh-scope`) reuses the session\'s owner scope.\n * @param session - the session whose buffered events must reach durable storage.\n * @dshScopeScan unsupported\n * @mode parallel\n */',
     summary: 'Awaited parallel durability checkpoint: every listener runs and the caller awaits all of them, with no waterfall veto.',
   },
   {
     name: 'subagent/end',
     mode: 'emit',
     signature: '\'subagent/end\'(this: Scoped<SubagentService>, info: SubagentRunEndInfo): void',
+    jsDoc: '/**\n * A ready child settled. Scope-filtered dispatch uses the same delegating\n * parent carrier as `subagent/start`, so the lifecycle pair reaches the\n * same scoped audience.\n * @param info - the run identity and terminal outcome.\n * @dshScopeScan unsupported\n * @mode emit\n */',
     summary: 'A ready child settled.',
   },
   {
     name: 'subagent/provider-added',
     mode: 'emit',
     signature: '\'subagent/provider-added\'(provider: SubagentProvider): void',
+    jsDoc: '/**\n * A provider became resolvable in the registry.\n * @param provider - the registered provider.\n * @mode emit\n */',
     summary: 'A provider became resolvable in the registry.',
   },
   {
     name: 'subagent/provider-removed',
     mode: 'emit',
     signature: '\'subagent/provider-removed\'(name: string): void',
+    jsDoc: '/**\n * A provider left the registry. Accepted runs remain holder-owned.\n * @param name - the provider name that no longer resolves.\n * @mode emit\n */',
     summary: 'A provider left the registry.',
   },
   {
     name: 'subagent/start',
     mode: 'emit',
     signature: '\'subagent/start\'(this: Scoped<SubagentService>, info: SubagentRunInfo): void',
+    jsDoc: '/**\n * A provider established a ready child. For in-process providers,\n * `ctx.agents.get(info.id)` resolves during this notification.\n * Scope-filtered dispatch keys the carrier by the delegating parent, so a\n * parent-scoped listener observes only its own delegations. Paired with\n * `subagent/end`.\n * @param info - the provider and ready child identity.\n * @dshScopeScan unsupported\n * @mode emit\n */',
     summary: 'A provider established a ready child.',
   },
   {
     name: 'system-prompt/assemble',
     mode: 'waterfall',
     signature: '\'system-prompt/assemble\'(this: Scoped<SystemPrompt>, assembly: PromptAssembly, context: AssembleContext, next: () => Promise<PromptAssembly>): Promise<PromptAssembly>',
+    jsDoc: '/**\n * Expert waterfall over the assembled sections, tools, and variables.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners\n * receive only that scope\'s assemblies. The returned value is authoritative.\n * @param assembly - the mutable assembly built from registered providers.\n * @param context - the caller\'s per-assembly context.\n * @mode waterfall\n */',
     summary: 'Expert waterfall over the assembled sections, tools, and variables.',
   },
   {
     name: 'system-prompt/change',
     mode: 'emit',
     signature: '\'system-prompt/change\'(): void',
+    jsDoc: '/**\n * Emitted when any prompt provider changes. This registry notification is\n * unfiltered because a global change affects every scope.\n * @mode emit\n */',
     summary: 'Emitted when any prompt provider changes.',
   },
   {
     name: 'tools/change',
     mode: 'emit',
     signature: '\'tools/change\'(): void',
+    jsDoc: '/**\n * A tool was registered or unregistered, or a scoped restriction changed\n * (the available tool set changed — possibly for one scope only). An\n * UNFILTERED registry-subject notification, deliberately not scope-filtered\n * dispatch: a global change concerns every agent\'s next assembly, so a\n * scoped listener subscribing here sees every change, not just its own\n * scope\'s.\n * @mode emit\n */',
     summary: 'A tool was registered or unregistered, or a scoped restriction changed (the available tool set changed — possibly for one scope only).',
   },
   {
     name: 'tools/execute',
     mode: 'waterfall',
     signature: '\'tools/execute\'(this: Scoped<ToolRegistry>, exec: ToolExecution, next: () => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>',
+    jsDoc: '/**\n * Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns\n * a normalized result; wrappers may change only `exec.signal`, while call\n * identity remains immutable.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent\'s calls.\n * @param exec - the allowed call about to dispatch (name, parsed arguments, caller agent, signal).\n * @mode waterfall\n */',
     summary: 'Around-dispatch waterfall for timeout, retry, or metrics.',
   },
   {
     name: 'tools/post-execute',
     mode: 'waterfall',
     signature: '\'tools/post-execute\'(this: Scoped<ToolRegistry>, exec: ToolExecution, result: Readonly<ToolExecutionResult>, next: () => Promise<PostToolDecision>): Promise<PostToolDecision>',
+    jsDoc: '/**\n * Accept, replace, enrich, or block a normalized dispatch result. `next()`\n * accepts it unchanged; thrown tools still reach this seam as errors.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent\'s calls.\n * @param exec - the call that just ran (name, parsed arguments, caller agent).\n * @param result - the dispatch outcome a listener may accept, replace, or block.\n * @mode waterfall\n */',
     summary: 'Accept, replace, enrich, or block a normalized dispatch result.',
   },
   {
     name: 'tools/pre-execute',
     mode: 'waterfall',
     signature: '\'tools/pre-execute\'(this: Scoped<ToolRegistry>, exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision>',
+    jsDoc: '/**\n * Allow, deny, or ask before dispatch. `next()` delegates to allow; missing\n * approval support turns `ask` into denial.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent\'s calls.\n * @param exec - the pending call (name, parsed arguments, caller agent).\n * @mode waterfall\n */',
     summary: 'Allow, deny, or ask before dispatch.',
   },
   {
     name: 'tools/result',
     mode: 'emit',
     signature: '\'tools/result\'(this: Scoped<ToolRegistry>, exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): undefined',
+    jsDoc: '/**\n * Observe the frozen, lossless-JSON final outcome. Listener failures are contained.\n * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): keyed by `exec.agent`.\n * @param exec - the execution object that traversed the pipeline.\n * @param result - a deep-frozen snapshot of the final returned result.\n * @mode emit\n */',
     summary: 'Observe the frozen, lossless-JSON final outcome.',
   },
   {
     name: 'workflow/agent-end',
     mode: 'emit',
     signature: '\'workflow/agent-end\'(info: WorkflowRunInfo, agent: WorkflowAgentEndInfo): void',
+    jsDoc: '/**\n * One `agent()` call settled (clean result, child failure, or run\n * cancellation). Paired with {@link Events[\'workflow/agent-start\']} by\n * `agent.seq`, exactly once per started call on every stop path — on an\n * engine termination path (a worker killed past its grace) the end is\n * engine-synthesized with outcome `\'cancelled\'`.\n * @param info - the run\'s identity snapshot.\n * @param agent - the call identity plus its outcome.\n * @mode emit\n */',
     summary: 'One `agent()` call settled (clean result, child failure, or run cancellation).',
   },
   {
     name: 'workflow/agent-start',
     mode: 'emit',
     signature: '\'workflow/agent-start\'(info: WorkflowRunInfo, agent: WorkflowAgentInfo): void',
+    jsDoc: '/**\n * One `agent()` call established a ready child run. Paired with\n * {@link Events[\'workflow/agent-end\']} by `agent.seq`. A call that never\n * receives a ready run from the provider emits neither\n * event in this pair.\n * @param info - the run\'s identity snapshot.\n * @param agent - the call\'s sequence number, label, phase, and child id.\n * @mode emit\n */',
     summary: 'One `agent()` call established a ready child run.',
   },
   {
     name: 'workflow/end',
     mode: 'emit',
     signature: '\'workflow/end\'(info: WorkflowRunInfo, result: WorkflowResultInfo): void',
+    jsDoc: '/**\n * A workflow run settled (any stop reason). Fired when\n * {@link WorkflowRun.result} resolves. Paired with\n * {@link Events[\'workflow/start\']}.\n * @param info - the run\'s identity snapshot.\n * @param result - the outcome data (stop reason, error, agent count) —\n *   deliberately WITHOUT the result value (see {@link WorkflowResultInfo}).\n * @mode emit\n */',
     summary: 'A workflow run settled (any stop reason).',
   },
   {
     name: 'workflow/log',
     mode: 'emit',
     signature: '\'workflow/log\'(info: WorkflowRunInfo, message: string): void',
+    jsDoc: '/**\n * The script emitted a narration line (a `log(message)` call).\n * @param info - the run\'s identity snapshot.\n * @param message - the logged message, verbatim.\n * @mode emit\n */',
     summary: 'The script emitted a narration line (a `log(message)` call).',
   },
   {
     name: 'workflow/phase',
     mode: 'emit',
     signature: '\'workflow/phase\'(info: WorkflowRunInfo, title: string): void',
+    jsDoc: '/**\n * The script entered a phase (a `phase(title)` call) — progress grouping\n * for observers; no execution semantics.\n * @param info - the run\'s identity snapshot.\n * @param title - the phase title, verbatim.\n * @mode emit\n */',
     summary: 'The script entered a phase (a `phase(title)` call) — progress grouping for observers; no execution semantics.',
   },
   {
     name: 'workflow/start',
     mode: 'emit',
     signature: '\'workflow/start\'(info: WorkflowRunInfo): void',
+    jsDoc: '/**\n * A workflow run started — the script\'s meta block validated, the body\n * about to execute. Paired with {@link Events[\'workflow/end\']}.\n * @param info - the run\'s identity snapshot (id + meta).\n * @mode emit\n */',
     summary: 'A workflow run started — the script\'s meta block validated, the body about to execute.',
   },
 ]
diff --git a/packages/cordis/tool-cordis/src/index.ts b/packages/cordis/tool-cordis/src/index.ts
index 321546c8c3..fd15d75624 100644
--- a/packages/cordis/tool-cordis/src/index.ts
+++ b/packages/cordis/tool-cordis/src/index.ts
@@ -12,9 +12,9 @@ import z from 'schemastery'
 import { defineTool } from '@deepseek-ai/dsh-tools'
 import { STATE_LABELS } from './fiber-state.ts'
 import { isPlugin, pluginName } from './guard.ts'
+import { EVENT_API, INHERITED_CTX_API, SERVICE_API, TYPE_API } from './api-catalog.ts'
 import { describeApi, describeDynamic, describeEvents, describePlugins, describeServices, describeTools } from './inspect.ts'
-import { missingServices, mountDynamic } from './mount.ts'
-import type { DynamicMount } from './mount.ts'
+import { missingServices, mountDynamic, type DynamicMount } from './mount.ts'
 import { presentInspectCall, presentMountCall, presentUnmountCall } from './present.ts'
 import { createSandbox, evaluateMountCode } from './sandbox.ts'
 
@@ -63,15 +63,23 @@ export function apply(ctx: Context, config: Config): void {
       + '`dynamic` (plugins you mounted via cordis_mount: id, name, state, provided services, awaited services), '
       + '`api` (method signatures AND argument/return type shapes for every LIVE service — read this before writing plugin code that calls a service), '
       + '`events` (every harness event with its dispatch mode and exact signature — pick listener targets here). '
-      + 'Omit `what` to get all six sections.',
+      + 'Omit `what` to get all six sections. With `what:"api"` or `what:"events"`, pass an exact `name` '
+      + 'to narrow to one service/event and include its original source JSDoc.',
     parameters: {
       what: {
         type: 'string',
         enum: ['services', 'plugins', 'tools', 'dynamic', 'api', 'events'],
         description: 'Limit the report to one section. Omit for all sections.',
       },
+      name: {
+        type: 'string',
+        description: 'Exact service key or event name whose original JSDoc to include; valid only with what:"api" or what:"events".',
+      },
     },
     execute(args, exec): Promise<{ type: 'text'; text: string }[]> {
+      if (args.name !== undefined && args.what !== 'api' && args.what !== 'events') {
+        throw new Error('name is valid only with what:"api" or what:"events"')
+      }
       const sections: [heading: string, body: () => string[]][] = [
         ['services', () => describeServices(ctx)],
         ['plugins', () => describePlugins(ctx)],
@@ -79,8 +87,8 @@ export function apply(ctx: Context, config: Config): void {
         // globals absent — "what you can call", not the global registry.
         ['tools', () => describeTools(ctx, exec.agent)],
         ['dynamic', () => describeDynamic(ctx, mounts)],
-        ['api', () => describeApi(ctx)],
-        ['events', () => describeEvents()],
+        ['api', () => describeApi(ctx, SERVICE_API, INHERITED_CTX_API, TYPE_API, args.name)],
+        ['events', () => describeEvents(EVENT_API, args.name)],
       ]
       const selected = sections.filter(([heading]) => args.what === undefined || args.what === heading)
       const text = selected
diff --git a/packages/cordis/tool-cordis/src/inspect.ts b/packages/cordis/tool-cordis/src/inspect.ts
index b483b13712..7196f370ce 100644
--- a/packages/cordis/tool-cordis/src/inspect.ts
+++ b/packages/cordis/tool-cordis/src/inspect.ts
@@ -1,7 +1,8 @@
 /**
  * Read-only renderers over the live runtime for `cordis_inspect`: the service list, the flat
  * plugin list, the registered tools, the dynamic-mount table (with per-mount provides/waits),
- * and the catalog-backed `api` / `events` sections.
+ * and the catalog-backed `api` / `events` sections. Exact-name lookups add the
+ * original source JSDoc without inflating the default reports.
  * @module @deepseek-ai/dsh-tool-cordis/inspect
  */
 
@@ -126,6 +127,18 @@ function typeClosure(seeds: string[], types: readonly TypeApiEntry[]): TypeApiEn
   return [...included.values()].sort((a, b) => a.name.localeCompare(b.name))
 }
 
+/** Render one catalogued service, optionally including source-owned method JSDoc. */
+function serviceLines(entry: ServiceApiEntry, detailed: boolean): string[] {
+  const lines = [`- ${entry.key} — ${entry.summary}`]
+  for (const method of entry.methods) {
+    if (detailed) {
+      for (const docLine of method.jsDoc.split('\n')) lines.push(`    ${docLine}`)
+    }
+    lines.push(`    ${method.signature}`)
+  }
+  return lines
+}
+
 /**
  * Render the generated catalog against the live runtime: live catalogued services with methods,
  * uncatalogued live services with owners, absent loadable services, referenced type shapes, and
@@ -134,6 +147,7 @@ function typeClosure(seeds: string[], types: readonly TypeApiEntry[]): TypeApiEn
  * @param api - generated service entries, replaceable in tests.
  * @param inherited - inherited `ctx` entries, replaceable in tests.
  * @param types - public type shapes, replaceable in tests.
+ * @param name - exact live service key whose methods should include original JSDoc; omitted for the compact catalog.
  * @returns the section lines.
  */
 export function describeApi(
@@ -141,25 +155,33 @@ export function describeApi(
   api: readonly ServiceApiEntry[] = SERVICE_API,
   inherited: readonly InheritedApiEntry[] = INHERITED_CTX_API,
   types: readonly TypeApiEntry[] = TYPE_API,
+  name?: string,
 ): string[] {
   const live = new Map<string, string>()
   for (const impl of liveImpls(ctx)) live.set(impl.name, impl.fiber.name)
   const lines: string[] = []
   const liveMethodTexts: string[] = []
-  for (const entry of api) {
-    if (!live.has(entry.key)) continue
-    lines.push(`- ${entry.key} — ${entry.summary}`)
+  let selected = api.filter(entry => live.has(entry.key))
+  if (name !== undefined) {
+    const entry = api.find(candidate => candidate.key === name)
+    if (!entry) throw new Error(`no catalogued service named "${name}"`)
+    if (!live.has(name)) throw new Error(`catalogued service "${name}" is not running`)
+    selected = [entry]
+  }
+  for (const entry of selected) {
+    lines.push(...serviceLines(entry, name !== undefined))
     for (const method of entry.methods) {
-      lines.push(`    ${method}`)
-      liveMethodTexts.push(method)
+      liveMethodTexts.push(method.signature)
     }
   }
-  const catalogued = new Set(api.map(entry => entry.key))
-  for (const [name, fiber] of [...live].sort(([a], [b]) => a.localeCompare(b))) {
-    if (!catalogued.has(name)) lines.push(`- ${name} (provided by ${fiber}, no catalog entry)`)
+  if (name === undefined) {
+    const catalogued = new Set(api.map(entry => entry.key))
+    for (const [liveName, fiber] of [...live].sort(([a], [b]) => a.localeCompare(b))) {
+      if (!catalogued.has(liveName)) lines.push(`- ${liveName} (provided by ${fiber}, no catalog entry)`)
+    }
+    const notRunning = api.filter(entry => !live.has(entry.key)).map(entry => entry.key)
+    if (notRunning.length > 0) lines.push(`not running (loadable services with no live provider): ${notRunning.join(', ')}`)
   }
-  const notRunning = api.filter(entry => !live.has(entry.key)).map(entry => entry.key)
-  if (notRunning.length > 0) lines.push(`not running (loadable services with no live provider): ${notRunning.join(', ')}`)
   const shapes = typeClosure(liveMethodTexts, types)
   if (shapes.length > 0) {
     lines.push('type shapes (referenced by the signatures above — read these before assuming a field is a string):')
@@ -167,8 +189,10 @@ export function describeApi(
       for (const declLine of shape.declaration.split('\n')) lines.push(`    ${declLine}`)
     }
   }
-  lines.push('inherited ctx API:')
-  for (const entry of inherited) lines.push(`- ${entry.name} — ${entry.summary}`)
+  if (name === undefined) {
+    lines.push('inherited ctx API:')
+    for (const entry of inherited) lines.push(`- ${entry.name} — ${entry.summary}`)
+  }
   return lines
 }
 
@@ -176,13 +200,24 @@ export function describeApi(
  * The `events` section: every harness event with its dispatch mode, one-line
  * summary, and exact signature, closed by the waterfall caution.
  * @param events - the event catalog (the generated one by default; injectable for tests).
+ * @param name - exact event name whose signature should include original JSDoc; omitted for the compact catalog.
  * @returns the section lines.
  */
-export function describeEvents(events: readonly EventApiEntry[] = EVENT_API): string[] {
-  const lines = events.flatMap(event => [
-    `- ${event.name} [${event.mode}] — ${event.summary}`,
-    `    ${event.signature}`,
-  ])
+export function describeEvents(events: readonly EventApiEntry[] = EVENT_API, name?: string): string[] {
+  let selected = events
+  if (name !== undefined) {
+    const event = events.find(candidate => candidate.name === name)
+    if (!event) throw new Error(`no catalogued event named "${name}"`)
+    selected = [event]
+  }
+  const lines = selected.flatMap((event) => {
+    const entry = [`- ${event.name} [${event.mode}] — ${event.summary}`]
+    if (name !== undefined) {
+      for (const docLine of event.jsDoc.split('\n')) entry.push(`    ${docLine}`)
+    }
+    entry.push(`    ${event.signature}`)
+    return entry
+  })
   lines.push('waterfall listeners receive a trailing next() and MUST call it to delegate — returning without next() vetoes the chain.')
   return lines
 }
diff --git a/packages/cordis/tool-cordis/src/present.ts b/packages/cordis/tool-cordis/src/present.ts
index 614b070193..e13570cf43 100644
--- a/packages/cordis/tool-cordis/src/present.ts
+++ b/packages/cordis/tool-cordis/src/present.ts
@@ -15,11 +15,12 @@ import type { GenericCallView } from '@deepseek-ai/dsh-tools'
  * @param args - the validated call arguments.
  * @returns the generic card the ACP bridge renders.
  */
-export function presentInspectCall(args: { what?: string }): GenericCallView {
+export function presentInspectCall(args: { what?: string; name?: string }): GenericCallView {
+  const target = args.name === undefined ? args.what : `${args.what}: ${args.name}`
   return {
     card: 'generic',
     kind: 'read',
-    title: args.what === undefined ? 'Inspect cordis runtime' : `Inspect cordis runtime: ${args.what}`,
+    title: target === undefined ? 'Inspect cordis runtime' : `Inspect cordis runtime: ${target}`,
   }
 }
 
diff --git a/packages/cordis/tool-cordis/tests/inspect.spec.ts b/packages/cordis/tool-cordis/tests/inspect.spec.ts
index 1a8c39467a..4d986d4f3e 100644
--- a/packages/cordis/tool-cordis/tests/inspect.spec.ts
+++ b/packages/cordis/tool-cordis/tests/inspect.spec.ts
@@ -64,6 +64,24 @@ describe('cordis_inspect', () => {
     // The inherited ctx surface closes the section.
     expect(report).toContain('inherited ctx API:')
     expect(report).toContain('- ctx.effect — ')
+    // The broad report stays compact; exact-name lookup owns full JSDoc.
+    expect(report).not.toContain('/**')
+    expect(report).not.toContain('@param definition')
+  })
+
+  it('adds original method JSDoc only for an exact live api name', async () => {
+    const ctx = await setup()
+    const report = text(await call(ctx, 'cordis_inspect', { what: 'api', name: 'tools' }))
+    expect(report).toContain('## api')
+    expect(report).toContain('- tools — Tool registry and execution pipeline.')
+    expect(report).toContain('/**')
+    expect(report).toContain('Register globally or in the calling agent scope.')
+    expect(report).toContain('@param definition - the tool schema')
+    expect(report).toContain('@returns the exact disposer')
+    expect(report).toContain('register(definition: ToolDefinition)')
+    expect(report).toContain('type shapes (referenced by the signatures above')
+    expect(report).not.toContain('not running (loadable services')
+    expect(report).not.toContain('inherited ctx API:')
   })
 
   it('renders the events section with mode badges, signatures, and the waterfall caution', async () => {
@@ -73,6 +91,39 @@ describe('cordis_inspect', () => {
     expect(report).toContain('- tools/pre-execute [waterfall]')
     expect(report).toMatch(/'agent\/status'\(/)
     expect(report).toContain('returning without next() vetoes the chain')
+    expect(report).not.toContain('/**')
+    expect(report).not.toContain('@mode waterfall')
+  })
+
+  it('adds original event JSDoc only for an exact event name', async () => {
+    const ctx = await setup()
+    const report = text(await call(ctx, 'cordis_inspect', { what: 'events', name: 'tools/pre-execute' }))
+    expect(report).toContain('## events')
+    expect(report).toContain('- tools/pre-execute [waterfall]')
+    expect(report).toContain('/**')
+    expect(report).toContain('Allow, deny, or ask before dispatch.')
+    expect(report).toContain('@param exec - the pending call')
+    expect(report).toContain('@mode waterfall')
+    expect(report).not.toContain('- tools/change [emit]')
+  })
+
+  it('fails loud for incompatible, unknown, and non-running names', async () => {
+    const ctx = await setup()
+    const incompatible = await call(ctx, 'cordis_inspect', { what: 'tools', name: 'tools' })
+    expect(incompatible.isError).toBe(true)
+    expect(text(incompatible)).toContain('name is valid only with what:"api" or what:"events"')
+
+    const unknownService = await call(ctx, 'cordis_inspect', { what: 'api', name: 'not-a-service' })
+    expect(unknownService.isError).toBe(true)
+    expect(text(unknownService)).toContain('no catalogued service named "not-a-service"')
+
+    const nonRunning = await call(ctx, 'cordis_inspect', { what: 'api', name: 'bash' })
+    expect(nonRunning.isError).toBe(true)
+    expect(text(nonRunning)).toContain('catalogued service "bash" is not running')
+
+    const unknownEvent = await call(ctx, 'cordis_inspect', { what: 'events', name: 'not/an-event' })
+    expect(unknownEvent.isError).toBe(true)
+    expect(text(unknownEvent)).toContain('no catalogued event named "not/an-event"')
   })
 })
 
@@ -102,7 +153,11 @@ describe('inspect renderers (direct)', () => {
 
   it('describeApi omits the not-running line and type shapes when nothing applies', async () => {
     const ctx = await setup()
-    const lines = describeApi(ctx, [{ key: 'tools', summary: 'The registry.', methods: ['register(x): void'] }], [], [])
+    const lines = describeApi(ctx, [{
+      key: 'tools',
+      summary: 'The registry.',
+      methods: [{ signature: 'register(x): void', jsDoc: '/** Register x. */' }],
+    }], [], [])
     expect(lines[0]).toBe('- tools — The registry.')
     expect(lines[1]).toBe('    register(x): void')
     expect(lines.join('\n')).not.toContain('not running')
diff --git a/packages/cordis/tool-cordis/tests/present.spec.ts b/packages/cordis/tool-cordis/tests/present.spec.ts
index d8f380439f..ed45fd1518 100644
--- a/packages/cordis/tool-cordis/tests/present.spec.ts
+++ b/packages/cordis/tool-cordis/tests/present.spec.ts
@@ -11,6 +11,11 @@ describe('presenters', () => {
   it('cordis_inspect renders a generic read card titled with the section', () => {
     expect(presentInspectCall({})).toEqual({ card: 'generic', kind: 'read', title: 'Inspect cordis runtime' })
     expect(presentInspectCall({ what: 'api' })).toEqual({ card: 'generic', kind: 'read', title: 'Inspect cordis runtime: api' })
+    expect(presentInspectCall({ what: 'events', name: 'tools/change' })).toEqual({
+      card: 'generic',
+      kind: 'read',
+      title: 'Inspect cordis runtime: events: tools/change',
+    })
   })
 
   it('cordis_mount renders a generic execute card carrying the code as raw input', () => {
@@ -33,6 +38,9 @@ describe('presenters', () => {
       kind: 'read',
       title: 'Inspect cordis runtime: tools',
     })
+    expect(ctx.tools.get('cordis_inspect')!.presentCall!({ what: 'api', name: 'tools' })).toMatchObject({
+      title: 'Inspect cordis runtime: api: tools',
+    })
     expect(ctx.tools.get('cordis_mount')!.presentCall!({ code: 'return 1' })).toMatchObject({ kind: 'execute' })
     expect(ctx.tools.get('cordis_unmount')!.presentCall!({ id: 'dyn-2' })).toMatchObject({ title: 'Unmount dyn-2' })
     // Soft validation: presenter args that fail the schema render as no card, never a throw.
diff --git a/packages/cordis/tool-cordis/tests/tool-cordis.spec.ts b/packages/cordis/tool-cordis/tests/tool-cordis.spec.ts
index 8953b5da94..d305a92883 100644
--- a/packages/cordis/tool-cordis/tests/tool-cordis.spec.ts
+++ b/packages/cordis/tool-cordis/tests/tool-cordis.spec.ts
@@ -32,8 +32,9 @@ describe('tool registration', () => {
     const names = ctx.tools.schemas().map(schema => schema.name)
     expect(names).toEqual(expect.arrayContaining(['cordis_inspect', 'cordis_mount', 'cordis_unmount']))
     const inspect = ctx.tools.schemas().find(schema => schema.name === 'cordis_inspect')!
-    const props = (inspect.parameters as { properties: Record<string, { enum?: string[] }> }).properties
+    const props = (inspect.parameters as { properties: Record<string, { enum?: string[]; type?: string }> }).properties
     expect(props.what?.enum).toEqual(['services', 'plugins', 'tools', 'dynamic', 'api', 'events'])
+    expect(props.name?.type).toBe('string')
   })
 })
 
diff --git a/packages/core/README.md b/packages/core/README.md
index b7e059c34e..fe98a78c22 100644
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -8,11 +8,11 @@ The session log, system-prompt assembly, tool registry, agent vocabulary, and co
 | `session/` | Event-sourced session log + in-memory store | `ctx.sessions` |
 | `system-prompt/` | Prompt-section + tool-schema assembly registry | `ctx.systemPrompt` |
 | `tools/` | Scoped tool registry + pre-policy, guards, around-dispatch, post-policy, and final-result observation | `ctx.tools` |
-| `agent/` | Agent interface, registry, `agent/*` event vocabulary | `ctx.agents` |
+| `agent/` | Agent interface, live registry, process-local initiator scope, `agent/*` event vocabulary | `ctx.agents` |
 | `agent-loop/` | Concrete plugin implementing the public `Agent` contract and owning the loop driver | `ctx.agentLoop` |
 
 `scope/` is the one non-service package here: a dependency-free library (`createScope`/`scopeOf`/`scopeTarget`) the registries and the loop build per-agent scoping on — it sits below `session/` and `system-prompt/` in the module graph precisely so they can consume it without a cycle.
 
-`agent-loop` is the one concrete implementation of the `agent` seam and lives here because it is the harness's default product loop; everything else in `core/` is interface/vocabulary. Plugins depend on the `agent` vocabulary, never on `agent-loop` directly, so the loop stays swappable.
+`agent-loop` is the one concrete implementation of the `agent` seam and lives here because it is the harness's default product loop. It runs each driver inside `ctx.agents.withInitiator()`. Extension plugins depend on `agent`, including when they need the initiating Agent, and never on `agent-loop` directly, so the loop stays swappable.
 
 The default composition that wires this spine into a runnable agent lives in [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md): one bundle plugin that loads the control spine plus selected default capabilities (`timer` + `llm` + sessions + system-prompt + tools + agents + invariants + the local [skill family](../skill/README.md) + `tool-bash` + workspace-context + `agent-loop`) and forwards `agent-loop`'s `agents` list as its own config. It sits in `examples/` — ready-to-run demo/reference bundles — not in `core/`: `core/` ships the swappable spine pieces, while a demo bundle picks one concrete composition of them and adds a front door.
diff --git a/packages/core/agent-loop/README.md b/packages/core/agent-loop/README.md
index 5b7e0307f1..6d373a303a 100644
--- a/packages/core/agent-loop/README.md
+++ b/packages/core/agent-loop/README.md
@@ -50,7 +50,7 @@ The concrete `Agent` class, its `Inbox`, `runLoop`, and instance-bound publicati
 
 ### Loop lifecycle (`loop.ts`)
 
-The internal loop driver runs one agent for its whole lifetime:
+The driver owns one agent for its lifetime and runs inside `ctx.agents.withInitiator(agent, ...)`. Package-private orchestration entry points recover the exact Agent, derive `agent.session` once, and let operation-local helpers capture it instead of forwarding the concrete driver or per-operation `Session` through shallow interfaces. A helper keeps an explicit `Session` when that is its actual interface, while creation, persistence load, unpublished setup, services, workers, processes, persistence, and wire protocols retain their explicit identities. The [agent service](../agent/README.md#initiating-agent-scope) owns propagation, teardown, and detached-work rules.
 
 Every provider call that reaches a successful finish appends exactly one `assistant/message` completion anchor, including content-less calls and `max-tokens` finishes. A successful `agent/step-result` stores its transformed content; a rejected result records empty content before the original failure continues. The anchor retains exact chunk provenance (`[]` for a stream with no chunks) and usage when available, while empty content stays out of derived message history.
 
diff --git a/packages/core/agent-loop/src/agent.ts b/packages/core/agent-loop/src/agent.ts
index d93832b361..61b661c082 100644
--- a/packages/core/agent-loop/src/agent.ts
+++ b/packages/core/agent-loop/src/agent.ts
@@ -387,7 +387,7 @@ export class ReactLoopAgent implements Agent {
   [startDriver](): void {
     if (this._status === 'disposed') return
     this.driverStarted = true
-    this.done = runLoop(this.loopCtx, this, {
+    this.done = this.loopCtx.agents.withInitiator(this, () => runLoop(this.loopCtx, {
       inbox: this.#inbox,
       maxParallelToolCalls: this.maxParallelToolCalls,
       setStatus: (status) => { this.setStatus(status) },
@@ -400,7 +400,7 @@ export class ReactLoopAgent implements Agent {
       withToolBatch: run => this.withToolBatch(run),
       // Pre-step cancellation re-parks without emitting a status transition.
       settleIdle: () => { this.settleIdleWaiters() },
-    })
+    }))
   }
 
   /**
diff --git a/packages/core/agent-loop/src/loop.ts b/packages/core/agent-loop/src/loop.ts
index a153eba7e4..ce95af3d13 100644
--- a/packages/core/agent-loop/src/loop.ts
+++ b/packages/core/agent-loop/src/loop.ts
@@ -19,7 +19,6 @@ import { renderPrompt } from '@deepseek-ai/dsh-system-prompt'
 import type { PromptAssembly } from '@deepseek-ai/dsh-system-prompt'
 import type {} from '@deepseek-ai/dsh-tools'
 import { executeToolCalls } from './tool-calls.ts'
-import type { ReactLoopAgent } from './agent.ts'
 import type { Inbox } from './inbox.ts'
 
 /** An Error with an optional machine-readable code (e.g., from LlmError or a throwing plugin). */
@@ -95,12 +94,17 @@ export interface LoopHandle {
 
 /**
  * Drive queued batches as durable turns until disposal. Plugin failures end the
- * current turn without terminating the driver.
- * @param ctx - the plugin context the loop reaches events (agent/…, session/flush) and services (systemPrompt, llm, tools) through.
- * @param agent - the agent this invocation drives for its whole lifetime (its inbox, session, and options).
+ * current turn without terminating the driver. The caller establishes the
+ * `ctx.agents.withInitiator()` boundary before entry; package-private
+ * orchestration recovers that exact Agent and captures its Session locally.
+ * @param ctx - the plugin context the loop reaches its initiating Agent,
+ * events (agent/…, session/flush), and services (systemPrompt, llm, tools)
+ * through.
  * @param handle - the bridge to the agent's mutable state: status/abort setters plus the disposal and cancel-marker reads.
+ * @throws when no initiating Agent is active.
  */
-export async function runLoop(ctx: Context, agent: ReactLoopAgent, handle: LoopHandle): Promise<void> {
+export async function runLoop(ctx: Context, handle: LoopHandle): Promise<void> {
+  const agent = ctx.agents.requireInitiator()
   // Per-instance prefix and request-header state; conversation history remains in the session log.
   const transmission = createTransmissionLog()
 
@@ -138,7 +142,7 @@ export async function runLoop(ctx: Context, agent: ReactLoopAgent, handle: LoopH
     const turn = lastTurnNumber(session) + 1
     let terminalStopped = false
     try {
-      terminalStopped = await runTurn(ctx, events, agent, handle, turn, transmission)
+      terminalStopped = await runTurn(ctx, events, handle, turn, transmission)
     } catch (error: unknown) {
       // Pre-turn failure has no durable boundary to close; report it without appending outside a turn.
       const err = toError(error)
@@ -161,9 +165,17 @@ export async function runLoop(ctx: Context, agent: ReactLoopAgent, handle: LoopH
 }
 
 async function runTurn(
-  ctx: Context, events: AgentEventDispatch, agent: ReactLoopAgent, handle: LoopHandle, turn: number, transmission: TransmissionLog,
+  ctx: Context, events: AgentEventDispatch, handle: LoopHandle, turn: number, transmission: TransmissionLog,
 ): Promise<boolean> {
+  const agent = ctx.agents.requireInitiator()
   const { session } = agent
+  const drainSteering = (): boolean => {
+    const messages = handle.inbox.drainSteering()
+    for (const message of messages) {
+      session.append('steering/message', { turn, content: message.content, source: message.source }, { surfaceOp: 'append' })
+    }
+    return messages.length > 0
+  }
 
   // Drain before opening the turn, but append only after `turn/start`.
   const queued = handle.inbox.drainQueued()
@@ -262,7 +274,7 @@ async function runTurn(
 
       // Steering from the previous round's continuation listeners joins before
       // the request.
-      drainSteering(agent, handle.inbox, turn)
+      drainSteering()
 
       // The step's AbortController exists BEFORE any async pre-step work so a
       // dispose() or cancel() — in a synchronous turn-start listener or an
@@ -336,7 +348,7 @@ async function runTurn(
       let stepOutcome: { hadToolCalls: boolean; finish: FinishReason } | { error: Error }
       try {
         stepOutcome = await runStep(
-          ctx, events, agent, handle, turn, step, assembly, fullSystemPrompt, boundaryMessages, transmission, abort.signal)
+          ctx, events, handle, turn, step, assembly, fullSystemPrompt, boundaryMessages, transmission, abort.signal)
       } catch (error: unknown) {
         stepOutcome = { error: toError(error) }
       } finally {
@@ -365,7 +377,7 @@ async function runTurn(
       if (stepReason) reason = stepReason
 
       // Steering that arrived during streaming/tool execution.
-      const steered = drainSteering(agent, handle.inbox, turn)
+      const steered = drainSteering()
 
       closeStep()
 
@@ -454,15 +466,6 @@ async function runTurn(
   return terminalStopped
 }
 
-/** Drain the steering queue into the session. Returns whether any arrived. */
-function drainSteering(agent: ReactLoopAgent, inbox: Inbox, turn: number): boolean {
-  const messages = inbox.drainSteering()
-  for (const message of messages) {
-    agent.session.append('steering/message', { turn, content: message.content, source: message.source }, { surfaceOp: 'append' })
-  }
-  return messages.length > 0
-}
-
 /**
  * Run one committed step: transform call config, log the request header, build
  * the request from the cached prefix plus the step-boundary snapshot, stream and
@@ -472,7 +475,6 @@ function drainSteering(agent: ReactLoopAgent, inbox: Inbox, turn: number): boole
 async function runStep(
   ctx: Context,
   events: AgentEventDispatch,
-  agent: ReactLoopAgent,
   handle: LoopHandle,
   turn: number,
   step: number,
@@ -482,6 +484,7 @@ async function runStep(
   transmission: TransmissionLog,
   signal: AbortSignal,
 ): Promise<{ hadToolCalls: boolean; finish: FinishReason }> {
+  const agent = ctx.agents.requireInitiator()
   const { session, options } = agent
 
   // Seed the first request from agent options and later requests from the logged header;
@@ -538,15 +541,47 @@ async function runStep(
   const stepError = finishError(assembler.finish)
   if (stepError) throw stepError
 
+  const recordAssistantMessage = (
+    assembledContent: ContentBlock[],
+    message: Message,
+    preserveReplayState = true,
+  ): void => {
+    session.append(
+      'assistant/message',
+      {
+        turn,
+        step,
+        content: message.content,
+        provenance: assistantProvenance(
+          header.config,
+          assembler.replayState,
+          preserveReplayState && isDeepStrictEqual(message.content, assembledContent),
+        ),
+        ...assembler.usage === undefined ? {} : { usage: assembler.usage },
+      },
+      { surfaceOp: 'append', sourceEventSeqs: chunkSeqs },
+    )
+  }
+
+  // A rejected result still records the successful provider call without retaining rejected output.
+  const processStepResult = async (assembledContent: ContentBlock[], message: Message): Promise<Message> => {
+    try {
+      return await events.waterfall(
+        'agent/step-result', turn, step, message, () => Promise.resolve(message),
+      )
+    } catch (error: unknown) {
+      recordAssistantMessage(assembledContent, { ...message, content: [] }, false)
+      throw error
+    }
+  }
+
   if (assembler.finish.kind === 'max-tokens') {
     const assembled = assembler.message()
     const assembledContent = structuredClone(assembled.content)
     let message: Message = withoutToolCalls(assembled)
-    message = withoutToolCalls(await processStepResult(
-      events, session, turn, step, header.config, assembledContent, message, assembler, chunkSeqs,
-    ))
+    message = withoutToolCalls(await processStepResult(assembledContent, message))
     // Preserve usage even when max-token truncation produced no content.
-    recordAssistantMessage(session, turn, step, header.config, assembledContent, message, assembler, chunkSeqs)
+    recordAssistantMessage(assembledContent, message)
     return { hadToolCalls: false, finish: assembler.finish }
   }
 
@@ -554,86 +589,23 @@ async function runStep(
   const assembled = assembler.message()
   const assembledContent = structuredClone(assembled.content)
   let message: Message = assembled
-  message = await processStepResult(
-    events, session, turn, step, header.config, assembledContent, message, assembler, chunkSeqs,
-  )
+  message = await processStepResult(assembledContent, message)
 
   // Every successful call records its completion anchor, including explicit
   // empty chunk provenance for a contentless, usage-less provider response.
-  recordAssistantMessage(session, turn, step, header.config, assembledContent, message, assembler, chunkSeqs)
+  recordAssistantMessage(assembledContent, message)
 
   // Dispatch may overlap; policy, durable results, and result context stay model-ordered.
   const toolCalls = message.content.filter(block => block.type === 'tool-call')
   if (toolCalls.length === 0) return { hadToolCalls: false, finish: assembler.finish }
   return handle.withToolBatch(async (acceptContext) => {
     await executeToolCalls(
-      ctx, agent, turn, step, toolCalls, signal, handle.maxParallelToolCalls, acceptContext,
+      ctx, turn, step, toolCalls, signal, handle.maxParallelToolCalls, acceptContext,
     )
     return { hadToolCalls: true, finish: assembler.finish }
   })
 }
 
-/** Preserve successful-call accounting without retaining output that result processing rejected. */
-async function processStepResult(
-  events: AgentEventDispatch,
-  session: Session,
-  turn: number,
-  step: number,
-  config: LlmCallConfig,
-  assembledContent: ContentBlock[],
-  message: Message,
-  assembler: BlockAssembler,
-  chunkSeqs: number[],
-): Promise<Message> {
-  try {
-    return await events.waterfall(
-      'agent/step-result', turn, step, message, () => Promise.resolve(message),
-    )
-  } catch (error: unknown) {
-    recordAssistantMessage(
-      session,
-      turn,
-      step,
-      config,
-      assembledContent,
-      { ...message, content: [] },
-      assembler,
-      chunkSeqs,
-      false,
-    )
-    throw error
-  }
-}
-
-/** Record one content-or-usage assistant message with replay-safe provenance. */
-function recordAssistantMessage(
-  session: Session,
-  turn: number,
-  step: number,
-  config: LlmCallConfig,
-  assembledContent: ContentBlock[],
-  message: Message,
-  assembler: BlockAssembler,
-  chunkSeqs: number[],
-  preserveReplayState = true,
-): void {
-  session.append(
-    'assistant/message',
-    {
-      turn,
-      step,
-      content: message.content,
-      provenance: assistantProvenance(
-        config,
-        assembler.replayState,
-        preserveReplayState && isDeepStrictEqual(message.content, assembledContent),
-      ),
-      ...assembler.usage === undefined ? {} : { usage: assembler.usage },
-    },
-    { surfaceOp: 'append', sourceEventSeqs: chunkSeqs },
-  )
-}
-
 /** Build durable assistant provenance, dropping replay state after any content rewrite. */
 function assistantProvenance(config: LlmCallConfig, replayState: unknown, contentUnchanged: boolean): NonNullable<Message['provenance']> {
   return {
diff --git a/packages/core/agent-loop/src/tool-calls.ts b/packages/core/agent-loop/src/tool-calls.ts
index 3f3581c70a..5ec1ceb4c2 100644
--- a/packages/core/agent-loop/src/tool-calls.ts
+++ b/packages/core/agent-loop/src/tool-calls.ts
@@ -12,9 +12,7 @@
 import type { Context } from 'cordis'
 import { assertNever, type ToolCallBlock } from '@deepseek-ai/dsh-llm'
 import type { HookContext } from '@deepseek-ai/dsh-agent'
-import type { Session } from '@deepseek-ai/dsh-session'
 import { TOOL_REGISTRY_SCHEDULER, type ToolExecutionInput, type ToolExecutionMode, type ToolExecutionResult, type ToolRunContext } from '@deepseek-ai/dsh-tools'
-import type { ReactLoopAgent } from './agent.ts'
 
 /** One tool call after argument parsing, ready to schedule. */
 interface PlannedCall {
@@ -33,9 +31,10 @@ interface Slot {
  * Schedule one assistant step's tool calls by their live concurrency mode.
  * Started calls receive ordered results. Abort drains them and rethrows after
  * accepting their context into the batch FIFO owned by the caller.
+ * The committed step's AgentLoop driver boundary supplies the initiating Agent
+ * that becomes each explicit {@link ToolExecutionInput.agent}.
  *
- * @param ctx - loop context that owns the tool registry.
- * @param agent - agent and session receiving the call lifecycle.
+ * @param ctx - loop context that owns the tool registry and carries the initiating Agent.
  * @param turn - current turn number.
  * @param step - current step number.
  * @param toolCalls - assistant calls in model order.
@@ -45,7 +44,6 @@ interface Slot {
  */
 export async function executeToolCalls(
   ctx: Context,
-  agent: ReactLoopAgent,
   turn: number,
   step: number,
   toolCalls: ToolCallBlock[],
@@ -53,7 +51,7 @@ export async function executeToolCalls(
   maxParallel: number,
   acceptContext: (context: HookContext) => void,
 ): Promise<void> {
-  const { session } = agent
+  const agent = ctx.agents.requireInitiator()
 
   // Inputs are distinct because tools/execute wrappers may replace `exec.signal`.
   const planned: PlannedCall[] = toolCalls.map(block => ({
@@ -74,7 +72,7 @@ export async function executeToolCalls(
     const first = planned[next]!
     const mode = ctx.tools.executionMode(first.exec).kind
     const group = mode === 'parallel' ? planned.slice(next) : [first]
-    next += await runGroup(ctx, session, turn, step, group, mode, signal, maxParallel, acceptContext)
+    next += await runGroup(ctx, turn, step, group, mode, signal, maxParallel, acceptContext)
   }
 }
 
@@ -96,7 +94,6 @@ function parseArguments(raw: string): unknown {
  */
 async function runGroup(
   ctx: Context,
-  session: Session,
   turn: number,
   step: number,
   group: PlannedCall[],
@@ -105,6 +102,30 @@ async function runGroup(
   maxParallel: number,
   acceptContext: (context: HookContext) => void,
 ): Promise<number> {
+  const { session } = ctx.agents.requireInitiator()
+  const appendToolCall = (block: ToolCallBlock): number => {
+    return session.append('tool/call', {
+      turn,
+      step,
+      callId: block.id,
+      name: block.name,
+      arguments: block.arguments,
+    }).seq
+  }
+  const appendToolResult = (block: ToolCallBlock, result: ToolExecutionResult, callSeq: number): void => {
+    session.append('tool/result', {
+      turn,
+      step,
+      // Correlation stays with the loop's authoritative model-transcript call id;
+      // registry results deliberately do not duplicate it.
+      callId: block.id,
+      content: result.content,
+      isError: result.isError,
+      ...result.error ? { error: result.error } : {},
+      // Persist presentation payloads so UI bridges reproduce result cards on replay.
+      ...result.meta !== undefined ? { meta: result.meta } : {},
+    }, { surfaceOp: 'append', sourceEventSeqs: [callSeq] })
+  }
   /* v8 ignore next -- signal.reason always set: cancel()/disposal provide a default */
   if (signal.aborted) throw new Error(String(signal.reason ?? 'aborted'))
   const slots: (Slot | undefined)[] = group.map(() => undefined)
@@ -125,7 +146,7 @@ async function runGroup(
         ? await ctx.tools[TOOL_REGISTRY_SCHEDULER].finalize(slot.exec, slot.result)
         : ctx.tools[TOOL_REGISTRY_SCHEDULER].finish(slot.exec, slot.result)
       // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- bounded index
-      appendToolResult(session, turn, step, call!.block, result, callSeqs[committed]!)
+      appendToolResult(call!.block, result, callSeqs[committed]!)
       for (const context of result.additionalContexts ?? []) acceptContext(context)
       committed++
     }
@@ -136,7 +157,7 @@ async function runGroup(
   const startCall = async (index: number): Promise<void> => {
     // eslint-disable-next-line @typescript-eslint/no-non-null-assertion -- bounded index
     const call = group[index]!
-    callSeqs[index] = appendToolCall(session, turn, step, call.block)
+    callSeqs[index] = appendToolCall(call.block)
     started++
     const prepared = await ctx.tools[TOOL_REGISTRY_SCHEDULER].prepare(call.exec)
     switch (prepared.kind) {
@@ -198,32 +219,3 @@ async function runGroup(
   if (committed !== started) throw new Error('tool-call scheduler: uncommitted settled calls')
   return started
 }
-
-/** Append a started call and return its provenance sequence. */
-function appendToolCall(session: Session, turn: number, step: number, block: ToolCallBlock): number {
-  const event = session.append('tool/call', { turn, step, callId: block.id, name: block.name, arguments: block.arguments })
-  return event.seq
-}
-
-/** Append a model-ordered result linked to its call event. */
-function appendToolResult(
-  session: Session,
-  turn: number,
-  step: number,
-  block: ToolCallBlock,
-  result: ToolExecutionResult,
-  callSeq: number,
-): void {
-  session.append('tool/result', {
-    turn, step,
-    // Correlation stays with the loop's authoritative model-transcript call id;
-    // registry results deliberately do not duplicate it.
-    callId: block.id,
-    content: result.content,
-    isError: result.isError,
-    ...result.error ? { error: result.error } : {},
-    // The tool's private presentation payload (e.g. a result-time diff),
-    // persisted so a UI bridge reproduces the card on replay.
-    ...result.meta !== undefined ? { meta: result.meta } : {},
-  }, { surfaceOp: 'append', sourceEventSeqs: [callSeq] })
-}
diff --git a/packages/core/agent-loop/tests/agent-initiator.spec.ts b/packages/core/agent-loop/tests/agent-initiator.spec.ts
new file mode 100644
index 0000000000..8e9b951fa1
--- /dev/null
+++ b/packages/core/agent-loop/tests/agent-initiator.spec.ts
@@ -0,0 +1,335 @@
+import { describe, expect, it } from 'vitest'
+import { Context, type Fiber } from 'cordis'
+import AgentRegistry, { type Agent } from '@deepseek-ai/dsh-agent'
+import AgentLoop from '@deepseek-ai/dsh-agent-loop'
+import LlmService, { CallId, LlmAdapter } from '@deepseek-ai/dsh-llm'
+import type { GenerateOptions, StreamChunk } from '@deepseek-ai/dsh-llm'
+import SessionStore, { SessionId } from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry, { defineTool } from '@deepseek-ai/dsh-tools'
+import { MockAdapter, textResponse, toolCallResponse } from './mock-adapter.ts'
+
+interface Harness {
+  ctx: Context
+  agentsFiber: Fiber
+  loopFiber: Fiber
+}
+
+async function harness(adapter: LlmAdapter): Promise<Harness> {
+  const ctx = new Context()
+  await ctx.plugin(LlmService)
+  await ctx.plugin(SessionStore)
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  const agentsFiber = await ctx.plugin(AgentRegistry)
+  const loopFiber = await ctx.plugin(AgentLoop, { agents: [] })
+  ctx.llm.registerAdapter(['mock'], adapter)
+  return { ctx, agentsFiber, loopFiber }
+}
+
+function waitForIdle(ctx: Context, agent: Agent): Promise<void> {
+  return new Promise((resolve) => {
+    const dispose = ctx.on('agent/status', (subject, status) => {
+      if (subject === agent && status === 'idle') {
+        dispose()
+        resolve()
+      }
+    })
+  })
+}
+
+function send(agent: Agent, text: string): void {
+  agent.send([{ type: 'text', text }])
+}
+
+/** Adapter that holds both drivers at the same awaited continuation. */
+class OverlapAdapter extends LlmAdapter {
+  private readonly bothStarted = Promise.withResolvers<boolean>()
+  private starts = 0
+  readonly observations: { sessionId: SessionId | undefined; before: Agent; after: Agent }[] = []
+
+  constructor(private readonly ctx: Context) {
+    super()
+  }
+
+  async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    const before = this.ctx.agents.requireInitiator()
+    this.starts += 1
+    if (this.starts === 2) this.bothStarted.resolve(true)
+    await this.bothStarted.promise
+    await Promise.resolve()
+    const after = this.ctx.agents.requireInitiator()
+    this.observations.push({ sessionId: options.sessionId, before, after })
+    yield* textResponse('done')
+  }
+}
+
+/** Test-only transport that materializes ambient identity at its request boundary. */
+class TestCapabilityTransport {
+  readonly requests: { path: string; headers: Record<string, string> }[] = []
+
+  constructor(private readonly agents: AgentRegistry) {}
+
+  async request(path: string): Promise<Record<string, string>> {
+    await Promise.resolve()
+    const headers = {
+      'X-Harness-Session-Id': this.agents.requireInitiator().session.id,
+    }
+    this.requests.push({ path, headers })
+    return headers
+  }
+}
+
+/** Adapter whose first call waits for cancellation and whose later calls complete. */
+class ReloadAdapter extends LlmAdapter {
+  readonly firstStarted = Promise.withResolvers<boolean>()
+  firstAgentDuringAbort: Agent | undefined
+  laterAgent: Agent | undefined
+  calls = 0
+  agents: AgentRegistry | undefined
+
+  async * stream(options: GenerateOptions): AsyncIterable<StreamChunk> {
+    const agents = this.agents
+    if (agents === undefined) throw new Error('agent service missing')
+    this.calls += 1
+    if (this.calls === 1) {
+      this.firstStarted.resolve(true)
+      try {
+        await new Promise<void>((_resolve, reject) => {
+          const abort = (): void => { reject(new Error('aborted')) }
+          if (options.signal?.aborted === true) abort()
+          else options.signal?.addEventListener('abort', abort, { once: true })
+        })
+      } catch (error: unknown) {
+        await Promise.resolve()
+        this.firstAgentDuringAbort = agents.requireInitiator()
+        throw error
+      }
+      return
+    }
+    await Promise.resolve()
+    this.laterAgent = agents.requireInitiator()
+    yield* textResponse('reloaded')
+  }
+}
+
+describe('AgentLoop initiator scope', () => {
+  it('keeps overlapping driver continuations bound to their exact Agents', async () => {
+    const ctx = new Context()
+    const adapter = new OverlapAdapter(ctx)
+    await ctx.plugin(LlmService)
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(AgentLoop, { agents: [] })
+    ctx.llm.registerAdapter(['mock'], adapter)
+
+    const a = ctx.agentLoop.create(SessionId('a'), { provider: 'mock', model: 'mock' })
+    const b = ctx.agentLoop.create(SessionId('b'), { provider: 'mock', model: 'mock' })
+    const idleA = waitForIdle(ctx, a)
+    const idleB = waitForIdle(ctx, b)
+    send(a, 'a')
+    send(b, 'b')
+    await Promise.all([idleA, idleB])
+
+    expect(adapter.observations).toHaveLength(2)
+    expect(adapter.observations).toEqual(expect.arrayContaining([
+      { sessionId: a.session.id, before: a, after: a },
+      { sessionId: b.session.id, before: b, after: b },
+    ]))
+    expect(ctx.agents.currentInitiator()).toBeUndefined()
+    await ctx.fiber.dispose()
+  })
+
+  it('keeps child setup under the parent boundary and restores the parent while the child driver remains active', async () => {
+    const adapter = new MockAdapter([
+      toolCallResponse('spawn', 'spawn-child', {}),
+      toolCallResponse('observe', 'observe-child', {}),
+      textResponse('child done'),
+      textResponse('parent done'),
+    ])
+    const { ctx } = await harness(adapter)
+    let parentDuringSetup: Agent | undefined
+    let explicitChild: Agent | undefined
+    let childDuringDriver: Agent | undefined
+    let parentWhileChildDriverActive: Agent | undefined
+    let child: Agent | undefined
+
+    ctx.tools.register(defineTool({
+      name: 'spawn-child',
+      description: 'create one child agent',
+      parameters: {},
+      execute: async (_args, exec) => {
+        if (exec.agent === undefined) throw new Error('parent agent missing')
+        const handle = await exec.agent.ctx.agents.create({
+          sessionId: SessionId('child-session'),
+          agentOptions: { provider: 'mock', model: 'mock' },
+          setup: (agentCtx) => {
+            parentDuringSetup = ctx.agents.requireInitiator()
+            explicitChild = agentCtx.agent
+            agentCtx.tools.register(defineTool({
+              name: 'observe-child',
+              description: 'observe child execution identity',
+              parameters: {},
+              execute: async () => {
+                await Promise.resolve()
+                childDuringDriver = ctx.agents.requireInitiator()
+                return [{ type: 'text', text: 'observed' }]
+              },
+            }))
+          },
+        })
+        child = handle.agent
+        parentWhileChildDriverActive = ctx.agents.requireInitiator()
+        send(handle.agent, 'run child')
+        await handle.agent.whenIdle()
+        await handle.dispose()
+        return [{ type: 'text', text: 'child completed' }]
+      },
+    }))
+
+    const parentHandle = await ctx.agents.create({
+      sessionId: SessionId('parent-session'),
+      agentOptions: { provider: 'mock', model: 'mock' },
+    })
+    const idle = waitForIdle(ctx, parentHandle.agent)
+    send(parentHandle.agent, 'spawn')
+    await idle
+
+    expect(parentDuringSetup).toBe(parentHandle.agent)
+    expect(explicitChild).toBe(child)
+    expect(childDuringDriver).toBe(child)
+    expect(parentWhileChildDriverActive).toBe(parentHandle.agent)
+    expect(ctx.agents.currentInitiator()).toBeUndefined()
+    await parentHandle.dispose()
+    await ctx.fiber.dispose()
+  })
+
+  it('keeps agentless direct tools ambient-free and builds trusted transport headers internally', async () => {
+    const adapter = new MockAdapter([
+      toolCallResponse('capability', 'capability-request', { path: '/v1/capability' }),
+      textResponse('done'),
+    ])
+    const { ctx } = await harness(adapter)
+    const transport = new TestCapabilityTransport(ctx.agents)
+    let directAmbient: Agent | undefined
+    let captured: Agent | undefined
+
+    ctx.tools.register(defineTool({
+      name: 'agentless-probe',
+      description: 'observe an agentless call',
+      parameters: {},
+      execute: async () => {
+        await Promise.resolve()
+        directAmbient = ctx.agents.currentInitiator()
+        return [{ type: 'text', text: 'ok' }]
+      },
+    }))
+    ctx.tools.register(defineTool({
+      name: 'capability-request',
+      description: 'call the test capability transport',
+      parameters: { path: { type: 'string' } },
+      execute: async (args) => {
+        captured = ctx.agents.requireInitiator()
+        const path = (args as { path: string }).path
+        const headers = await transport.request(path)
+        return [{ type: 'text', text: JSON.stringify(headers) }]
+      },
+    }))
+
+    const direct = await ctx.tools.execute({
+      callId: CallId('direct'),
+      name: 'agentless-probe',
+      arguments: {},
+    })
+    expect(direct.isError).toBe(false)
+    expect(directAmbient).toBeUndefined()
+
+    const handle = await ctx.agents.create({
+      sessionId: SessionId('transport-session'),
+      agentOptions: { provider: 'mock', model: 'mock' },
+    })
+    const idle = waitForIdle(ctx, handle.agent)
+    send(handle.agent, 'call transport')
+    await idle
+
+    expect(transport.requests).toEqual([{
+      path: '/v1/capability',
+      headers: { 'X-Harness-Session-Id': 'transport-session' },
+    }])
+    const schema = adapter.requests[0]?.tools?.find(tool => tool.name === 'capability-request')
+    expect(JSON.stringify(schema?.parameters)).not.toMatch(/session|harness/i)
+    const call = handle.agent.session.events.find(event => event.type === 'tool/call')
+    expect(call?.type === 'tool/call' ? call.data.arguments : undefined)
+      .toBe(JSON.stringify({ path: '/v1/capability' }))
+    expect(captured).toBe(handle.agent)
+
+    await handle.dispose()
+    expect(captured?.status).toBe('disposed')
+    expect(ctx.agents.currentInitiator()).toBeUndefined()
+    await ctx.fiber.dispose()
+  })
+
+  it('drains the old driver before disabling ALS during agent-service restart', async () => {
+    const adapter = new ReloadAdapter()
+    const { ctx, agentsFiber, loopFiber } = await harness(adapter)
+    const oldService = ctx.agents
+    adapter.agents = oldService
+    const oldHandle = await ctx.agents.create({
+      sessionId: SessionId('before-restart-session'),
+      agentOptions: { provider: 'mock', model: 'mock' },
+    })
+    const oldAgent = oldHandle.agent
+    send(oldAgent, 'block')
+    await adapter.firstStarted.promise
+
+    await agentsFiber.restart()
+    await loopFiber.await()
+    expect(adapter.firstAgentDuringAbort?.id).toBe(oldAgent.id)
+    expect(adapter.firstAgentDuringAbort?.session).toBe(oldAgent.session)
+    expect(oldAgent.status).toBe('disposed')
+    expect(() => oldService.currentInitiator()).toThrow('agent initiator scope is disposed')
+    expect(ctx.agents).not.toBe(oldService)
+    adapter.agents = ctx.agents
+
+    const newHandle = await ctx.agents.create({
+      sessionId: SessionId('after-restart-session'),
+      agentOptions: { provider: 'mock', model: 'mock' },
+    })
+    const newAgent = newHandle.agent
+    const idle = waitForIdle(ctx, newAgent)
+    send(newAgent, 'continue')
+    await idle
+    expect(adapter.laterAgent?.id).toBe(newAgent.id)
+    expect(adapter.laterAgent?.session).toBe(newAgent.session)
+    await ctx.fiber.dispose()
+  })
+
+  it('keeps ALS readable while root disposal drains sibling AgentLoop fibers', async () => {
+    const ctx = new Context()
+    const adapter = new ReloadAdapter()
+    await ctx.plugin(LlmService)
+    await ctx.plugin(SessionStore)
+    await ctx.plugin(SystemPrompt)
+    await ctx.plugin(ToolRegistry)
+    await ctx.plugin(AgentRegistry)
+    await ctx.plugin(AgentLoop, { agents: [] })
+    ctx.llm.registerAdapter(['mock'], adapter)
+    const service = ctx.agents
+    adapter.agents = service
+    const handle = await ctx.agents.create({
+      sessionId: SessionId('root-dispose-session'),
+      agentOptions: { provider: 'mock', model: 'mock' },
+    })
+    const agent = handle.agent
+    send(agent, 'block')
+    await adapter.firstStarted.promise
+
+    await ctx.fiber.dispose()
+    expect(adapter.firstAgentDuringAbort?.id).toBe(agent.id)
+    expect(adapter.firstAgentDuringAbort?.session).toBe(agent.session)
+    expect(agent.status).toBe('disposed')
+    expect(() => service.currentInitiator()).toThrow('agent initiator scope is disposed')
+  })
+})
diff --git a/packages/core/agent-loop/tests/agent.spec.ts b/packages/core/agent-loop/tests/agent.spec.ts
index 9ce72f9d4b..d23b69efb7 100644
--- a/packages/core/agent-loop/tests/agent.spec.ts
+++ b/packages/core/agent-loop/tests/agent.spec.ts
@@ -264,6 +264,7 @@ describe('Agent', () => {
     // early-return branch.
     const ctx = new Context()
     await ctx.plugin(SessionStore)
+    await ctx.plugin(AgentRegistry)
     const session = ctx.sessions.create(SessionId('test'))
     const prepared = prepareReactLoopAgent(
       ctx, SessionId('bare'), { provider: 'mock', model: 'mock' }, session, DEFAULT_MAX_PARALLEL_TOOL_CALLS,
diff --git a/packages/core/agent/README.md b/packages/core/agent/README.md
index 122e58f39d..3cf8bbb6ad 100644
--- a/packages/core/agent/README.md
+++ b/packages/core/agent/README.md
@@ -1,10 +1,10 @@
 # dsh-agent
 
-Agent interface, registry, and `agent/*` event vocabulary. Every plugin (UI, hooks, orchestrators) programs against the `Agent` handle defined here — it has zero loop dependency, so the loop is swappable.
+Agent interface, registry, process-local initiator scope, and `agent/*` event vocabulary. Every plugin (UI, hooks, orchestrators) programs against the `Agent` handle defined here — it has zero loop dependency, so the loop is swappable.
 
 ## Service: `AgentRegistry` (ctx key: `agents`)
 
-Tracks live agents so UI, hook, and orchestrator plugins can find them without importing the concrete loop package.
+Tracks live agents and carries the initiating Agent through asynchronous driver work without importing the concrete loop package.
 
 ### Public API
 
@@ -17,6 +17,17 @@ The scoped-registration surface: `Agent.ctx` is the agent's scope context (`dsh-
 - `ctx.agents.list(): Agent[]`
 - `ctx.agents.roots(): Agent[]` — live agents created without an owning agent context; a resumed lineage-bearing session can still be a runtime root.
 
+#### Initiating Agent scope
+
+`AgentLoop` runs each concrete driver's complete lifetime inside an initiator boundary. Concurrent drivers remain isolated: a child driver's continuations carry the child, while the parent continuation regains the parent as soon as `withInitiator()` returns; drain tracking continues until the child driver's Promise settles. Creation, persistence load, and unpublished setup remain outside the child's boundary, so setup initiated by a parent inherits the parent while `agentCtx.agent` identifies the child explicitly.
+
+- `ctx.agents.currentInitiator(): Agent | undefined` — read the inherited initiator without requiring one.
+- `ctx.agents.requireInitiator(): Agent` — read it or throw `no initiating agent is active`.
+- `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. 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)
 
 Agent *creation* is provided by the plugin implementing `AgentFactory` (`dsh-agent-loop`), registered via `setFactory`. This keeps creation on the `dsh-agent` interface so consumers (UI, the ACP bridge) program against `ctx.agents` without depending on the concrete loop package. The registry canonicalizes an already traced Service to its concrete target and re-traces each call through the caller's context; this avoids nested Cordis shadows while passing an explicit caller-bound `ownerCtx` to plain factories.
@@ -72,6 +83,8 @@ The handle every plugin programs against:
 
 ## Known Limitations and Deferred Work
 
+- **Initiator scope is process-local** — workers, child processes, HTTP, durable queues, and restarts materialize any required identity explicitly.
+- **Ambient identity may outlive liveness** — consumers still check `agent.status`, cancellation, and the owning capability contract before lifecycle-sensitive work.
 - **Inter-agent channels beyond delegation** — shared state, streaming child output, and background/poll semantics remain outside the current synchronous `ctx.subagents` seam.
 - **`agent/session-start` cannot gate startup** — it remains a synchronous, veto-less notification; async composition that must finish before publication belongs in the factory's `setup(agentCtx)` transaction instead.
 - **No public step-only abort** — `cancel()` clears ALL pending work (queued + steering + in-flight); an abort that preserves queued prompts returns only with a named consumer ([stop-surface RFC](../../../docs/rfc/implemented/simplification/2026-06-20-public-agent-stop-surface.md)).
diff --git a/packages/core/agent/package.json b/packages/core/agent/package.json
index 72cd18942e..bcf75ea7ca 100644
--- a/packages/core/agent/package.json
+++ b/packages/core/agent/package.json
@@ -1,6 +1,6 @@
 {
   "name": "@deepseek-ai/dsh-agent",
-  "description": "Agent interface, registry, and event vocabulary for the DeepSeek Harness",
+  "description": "Agent interface, registry, initiator scope, and event vocabulary for the DeepSeek Harness",
   "version": "0.0.1",
   "private": true,
   "type": "module",
diff --git a/packages/core/agent/src/index.ts b/packages/core/agent/src/index.ts
index 8a9ed68ab6..75f00daebb 100644
--- a/packages/core/agent/src/index.ts
+++ b/packages/core/agent/src/index.ts
@@ -1,11 +1,14 @@
 /**
- * Agent registry service. Tracks live agents so plugins can find them without
- * depending on the concrete loop package. Agent creation belongs to the loop.
+ * Agent service: live registry, factory delegation, and process-local
+ * initiator scope. Concrete creation and driving belong to the loop.
  *
  * @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'
 import type { Scoped } from '@deepseek-ai/dsh-scope'
 import type { SessionEvent, SessionId } from '@deepseek-ai/dsh-session'
@@ -173,6 +176,8 @@ export interface AgentFactory {
 
 /** Thrown when create/resume is called before an agent factory is registered. */
 const NO_FACTORY_MESSAGE = 'no agent factory registered (load an agent-loop plugin)'
+const NO_INITIATOR_MESSAGE = 'no initiating agent is active'
+const DISPOSED_INITIATOR_MESSAGE = 'agent initiator scope is disposed'
 
 /** All mutable lifecycle state for one exact registry entry. */
 interface AgentEntry {
@@ -186,21 +191,38 @@ 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
 }
 
 /**
- * Agent registry (`ctx.agents`): tracks live agents so UI, hook, and
- * orchestrator plugins can find them without depending on the concrete loop
- * package. Agent *creation* is provided by whichever plugin implements the
- * {@link AgentFactory} (`@deepseek-ai/dsh-agent-loop`), registered via
- * {@link setFactory}.
+ * 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 {@link AgentFactory}
+ * (`@deepseek-ai/dsh-agent-loop`), registered via {@link setFactory}.
+ *
+ * Initiator methods provide same-process causal attribution only. Ambient
+ * presence is neither liveness proof nor authorization; subjects and owners
+ * remain explicit, as does identity at worker, process, persistence, and wire
+ * boundaries. Returned Promise boundaries drain during teardown, except a
+ * nested lineage that starts an owning-fiber unload is excluded from its own drain.
  */
 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
+  private initiatorDisposal: Promise<void> | undefined
 
   constructor(ctx: Context) {
     super(ctx, 'agents')
@@ -211,6 +233,75 @@ 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() }
+    }.bind(this), 'agents.initiatorLifecycle()')
+  }
+
+  /**
+   * Read the Agent that initiated the inherited asynchronous driver chain.
+   * Use this optional form for logging, tracing, metrics, or host attribution
+   * that also supports agentless calls. When a parent creates a child, setup
+   * reports the causal parent while `agentCtx.agent` identifies the child.
+   * @returns the inherited Agent, or `undefined` outside an initiator boundary
+   *   and inside an explicit clearing boundary.
+   * @throws when this service instance has been disposed.
+   */
+  currentInitiator(): Agent | undefined {
+    this.assertInitiatorsReadable()
+    return this.initiators.getStore()
+  }
+
+  /**
+   * Read the initiating Agent and fail when no initiator boundary is active.
+   * Use this for private helpers contractually below a driver, or for a
+   * deployment-owned outbound request whose contract forbids agentless calls.
+   * Generic or direct-call seams use optional lookup or explicit request fields.
+   * @returns the inherited Agent.
+   * @throws when no initiator is active or this service instance has been disposed.
+   */
+  requireInitiator(): Agent {
+    const agent = this.currentInitiator()
+    if (agent === undefined) throw new Error(NO_INITIATOR_MESSAGE)
+    return 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.
+   * Custom drivers and test harnesses wrap their complete returned foreground
+   * lifetime.
+   * A queue or wire receiver may establish this boundary only after validating
+   * explicit identity and resolving the exact live Agent; this method does neither.
+   * Detached work remains owned by the subsystem that starts it.
+   * @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`.
+   * @throws when the initiator scope is closing/disposed, or when `operation` throws.
+   */
+  withInitiator<T>(agent: Agent, operation: () => T): T {
+    return this.runWithInitiator(agent, operation)
+  }
+
+  /**
+   * Run an operation inside a boundary that hides any inherited initiating
+   * Agent. The exact synchronous value or Promise is preserved.
+   * Use this while creating lazy shared timers, queue pumps, pool maintenance,
+   * watchers, or exporters so they do not inherit the first Agent that happens
+   * to initialize them. It clears only initiator attribution, not explicit
+   * fields, and does not own or drain detached resources.
+   * @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.
+   */
+  withoutInitiator<T>(operation: () => T): T {
+    return this.runWithInitiator(undefined, operation)
   }
 
   /**
@@ -471,6 +562,92 @@ export class AgentRegistry extends Service {
       .filter(entry => entry.owner === undefined)
       .map(entry => entry.agent)
   }
+
+  /** Reject new initiator boundaries while inherited continuations drain. */
+  private closeInitiators(): void {
+    if (this.initiatorState === 'active') this.initiatorState = 'closing'
+  }
+
+  /** Wait for returned-Promise boundaries, then invalidate retained references. */
+  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.initiatorRuns.run(run, () => this.initiators.run(agent, operation))
+    } catch (error: unknown) {
+      this.releaseInitiatorRun(run)
+      throw error
+    }
+    if (isPromise(result)) {
+      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(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)
+  }
+
+  /** 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()
+    this.initiatorDrain = undefined
+  }
 }
 
 export default AgentRegistry
diff --git a/packages/core/agent/tests/agent-initiator.spec.ts b/packages/core/agent/tests/agent-initiator.spec.ts
new file mode 100644
index 0000000000..7e0b70d13c
--- /dev/null
+++ b/packages/core/agent/tests/agent-initiator.spec.ts
@@ -0,0 +1,265 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { runInNewContext } from 'node:vm'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import type { Agent } from '@deepseek-ai/dsh-agent'
+import { SessionId } from '@deepseek-ai/dsh-session'
+
+function agent(id: string): Agent {
+  return { id: SessionId(id) } as Agent
+}
+
+async function harness(): Promise<{
+  ctx: Context
+  service: AgentRegistry
+  dispose: () => Promise<void>
+}> {
+  const ctx = new Context()
+  const fiber = await ctx.plugin(AgentRegistry)
+  return {
+    ctx,
+    service: ctx.agents,
+    dispose: fiber.dispose,
+  }
+}
+
+/** 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()
+    expect(service.currentInitiator()).toBeUndefined()
+    expect(() => service.requireInitiator()).toThrow('no initiating agent is active')
+    await dispose()
+  })
+
+  it('preserves exact synchronous and Promise return identities across await', async () => {
+    const { service, dispose } = await harness()
+    const initiator = agent('identity')
+    const value = { result: true }
+    expect(service.withInitiator(initiator, () => {
+      expect(service.requireInitiator()).toBe(initiator)
+      return value
+    })).toBe(value)
+
+    const promise = service.withInitiator(initiator, async () => {
+      expect(service.requireInitiator()).toBe(initiator)
+      await Promise.resolve()
+      expect(service.requireInitiator()).toBe(initiator)
+      return value
+    })
+    expect(service.withInitiator(initiator, () => promise)).toBe(promise)
+    await expect(promise).resolves.toBe(value)
+    expect(service.currentInitiator()).toBeUndefined()
+    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')
+    const b = agent('b')
+    const bothStarted = Promise.withResolvers<boolean>()
+    const release = Promise.withResolvers<boolean>()
+    let starts = 0
+    const run = (initiator: Agent): Promise<void> => service.withInitiator(initiator, async () => {
+      expect(service.requireInitiator()).toBe(initiator)
+      starts += 1
+      if (starts === 2) bothStarted.resolve(true)
+      await release.promise
+      expect(service.requireInitiator()).toBe(initiator)
+    })
+
+    const pending = [run(a), run(b)]
+    await bothStarted.promise
+    expect(service.currentInitiator()).toBeUndefined()
+    release.resolve(true)
+    await Promise.all(pending)
+    await dispose()
+  })
+
+  it('restores nested and explicitly cleared boundaries', async () => {
+    const { service, dispose } = await harness()
+    const parent = agent('parent')
+    const child = agent('child')
+
+    service.withInitiator(parent, () => {
+      expect(service.requireInitiator()).toBe(parent)
+      service.withInitiator(child, () => { expect(service.requireInitiator()).toBe(child) })
+      expect(service.requireInitiator()).toBe(parent)
+      service.withoutInitiator(() => {
+        expect(service.currentInitiator()).toBeUndefined()
+        expect(() => service.requireInitiator()).toThrow('no initiating agent is active')
+      })
+      expect(service.requireInitiator()).toBe(parent)
+    })
+    expect(service.currentInitiator()).toBeUndefined()
+    await dispose()
+  })
+
+  it('restores the parent after synchronous throws and rejected operations', async () => {
+    const { service, dispose } = await harness()
+    const parent = agent('parent')
+    const child = agent('child')
+    const syncError = new Error('sync failure')
+    const asyncError = new Error('async failure')
+
+    service.withInitiator(parent, () => {
+      expect(() => service.withInitiator(child, () => { throw syncError })).toThrow(syncError)
+      expect(service.requireInitiator()).toBe(parent)
+    })
+    await expect(service.withInitiator(child, async () => {
+      await Promise.resolve()
+      throw asyncError
+    })).rejects.toBe(asyncError)
+    expect(service.currentInitiator()).toBeUndefined()
+    await dispose()
+  })
+
+  it('stops new boundaries, drains active Promises, and invalidates retained references', async () => {
+    const { ctx, service, dispose } = await harness()
+    const initiator = agent('draining')
+    const release = Promise.withResolvers<boolean>()
+    const pending = service.withInitiator(initiator, async () => {
+      await release.promise
+      expect(service.requireInitiator()).toBe(initiator)
+    })
+    let disposed = false
+    const disposal = dispose().then(() => { disposed = true })
+    await Promise.resolve()
+
+    expect(() => service.withInitiator(initiator, () => 1)).toThrow('agent initiator scope is disposed')
+    expect(() => service.withoutInitiator(() => 1)).toThrow('agent initiator scope is disposed')
+    expect(disposed).toBe(false)
+    expect(ctx.get('agents')).toBeUndefined()
+    release.resolve(true)
+    await pending
+    await disposal
+    expect(() => service.currentInitiator()).toThrow('agent initiator scope is disposed')
+    expect(() => service.requireInitiator()).toThrow('agent initiator scope is disposed')
+  })
+
+  it('drains cross-realm Promise boundaries before disposal', async () => {
+    const { service, dispose } = await harness()
+    const initiator = agent('cross-realm')
+    const release = Promise.withResolvers<boolean>()
+    const operation = runInNewContext(
+      '(async () => { await release; inspect() })',
+      {
+        release: release.promise,
+        inspect: () => { expect(service.requireInitiator()).toBe(initiator) },
+      },
+    ) as () => Promise<void>
+    const pending = service.withInitiator(initiator, operation)
+    expect(pending).not.toBeInstanceOf(Promise)
+
+    let disposed = false
+    const disposal = dispose().then(() => { disposed = true })
+    await Promise.resolve()
+    expect(disposed).toBe(false)
+
+    release.resolve(true)
+    await pending
+    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')
+  })
+})
diff --git a/packages/core/agent/tests/gen-cordis-catalog.spec.ts b/packages/core/agent/tests/gen-cordis-catalog.spec.ts
index 24841c8c8e..23c558bd95 100644
--- a/packages/core/agent/tests/gen-cordis-catalog.spec.ts
+++ b/packages/core/agent/tests/gen-cordis-catalog.spec.ts
@@ -1,5 +1,6 @@
 /**
- * Negative-path tests for the cordis catalog generator (`scripts/gen-cordis-catalog.ts`).
+ * Contract and negative-path tests for the cordis catalog generator
+ * (`scripts/gen-cordis-catalog.ts`).
  */
 
 import { mkdtempSync, mkdirSync, rmSync, writeFileSync } from 'node:fs'
@@ -76,6 +77,33 @@ describe('gen-cordis-catalog collectEvents', () => {
     expect(events[0]?.mode).toBe('parallel')
   })
 
+  it('accepts linked, foundation, generic-parameter, and explicitly exempt signature types', () => {
+    const events = collectEvents(make(
+      '    /**\n     * Carry linked and foundation types.\n     * @param value - the linked value.\n     * @param preset - deployment metadata outside the core catalog.\n     * @param signal - cancellation.\n     * @mode parallel\n     */\n    \'fix/typed\'<T extends SessionEvent>(value: Readonly<T>, preset: PresetSpec, signal: AbortSignal): Promise<T>',
+    ))
+    expect(events).toHaveLength(1)
+    expect(renderEvents(events)).toContain('Types: [SessionEvent](../core-data-structures/core.md)')
+    expect(renderEvents(events)).not.toContain('[PresetSpec]')
+  })
+
+  it('aggregates every unclassified signature type with its source and remediation', () => {
+    const expected = new RegExp([
+      '2 signature type-link coverage violation\\(s\\)',
+      'fix/one',
+      'packages/group/fix/src/index.ts',
+      'MissingOne',
+      'fix/two',
+      'packages/group/fix/src/index.ts',
+      'missingTwo',
+      'Add it to LINK_MAP',
+      'FOUNDATION_TYPE_NAMES',
+      'TYPE_LINK_EXEMPTIONS',
+    ].join('[\\s\\S]*'))
+    expect(() => collectEvents(make(
+      '    /**\n     * First.\n     * @param value - first value.\n     * @mode emit\n     */\n    \'fix/one\'(value: MissingOne): void\n    /**\n     * Second.\n     * @param value - second value.\n     * @mode emit\n     */\n    \'fix/two\'(value: missingTwo): void',
+    ))).toThrow(expected)
+  })
+
   it('hard-errors when an event is missing its @mode tag', () => {
     expect(() => collectEvents(make(
       '    /** No mode here. */\n    \'fix/untagged\'(): void',
@@ -167,6 +195,12 @@ export class FixService {
     expect(renderServices(services)).toContain('```ts cordis-catalog\n/**\n * Do the thing.\n * @param id - which thing to do.\n * @returns the outcome of doing it.\n */\nrun(id: string): string\n\n/** Fire and forget (void needs no @returns). */\npoke(): void')
   })
 
+  it('hard-errors on an unclassified service-method signature type', () => {
+    expect(() => collectServices(makeService(
+      '/** Fixture service. */\nexport class FixService {\n  /**\n   * Use an unknown value.\n   * @param value - the value.\n   */\n  run(value: MissingServiceType): void {}\n}',
+    ))).toThrow(/service method ctx\.fix\.run .* references unclassified type 'MissingServiceType'/)
+  })
+
   it('hard-errors on a public method with no JSDoc at all', () => {
     expect(() => collectServices(makeService(
       '/** Fixture service. */\nexport class FixService {\n  run(id: string): string { return id }\n}',
diff --git a/packages/examples/README.md b/packages/examples/README.md
index 0135b730e2..5703039d94 100644
--- 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.
 
diff --git a/packages/examples/agent-spine-demo/README.md b/packages/examples/agent-spine-demo/README.md
index aa461e90db..409aef5ef2 100644
--- a/packages/examples/agent-spine-demo/README.md
+++ b/packages/examples/agent-spine-demo/README.md
@@ -16,7 +16,7 @@ Read this package for the whole plugin tree and its composition order.
 @deepseek-ai/dsh-tools            registry + guarded pre/around/post/final-result pipeline
 @deepseek-ai/dsh-skill            skill provider registry
 @deepseek-ai/dsh-skill-local      local filesystem skill provider
-@deepseek-ai/dsh-agent            agent registry + agent/* event vocabulary
+@deepseek-ai/dsh-agent            agent registry + initiator scope + agent/* events
 @deepseek-ai/dsh-tasks            generic background-task registry
 @deepseek-ai/dsh-invariants       dev-mode event-contract assertions
 @deepseek-ai/dsh-tool-bash        the model-facing bash schema
diff --git a/packages/examples/cli-demo/README.md b/packages/examples/cli-demo/README.md
new file mode 100644
index 0000000000..c938f6c583
--- /dev/null
+++ 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.
diff --git a/packages/examples/cli-demo/package.json b/packages/examples/cli-demo/package.json
new file mode 100644
index 0000000000..7b035e2524
--- /dev/null
+++ 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"
+  }
+}
diff --git a/packages/examples/cli-demo/src/bin.ts b/packages/examples/cli-demo/src/bin.ts
new file mode 100644
index 0000000000..5b6638ef72
--- /dev/null
+++ 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 */
diff --git a/packages/examples/cli-demo/src/cli.ts b/packages/examples/cli-demo/src/cli.ts
new file mode 100644
index 0000000000..68c9598e6c
--- /dev/null
+++ 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
+}
diff --git a/packages/examples/cli-demo/src/index.ts b/packages/examples/cli-demo/src/index.ts
new file mode 100644
index 0000000000..1308209681
--- /dev/null
+++ 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 })
+}
diff --git a/packages/examples/cli-demo/tests/built-bin.e2e.ts b/packages/examples/cli-demo/tests/built-bin.e2e.ts
new file mode 100644
index 0000000000..25043b40c4
--- /dev/null
+++ 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)
+  })
+})
diff --git a/packages/examples/cli-demo/tests/cli-demo.spec.ts b/packages/examples/cli-demo/tests/cli-demo.spec.ts
new file mode 100644
index 0000000000..343d6184d7
--- /dev/null
+++ 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')
+  })
+})
diff --git a/packages/examples/cli-demo/tests/cli.spec.ts b/packages/examples/cli-demo/tests/cli.spec.ts
new file mode 100644
index 0000000000..fe61a42304
--- /dev/null
+++ 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')
+  })
+})
diff --git a/packages/examples/cli-demo/tsconfig.json b/packages/examples/cli-demo/tsconfig.json
new file mode 100644
index 0000000000..f25b1592ca
--- /dev/null
+++ 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" }
+  ]
+}
diff --git a/packages/examples/cli-demo/tsdown.config.ts b/packages/examples/cli-demo/tsdown.config.ts
new file mode 100644
index 0000000000..e5b164d46f
--- /dev/null
+++ 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,
+})
diff --git a/packages/session-persistence/session-persistence-jsonl/README.md b/packages/session-persistence/session-persistence-jsonl/README.md
index 43f4443107..9fcf537123 100644
--- 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.
diff --git a/packages/session-persistence/session-persistence-jsonl/src/index.ts b/packages/session-persistence/session-persistence-jsonl/src/index.ts
index 0c8a2ee3ef..4e52cb0b9e 100644
--- 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()
     }
diff --git a/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts b/packages/session-persistence/session-persistence-jsonl/tests/jsonl.spec.ts
index 4b279e3c6e..e7dc469132 100644
--- 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)
diff --git a/packages/support/llm-replay/README.md b/packages/support/llm-replay/README.md
index 3272f29b9a..b256ef9a59 100644
--- 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
 
diff --git a/packages/support/loader-smoke/README.md b/packages/support/loader-smoke/README.md
index 04f519b4c1..0b783efc0d 100644
--- 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.
 
diff --git a/packages/support/loader-smoke/src/index.ts b/packages/support/loader-smoke/src/index.ts
index edbe39d8ca..36ab137f32 100644
--- 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 })
   }
diff --git a/packages/support/loader-smoke/tests/fixtures/success.ts b/packages/support/loader-smoke/tests/fixtures/success.ts
index fed57162e2..82a63cdfd3 100644
--- 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,
diff --git a/packages/support/loader-smoke/tests/loader-smoke.spec.ts b/packages/support/loader-smoke/tests/loader-smoke.spec.ts
index b99d810188..e8f6554691 100644
--- 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',
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml
index 6c7e4a3d05..d7649345fc 100644
--- 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':
diff --git a/scripts/doc-budgets.manifest.json b/scripts/doc-budgets.manifest.json
index 3b99ad454a..b4d2bca159 100644
--- a/scripts/doc-budgets.manifest.json
+++ b/scripts/doc-budgets.manifest.json
@@ -6,6 +6,6 @@
   "docs/defensive-patterns.md": 550,
   "docs/testing.md": 960,
   "examples/AGENTS.md": 310,
-  "packages/AGENTS.md": 290,
+  "packages/AGENTS.md": 370,
   "packages/README.md": 760
 }
diff --git a/scripts/doc-typecheck.ts b/scripts/doc-typecheck.ts
index 7549ee982b..34af82b48b 100644
--- a/scripts/doc-typecheck.ts
+++ b/scripts/doc-typecheck.ts
@@ -1,6 +1,6 @@
 /**
  * Typecheck Markdown `ts` fences against the workspace API. `ignore-check` fences are reported as
- * opt-outs; generated catalog fragments and `type-equiv` blocks are skipped here because their
+ * opt-outs; generated catalog fragments and source-equivalence blocks are skipped here because their
  * owning gates verify them. A build-coordinated mode consumes existing declarations without emit.
  */
 
@@ -33,6 +33,7 @@ const KIND_BY_INFO: Record<string, BlockKind> = {
   'ts': 'check',
   'ts ignore-check': 'ignore',
   'ts type-equiv': 'type-equiv',
+  'ts public-api': 'type-equiv',
   'ts cordis-catalog': 'cordis-catalog',
   'ts persistence-catalog': 'persistence-catalog',
   'ts config-catalog': 'config-catalog',
diff --git a/scripts/gen-cordis-api.ts b/scripts/gen-cordis-api.ts
index 5d8a70fba4..7c61b9395d 100644
--- a/scripts/gen-cordis-api.ts
+++ b/scripts/gen-cordis-api.ts
@@ -1,8 +1,9 @@
 /**
  * Generate the model-facing Cordis API data module from the same event/service
- * collector as the documentation catalogs. It emits first-sentence docs, raw
- * signatures, transitive public type shapes, and inherited context entries,
- * without source pointers; output is deterministic and `--check` verifies it.
+ * collector as the documentation catalogs. It emits original declaration
+ * JSDoc, first-sentence summaries, raw signatures, transitive public type
+ * shapes, and inherited context entries, without source pointers; output is
+ * deterministic and `--check` verifies it.
  */
 
 import { globSync, readFileSync, writeFileSync } from 'node:fs'
@@ -88,22 +89,30 @@ function render(): string {
     ' * `pnpm run verify-cordis-api` in doc-sync).',
     ' *',
     ' * The machine-readable cordis API catalog `cordis_inspect` serves to the',
-    ' * model: harness services (summary + public method signatures), harness',
-    ' * events (mode + signature), and the inherited `ctx` surface. Produced by',
+    ' * model: harness services (summary + public method signatures/JSDoc),',
+    ' * harness events (mode + signature/JSDoc), and the inherited `ctx` surface. Produced by',
     ' * the same AST walk as docs/cordis-catalog, so this data and the rendered',
     ' * docs cannot diverge.',
     ' *',
     ' * @module @deepseek-ai/dsh-tool-cordis/api-catalog',
     ' */',
     '',
-    '/** One harness `ctx.<key>` service: its one-line summary and public method signatures. */',
+    '/** One public service method and its source-owned contract. */',
+    'export interface ServiceApiMethod {',
+    '  /** Public method signature with its body stripped. */',
+    '  signature: string',
+    '  /** Original method JSDoc, with only container indentation removed. */',
+    '  jsDoc: string',
+    '}',
+    '',
+    '/** One harness `ctx.<key>` service: its one-line summary and public methods. */',
     'export interface ServiceApiEntry {',
     '  /** The `ctx.<key>` name, e.g. `tools`. */',
     '  key: string',
     '  /** First sentence of the service class JSDoc. */',
     '  summary: string',
-    '  /** Public method signatures, bodies stripped, in source order. */',
-    '  methods: readonly string[]',
+    '  /** Public methods, bodies stripped, in source order. */',
+    '  methods: readonly ServiceApiMethod[]',
     '}',
     '',
     '/** One harness event: its dispatch mode, exact signature, and one-line summary. */',
@@ -114,6 +123,8 @@ function render(): string {
     '  mode: string',
     '  /** The exact listener signature, whitespace-normalized. */',
     '  signature: string',
+    '  /** Original event JSDoc, with only container indentation removed. */',
+    '  jsDoc: string',
     '  /** First sentence of the event JSDoc. */',
     '  summary: string',
     '}',
@@ -145,7 +156,12 @@ function render(): string {
       lines.push('    methods: [],')
     } else {
       lines.push('    methods: [')
-      for (const method of service.methods) lines.push(`      ${quote(method.signature)},`)
+      for (const method of service.methods) {
+        lines.push('      {')
+        lines.push(`        signature: ${quote(method.signature)},`)
+        lines.push(`        jsDoc: ${quote(method.jsDoc)},`)
+        lines.push('      },')
+      }
       lines.push('    ],')
     }
     lines.push('  },')
@@ -161,6 +177,7 @@ function render(): string {
     lines.push(`    name: ${quote(event.name)},`)
     lines.push(`    mode: ${quote(event.mode)},`)
     lines.push(`    signature: ${quote(event.signature)},`)
+    lines.push(`    jsDoc: ${quote(event.jsDoc)},`)
     lines.push(`    summary: ${quote(firstSentence(event.doc))},`)
     lines.push('  },')
   }
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 08f04947da..5176c8e330 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -1,8 +1,8 @@
 /**
  * Generate the Cordis event and service catalogs from static declarations.
- * The walk enforces event modes plus JSDoc parameter/return completeness;
- * inherited Cordis services come from the curated table below. `--check`
- * verifies both committed artifacts.
+ * The walk enforces event modes, JSDoc parameter/return completeness, and
+ * signature type-link coverage; inherited Cordis services come from the
+ * curated table below. `--check` verifies both committed artifacts.
  */
 
 import { globSync, readFileSync, writeFileSync } from 'node:fs'
@@ -20,48 +20,196 @@ const OUT_SERVICES = 'docs/cordis-catalog/services.md'
 const FENCE = 'ts cordis-catalog'
 
 /**
- * One primary core-data-structures page per signature type, shared by the
- * Cordis and config catalogs; union names intentionally do not reuse the
- * type-equivalence manifest's map-symbol entries.
+ * One primary core-data-structures page per project type used by a generated
+ * signature. This stays curated because union names intentionally do not
+ * reuse the type-equivalence manifest's map-symbol entries and some symbols
+ * appear on more than one page.
  */
-// TODO(catalog-type-links): verify or generate link-map coverage.
 export const LINK_MAP: Record<string, string> = {
   Agent: 'core.md',
+  AgentOptions: 'core.md',
+  AgentStatus: 'core.md',
   ContentBlock: 'core.md',
-  Message: 'core.md',
-  MessageSource: 'core.md',
+  ContinuationDecision: 'core.md',
+  ContinuationStop: 'core.md',
   GenerateOptions: 'core.md',
   LlmCallConfig: 'core.md',
+  LlmModelInfo: 'core.md',
+  LlmProviderInfo: 'core.md',
+  Message: 'core.md',
+  MessageSource: 'core.md',
+  PromptDecision: 'core.md',
   SessionEvent: 'core.md',
+  SessionId: 'core.md',
   SessionStartSource: 'core.md',
-  StreamChunk: 'llm-streaming.md',
-  TurnEndReason: 'session.md',
-  ToolDefinition: 'tools.md',
-  ToolExecution: 'tools.md',
-  ToolExecutionMode: 'tools.md',
-  ToolExecutionInput: 'tools.md',
-  ToolExecutionResult: 'tools.md',
-  ToolExecutionToken: 'tools.md',
   ApprovalOutcome: 'approval.md',
   ApprovalPolicy: 'approval.md',
   ApprovalRequest: 'approval.md',
+  ApprovalService: 'approval.md',
   BashExecRequest: 'bash.md',
   BashExecSpec: 'bash.md',
+  BashProcess: 'bash.md',
   BashRunResult: 'bash.md',
-  ConfinedArgv: 'sandbox.md',
-  SandboxMode: 'sandbox.md',
-  SandboxPolicy: 'sandbox.md',
+  DshEnvironment: 'bash.md',
   CodeRunRequest: 'code-runtime.md',
   CodeRunResult: 'code-runtime.md',
+  CompactionResult: 'compaction.md',
+  FileReadOutcome: 'filesystem.md',
+  FsDirEntry: 'filesystem.md',
   FsEditOutcome: 'filesystem.md',
   FsEditRequest: 'filesystem.md',
   FsInfo: 'filesystem.md',
+  FsPathInfo: 'filesystem.md',
+  FsPolicyExec: 'filesystem.md',
   FsTarget: 'filesystem.md',
   FsVersion: 'filesystem.md',
   FsWriteIntent: 'filesystem.md',
   FsWriteOutcome: 'filesystem.md',
-  FsPolicyExec: 'filesystem.md',
-  FileReadOutcome: 'filesystem.md',
+  LlmAdapter: 'llm-streaming.md',
+  LlmService: 'llm-streaming.md',
+  StreamChunk: 'llm-streaming.md',
+  CreateSessionOptions: 'persistence.md',
+  SessionHeader: 'persistence.md',
+  SessionLocation: 'persistence.md',
+  ConfinedArgv: 'sandbox.md',
+  SandboxMode: 'sandbox.md',
+  SandboxPolicy: 'sandbox.md',
+  ScopeKey: 'scope.md',
+  Scoped: 'scope.md',
+  EpochHeader: 'session.md',
+  Session: 'session.md',
+  TurnEndReason: 'session.md',
+  SessionEventReadRequest: 'session-query.md',
+  SessionEventRecord: 'session-query.md',
+  SessionEventTrace: 'session-query.md',
+  SessionEventTraceRequest: 'session-query.md',
+  SessionEventWindow: 'session-query.md',
+  SessionLineageTrace: 'session-query.md',
+  SessionRecord: 'session-query.md',
+  SkillDefinition: 'skills.md',
+  SkillLookupOptions: 'skills.md',
+  SkillProvider: 'skills.md',
+  SkillRegistration: 'skills.md',
+  SkillSummary: 'skills.md',
+  SaveTextSpill: 'spill.md',
+  SpillRef: 'spill.md',
+  SubagentProvider: 'subagent.md',
+  SubagentRun: 'subagent.md',
+  SubagentService: 'subagent.md',
+  SubagentStartRequest: 'subagent.md',
+  AssembleContext: 'system-prompt.md',
+  PromptSection: 'system-prompt.md',
+  SystemPrompt: 'system-prompt.md',
+  ToolProviderResult: 'system-prompt.md',
+  TaskDoneListener: 'tasks.md',
+  TaskId: 'tasks.md',
+  TaskRead: 'tasks.md',
+  TaskSnapshot: 'tasks.md',
+  TaskStart: 'tasks.md',
+  TokenMeasurement: 'token-meter.md',
+  PostToolDecision: 'tools.md',
+  PreToolDecision: 'tools.md',
+  ToolDefinition: 'tools.md',
+  ToolExecution: 'tools.md',
+  ToolExecutionInput: 'tools.md',
+  ToolExecutionMode: 'tools.md',
+  ToolExecutionResult: 'tools.md',
+  ToolExecutionToken: 'tools.md',
+  ToolGuard: 'tools.md',
+  ToolRegistry: 'tools.md',
+  ToolRestriction: 'tools.md',
+  ToolSchema: 'tools.md',
+  AskUserQuestionAnswer: 'user-interaction.md',
+  AskUserQuestionRequest: 'user-interaction.md',
+  UserInteractionProvider: 'user-interaction.md',
+  WebFetchProvider: 'web.md',
+  WebFetchRequest: 'web.md',
+  WebFetchResult: 'web.md',
+  WebSearchProvider: 'web.md',
+  WebSearchRequest: 'web.md',
+  WebSearchResult: 'web.md',
+  WorkflowRun: 'workflow.md',
+  WorkflowRunInfo: 'workflow.md',
+  WorkflowStartRequest: 'workflow.md',
+}
+
+/** TypeScript lib and pinned framework types that have no repository-owned data page. */
+const FOUNDATION_TYPE_NAMES = new Set([
+  'AbortSignal',
+  'AsyncIterable',
+  'Context',
+  'Error',
+  'Pick',
+  'Promise',
+  'Readonly',
+])
+
+/** Project types deliberately documented outside the core-data catalog. */
+const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
+  AgentFactory: 'agent creation seam is owned by packages/core/agent/README.md',
+  AgentHandle: 'agent ownership handle is owned by packages/core/agent/README.md',
+  BashEnvContributor: 'service-local extension type is owned by packages/bash/tool-bash/src/index.ts',
+  BashEnvVariableInfo: 'service-local metadata type is owned by packages/bash/tool-bash/src/index.ts',
+  CompactAgentContext: 'compaction service input is owned by packages/compact/compact/src/index.ts',
+  CreateAgentOptions: 'agent creation contract is owned by packages/core/agent/README.md',
+  PresetOption: 'deployment menu metadata is owned by packages/ui/permission/README.md',
+  PresetSpec: 'deployment preset composition is owned by packages/ui/permission/README.md',
+  PromptAssembly: 'assembly result is owned by packages/core/system-prompt/README.md',
+  ResumeAgentOptions: 'agent resume contract is owned by packages/core/agent/README.md',
+  SessionForkSource: 'service-local fork input is owned by packages/core/session/src/index.ts',
+  SubagentRunEndInfo: 'event-local snapshot is owned by packages/subagent/subagent/src/index.ts',
+  SubagentRunInfo: 'event-local snapshot is owned by packages/subagent/subagent/src/index.ts',
+  WorkflowAgentEndInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
+  WorkflowAgentInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
+  WorkflowResultInfo: 'event-local snapshot is owned by packages/workflow/workflow/src/index.ts',
+}
+
+/** Collect named references from parameter, generic-constraint/default, and return types. */
+function signatureTypeNames(member: ts.MethodSignature | ts.MethodDeclaration, sf: ts.SourceFile): string[] {
+  const declared = new Set(member.typeParameters?.map(parameter => parameter.name.text) ?? [])
+  const referenced = new Set<string>()
+  const visit = (node: ts.Node): void => {
+    if (ts.isTypeReferenceNode(node)) referenced.add(node.typeName.getText(sf))
+    if (ts.isTypeQueryNode(node)) referenced.add(node.exprName.getText(sf))
+    ts.forEachChild(node, visit)
+  }
+  for (const parameter of member.typeParameters ?? []) {
+    if (parameter.constraint) visit(parameter.constraint)
+    if (parameter.default) visit(parameter.default)
+  }
+  for (const parameter of member.parameters) {
+    if (parameter.type) visit(parameter.type)
+  }
+  if (member.type) visit(member.type)
+  return [...referenced].filter(name => !declared.has(name)).sort()
+}
+
+/** Append fail-closed signature type-link violations with actionable ownership choices. */
+function checkTypeLinks(
+  where: string,
+  member: ts.MethodSignature | ts.MethodDeclaration,
+  sf: ts.SourceFile,
+  violations: string[],
+): void {
+  for (const name of signatureTypeNames(member, sf)) {
+    if (Object.hasOwn(LINK_MAP, name)
+      || FOUNDATION_TYPE_NAMES.has(name)
+      || Object.hasOwn(TYPE_LINK_EXEMPTIONS, name)) continue
+    violations.push(
+      `${where} references unclassified type '${name}'. Add it to LINK_MAP with its core-data-structures page, `
+      + 'to FOUNDATION_TYPE_NAMES if TypeScript or Cordis owns it, or to TYPE_LINK_EXEMPTIONS with '
+      + 'the non-catalog documentation owner.',
+    )
+  }
+}
+
+/** Throw one aggregated diagnostic for every unclassified signature type. */
+function reportTypeLinkViolations(gate: string, violations: string[]): void {
+  if (violations.length === 0) return
+  throw new Error(
+    `${gate}: ${violations.length} signature type-link coverage violation(s):\n`
+    + violations.map(violation => `  ${violation}`).join('\n'),
+  )
 }
 
 /** One harness event, extracted from an `interface Events` block. */
@@ -148,6 +296,7 @@ function jsDocText(text: string, sf: ts.SourceFile, node: ts.Node): string {
 export function collectEvents(scanRoot: string = root): EventEntry[] {
   const entries: EventEntry[] = []
   const violations: string[] = []
+  const typeLinkViolations: string[] = []
   for (const rel of globSync('packages/*/*/src/*.ts', { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
     const abs = resolve(scanRoot, rel)
     const text = readFileSync(abs, 'utf8')
@@ -161,6 +310,7 @@ export function collectEvents(scanRoot: string = root): EventEntry[] {
       const { doc, mode } = parseJsDoc(raw)
       const src = pointer(rel, sf, member)
       const where = `event '${name}' (${src})`
+      checkTypeLinks(where, member, sf, typeLinkViolations)
       if (!mode) {
         violations.push(`${where} is missing an @mode tag. Add '@mode emit|waterfall|parallel|serial' to its JSDoc (see AGENTS.md).`)
       }
@@ -185,6 +335,7 @@ export function collectEvents(scanRoot: string = root): EventEntry[] {
     }
   }
   reportViolations('gen-cordis-catalog', violations)
+  reportTypeLinkViolations('gen-cordis-catalog', typeLinkViolations)
   return entries
 }
 
@@ -197,6 +348,7 @@ export function collectEvents(scanRoot: string = root): EventEntry[] {
 export function collectServices(scanRoot: string = root): ServiceEntry[] {
   const entries: ServiceEntry[] = []
   const violations: string[] = []
+  const typeLinkViolations: string[] = []
   for (const rel of globSync('packages/*/*/src/index.ts', { cwd: scanRoot }).map(s => s.split(sep).join('/')).sort()) {
     const abs = resolve(scanRoot, rel)
     const text = readFileSync(abs, 'utf8')
@@ -220,6 +372,7 @@ export function collectServices(scanRoot: string = root): ServiceEntry[] {
         const memberName = member.name.getText(sf)
         if (memberName.startsWith('[')) continue // computed/symbol members
         const where = `service method ctx.${key}.${memberName} (${pointer(rel, sf, member)})`
+        checkTypeLinks(where, member, sf, typeLinkViolations)
         const raw = rawJsDoc(text, member)
         methods.push({ signature: memberSignature(member, sf), jsDoc: jsDocText(text, sf, member) })
         if (!raw) { violations.push(`${where} has no JSDoc.`); continue }
@@ -243,6 +396,7 @@ export function collectServices(scanRoot: string = root): ServiceEntry[] {
     }
   }
   reportViolations('gen-cordis-catalog', violations)
+  reportTypeLinkViolations('gen-cordis-catalog', typeLinkViolations)
   return entries.sort((a, b) => a.key.localeCompare(b.key))
 }
 
diff --git a/scripts/gen-doc-graphs.ts b/scripts/gen-doc-graphs.ts
index 7c698c0cb9..6fe043cb25 100644
--- 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.',
   },
   {
@@ -156,10 +156,10 @@ const SERVICE_ROLES: ServiceRole[] = [
   {
     key: 'agents',
     pkg: 'agent',
-    title: 'Agent registry',
+    title: 'Agent service',
     mode: 'core',
-    consumers: ['agent-loop', 'acp', 'subagent-inprocess', 'stdio-demo', 'invariants'],
-    note: 'Owns live Agent handles and the create/resume factory seam.',
+    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.',
   },
   {
     key: 'agentLoop',
@@ -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',
diff --git a/scripts/gen-website-api.ts b/scripts/gen-website-api.ts
index 0420ad2ff3..480c19779f 100644
--- a/scripts/gen-website-api.ts
+++ b/scripts/gen-website-api.ts
@@ -20,11 +20,12 @@
  * cannot land undocumented without CI going red. Pages are English (the
  * planned zh translation flow arrives separately; see docs/i18n/README.md).
  *
- * Signature fences use the ` ```ts website-api ` info string: doc-typecheck
- * only processes its known info strings, so these bare (non-compilable)
- * signature fragments are skipped there, while VitePress still highlights the
- * `ts` token. The sidebar fragment `website/.vitepress/config/api-sidebar.json`
- * is generated alongside so navigation can never drift from the page set.
+ * Signature fences use the ` ```ts website-api ` info string and retain the
+ * declaration's original source JSDoc. doc-typecheck only processes its known
+ * info strings, so these bare (non-compilable) fragments are skipped there,
+ * while VitePress still highlights the `ts` token. The sidebar fragment
+ * `website/.vitepress/config/api-sidebar.json` is generated alongside so
+ * navigation can never drift from the page set.
  *
  *   `tsx scripts/gen-website-api.ts`          → write pages + sidebar
  *   `tsx scripts/gen-website-api.ts --check`  → exit 1 if committed copies are
@@ -64,6 +65,8 @@ interface MemberDoc {
   heading: string
   /** All overload signature lines (bodies stripped). */
   signatures: string[]
+  /** Original source JSDoc, dedented only from its containing declaration. */
+  jsDoc: string
   /** Description prose, one paragraph per line. */
   doc: string
   /** Parameter name → `@param` text, in declaration order. */
@@ -166,6 +169,20 @@ function load(rel: string): { sf: ts.SourceFile; text: string } {
 // The module-merge walk (cordisModuleBody / eventMembers / serviceClasses) is
 // shared with gen-cordis-catalog.ts via cordis-walk.ts.
 
+/** Original JSDoc with only the source container's indentation removed. */
+function sourceJSDoc(text: string, sf: ts.SourceFile, node: ts.Node): string {
+  const raw = rawJsDoc(text, node)
+  if (raw === '') return ''
+  const { line } = sf.getLineAndCharacterOfPosition(node.getStart(sf))
+  const lineStart = sf.getPositionOfLineAndCharacter(line, 0)
+  const indent = text.slice(lineStart, node.getStart(sf))
+  return raw.split('\n')
+    .map((sourceLine, index) => index > 0 && sourceLine.startsWith(indent)
+      ? sourceLine.slice(indent.length)
+      : sourceLine)
+    .join('\n')
+}
+
 /** Signature text of a member: full text minus body/initializer, whitespace
  * collapsed, trailing semicolon stripped. */
 function signatureOf(member: ts.Node, sf: ts.SourceFile): string {
@@ -219,7 +236,7 @@ function memberDoc(
   const first = group[0]
   if (!first) throw new Error(`gen-website-api: empty member group for ${name}`)
   // Doc from the first overload that carries JSDoc prose.
-  const rawDocs = group.map(m => rawJsDoc(text, m))
+  const rawDocs = group.map(m => sourceJSDoc(text, sf, m))
   const docIndex = rawDocs.findIndex(r => parseJsDoc(r).doc !== '')
   const raw = docIndex === -1 ? '' : (rawDocs[docIndex] ?? '')
   const doc = parseJsDoc(raw).doc
@@ -255,6 +272,7 @@ function memberDoc(
     signatures: (ts.isMethodDeclaration(first) && funcLike.length > 1
       ? funcLike.filter(m => ts.isMethodDeclaration(m) && !m.body)
       : group).map(m => signatureOf(m, sf)),
+    jsDoc: raw,
     doc,
     params,
     returns: returnsText,
@@ -424,8 +442,13 @@ function declPaste(rel: string, symbol: string): { doc: string; code: string; so
   if (matches.length === 0) throw new Error(`gen-website-api: declaration ${symbol} not found in ${rel}`)
   const first = matches[0]
   if (!first) throw new Error(`gen-website-api: declaration ${symbol} not found in ${rel}`)
-  const doc = parseJsDoc(rawJsDoc(text, first)).doc
-  const code = matches.map(s => stripBodies(s, sf).replace(/^export\s+(default\s+)?/, '')).join('\n\n')
+  const firstJSDoc = sourceJSDoc(text, sf, first)
+  const doc = parseJsDoc(firstJSDoc).doc
+  const code = matches.map((statement) => {
+    const jsDoc = sourceJSDoc(text, sf, statement)
+    const declaration = stripBodies(statement, sf).replace(/^export\s+(default\s+)?/, '')
+    return jsDoc === '' ? declaration : `${jsDoc}\n${declaration}`
+  }).join('\n\n')
   return { doc, code, source: pointer(rel, sf, first) }
 }
 
@@ -480,6 +503,8 @@ interface HarnessEvent {
   scope: string
   mode: Mode | null
   signature: string
+  /** Original source event JSDoc, dedented from its module/interface. */
+  jsDoc: string
   doc: string
   params: { name: string; text: string }[]
   source: string
@@ -494,7 +519,7 @@ function collectHarnessEvents(violations: string[]): HarnessEvent[] {
     const body = cordisModuleBody(sf)
     if (!body) continue
     for (const { name, member } of eventMembers(body, sf)) {
-      const raw = rawJsDoc(text, member)
+      const raw = sourceJSDoc(text, sf, member)
       const { doc, mode } = parseJsDoc(raw)
       if (!mode) violations.push(`event '${name}' (${pointer(rel, sf, member)}) is missing @mode.`)
       if (!doc) violations.push(`event '${name}' (${pointer(rel, sf, member)}) has no JSDoc prose.`)
@@ -509,7 +534,7 @@ function collectHarnessEvents(violations: string[]): HarnessEvent[] {
         const tag = tags.get(pname)
         if (tag) params.push({ name: pname, text: tag })
       }
-      events.push({ name, scope: name.split('/')[0] ?? name, mode, signature: signatureOf(member, sf), doc, params, source: pointer(rel, sf, member) })
+      events.push({ name, scope: name.split('/')[0] ?? name, mode, signature: signatureOf(member, sf), jsDoc: raw, doc, params, source: pointer(rel, sf, member) })
     }
   }
   return events.sort((a, b) => a.name.localeCompare(b.name))
@@ -548,6 +573,7 @@ function renderMember(prefix: string, m: MemberDoc): string[] {
   const call = m.heading === '' ? '' : m.heading
   lines.push(`### ${prefix}${m.name}${call}`, '')
   lines.push('```' + FENCE)
+  lines.push(m.jsDoc)
   for (const sig of m.signatures) lines.push(sig)
   lines.push('```', '')
   lines.push(...prose(m.doc), '')
@@ -620,7 +646,7 @@ function renderEventsPage(events: HarnessEvent[]): string {
     for (const e of events.filter(ev => ev.scope === scope)) {
       lines.push(`### ${e.name}`, '')
       lines.push(`**Mode:** \`${e.mode ?? 'unknown'}\``, '')
-      lines.push('```' + FENCE, e.signature, '```', '')
+      lines.push('```' + FENCE, e.jsDoc, e.signature, '```', '')
       lines.push(...prose(e.doc), '')
       if (e.params.length > 0) {
         for (const p of e.params) lines.push(`- \`${p.name}\` — ${unlink(p.text)}`)
@@ -653,6 +679,16 @@ export function generate(): Map<string, string> {
   const events = collectHarnessEvents(violations)
   files.set(`${PAGES_DIR}/harness/events.md`, renderEventsPage(events))
 
+  for (const [rel, content] of files) {
+    if (!rel.endsWith('.md')) continue
+    for (const match of content.matchAll(/^```ts website-api\n([\s\S]*?)\n```$/gm)) {
+      const body = match[1] ?? ''
+      if (!body.startsWith('/**')) {
+        violations.push(`${rel}: a ts website-api fence does not begin with original source JSDoc.`)
+      }
+    }
+  }
+
   reportViolations('gen-website-api', violations)
 
   const sidebar = {
diff --git a/scripts/run-gates.ts b/scripts/run-gates.ts
index 716bdb24ac..f46de4475a 100644
--- 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
diff --git a/scripts/type-equiv.manifest.json b/scripts/type-equiv.manifest.json
index 566bdade7b..831c45e610 100644
--- a/scripts/type-equiv.manifest.json
+++ b/scripts/type-equiv.manifest.json
@@ -1,5 +1,5 @@
 {
-  "comment": "Maps each ` ```ts type-equiv ` block (by doc + declared symbol) to the source declaration and original JSDoc it must match. verify-type-equiv.ts enforces a 1:1 correspondence: every type-equiv block has exactly one entry here, and every entry resolves to exactly one block. Add an entry when you add a type-equiv block; remove it when you remove the block.",
+  "comment": "Maps each ` ```ts type-equiv ` or ` ```ts public-api ` block (by doc + declared symbol + projection) to the source declaration and original JSDoc it must match. Omit projection for the complete declaration; use public-api with a ` ```ts public-api ` block for a body-stripped public class declaration. verify-type-equiv.ts enforces a 1:1 correspondence: every source-equivalence block has exactly one entry here, and every entry resolves to exactly one block. Add an entry when you add a source-equivalence block; remove it when you remove the block.",
   "entries": [
     { "doc": "docs/core-data-structures/core.md", "symbol": "Branded", "source": "packages/util/brand/src/index.ts" },
     { "doc": "docs/core-data-structures/core.md", "symbol": "ContentBlockMap", "source": "packages/llm/llm/src/types.ts" },
@@ -33,6 +33,8 @@
     { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "TokenUsage", "source": "packages/llm/llm/src/types.ts" },
     { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "ContentBlockMap", "source": "packages/llm/llm/src/types.ts" },
     { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "AppIdentity", "source": "packages/llm/llm/src/attribution.ts" },
+    { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "BlockAssembler", "source": "packages/llm/llm/src/assembler.ts", "projection": "public-api" },
+    { "doc": "docs/core-data-structures/llm-streaming.md", "symbol": "LlmAdapter", "source": "packages/llm/llm/src/index.ts", "projection": "public-api" },
 
     { "doc": "docs/core-data-structures/token-meter.md", "symbol": "TokenMeasurement", "source": "packages/llm/token-meter/src/types.ts" },
     { "doc": "docs/core-data-structures/token-meter.md", "symbol": "TokenSurfaceNode", "source": "packages/llm/token-meter/src/types.ts" },
@@ -50,6 +52,7 @@
     { "doc": "docs/core-data-structures/session.md", "symbol": "SessionSurface", "source": "packages/core/session/src/surface.ts" },
     { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceFoldReplacement", "source": "packages/core/session/src/surface.ts" },
     { "doc": "docs/core-data-structures/session.md", "symbol": "SurfaceFoldResult", "source": "packages/core/session/src/surface.ts" },
+    { "doc": "docs/core-data-structures/session.md", "symbol": "Session", "source": "packages/core/session/src/index.ts", "projection": "public-api" },
 
     { "doc": "docs/core-data-structures/persistence.md", "symbol": "SessionHeader", "source": "packages/core/session/src/types.ts" },
     { "doc": "docs/core-data-structures/persistence.md", "symbol": "CreateSessionOptions", "source": "packages/core/session/src/types.ts" },
diff --git a/scripts/verify-type-equiv.ts b/scripts/verify-type-equiv.ts
index 585796206c..d703536f17 100644
--- a/scripts/verify-type-equiv.ts
+++ b/scripts/verify-type-equiv.ts
@@ -1,6 +1,8 @@
 /**
- * Verify every `ts type-equiv` block against the source symbol named by the
- * manifest. Blocks and entries have a one-to-one relationship; comparison
+ * Verify every `ts type-equiv` and `ts public-api` block against the source
+ * symbol named by the manifest. Ordinary entries preserve the complete
+ * declaration; `public-api` entries preserve a class's body-stripped public
+ * declaration. Blocks and entries have a one-to-one relationship; comparison
  * ignores whitespace and non-JSDoc comments but preserves declaration
  * structure and every original JSDoc comment.
  */
@@ -14,23 +16,27 @@ const root = resolve(import.meta.dirname, '..')
 /** Scan doc-typecheck's full Markdown scope so unmanifested blocks also fail. */
 const MARKDOWN_GLOBS = ['README.md', 'docs/**/*.md', 'packages/*/*.md', 'packages/*/*/*.md', 'website/zh-CN/**/*.md']
 
-/** One manifest entry: a documented type-equiv block and its source symbol. */
+/** One manifest entry: a source-equivalence block and its source symbol. */
 interface ManifestEntry {
-  /** Doc file (repo-relative) containing the ` ```ts type-equiv ` block. */
+  /** Doc file (repo-relative) containing the source-equivalence block. */
   doc: string
   /** The declared symbol the block must match (e.g. `SessionEvent`). */
   symbol: string
   /** Source file (repo-relative) that exports the symbol. */
   source: string
+  /** Complete declaration (default), or a body-stripped public class API. */
+  projection?: 'public-api'
 }
 
-/** One extracted ` ```ts type-equiv ` block. */
+/** One extracted ` ```ts type-equiv ` or ` ```ts public-api ` block. */
 interface EquivBlock {
   doc: string
   /** 1-based line of the opening fence (for diagnostics). */
   line: number
   /** Symbol name parsed from the block's declaration. */
   symbol: string
+  /** Complete declaration (default), or a body-stripped public class API. */
+  projection?: 'public-api'
   /** Block body (the pasted declaration). */
   code: string
 }
@@ -58,7 +64,7 @@ function stripExport(code: string): string {
   return code.replace(/^export\s+(default\s+)?/, '')
 }
 
-/** Parse the declared symbol name from a type-equiv block body. */
+/** Parse the declared symbol name from a source-equivalence block body. */
 function blockSymbol(code: string): string | null {
   const sf = ts.createSourceFile('type-equiv.ts', code, ts.ScriptTarget.Latest, /* setParentNodes */ false, ts.ScriptKind.TS)
   for (const stmt of sf.statements) {
@@ -70,12 +76,12 @@ function blockSymbol(code: string): string | null {
   return null
 }
 
-/** Extract every ` ```ts type-equiv ` block from one Markdown file. */
+/** Extract every source-equivalence block from one Markdown file. */
 function extractEquivBlocks(docRel: string): EquivBlock[] {
   const text = readFileSync(resolve(root, docRel), 'utf8')
   const lines = text.split('\n')
   const blocks: EquivBlock[] = []
-  let open: { line: number; body: string[] } | null = null
+  let open: { line: number; body: string[]; projection?: 'public-api' } | null = null
 
   for (let i = 0; i < lines.length; i++) {
     const raw = lines[i] ?? ''
@@ -90,11 +96,22 @@ function extractEquivBlocks(docRel: string): EquivBlock[] {
       if (!symbol) {
         throw new Error(`verify-type-equiv: ${docRel}:${open.line} — type-equiv block has no parseable interface/type/class declaration`)
       }
-      blocks.push({ doc: docRel, line: open.line, symbol, code })
+      blocks.push({
+        doc: docRel,
+        line: open.line,
+        symbol,
+        code,
+        ...(open.projection === undefined ? {} : { projection: open.projection }),
+      })
       open = null
       continue
     }
-    if ((fence[2] ?? '').trim() === 'ts type-equiv') open = { line: i + 1, body: [] }
+    const info = (fence[2] ?? '').trim()
+    if (info === 'ts type-equiv public-api') {
+      throw new Error(`verify-type-equiv: ${docRel}:${i + 1} — use the concise \`ts public-api\` fence`)
+    }
+    if (info === 'ts type-equiv') open = { line: i + 1, body: [] }
+    if (info === 'ts public-api') open = { line: i + 1, body: [], projection: 'public-api' }
   }
   if (open) throw new Error(`verify-type-equiv: ${docRel}:${open.line} — unterminated type-equiv block`)
   return blocks
@@ -127,13 +144,77 @@ function sourceDeclaration(sourceRel: string, symbol: string): string | null {
   return null
 }
 
+/** Leading source JSDoc attached to one declaration or member. */
+function sourceJSDoc(text: string, node: ts.Node): string {
+  return ts.getJSDocCommentsAndTags(node)
+    .filter(ts.isJSDoc)
+    .map(doc => text.slice(doc.pos, doc.end))
+    .join('\n')
+}
+
+/** Whether a class member is part of its public declaration. */
+function isPublicMember(member: ts.ClassElement): boolean {
+  if (ts.isClassStaticBlockDeclaration(member)) return false
+  const name = ts.getNameOfDeclaration(member)
+  if (name && ts.isPrivateIdentifier(name)) return false
+  const modifiers = ts.canHaveModifiers(member) ? ts.getModifiers(member) : undefined
+  return !(modifiers?.some(modifier =>
+    modifier.kind === ts.SyntaxKind.PrivateKeyword
+    || modifier.kind === ts.SyntaxKind.ProtectedKeyword,
+  ) ?? false)
+}
+
+/** Remove an implementation body while retaining the source signature. */
+function bodylessMember(text: string, sf: ts.SourceFile, member: ts.ClassElement): string {
+  const start = member.getStart(sf)
+  let end = member.end
+  if (ts.isConstructorDeclaration(member) || ts.isMethodDeclaration(member)
+    || ts.isGetAccessorDeclaration(member) || ts.isSetAccessorDeclaration(member)) {
+    if (member.body) end = member.body.getStart(sf)
+  }
+  if (ts.isPropertyDeclaration(member) && member.initializer) end = member.initializer.getStart(sf)
+  const signature = text.slice(start, end).trimEnd().replace(/;$/, '').replace(/=\s*$/, '').trimEnd()
+  return `${signature};`
+}
+
+/**
+ * Render a class as an ambient declaration containing only its public fields,
+ * constructor, accessors, and methods. Implementation bodies and private or
+ * protected members are deliberately absent; original class/member JSDoc is
+ * retained so the projection is the source-owned public contract.
+ */
+function sourcePublicApi(sourceRel: string, symbol: string): string | null {
+  const abs = resolve(root, sourceRel)
+  const text = readFileSync(abs, 'utf8')
+  const sf = ts.createSourceFile(abs, text, ts.ScriptTarget.Latest, /* setParentNodes */ true)
+  for (const stmt of sf.statements) {
+    if (!ts.isClassDeclaration(stmt) || stmt.name?.text !== symbol) continue
+    const classDoc = sourceJSDoc(text, stmt)
+    const abstract = stmt.modifiers?.some(modifier => modifier.kind === ts.SyntaxKind.AbstractKeyword) ? 'abstract ' : ''
+    const typeParameters = stmt.typeParameters?.map(parameter => parameter.getText(sf)).join(', ')
+    const heritage = stmt.heritageClauses?.map(clause => clause.getText(sf)).join(' ')
+    const header = `declare ${abstract}class ${symbol}${typeParameters ? `<${typeParameters}>` : ''}${heritage ? ` ${heritage}` : ''} {`
+    const members = stmt.members
+      .filter(isPublicMember)
+      .map((member) => {
+        const jsDoc = sourceJSDoc(text, member)
+        const declaration = bodylessMember(text, sf, member)
+        return jsDoc === '' ? declaration : `${jsDoc}\n${declaration}`
+      })
+    const declaration = [header, ...members.map(member => member.split('\n').map(line => `  ${line}`).join('\n')), '}'].join('\n')
+    return classDoc === '' ? declaration : `${classDoc}\n${declaration}`
+  }
+  return null
+}
+
 const manifestRaw = readFileSync(resolve(root, 'scripts/type-equiv.manifest.json'), 'utf8')
 const manifest = JSON.parse(manifestRaw) as { entries: ManifestEntry[] }
 const entries = manifest.entries
 
-// Key a block/entry by doc + symbol (a symbol may be documented in more than one
-// doc, but at most once per doc).
-const keyOf = (x: { doc: string; symbol: string }): string => `${x.doc}::${x.symbol}`
+// Key a block/entry by doc + symbol + projection. A symbol may be documented in
+// more than one doc, and a doc may carry both complete and projected forms.
+const keyOf = (x: { doc: string; symbol: string; projection?: 'public-api' }): string =>
+  `${x.doc}::${x.symbol}::${x.projection ?? 'declaration'}`
 
 // Collect every type-equiv block across ALL docs in scope — not only the docs
 // the manifest names — so a block in an unmanifested doc is found and reported
@@ -152,7 +233,7 @@ for (const d of [...new Set(entries.map(e => e.doc))]) {
   else if (!docSet.has(d)) errors.push(`manifest references ${d}, which is outside the scanned markdown scope (${MARKDOWN_GLOBS.join(', ')})`)
 }
 
-// Duplicate-block guard: the same symbol twice in one doc is ambiguous.
+// Duplicate-block guard: the same projected symbol twice in one doc is ambiguous.
 const blockByKey = new Map<string, EquivBlock>()
 for (const b of blocks) {
   const k = keyOf(b)
@@ -192,7 +273,9 @@ let verified = 0
 for (const e of entries) {
   const b = blockByKey.get(keyOf(e))
   if (!b) continue // already reported as an orphan entry
-  const decl = sourceDeclaration(e.source, e.symbol)
+  const decl = e.projection === 'public-api'
+    ? sourcePublicApi(e.source, e.symbol)
+    : sourceDeclaration(e.source, e.symbol)
   if (decl === null) {
     errors.push(`symbol ${e.symbol} not found in ${e.source} (manifest entry for ${e.doc})`)
     continue
diff --git a/tsconfig.build.json b/tsconfig.build.json
index 31a42172e4..36d6c6d462 100644
--- 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" },
diff --git a/tsconfig.json b/tsconfig.json
index 9d1a299b1b..59bb4be2ca 100644
--- 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" },
diff --git a/vitest.snapshot.config.ts b/vitest.snapshot.config.ts
index 18127b55ee..fb2e890eb7 100644
--- 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)
diff --git a/website/zh-CN/api/cordis/context.md b/website/zh-CN/api/cordis/context.md
index cc08f4e28a..0fbb2fcc70 100644
--- a/website/zh-CN/api/cordis/context.md
+++ b/website/zh-CN/api/cordis/context.md
@@ -12,6 +12,15 @@ A context is a proxy: normal property reads go through the service resolver, whi
 ### ctx.extend(meta?)
 
 ```ts website-api
+/**
+ * Create a child context with extra metadata on top of the current scope.
+ *
+ * The child prototypally inherits every property of this context; own
+ * properties of `meta` shadow the inherited ones. The parent is not mutated.
+ *
+ * @param meta — own properties (including symbol keys) to define on the child.
+ * @returns a child context inheriting from this one.
+ */
 extend(meta = {}): this
 ```
 
@@ -27,6 +36,18 @@ The child prototypally inherits every property of this context; own properties o
 ### ctx.isolate(name, label?)
 
 ```ts website-api
+/**
+ * Create a child context with an independent service scope for `name`.
+ *
+ * Below the returned context, reads and writes of the service `name`
+ * resolve against the new label instead of the parent's, so a different
+ * implementation can be provided without affecting the parent scope.
+ * Passing the same `label` to two `isolate()` calls joins their scopes.
+ *
+ * @param name — the service name to isolate.
+ * @param label — scope label to join; defaults to a fresh unique symbol.
+ * @returns a child context whose `name` service resolves in the new scope.
+ */
 isolate(name: string, label?: symbol)
 ```
 
@@ -43,6 +64,18 @@ Below the returned context, reads and writes of the service `name` resolve again
 ### ctx.intercept(name, config)
 
 ```ts website-api
+/**
+ * Add service-specific intercept config for plugins started below this
+ * context.
+ *
+ * Plugins loaded under the returned context see `config` merged into the
+ * service's resolved config (ancestor entries first; see
+ * `Service[symbols.resolveConfig]`). The parent context is not affected.
+ *
+ * @param name — the service name whose config to intercept.
+ * @param config — the intercept config to merge for that service.
+ * @returns a child context carrying the additional intercept entry.
+ */
 intercept<K extends InjectKey>(name: K, config: Context[K] extends { [symbols.config]: infer T } ? T : never): this
 intercept(name: string, config: any): this
 ```
@@ -60,6 +93,7 @@ Plugins loaded under the returned context see `config` merged into the service's
 ### ctx.root
 
 ```ts website-api
+/** The root context of the application (every child context shares it). @experimental */
 root: this
 ```
 
@@ -70,6 +104,7 @@ The root context of the application (every child context shares it). @experiment
 ### ctx.baseUrl
 
 ```ts website-api
+/** Base URL used to resolve relative plugin/module specifiers, if the runtime sets one. */
 baseUrl?: string
 ```
 
@@ -80,6 +115,7 @@ Base URL used to resolve relative plugin/module specifiers, if the runtime sets
 ### ctx.events
 
 ```ts website-api
+/** The event bus. Its methods are also mixed onto `ctx` (`ctx.on`, `ctx.emit`, ...). */
 events: EventsService
 ```
 
@@ -90,6 +126,7 @@ The event bus. Its methods are also mixed onto `ctx` (`ctx.on`, `ctx.emit`, ...)
 ### ctx.logger
 
 ```ts website-api
+/** The logging service. Call `ctx.logger(name)` for a named logger. */
 logger: LoggerService
 ```
 
@@ -100,6 +137,7 @@ The logging service. Call `ctx.logger(name)` for a named logger.
 ### ctx.reflect
 
 ```ts website-api
+/** The reflection layer backing the context proxy (`ctx.get`, `ctx.provide`, ...). */
 reflect: ReflectService
 ```
 
@@ -110,6 +148,7 @@ The reflection layer backing the context proxy (`ctx.get`, `ctx.provide`, ...).
 ### ctx.registry
 
 ```ts website-api
+/** The plugin registry. Its methods are mixed onto `ctx` (`ctx.plugin`, `ctx.inject`). */
 registry: RegistryService
 ```
 
@@ -122,6 +161,7 @@ The plugin registry. Its methods are mixed onto `ctx` (`ctx.plugin`, `ctx.inject
 ### Context.effect
 
 ```ts website-api
+/** Symbol key under which a disposer exposes its {@link EffectMeta} diagnostics tree. */
 static readonly effect: unique symbol
 ```
 
@@ -132,6 +172,7 @@ Symbol key under which a disposer exposes its EffectMeta diagnostics tree.
 ### Context.filter
 
 ```ts website-api
+/** Symbol key for a context's listener filter, consulted on every event dispatch. */
 static readonly filter: unique symbol
 ```
 
@@ -142,6 +183,7 @@ Symbol key for a context's listener filter, consulted on every event dispatch.
 ### Context.isolate
 
 ```ts website-api
+/** Symbol key of the isolation map (see the `Context[symbols.isolate]` property). */
 static readonly isolate: unique symbol
 ```
 
@@ -152,6 +194,7 @@ Symbol key of the isolation map (see the `Context[symbols.isolate]` property).
 ### Context.intercept
 
 ```ts website-api
+/** Symbol key of the intercept map (see the `Context[symbols.intercept]` property). */
 static readonly intercept: unique symbol
 ```
 
@@ -162,6 +205,15 @@ Symbol key of the intercept map (see the `Context[symbols.intercept]` property).
 ### Context.is(value)
 
 ```ts website-api
+/**
+ * Returns true for Cordis context proxies and context prototypes.
+ *
+ * Works across realms and across multiple copies of cordis, because the
+ * brand is keyed by a global symbol rather than by `instanceof`.
+ *
+ * @param value — the value to test.
+ * @returns `true` if `value` is a Cordis context, narrowing its type.
+ */
 static is(value: any): value is Context
 ```
 
@@ -179,6 +231,14 @@ Works across realms and across multiple copies of cordis, because the brand is k
 ### ctx.get(name, strict?)
 
 ```ts website-api
+/**
+ * Read a service from the store without the inject requirement.
+ *
+ * @param name — the service name.
+ * @param strict — when `true` (default), only return implementations
+ * whose providing fiber is currently active.
+ * @returns the service value, or `undefined` when not (yet) provided.
+ */
 get<K extends string & keyof this>(name: K, strict?: boolean): undefined | this[K]
 get(name: string, strict?: boolean): any
 ```
@@ -195,6 +255,15 @@ Read a service from the store without the inject requirement.
 ### ctx.set(name, value)
 
 ```ts website-api
+/**
+ * Overwrite a provided service's value.
+ *
+ * Only the fiber that provided the service may set it; setting an
+ * unprovided name throws.
+ *
+ * @param name — the service name.
+ * @param value — the new service value.
+ */
 set<K extends string & keyof this>(name: K, value: undefined | this[K]): void
 set(name: string, value: any): void
 ```
@@ -210,6 +279,18 @@ Only the fiber that provided the service may set it; setting an unprovided name
 ### ctx.provide(name, value)
 
 ```ts website-api
+/**
+ * Register a service implementation owned by the current fiber.
+ *
+ * The service becomes visible to dependents in the same isolation scope
+ * once the fiber is active; it is unregistered (waking dependents) when
+ * the returned disposer runs or the fiber unloads. Throws if the name is
+ * already provided in this scope or declared as an accessor.
+ *
+ * @param name — the service name.
+ * @param value — the service value.
+ * @returns a disposer that unregisters the service.
+ */
 provide<K extends string & keyof this>(name: K, value: undefined | this[K]): () => void
 provide(name: string, value?: any): () => void
 ```
@@ -227,6 +308,15 @@ The service becomes visible to dependents in the same isolation scope once the f
 ### ctx.accessor(name, options)
 
 ```ts website-api
+/**
+ * Define a computed context property backed by get/set hooks.
+ *
+ * The accessor is removed when the current fiber unloads. Throws if the
+ * name is already declared.
+ *
+ * @param name — the context property name.
+ * @param options — the `get` hook and optional `set` hook.
+ */
 accessor(name: string, options: Omit<Property.Accessor, 'type'>): void
 ```
 
@@ -241,6 +331,16 @@ The accessor is removed when the current fiber unloads. Throws if the name is al
 ### ctx.mixin(name, mixins)
 
 ```ts website-api
+/**
+ * Expose selected members of a service directly on `ctx`.
+ *
+ * Each mixed-in key becomes an accessor that forwards to the service
+ * (binding methods to it), so e.g. `ctx.on` forwards to `ctx.events.on`.
+ * Mixins are removed when the current fiber unloads.
+ *
+ * @param name — the context property holding the source service.
+ * @param mixins — keys to forward, or a source-key → ctx-key map.
+ */
 mixin<K extends string & keyof this>(name: K, mixins: (keyof this & keyof this[K])[] | Dict<string>): void
 mixin<T extends {}>(source: T, mixins: (keyof this & keyof T)[] | Dict<string>): void
 ```
diff --git a/website/zh-CN/api/cordis/events.md b/website/zh-CN/api/cordis/events.md
index b56f8096fe..77488b5d24 100644
--- a/website/zh-CN/api/cordis/events.md
+++ b/website/zh-CN/api/cordis/events.md
@@ -7,6 +7,13 @@ The event system mixed into every context. Harness-defined events are cataloged
 ### ctx.parallel(name, ...args)
 
 ```ts website-api
+/**
+ * Dispatch an event, running all listeners concurrently.
+ *
+ * @param name — the event name.
+ * @param args — arguments passed to every listener.
+ * @returns a promise resolving once every listener has settled.
+ */
 parallel<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): Promise<void>
 parallel<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): Promise<void>
 ```
@@ -23,6 +30,12 @@ Dispatch an event, running all listeners concurrently.
 ### ctx.emit(name, ...args)
 
 ```ts website-api
+/**
+ * Dispatch an event synchronously, ignoring listener return values.
+ *
+ * @param name — the event name.
+ * @param args — arguments passed to every listener.
+ */
 emit<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): void
 emit<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): void
 ```
@@ -37,6 +50,13 @@ Dispatch an event synchronously, ignoring listener return values.
 ### ctx.serial(name, ...args)
 
 ```ts website-api
+/**
+ * Dispatch an event, awaiting listeners in order until one bails.
+ *
+ * @param name — the event name.
+ * @param args — arguments passed to each listener.
+ * @returns the first bail value (non-null, non-false, non-undefined), if any.
+ */
 serial<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): Promisify<ReturnType<Events[K]>>
 serial<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): Promisify<ReturnType<Events[K]>>
 ```
@@ -53,6 +73,13 @@ Dispatch an event, awaiting listeners in order until one bails.
 ### ctx.bail(name, ...args)
 
 ```ts website-api
+/**
+ * Dispatch an event, calling listeners in order until one bails.
+ *
+ * @param name — the event name.
+ * @param args — arguments passed to each listener.
+ * @returns the first bail value (non-null, non-false, non-undefined), if any.
+ */
 bail<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): ReturnType<Events[K]>
 bail<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): ReturnType<Events[K]>
 ```
@@ -69,6 +96,16 @@ Dispatch an event, calling listeners in order until one bails.
 ### ctx.waterfall(name, ...args)
 
 ```ts website-api
+/**
+ * Dispatch an event whose last argument is a `next` continuation.
+ *
+ * Each listener wraps the rest of the chain: calling `next()` invokes the
+ * next listener (finally the built-in behavior); not calling it vetoes.
+ *
+ * @param name — the event name.
+ * @param args — listener arguments; the final one is the innermost `next`.
+ * @returns the outermost listener's return value.
+ */
 waterfall<K extends keyof Events>(name: K, ...args: Parameters<Events[K]>): ReturnType<Events[K]>
 waterfall<K extends keyof Events>(thisArg: NoInfer<ThisType<Events[K]>>, name: K, ...args: Parameters<Events[K]>): ReturnType<Events[K]>
 ```
@@ -86,6 +123,14 @@ Each listener wraps the rest of the chain: calling `next()` invokes the next lis
 ### ctx.on(name, listener, options?)
 
 ```ts website-api
+/**
+ * Register an event listener owned by the current fiber.
+ *
+ * @param name — the event name to listen for.
+ * @param listener — called with the dispatch arguments.
+ * @param options — listener options; a boolean is shorthand for `prepend`.
+ * @returns a disposer removing the listener; `true` if it was still registered.
+ */
 on<K extends keyof Events>(name: K, listener: Events[K], options?: boolean | EventOptions): () => boolean
 ```
 
@@ -102,6 +147,14 @@ Register an event listener owned by the current fiber.
 ### ctx.once(name, listener, options?)
 
 ```ts website-api
+/**
+ * Same as `on()`, but the listener disposes itself after its first call.
+ *
+ * @param name — the event name to listen for.
+ * @param listener — called at most once with the dispatch arguments.
+ * @param options — listener options; a boolean is shorthand for `prepend`.
+ * @returns a disposer removing the listener; `true` if it was still registered.
+ */
 once<K extends keyof Events>(name: K, listener: Events[K], options?: boolean | EventOptions): () => boolean
 ```
 
@@ -120,6 +173,7 @@ Same as `on()`, but the listener disposes itself after its first call.
 Options accepted by `ctx.on()` and `ctx.once()`.
 
 ```ts website-api
+/** Options accepted by `ctx.on()` and `ctx.once()`. */
 interface EventOptions {
   /** Add the listener before existing listeners for the same event. */
   prepend?: boolean
@@ -136,6 +190,14 @@ Event dispatch strategy used by the event service.
 `emit` runs synchronous listeners without awaiting them, `parallel` awaits all listeners together, `serial` awaits them in order until one bails, `bail` stops on the first synchronous bail value, and `waterfall` composes listeners around a final `next` callback.
 
 ```ts website-api
+/**
+ * Event dispatch strategy used by the event service.
+ *
+ * `emit` runs synchronous listeners without awaiting them, `parallel` awaits
+ * all listeners together, `serial` awaits them in order until one bails,
+ * `bail` stops on the first synchronous bail value, and `waterfall` composes
+ * listeners around a final `next` callback.
+ */
 type DispatchMode = 'emit' | 'parallel' | 'serial' | 'bail' | 'waterfall'
 ```
 
diff --git a/website/zh-CN/api/cordis/fiber.md b/website/zh-CN/api/cordis/fiber.md
index db93a6d273..f79adbaf20 100644
--- a/website/zh-CN/api/cordis/fiber.md
+++ b/website/zh-CN/api/cordis/fiber.md
@@ -7,6 +7,19 @@ A fiber is one loaded plugin instance: its lifecycle state, validated config, an
 ### ctx.effect(execute, label?)
 
 ```ts website-api
+/**
+ * Register a cleanup-aware effect on this fiber.
+ *
+ * `execute` runs immediately; the disposers it produces are collected and
+ * run (in reverse order) either when the returned disposer is called or
+ * when the fiber unloads, whichever comes first. Calling the disposer twice
+ * is a no-op. Throws `CordisError('INACTIVE_EFFECT')` if the fiber is
+ * already disposed, and `TypeError` if `execute` returns an invalid shape.
+ *
+ * @param execute — the effect body; see {@link Effect} for accepted shapes.
+ * @param label — effect label shown in `getEffects()` diagnostics.
+ * @returns a disposer that tears the effect down and settles once done.
+ */
 effect(execute: () => SyncEffect, label?: string): Disposable<Promise<void>>
 effect(execute: () => Effect, label?: string): AsyncDisposable<Promise<void>>
 ```
@@ -24,6 +37,7 @@ Register a cleanup-aware effect on this fiber.
 ### ctx.fiber
 
 ```ts website-api
+/** The fiber (plugin runtime instance) that owns this context. */
 fiber: Fiber
 ```
 
@@ -41,6 +55,7 @@ A fiber tracks dependency state, validated config, lifecycle effects, and cleanu
 ### fiber.uid
 
 ```ts website-api
+/** Unique id within the registry; 0 for the root fiber, `null` once disposed. */
 public uid: number | null
 ```
 
@@ -51,6 +66,7 @@ Unique id within the registry; 0 for the root fiber, `null` once disposed.
 ### fiber.ctx
 
 ```ts website-api
+/** The context this fiber's plugin runs in (extends the parent context). */
 public readonly ctx: Context
 ```
 
@@ -61,6 +77,7 @@ The context this fiber's plugin runs in (extends the parent context).
 ### fiber.config
 
 ```ts website-api
+/** The validated plugin config (updated by `update()`). */
 public config: any
 ```
 
@@ -71,6 +88,7 @@ The validated plugin config (updated by `update()`).
 ### fiber.state
 
 ```ts website-api
+/** Current lifecycle state; transitions emit `internal/status`. */
 public state
 ```
 
@@ -81,6 +99,7 @@ Current lifecycle state; transitions emit `internal/status`.
 ### fiber.dispose
 
 ```ts website-api
+/** Dispose this fiber: unload the plugin, then settle once cleanup finished. */
 public readonly dispose: () => Promise<void>
 ```
 
@@ -91,6 +110,7 @@ Dispose this fiber: unload the plugin, then settle once cleanup finished.
 ### fiber.store
 
 ```ts website-api
+/** Snapshot of required service implementations while loaded; `undefined` otherwise. */
 public store: Dict<Impl> | undefined
 ```
 
@@ -101,6 +121,7 @@ Snapshot of required service implementations while loaded; `undefined` otherwise
 ### fiber.inertia
 
 ```ts website-api
+/** The in-flight load/unload transition, if one is currently running. */
 public inertia: Promise<void> | undefined
 ```
 
@@ -111,6 +132,7 @@ The in-flight load/unload transition, if one is currently running.
 ### fiber.name
 
 ```ts website-api
+/** The plugin's display name, inherited from the nearest named ancestor, else `'root'`. */
 get name()
 ```
 
@@ -121,6 +143,12 @@ The plugin's display name, inherited from the nearest named ancestor, else `'roo
 ### fiber.assertActive()
 
 ```ts website-api
+/**
+ * Throw if the fiber has already been disposed.
+ *
+ * @returns nothing when the fiber is still active.
+ * @throws {CordisError} `INACTIVE_EFFECT` when the fiber's uid has been cleared.
+ */
 assertActive()
 ```
 
@@ -133,6 +161,19 @@ Throw if the fiber has already been disposed.
 ### fiber.effect(execute, label?)
 
 ```ts website-api
+/**
+ * Register a cleanup-aware effect on this fiber.
+ *
+ * `execute` runs immediately; the disposers it produces are collected and
+ * run (in reverse order) either when the returned disposer is called or
+ * when the fiber unloads, whichever comes first. Calling the disposer twice
+ * is a no-op. Throws `CordisError('INACTIVE_EFFECT')` if the fiber is
+ * already disposed, and `TypeError` if `execute` returns an invalid shape.
+ *
+ * @param execute — the effect body; see {@link Effect} for accepted shapes.
+ * @param label — effect label shown in `getEffects()` diagnostics.
+ * @returns a disposer that tears the effect down and settles once done.
+ */
 effect(execute: () => SyncEffect, label?: string): Disposable<Promise<void>>
 effect(execute: () => Effect, label?: string): AsyncDisposable<Promise<void>>
 ```
@@ -150,6 +191,11 @@ Register a cleanup-aware effect on this fiber.
 ### fiber.getEffects()
 
 ```ts website-api
+/**
+ * Return metadata for currently registered effects.
+ *
+ * @returns one {@link EffectMeta} tree per labeled live effect.
+ */
 getEffects()
 ```
 
@@ -162,6 +208,12 @@ Return metadata for currently registered effects.
 ### fiber.await()
 
 ```ts website-api
+/**
+ * Wait for current lifecycle work and rethrow startup errors.
+ *
+ * @returns this fiber, once it has settled into a stable state.
+ * @throws the config-validation or plugin-startup error, if any.
+ */
 async await()
 ```
 
@@ -174,6 +226,12 @@ Wait for current lifecycle work and rethrow startup errors.
 ### fiber.restart()
 
 ```ts website-api
+/**
+ * Dispose and immediately reload this plugin with its current config.
+ *
+ * @returns a promise resolving once the reload settled.
+ * @throws {CordisError} `INACTIVE_EFFECT` when the fiber is already disposed.
+ */
 async restart()
 ```
 
@@ -186,6 +244,17 @@ Dispose and immediately reload this plugin with its current config.
 ### fiber.update(config, noSave?)
 
 ```ts website-api
+/**
+ * Validate and apply new config, then restart the plugin.
+ *
+ * Runs the `internal/update` waterfall first, so update hooks (and HMR)
+ * can veto or replace the restart.
+ *
+ * @param config — the new raw config; validated before anything restarts.
+ * @param noSave — hint for persistence hooks not to write the change back.
+ * @returns nothing; the restart runs behind the `internal/update` waterfall.
+ * @throws {ValidationError} when the new config fails validation.
+ */
 update(config: any, noSave = false)
 ```
 
@@ -205,6 +274,13 @@ Effect body result accepted by `ctx.effect()` and plugin startup.
 Either a single disposer, a promise of one, or a (possibly async) iterable yielding several — generator effects register each yielded disposer as it is produced.
 
 ```ts website-api
+/**
+ * Effect body result accepted by `ctx.effect()` and plugin startup.
+ *
+ * Either a single disposer, a promise of one, or a (possibly async) iterable
+ * yielding several — generator effects register each yielded disposer as it
+ * is produced.
+ */
 type Effect<T = any> =
   | SyncEffect<T>
   | AsyncEffect<T>
@@ -218,6 +294,12 @@ Function returned by an effect to release resources during disposal.
 Disposers run in reverse registration order when the owning fiber unloads; they may be async, in which case unloading awaits them.
 
 ```ts website-api
+/**
+ * Function returned by an effect to release resources during disposal.
+ *
+ * Disposers run in reverse registration order when the owning fiber unloads;
+ * they may be async, in which case unloading awaits them.
+ */
 type Disposable<T = any> = () => T
 ```
 
@@ -228,6 +310,7 @@ type Disposable<T = any> = () => T
 Tree node used to expose nested effect labels for diagnostics.
 
 ```ts website-api
+/** Tree node used to expose nested effect labels for diagnostics. */
 interface EffectMeta {
   /** Human-readable effect label, e.g. `ctx.on("event")` or `ctx.provide("name")`. */
   label: string
@@ -243,6 +326,7 @@ interface EffectMeta {
 Framework error with a stable machine-readable code.
 
 ```ts website-api
+/** Framework error with a stable machine-readable code. */
 class CordisError extends Error {
   /**
    * @param code — the stable error code; also the default message.
@@ -251,6 +335,7 @@ class CordisError extends Error {
   constructor(public code: CordisError.Code, message?: string)
 }
 
+/** Cordis error code definitions. */
 namespace CordisError {
   export type Code = keyof typeof Code
 
@@ -267,6 +352,7 @@ namespace CordisError {
 Error raised when plugin configuration fails standard-schema validation.
 
 ```ts website-api
+/** Error raised when plugin configuration fails standard-schema validation. */
 class ValidationError extends TypeError {
   name = 'ValidationError'
 
diff --git a/website/zh-CN/api/cordis/registry.md b/website/zh-CN/api/cordis/registry.md
index 55f6d666e5..f91f5a72af 100644
--- a/website/zh-CN/api/cordis/registry.md
+++ b/website/zh-CN/api/cordis/registry.md
@@ -7,6 +7,16 @@ Plugin loading and dependency injection.
 ### ctx.inject(deps, callback)
 
 ```ts website-api
+/**
+ * Run a callback once the requested services are available.
+ *
+ * Shorthand for `ctx.plugin({ inject, apply: callback })`: the callback
+ * is unloaded and re-run whenever a required service changes.
+ *
+ * @param deps — required services, as an array or a name → config map.
+ * @param callback — plugin body called with `(ctx, config)`.
+ * @returns the fiber; awaiting it settles once loading finished.
+ */
 inject(deps: Inject, callback: Plugin.Function<void>): Fiber & PromiseLike<Fiber>
 ```
 
@@ -23,6 +33,14 @@ Shorthand for `ctx.plugin({ inject, apply: callback })`: the callback is unloade
 ### ctx.plugin(plugin, ...args)
 
 ```ts website-api
+/**
+ * Load a plugin in the current context.
+ *
+ * @param plugin — a function, class, or `{ apply }` object plugin.
+ * @param args — the plugin config, validated against its `Config` schema.
+ * @returns the fiber; awaiting it settles once loading finished
+ * (rejecting on config or startup errors).
+ */
 plugin<P extends Plugin>(plugin: P, ...args: Spread<GetPluginConfig<P>>): Fiber & PromiseLike<Fiber>
 ```
 
@@ -40,11 +58,13 @@ Load a plugin in the current context.
 Supported plugin entrypoint shapes.
 
 ```ts website-api
+/** Supported plugin entrypoint shapes. */
 type Plugin<T = any> =
   | Plugin.Function<T>
   | Plugin.Constructor<T>
   | Plugin.Object<T>
 
+/** Types associated with plugin entrypoints and runtime records. */
 namespace Plugin {
   /** Shared metadata understood by the plugin registry and related tooling. */
   export interface Base<T = any> {
@@ -104,8 +124,16 @@ Service dependency declaration accepted by plugins and the `@Inject` decorator.
 Array form requests services without intercept config. Object form maps each service name to optional intercept config for the plugin context.
 
 ```ts website-api
+/**
+ * Service dependency declaration accepted by plugins and the `@Inject`
+ * decorator.
+ *
+ * Array form requests services without intercept config. Object form maps each
+ * service name to optional intercept config for the plugin context.
+ */
 type Inject<M = Dict> = (keyof M)[] | { [K in keyof M]?: M[K] }
 
+/** Utilities for normalizing plugin dependency declarations. */
 namespace Inject {
   /**
    * Convert array/object/class-inherited inject metadata into a plain map.
diff --git a/website/zh-CN/api/cordis/service.md b/website/zh-CN/api/cordis/service.md
index acd43163d6..13aa82a2ca 100644
--- a/website/zh-CN/api/cordis/service.md
+++ b/website/zh-CN/api/cordis/service.md
@@ -12,6 +12,7 @@ Subclasses call `super(ctx, name)` from their constructor. The service is regist
 ### service.name
 
 ```ts website-api
+/** The service name this instance is registered under. */
 public name!: string
 ```
 
@@ -24,6 +25,7 @@ The service name this instance is registered under.
 ### Service.init
 
 ```ts website-api
+/** Symbol key of an instance method run after construction (class plugins). */
 static readonly init: unique symbol
 ```
 
@@ -34,6 +36,7 @@ Symbol key of an instance method run after construction (class plugins).
 ### Service.check
 
 ```ts website-api
+/** Symbol key of the availability predicate passed to `ctx.provide()`. */
 static readonly check: unique symbol
 ```
 
@@ -44,6 +47,7 @@ Symbol key of the availability predicate passed to `ctx.provide()`.
 ### Service.config
 
 ```ts website-api
+/** Symbol key of the phantom intercept-config type parameter. */
 static readonly config: unique symbol
 ```
 
@@ -54,6 +58,7 @@ Symbol key of the phantom intercept-config type parameter.
 ### Service.invoke
 
 ```ts website-api
+/** Symbol key of the call body making a service callable (e.g. `ctx.logger()`). */
 static readonly invoke: unique symbol
 ```
 
@@ -64,6 +69,7 @@ Symbol key of the call body making a service callable (e.g. `ctx.logger()`).
 ### Service.extend
 
 ```ts website-api
+/** Symbol key of the helper deriving an extended service instance. */
 static readonly extend: unique symbol
 ```
 
@@ -74,6 +80,7 @@ Symbol key of the helper deriving an extended service instance.
 ### Service.tracker
 
 ```ts website-api
+/** Symbol key of the tracker metadata used for context tracing. */
 static readonly tracker: unique symbol
 ```
 
@@ -84,6 +91,7 @@ Symbol key of the tracker metadata used for context tracing.
 ### Service.resolveConfig
 
 ```ts website-api
+/** Symbol key of the intercept-config resolution helper below. */
 static readonly resolveConfig: unique symbol
 ```
 
diff --git a/website/zh-CN/api/harness/agent-loop.md b/website/zh-CN/api/harness/agent-loop.md
index 6401898e24..9a43a1ba14 100644
--- a/website/zh-CN/api/harness/agent-loop.md
+++ b/website/zh-CN/api/harness/agent-loop.md
@@ -11,6 +11,15 @@ Concrete agent factory and driver service.
 ### ctx.agentLoop.create(id, options?, meta?)
 
 ```ts website-api
+/**
+ * Create an agent and session under one caller-supplied identity, owned by
+ * the accessing fiber. Constructor-driven config calls mint a fresh combined
+ * id before entering this boundary.
+ * @param id - shared agent/session identity.
+ * @param options - concrete loop options.
+ * @param meta - optional fresh-session workspace metadata.
+ * @returns the published running agent.
+ */
 create(id: SessionId, options: AgentOptions = {}, meta: Pick<SessionHeader, 'cwd'> = {}): Agent
 ```
 
@@ -27,6 +36,12 @@ Create an agent and session under one caller-supplied identity, owned by the acc
 ### ctx.agentLoop.createAgent(ownerCtx, options)
 
 ```ts website-api
+/**
+ * Create an owned agent on a caller-supplied session id.
+ * @param ownerCtx - caller context that structurally owns the transaction.
+ * @param options - identities, session seed/metadata, loop options, setup, and cancellation.
+ * @returns the published handle.
+ */
 async createAgent(ownerCtx: Context, options: CreateAgentOptions): Promise<AgentHandle>
 ```
 
@@ -42,6 +57,12 @@ Create an owned agent on a caller-supplied session id.
 ### ctx.agentLoop.resume(ownerCtx, options)
 
 ```ts website-api
+/**
+ * Resume an owned agent from the configured persistence service.
+ * @param ownerCtx - caller context that owns load, setup, and the live lifecycle.
+ * @param options - persisted identity, loop options, setup, and cancellation.
+ * @returns the published handle.
+ */
 async resume(ownerCtx: Context, options: ResumeAgentOptions): Promise<AgentHandle>
 ```
 
diff --git a/website/zh-CN/api/harness/agents.md b/website/zh-CN/api/harness/agents.md
index 8d6c84cc7a..bba6a7a5d4 100644
--- a/website/zh-CN/api/harness/agents.md
+++ b/website/zh-CN/api/harness/agents.md
@@ -4,13 +4,120 @@
 
 `AgentRegistry` — provided by `@deepseek-ai/dsh-agent`.
 
-Agent registry (`ctx.agents`): tracks live agents so UI, hook, and orchestrator plugins can find them without depending on the concrete loop package. Agent *creation* is provided by whichever plugin implements the AgentFactory (`@deepseek-ai/dsh-agent-loop`), registered via setFactory.
+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.
+Initiator methods provide same-process causal attribution only. Ambient presence is neither liveness proof nor authorization; subjects and owners remain explicit, as does identity at worker, process, persistence, and wire boundaries. Returned Promise boundaries drain during teardown, except a nested lineage that starts an owning-fiber unload is excluded from its own drain.
 
-[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L201)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L217)
+
+### ctx.agents.currentInitiator()
+
+```ts website-api
+/**
+ * Read the Agent that initiated the inherited asynchronous driver chain.
+ * Use this optional form for logging, tracing, metrics, or host attribution
+ * that also supports agentless calls. When a parent creates a child, setup
+ * reports the causal parent while `agentCtx.agent` identifies the child.
+ * @returns the inherited Agent, or `undefined` outside an initiator boundary
+ *   and inside an explicit clearing boundary.
+ * @throws when this service instance has been disposed.
+ */
+currentInitiator(): Agent | undefined
+```
+
+Read the Agent that initiated the inherited asynchronous driver chain. Use this optional form for logging, tracing, metrics, or host attribution that also supports agentless calls. When a parent creates a child, setup reports the causal parent while `agentCtx.agent` identifies the child.
+
+**Returns** the inherited Agent, or `undefined` outside an initiator boundary and inside an explicit clearing boundary.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L256)
+
+### ctx.agents.requireInitiator()
+
+```ts website-api
+/**
+ * Read the initiating Agent and fail when no initiator boundary is active.
+ * Use this for private helpers contractually below a driver, or for a
+ * deployment-owned outbound request whose contract forbids agentless calls.
+ * Generic or direct-call seams use optional lookup or explicit request fields.
+ * @returns the inherited Agent.
+ * @throws when no initiator is active or this service instance has been disposed.
+ */
+requireInitiator(): Agent
+```
+
+Read the initiating Agent and fail when no initiator boundary is active. Use this for private helpers contractually below a driver, or for a deployment-owned outbound request whose contract forbids agentless calls. Generic or direct-call seams use optional lookup or explicit request fields.
+
+**Returns** the inherited Agent.
+
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L269)
+
+### ctx.agents.withInitiator(agent, operation)
+
+```ts website-api
+/**
+ * Run an operation with one exact Agent as its process-local initiator. The
+ * exact synchronous value or Promise returned by the operation is preserved.
+ * Custom drivers and test harnesses wrap their complete returned foreground
+ * lifetime.
+ * A queue or wire receiver may establish this boundary only after validating
+ * explicit identity and resolving the exact live Agent; this method does neither.
+ * Detached work remains owned by the subsystem that starts it.
+ * @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`.
+ * @throws when the initiator scope is closing/disposed, or when `operation` throws.
+ */
+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. Custom drivers and test harnesses wrap their complete returned foreground lifetime. A queue or wire receiver may establish this boundary only after validating explicit identity and resolving the exact live Agent; this method does neither. Detached work remains owned by the subsystem that starts it.
+
+- `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#L288)
+
+### ctx.agents.withoutInitiator(operation)
+
+```ts website-api
+/**
+ * Run an operation inside a boundary that hides any inherited initiating
+ * Agent. The exact synchronous value or Promise is preserved.
+ * Use this while creating lazy shared timers, queue pumps, pool maintenance,
+ * watchers, or exporters so they do not inherit the first Agent that happens
+ * to initialize them. It clears only initiator attribution, not explicit
+ * fields, and does not own or drain detached resources.
+ * @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.
+ */
+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. Use this while creating lazy shared timers, queue pumps, pool maintenance, watchers, or exporters so they do not inherit the first Agent that happens to initialize them. It clears only initiator attribution, not explicit fields, and does not own or drain detached resources.
+
+- `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#L303)
 
 ### ctx.agents.setFactory(factory)
 
 ```ts website-api
+/**
+ * Register the agent-creation factory (the loop calls this on construction,
+ * effect-scoped). A traced Cordis service is canonicalized to its concrete
+ * target; each create/resume call is then traced through that caller's
+ * context so ownership follows the caller without stacking proxy layers.
+ * Throws if a factory is already registered. Returns the disposer; on
+ * dispose the factory slot is cleared.
+ * @param factory - the loop-owned factory {@link create}/{@link resume} delegate to.
+ * @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.
+ */
 setFactory(factory: AgentFactory): () => void
 ```
 
@@ -20,11 +127,20 @@ 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#L228)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L319)
 
 ### ctx.agents.create(options)
 
 ```ts website-api
+/**
+ * Create and publish a new agent through the registered factory.
+ * Distinct from {@link register} (which records an already-constructed
+ * agent): this constructs the agent and its session. Rejects if no factory is
+ * registered or creation/setup fails. The resolved {@link AgentHandle} lets
+ * the owner tear down exactly this agent.
+ * @param options - shared identity, session seed/metadata, and agent options.
+ * @returns the handle after setup, rollback-covered publication, and loop start complete.
+ */
 async create(options: CreateAgentOptions): Promise<AgentHandle>
 ```
 
@@ -34,11 +150,18 @@ 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#L261)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L352)
 
 ### ctx.agents.resume(options)
 
 ```ts website-api
+/**
+ * Load a persisted session and resume an agent on it through the registered
+ * factory. Rejects if no factory is registered; the factory rejects if
+ * session persistence is not configured or persistence/setup fails.
+ * @param options - persisted identity, configuration, and optional setup.
+ * @returns the handle after setup, rollback-covered publication, and loop start complete.
+ */
 async resume(options: ResumeAgentOptions): Promise<AgentHandle>
 ```
 
@@ -48,11 +171,29 @@ 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#L280)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L371)
 
 ### ctx.agents.register(agent)
 
 ```ts website-api
+/**
+ * Register a live agent. Throws if an agent with the same id is already
+ * registered. Emits `agent/created` on registration and `agent/disposed`
+ * when the calling fiber is disposed — both with the agent's scope carrier
+ * (`scopeTarget(agent, agent)`): the subject is the agent in hand, so the
+ * emits are scope-filtered regardless of which context invoked `register`
+ * (calling through `agent.ctx` scopes EFFECTS; dispatch scoping always
+ * requires passing the carrier). Returns the disposer.
+ * @param agent - the already-constructed agent to record in the store.
+ * @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.
+ */
 register(agent: Agent): () => void
 ```
 
@@ -62,11 +203,26 @@ 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#L306)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L397)
 
 ### ctx.agents.enter(agent, owner)
 
 ```ts website-api
+/**
+ * Insert an already-constructed agent without announcing it. This is the
+ * advanced ordered-lifecycle primitive used by the async agent factory: it
+ * first completes setup while the agent is unpublished, then assigns the
+ * returned detach closure into its pre-installed composite teardown before
+ * calling {@link announce}. Ordinary callers use {@link register}.
+ * @param agent - the prepared, unpublished agent.
+ * @param owner - live agent whose scoped context created this agent, or
+ *   undefined for a top-level runtime root. This is runtime ownership, not
+ *   the resumed session's durable parent lineage.
+ * @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.
+ */
 enter(agent: Agent, owner: Agent | undefined): () => void
 ```
 
@@ -77,11 +233,18 @@ 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#L330)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L421)
 
 ### ctx.agents.announce(agent)
 
 ```ts website-api
+/**
+ * Announce an agent previously inserted with {@link enter}.
+ * @param agent - the live inserted agent to announce.
+ * @throws if `agent` is not the exact live registry entry for its id, or its
+ *   creation announcement already began (including a reentrant call from a
+ *   creation listener).
+ */
 announce(agent: Agent): void
 ```
 
@@ -89,11 +252,16 @@ 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#L405)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L496)
 
 ### ctx.agents.get(id)
 
 ```ts website-api
+/**
+ * Look up a live agent.
+ * @param id - the shared agent/session id to look up.
+ * @returns the agent, or undefined when no live agent has that id.
+ */
 get(id: SessionId): Agent | undefined
 ```
 
@@ -103,11 +271,19 @@ 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#L439)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L530)
 
 ### ctx.agents.isOwnedBy(id, owner)
 
 ```ts website-api
+/**
+ * Test whether a live agent was created through one exact parent agent's
+ * scoped context. Runtime ownership is independent of durable session
+ * lineage and remains unambiguous when unrelated providers reuse an id.
+ * @param id - the candidate child agent's shared agent/session id.
+ * @param owner - the expected runtime creator agent.
+ * @returns true only while the exact child entry is live under that owner.
+ */
 isOwnedBy(id: SessionId, owner: Agent): boolean
 ```
 
@@ -118,11 +294,15 @@ 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#L451)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L542)
 
 ### ctx.agents.list()
 
 ```ts website-api
+/**
+ * All live agents, in registration order.
+ * @returns a fresh array; mutating it does not affect the registry.
+ */
 list(): Agent[]
 ```
 
@@ -130,11 +310,17 @@ 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#L459)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L550)
 
 ### ctx.agents.roots()
 
 ```ts website-api
+/**
+ * All live top-level agents in registration order. A top-level agent was
+ * created without an owning agent context; durable session lineage does not
+ * affect this runtime relation, so a resumed fork may still be a root.
+ * @returns a fresh array; mutating it does not affect the registry.
+ */
 roots(): Agent[]
 ```
 
@@ -142,4 +328,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#L469)
+[Source](https://github.com/deepseek-harness/deepseek-harness/blob/master/packages/core/agent/src/index.ts#L560)
diff --git a/website/zh-CN/api/harness/approval.md b/website/zh-CN/api/harness/approval.md
index fe3b090016..4aa2b8ad2d 100644
--- a/website/zh-CN/api/harness/approval.md
+++ b/website/zh-CN/api/harness/approval.md
@@ -11,6 +11,24 @@ Approval service that applies session policy before answerers and logs every ask
 ### ctx.approval.request(req)
 
 ```ts website-api
+/**
+ * Ask the composed answerers to decide one readonly same-process request.
+ * The service borrows the request, agent, session, and live signal directly.
+ * The request requires an open turn because the audit pair must be enclosed
+ * by the durable log's commit/replay boundary; an idle ask rejects before
+ * appending anything. The answerer phase always produces an outcome: an
+ * aborted signal yields `'cancelled'`, a missing or throwing answerer yields
+ * `'unavailable'` (fail closed), and a rogue non-vocabulary return value is
+ * normalized to `'unavailable'`. A failure that prevents either audit append
+ * from committing still rejects because returning an unlogged decision would
+ * violate the pair. Session contains post-commit observer failures, so an
+ * authoritative append cannot reject the request or suppress its matching
+ * audit event.
+ * @param req - the pending decision (agent, tool identity, reason, signal).
+ * @returns the closed outcome; `'allowed-once'` is the only grant.
+ * @throws when no turn is open or either audit event fails before the session
+ *   append commit point.
+ */
 async request(req: ApprovalRequest): Promise<ApprovalOutcome>
 ```
 
diff --git a/website/zh-CN/api/harness/bash-env.md b/website/zh-CN/api/harness/bash-env.md
index f8baf32bac..906464080e 100644
--- a/website/zh-CN/api/harness/bash-env.md
+++ b/website/zh-CN/api/harness/bash-env.md
@@ -11,6 +11,12 @@ Registry (`ctx.bashEnv`) for trusted, per-execution `DSH_*` variables. The names
 ### ctx.bashEnv.register(contributor)
 
 ```ts website-api
+/**
+ * Register one environment contributor. Names and keys are unique; built-in
+ * keys are reserved. Registration is disposed with the calling plugin fiber.
+ * @param contributor - declared key ownership and per-execution resolver.
+ * @returns the disposer that unregisters the contribution.
+ */
 register(contributor: BashEnvContributor): () => void
 ```
 
@@ -25,6 +31,11 @@ Register one environment contributor. Names and keys are unique; built-in keys a
 ### ctx.bashEnv.collect(execution)
 
 ```ts website-api
+/**
+ * Build the trusted `DSH_*` snapshot for one bash tool execution.
+ * @param execution - the current tool execution.
+ * @returns an immutable environment overlay containing built-ins and current contributions.
+ */
 collect(execution: ToolExecution): DshEnvironment
 ```
 
@@ -39,6 +50,10 @@ Build the trusted `DSH_*` snapshot for one bash tool execution.
 ### ctx.bashEnv.list()
 
 ```ts website-api
+/**
+ * Enumerate plugin-contributed variables without executing their resolvers.
+ * @returns declarations sorted by environment variable name.
+ */
 list(): BashEnvVariableInfo[]
 ```
 
diff --git a/website/zh-CN/api/harness/bash.md b/website/zh-CN/api/harness/bash.md
index c3e4173763..f340697063 100644
--- a/website/zh-CN/api/harness/bash.md
+++ b/website/zh-CN/api/harness/bash.md
@@ -16,6 +16,11 @@ Implementations must honor these semantics:
 ### ctx.bash.sandboxMode
 
 ```ts website-api
+/**
+ * The sandbox mode this executor applies by default, or `undefined` when it
+ * does not sandbox commands.
+ * @returns the configured default sandbox mode, when supported.
+ */
 get sandboxMode(): SandboxMode | undefined
 ```
 
@@ -26,6 +31,12 @@ The sandbox mode this executor applies by default, or `undefined` when it does n
 ### ctx.bash.resolve(request)
 
 ```ts website-api
+/**
+ * Apply implementation-owned defaults and caps to a request before execution.
+ * @param request - the caller's request; omitted fields get this
+ *   implementation's defaults, capped fields are clamped.
+ * @returns the fully-specified spec to hand to {@link run}/{@link start}.
+ */
 abstract resolve(request: BashExecRequest): BashExecSpec
 ```
 
@@ -40,6 +51,12 @@ Apply implementation-owned defaults and caps to a request before execution.
 ### ctx.bash.run(spec)
 
 ```ts website-api
+/**
+ * Run a command in the foreground; resolves when it finishes.
+ * @param spec - a resolved spec from {@link resolve}, never a raw request.
+ * @returns the outcome; nonzero exits, timeout kills, and abort kills
+ *   resolve with a descriptive result rather than reject.
+ */
 abstract run(spec: BashExecSpec): Promise<BashRunResult>
 ```
 
@@ -54,6 +71,11 @@ Run a command in the foreground; resolves when it finishes.
 ### ctx.bash.start(spec)
 
 ```ts website-api
+/**
+ * Start a background process and return its handle immediately.
+ * @param spec - a resolved spec from {@link resolve}, never a raw request.
+ * @returns the live process handle (reads, kill, quiescence promise).
+ */
 abstract start(spec: BashExecSpec): BashProcess
 ```
 
diff --git a/website/zh-CN/api/harness/code-runtime.md b/website/zh-CN/api/harness/code-runtime.md
index ee8300a9f0..fef72ce525 100644
--- a/website/zh-CN/api/harness/code-runtime.md
+++ b/website/zh-CN/api/harness/code-runtime.md
@@ -11,6 +11,13 @@ Registers one `ctx.codeRuntime` implementation. Program, budget, abort, and subs
 ### ctx.codeRuntime.language
 
 ```ts website-api
+/**
+ * The source language {@link run} expects `program` to be written in, as a
+ * lowercase identifier. Informational, not gating — a consumer that
+ * generates language-specific presentation (typed SDK stubs, usage
+ * instructions) switches on it and fails loud on a language it cannot
+ * present. Well-known value: `'typescript'`.
+ */
 abstract readonly language: string
 ```
 
@@ -21,6 +28,12 @@ The source language run expects `program` to be written in, as a lowercase ident
 ### ctx.codeRuntime.isolation
 
 ```ts website-api
+/**
+ * The execution substrate, as a lowercase identifier. Informational, not
+ * gating — a descriptor so deployments and diagnostics can tell backends
+ * apart, not a security claim. Well-known values: `'worker-thread'`,
+ * `'process'`, `'container'`.
+ */
 abstract readonly isolation: string
 ```
 
@@ -31,6 +44,15 @@ The execution substrate, as a lowercase identifier. Informational, not gating 
 ### ctx.codeRuntime.run(request)
 
 ```ts website-api
+/**
+ * Execute one program against the request's bindings and capture what it
+ * emitted. See the class doc for the resolution contract (error is a result
+ * field; rejection means seam misuse only).
+ * @param request - the program, its bindings, and the abort signal; the
+ *   request carries everything the runtime acts on, with no hidden defaults.
+ * @returns the run's outcome: completion value (when transferable), the
+ *   ordered log capture, and the failure (if any).
+ */
 abstract run(request: CodeRunRequest): Promise<CodeRunResult>
 ```
 
diff --git a/website/zh-CN/api/harness/compact.md b/website/zh-CN/api/harness/compact.md
index 67f17cc941..e06188ee27 100644
--- a/website/zh-CN/api/harness/compact.md
+++ b/website/zh-CN/api/harness/compact.md
@@ -11,6 +11,21 @@ Abstract compaction service. Implementations own trigger policy, retention, and
 ### ctx.compact.compactIfNeeded(agent, fullSystemPrompt, sessionPrefix, signal)
 
 ```ts website-api
+/**
+ * Check token pressure and compact if the conversation is too large.
+ * Estimate the next request, including its session prefix, derived history,
+ * and system prompt. Above threshold, compact a head-anchored range ending at
+ * a balanced tool boundary and reconsolidate any prior automatic checkpoint.
+ * Return `null` when no compaction is needed or an open tail leaves no safe
+ * cutoff. A single oversized retained unit or prefix cannot be repaired here.
+ *
+ * @param agent - agent context owning the session surface and model options.
+ * @param fullSystemPrompt - assembled system prompt, counted toward the estimate.
+ * @param sessionPrefix - the instance's composed session prefix, counted toward the
+ *   estimate.
+ * @param signal - cancellation signal; model-backed implementations must forward it.
+ * @returns the compaction result, or `null` if no compaction was needed.
+ */
 abstract compactIfNeeded( agent: CompactAgentContext, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal, ): Promise<CompactionResult | null>
 ```
 
@@ -28,6 +43,23 @@ Check token pressure and compact if the conversation is too large. Estimate the
 ### ctx.compact.compactRegion(start, end, agent, signal?)
 
 ```ts website-api
+/**
+ * Forcibly compact a range of surface nodes into a single summary node.
+ * `start` and `end` name an inclusive span by surface position, not numeric seq
+ * order; replacements can make visible seqs non-monotonic. Both edges must be
+ * balanced so assistant tool calls remain paired with their results. A model-
+ * backed implementation forwards cancellation and rejects active, missing,
+ * reversed, or unbalanced ranges. The target session is `agent.session`.
+ * Use {@link toolPairingBalancedBefore} and {@link toolPairingBalancedAfter}
+ * for the edge checks.
+ *
+ * @param start - first surface seq, inclusive.
+ * @param end - last surface seq, inclusive.
+ * @param agent - context whose session is mutated and whose routing options guide summarization.
+ * @param signal - optional cancellation; model-backed implementations must forward it.
+ * @throws when compaction is active or the range is missing, reversed, or unbalanced.
+ * @returns the appended event seqs, summary, replaced range, and token accounting.
+ */
 abstract compactRegion( start: number, end: number, agent: CompactAgentContext, signal?: AbortSignal, ): Promise<CompactionResult>
 ```
 
diff --git a/website/zh-CN/api/harness/events.md b/website/zh-CN/api/harness/events.md
index 8d494739ba..fcfa426a81 100644
--- a/website/zh-CN/api/harness/events.md
+++ b/website/zh-CN/api/harness/events.md
@@ -11,6 +11,16 @@ Every event the harness packages declare on the cordis event bus (40 total), gro
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * A fully configured agent and live session were published. Setup is
+ * composition-only; `agent/session-start` is the first startup-driving seam.
+ * Synchronous listener failure vetoes publication, while returned-promise
+ * rejection is reported. Detach requested during dispatch waits until every
+ * creation listener has observed the stable entry.
+ * @param agent - the newly registered agent with its live session and completed setup.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
 'agent/created'(this: Scoped<Agent>, agent: Agent): void
 ```
 
@@ -25,6 +35,14 @@ A fully configured agent and live session were published. Setup is composition-o
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * An agent left the registry; AgentLoop emits this after driver quiescence
+ * but before session detachment and scoped-registration unwind. Custom
+ * registry users own their driver-ordering contract.
+ * @param agent - the exact agent removed from the registry.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
 'agent/disposed'(this: Scoped<Agent>, agent: Agent): void
 ```
 
@@ -39,6 +57,16 @@ An agent left the registry; AgentLoop emits this after driver quiescence but bef
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * A step or turn errored. The loop reports a failure here (plus the logger)
+ * even when the error has no in-turn position for a session `error` event.
+ * @param agent - the agent whose turn errored.
+ * @param turn - the turn in which the failure surfaced.
+ * @param step - the step at which the failure surfaced.
+ * @param error - the failure, verbatim.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
 'agent/error'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, error: Error): void
 ```
 
@@ -56,6 +84,22 @@ A step or turn errored. The loop reports a failure here (plus the logger) even w
 **Mode:** `serial`
 
 ```ts website-api
+/**
+ * Awaited serial checkpoint for session-surface mutation after prompt
+ * assembly and before `step/start`; appends land outside the pending step.
+ * The loop derives history once afterward, so compaction records and
+ * replacements are included without rewriting an assembled request. The
+ * prompt and prefix are the exact pressure inputs for that request, and
+ * `signal` cancels listener work.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @param agent - the agent opening the step.
+ * @param turn - the open turn number.
+ * @param step - the pending step number.
+ * @param fullSystemPrompt - the assembled prompt.
+ * @param sessionPrefix - the frozen request prefix.
+ * @param signal - the turn abort signal.
+ * @mode serial
+ */
 'agent/pre-step'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, fullSystemPrompt: string, sessionPrefix: readonly Message[], signal: AbortSignal): Promise<void> | void
 ```
 
@@ -75,6 +119,15 @@ Awaited serial checkpoint for session-surface mutation after prompt assembly and
 **Mode:** `waterfall`
 
 ```ts website-api
+/**
+ * Allow, rewrite, or block one drained prompt before it becomes a user
+ * message. Call `next()` for the unchanged default.
+ * @param agent - the agent draining its inbox.
+ * @param content - the drained message's blocks, as queued.
+ * @param source - the message's resolved source.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode waterfall
+ */
 'agent/prompt-submit'(this: Scoped<Agent>, agent: Agent, content: ContentBlock[], source: MessageSource, next: () => Promise<PromptDecision>): Promise<PromptDecision>
 ```
 
@@ -91,6 +144,15 @@ Allow, rewrite, or block one drained prompt before it becomes a user message. Ca
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * Detached, frozen content entered the agent's inbox. Source defaults have
+ * already been applied, so these are the exact values retained for the log.
+ * @param agent - the agent whose inbox received the message.
+ * @param content - the accepted content blocks retained by the inbox.
+ * @param info - the accepted source plus whether it entered as steering.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
 'agent/queued'(this: Scoped<Agent>, agent: Agent, content: ContentBlock[], info: { source: MessageSource; steering: boolean }): void
 ```
 
@@ -107,6 +169,17 @@ Detached, frozen content entered the agent's inbox. Source defaults have already
 **Mode:** `waterfall`
 
 ```ts website-api
+/**
+ * Replace the frozen call configuration. Model-visible content must use
+ * logged channels; this seam cannot mutate messages. Injection here joins
+ * the next request because the current step boundary is already fixed.
+ * @param agent - the agent making the model call.
+ * @param turn - the open turn number.
+ * @param step - the step whose request this is.
+ * @param config - the config the loop would use (frozen); return a replacement to switch.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode waterfall
+ */
 'agent/request'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, config: LlmCallConfig, next: () => Promise<LlmCallConfig>): Promise<LlmCallConfig>
 ```
 
@@ -124,6 +197,20 @@ Replace the frozen call configuration. Model-visible content must use logged cha
 **Mode:** `waterfall`
 
 ```ts website-api
+/**
+ * Compose request-only messages placed before derived history. The frozen
+ * result is computed once per loop instance, logged on its anchoring request
+ * header, and reused so the provider prefix remains stable. Interrupted
+ * composition is discarded. Composition precedes the first `agent/pre-step`
+ * and request boundary, so listener appends join the current request and
+ * pressure accounting sees the composed prefix. Changing context belongs in
+ * history; contributors should prepend to `await next()` to preserve registration order.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @param agent - the agent whose session prefix is being composed.
+ * @param prefix - the frozen seed; return an extended replacement.
+ * @param signal - aborts composition when the step is torn down.
+ * @mode waterfall
+ */
 'agent/session-prefix'(this: Scoped<Agent>, agent: Agent, prefix: Message[], signal: AbortSignal, next: () => Promise<Message[]>): Promise<Message[]>
 ```
 
@@ -140,6 +227,16 @@ Compose request-only messages placed before derived history. The frozen result i
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * The session lifecycle began, once before the first turn. Use
+ * `agent.inject()` to seed model-facing context. This is a notification, not
+ * a veto; disposal requested by a lifecycle owner is rechecked before the
+ * driver starts.
+ * @param agent - the agent whose session lifecycle began.
+ * @param source - why the session started (fresh startup, resume, …).
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
 'agent/session-start'(this: Scoped<Agent>, agent: Agent, source: SessionStartSource): void
 ```
 
@@ -155,6 +252,14 @@ The session lifecycle began, once before the first turn. Use `agent.inject()` to
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * Agent status changed (`idle` ⇄ `running`, or → `disposed`). `send()` does
+ * not enter `running` synchronously; drive lifecycle from this event.
+ * @param agent - the agent whose status flipped.
+ * @param status - the status just entered (the transition's destination).
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode emit
+ */
 'agent/status'(this: Scoped<Agent>, agent: Agent, status: AgentStatus): void
 ```
 
@@ -170,6 +275,16 @@ Agent status changed (`idle` ⇄ `running`, or → `disposed`). `send()` does no
 **Mode:** `waterfall`
 
 ```ts website-api
+/**
+ * Waterfall: post-process the assembled assistant {@link Message} before
+ * tool dispatch (validation, content rewriting, …).
+ * @param agent - the agent that received the step's response.
+ * @param turn - the open turn number.
+ * @param step - the step that produced the message.
+ * @param message - the assistant message as assembled from the stream.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode waterfall
+ */
 'agent/step-result'(this: Scoped<Agent>, agent: Agent, turn: number, step: number, message: Message, next: () => Promise<Message>): Promise<Message>
 ```
 
@@ -187,6 +302,15 @@ Waterfall: post-process the assembled assistant Message before tool dispatch (va
 **Mode:** `waterfall`
 
 ```ts website-api
+/**
+ * Override whether the turn continues. The default continues after tool
+ * calls or steering and stops otherwise; a continue reason becomes steering.
+ * @param agent - the agent deciding whether to run another step.
+ * @param turn - the turn being continued or stopped.
+ * @param defaultDecision - what the loop would do absent an override.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode waterfall
+ */
 'agent/turn-continuation'(this: Scoped<Agent>, agent: Agent, turn: number, defaultDecision: ContinuationDecision, next: () => Promise<ContinuationDecision>): Promise<ContinuationDecision>
 ```
 
@@ -203,6 +327,15 @@ Override whether the turn continues. The default continues after tool calls or s
 **Mode:** `serial`
 
 ```ts website-api
+/**
+ * Monotonic terminal-stop checkpoint after continuation and steering are
+ * folded; a stop remains authoritative through turn close and flush:
+ * steering queued in that window is discarded, while ordinary sends survive.
+ * @param agent - the agent whose composed continuation outcome may be stopped.
+ * @param turn - the turn at its terminal-stop checkpoint.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @mode serial
+ */
 'agent/turn-stop'(this: Scoped<Agent>, agent: Agent, turn: number): ContinuationStop | undefined
 ```
 
@@ -220,6 +353,15 @@ Monotonic terminal-stop checkpoint after continuation and steering are folded; a
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * A declarative agent entry failed before it could publish a live agent.
+ * Consumers that buffer work for the configured identity use this
+ * transient signal to reject that work instead of waiting forever. Normal
+ * factory teardown suppresses failures from the cancelled startup attempt.
+ * @param sessionId - exact shared agent/session identity that failed startup.
+ * @param error - persistence, setup, or publication failure.
+ * @mode emit
+ */
 'agent-loop/config-start-failed'(sessionId: SessionId, error: unknown): void
 ```
 
@@ -237,6 +379,13 @@ A declarative agent entry failed before it could publish a live agent. Consumers
 **Mode:** `waterfall`
 
 ```ts website-api
+/**
+ * Ask composed answerers for one decision. Return an outcome to claim the
+ * request or call `next()`; failure yields the fail-closed default.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent.
+ * @param req - the pending decision (agent, tool identity, reason, signal).
+ * @mode waterfall
+ */
 'approval/request'(this: Scoped<ApprovalService>, req: ApprovalRequest, next: () => Promise<ApprovalOutcome>): Promise<ApprovalOutcome>
 ```
 
@@ -253,6 +402,13 @@ Ask composed answerers for one decision. Return an outcome to claim the request
 **Mode:** `waterfall`
 
 ```ts website-api
+/**
+ * Single-slot decision for the next {@link FileSystem.editText}. Calling
+ * `next()` yields an unconditional edit; the first returned guard wins.
+ * @param target - the resolved target about to be edited.
+ * @param actor - the opaque tool-execution context the decider keys off.
+ * @mode waterfall
+ */
 'fs/edit-intent'(target: FsTarget, actor: object | undefined, next: () => { version: FsVersion } | undefined | Promise<{ version: FsVersion } | undefined>): Promise<{ version: FsVersion } | undefined>
 ```
 
@@ -268,6 +424,14 @@ Single-slot decision for the next FileSystem.editText. Calling `next()` yields a
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * Record a successful observation. Listeners must be synchronous recorders:
+ * throws fail the tool call and returned promises are not awaited.
+ * @param target - the target that was read/written/edited.
+ * @param version - the version the actor now holds as its observation.
+ * @param actor - the observing tool-execution context; undefined records nothing useful.
+ * @mode emit
+ */
 'fs/observed'(target: FsTarget, version: FsVersion, actor: object | undefined): void
 ```
 
@@ -284,6 +448,14 @@ Record a successful observation. Listeners must be synchronous recorders: throws
 **Mode:** `waterfall`
 
 ```ts website-api
+/**
+ * Single-slot decision for the next {@link FileSystem.writeText}. Calling
+ * `next()` yields the bare provider's unconditional write; the first listener
+ * that returns an intent owns the decision rather than composing with peers.
+ * @param target - the resolved target about to be written.
+ * @param actor - the opaque tool-execution context the decider keys off.
+ * @mode waterfall
+ */
 'fs/write-intent'(target: FsTarget, actor: object | undefined, next: () => FsWriteIntent | undefined | Promise<FsWriteIntent | undefined>): Promise<FsWriteIntent | undefined>
 ```
 
@@ -301,6 +473,17 @@ Single-slot decision for the next FileSystem.writeText. Calling `next()` yields
 **Mode:** `waterfall`
 
 ```ts website-api
+/**
+ * Waterfall around every streaming model call (retry, replay, routing).
+ * Bound to the {@link LlmService}; call `next()` to reach the resolved
+ * adapter's stream, or yield your own chunks to short-circuit.
+ * @param options - the full request. A LOOP-built request arrives
+ *   deep-frozen (mutation throws): its content is a pure function of the
+ *   session log (the reconstructability RFC), so listeners read it, never
+ *   rewrite it. A hand-built one-shot (compaction summarize) is the
+ *   caller's own object and stays mutable here.
+ * @mode waterfall
+ */
 'llm/stream'(this: LlmService, options: GenerateOptions, next: () => AsyncIterable<StreamChunk>): AsyncIterable<StreamChunk>
 ```
 
@@ -317,6 +500,17 @@ Waterfall around every streaming model call (retry, replay, routing). Bound to t
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * Creation announcement during session publication. A synchronous throw vetoes and rolls
+ * back with a paired disposal; detach requested during dispatch is deferred.
+ * A returned-promise rejection is logged but cannot retroactively veto this
+ * synchronous boundary.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners
+ * receive only sessions entered through that agent's context.
+ * @param session - the session just entered and announced.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
 'session/created'(this: Scoped<Session>, session: Session): void
 ```
 
@@ -331,6 +525,15 @@ Creation announcement during session publication. A synchronous throw vetoes and
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * Emitted once when an announced session leaves the store, including
+ * publication rollback, but never for an entry whose creation announcement
+ * did not begin. Listener failures are logged and contained.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`) reuses the owner scope.
+ * @param session - the session that is no longer live in the store.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
 'session/disposed'(this: Scoped<Session>, session: Session): void
 ```
 
@@ -345,6 +548,17 @@ Emitted once when an announced session leaves the store, including publication r
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * Post-commit, fire-and-forget append feed. The listener snapshot resolves
+ * before the log push, but callbacks run after it; observer failures are
+ * logged and contained without making the committed append fail.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners
+ * receive only events from sessions entered through that agent's context.
+ * @param session - the session whose log grew.
+ * @param event - the appended event, exactly as recorded.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
 'session/event'(this: Scoped<Session>, session: Session, event: SessionEvent): void
 ```
 
@@ -360,6 +574,15 @@ Post-commit, fire-and-forget append feed. The listener snapshot resolves before
 **Mode:** `parallel`
 
 ```ts website-api
+/**
+ * Awaited parallel durability checkpoint: every listener runs and the
+ * caller awaits all of them, with no waterfall veto. Dispatch through
+ * {@link SessionStore.flush}. Scope-filtered dispatch
+ * (`@deepseek-ai/dsh-scope`) reuses the session's owner scope.
+ * @param session - the session whose buffered events must reach durable storage.
+ * @dshScopeScan unsupported
+ * @mode parallel
+ */
 'session/flush'(this: Scoped<Session>, session: Session): Promise<void> | void
 ```
 
@@ -376,6 +599,14 @@ Awaited parallel durability checkpoint: every listener runs and the caller await
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * A ready child settled. Scope-filtered dispatch uses the same delegating
+ * parent carrier as `subagent/start`, so the lifecycle pair reaches the
+ * same scoped audience.
+ * @param info - the run identity and terminal outcome.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
 'subagent/end'(this: Scoped<SubagentService>, info: SubagentRunEndInfo): void
 ```
 
@@ -390,6 +621,11 @@ A ready child settled. Scope-filtered dispatch uses the same delegating parent c
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * A provider became resolvable in the registry.
+ * @param provider - the registered provider.
+ * @mode emit
+ */
 'subagent/provider-added'(provider: SubagentProvider): void
 ```
 
@@ -404,6 +640,11 @@ A provider became resolvable in the registry.
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * A provider left the registry. Accepted runs remain holder-owned.
+ * @param name - the provider name that no longer resolves.
+ * @mode emit
+ */
 'subagent/provider-removed'(name: string): void
 ```
 
@@ -418,6 +659,16 @@ A provider left the registry. Accepted runs remain holder-owned.
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * A provider established a ready child. For in-process providers,
+ * `ctx.agents.get(info.id)` resolves during this notification.
+ * Scope-filtered dispatch keys the carrier by the delegating parent, so a
+ * parent-scoped listener observes only its own delegations. Paired with
+ * `subagent/end`.
+ * @param info - the provider and ready child identity.
+ * @dshScopeScan unsupported
+ * @mode emit
+ */
 'subagent/start'(this: Scoped<SubagentService>, info: SubagentRunInfo): void
 ```
 
@@ -434,6 +685,14 @@ A provider established a ready child. For in-process providers, `ctx.agents.get(
 **Mode:** `waterfall`
 
 ```ts website-api
+/**
+ * Expert waterfall over the assembled sections, tools, and variables.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): scoped listeners
+ * receive only that scope's assemblies. The returned value is authoritative.
+ * @param assembly - the mutable assembly built from registered providers.
+ * @param context - the caller's per-assembly context.
+ * @mode waterfall
+ */
 'system-prompt/assemble'(this: Scoped<SystemPrompt>, assembly: PromptAssembly, context: AssembleContext, next: () => Promise<PromptAssembly>): Promise<PromptAssembly>
 ```
 
@@ -449,6 +708,11 @@ Expert waterfall over the assembled sections, tools, and variables. Scope-filter
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * Emitted when any prompt provider changes. This registry notification is
+ * unfiltered because a global change affects every scope.
+ * @mode emit
+ */
 'system-prompt/change'(): void
 ```
 
@@ -463,6 +727,15 @@ Emitted when any prompt provider changes. This registry notification is unfilter
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * A tool was registered or unregistered, or a scoped restriction changed
+ * (the available tool set changed — possibly for one scope only). An
+ * UNFILTERED registry-subject notification, deliberately not scope-filtered
+ * dispatch: a global change concerns every agent's next assembly, so a
+ * scoped listener subscribing here sees every change, not just its own
+ * scope's.
+ * @mode emit
+ */
 'tools/change'(): void
 ```
 
@@ -475,6 +748,14 @@ A tool was registered or unregistered, or a scoped restriction changed (the avai
 **Mode:** `waterfall`
 
 ```ts website-api
+/**
+ * Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns
+ * a normalized result; wrappers may change only `exec.signal`, while call
+ * identity remains immutable.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+ * @param exec - the allowed call about to dispatch (name, parsed arguments, caller agent, signal).
+ * @mode waterfall
+ */
 'tools/execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, next: () => Promise<ToolExecutionResult>): Promise<ToolExecutionResult>
 ```
 
@@ -489,6 +770,14 @@ Around-dispatch waterfall for timeout, retry, or metrics. `next()` returns a nor
 **Mode:** `waterfall`
 
 ```ts website-api
+/**
+ * Accept, replace, enrich, or block a normalized dispatch result. `next()`
+ * accepts it unchanged; thrown tools still reach this seam as errors.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+ * @param exec - the call that just ran (name, parsed arguments, caller agent).
+ * @param result - the dispatch outcome a listener may accept, replace, or block.
+ * @mode waterfall
+ */
 'tools/post-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, result: Readonly<ToolExecutionResult>, next: () => Promise<PostToolDecision>): Promise<PostToolDecision>
 ```
 
@@ -504,6 +793,13 @@ Accept, replace, enrich, or block a normalized dispatch result. `next()` accepts
 **Mode:** `waterfall`
 
 ```ts website-api
+/**
+ * Allow, deny, or ask before dispatch. `next()` delegates to allow; missing
+ * approval support turns `ask` into denial.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): agent-scoped listeners receive only that agent's calls.
+ * @param exec - the pending call (name, parsed arguments, caller agent).
+ * @mode waterfall
+ */
 'tools/pre-execute'(this: Scoped<ToolRegistry>, exec: ToolExecution, next: () => Promise<PreToolDecision>): Promise<PreToolDecision>
 ```
 
@@ -518,6 +814,13 @@ Allow, deny, or ask before dispatch. `next()` delegates to allow; missing approv
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * Observe the frozen, lossless-JSON final outcome. Listener failures are contained.
+ * Scope-filtered dispatch (`@deepseek-ai/dsh-scope`): keyed by `exec.agent`.
+ * @param exec - the execution object that traversed the pipeline.
+ * @param result - a deep-frozen snapshot of the final returned result.
+ * @mode emit
+ */
 'tools/result'(this: Scoped<ToolRegistry>, exec: Readonly<ToolExecution>, result: Readonly<ToolExecutionResult>): undefined
 ```
 
@@ -535,6 +838,16 @@ Observe the frozen, lossless-JSON final outcome. Listener failures are contained
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * One `agent()` call settled (clean result, child failure, or run
+ * cancellation). Paired with {@link Events['workflow/agent-start']} by
+ * `agent.seq`, exactly once per started call on every stop path — on an
+ * engine termination path (a worker killed past its grace) the end is
+ * engine-synthesized with outcome `'cancelled'`.
+ * @param info - the run's identity snapshot.
+ * @param agent - the call identity plus its outcome.
+ * @mode emit
+ */
 'workflow/agent-end'(info: WorkflowRunInfo, agent: WorkflowAgentEndInfo): void
 ```
 
@@ -550,6 +863,15 @@ One `agent()` call settled (clean result, child failure, or run cancellation). P
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * One `agent()` call established a ready child run. Paired with
+ * {@link Events['workflow/agent-end']} by `agent.seq`. A call that never
+ * receives a ready run from the provider emits neither
+ * event in this pair.
+ * @param info - the run's identity snapshot.
+ * @param agent - the call's sequence number, label, phase, and child id.
+ * @mode emit
+ */
 'workflow/agent-start'(info: WorkflowRunInfo, agent: WorkflowAgentInfo): void
 ```
 
@@ -565,6 +887,15 @@ One `agent()` call established a ready child run. Paired with Events['workflow/a
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * A workflow run settled (any stop reason). Fired when
+ * {@link WorkflowRun.result} resolves. Paired with
+ * {@link Events['workflow/start']}.
+ * @param info - the run's identity snapshot.
+ * @param result - the outcome data (stop reason, error, agent count) —
+ *   deliberately WITHOUT the result value (see {@link WorkflowResultInfo}).
+ * @mode emit
+ */
 'workflow/end'(info: WorkflowRunInfo, result: WorkflowResultInfo): void
 ```
 
@@ -580,6 +911,12 @@ A workflow run settled (any stop reason). Fired when WorkflowRun.result resolves
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * The script emitted a narration line (a `log(message)` call).
+ * @param info - the run's identity snapshot.
+ * @param message - the logged message, verbatim.
+ * @mode emit
+ */
 'workflow/log'(info: WorkflowRunInfo, message: string): void
 ```
 
@@ -595,6 +932,13 @@ The script emitted a narration line (a `log(message)` call).
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * The script entered a phase (a `phase(title)` call) — progress grouping
+ * for observers; no execution semantics.
+ * @param info - the run's identity snapshot.
+ * @param title - the phase title, verbatim.
+ * @mode emit
+ */
 'workflow/phase'(info: WorkflowRunInfo, title: string): void
 ```
 
@@ -610,6 +954,12 @@ The script entered a phase (a `phase(title)` call) — progress grouping for obs
 **Mode:** `emit`
 
 ```ts website-api
+/**
+ * A workflow run started — the script's meta block validated, the body
+ * about to execute. Paired with {@link Events['workflow/end']}.
+ * @param info - the run's identity snapshot (id + meta).
+ * @mode emit
+ */
 'workflow/start'(info: WorkflowRunInfo): void
 ```
 
diff --git a/website/zh-CN/api/harness/fs.md b/website/zh-CN/api/harness/fs.md
index 1246bbd27f..aed69681f6 100644
--- a/website/zh-CN/api/harness/fs.md
+++ b/website/zh-CN/api/harness/fs.md
@@ -11,6 +11,15 @@ Abstract filesystem provider. Targets must preserve identity across aliases; rea
 ### ctx.fs.resolve(path, opts?)
 
 ```ts website-api
+/**
+ * Resolve a model/plugin-supplied path into a stable {@link FsTarget}. May perform I/O (a
+ * remote/sandboxed backend may need a round-trip to map a path to a stable identity), hence
+ * async even though the local backend only normalizes + realpaths.
+ *
+ * @param path - the path to resolve; relative paths resolve against `opts.cwd`.
+ * @param opts - optional cwd override and cancellation signal.
+ * @returns the stable target; the same file yields the same `targetKey`.
+ */
 abstract resolve(path: string, opts?: { cwd?: string; signal?: AbortSignal }): Promise<FsTarget>
 ```
 
@@ -26,6 +35,12 @@ Resolve a model/plugin-supplied path into a stable FsTarget. May perform I/O (a
 ### ctx.fs.stat(target, signal?)
 
 ```ts website-api
+/**
+ * Return target metadata, or `undefined` when the target does not exist.
+ * @param target - the resolved target to stat.
+ * @param signal - aborts the metadata round-trip.
+ * @returns metadata only, never content; undefined for an absent target.
+ */
 abstract stat(target: FsTarget, signal?: AbortSignal): Promise<FsInfo | undefined>
 ```
 
@@ -41,6 +56,20 @@ Return target metadata, or `undefined` when the target does not exist.
 ### ctx.fs.lstat(path, opts?, signal?)
 
 ```ts website-api
+/**
+ * Return path metadata without following the final path component when it is a
+ * symbolic link. This is intentionally path-shaped, not target-shaped:
+ * {@link resolve} follows symlinks to produce the stable identity used by
+ * normal reads/writes, while `lstat` lets a consumer reject the path itself
+ * before that follow happens.
+ *
+ * `opts.cwd` follows {@link resolve}'s cwd rules. `undefined` means the path is
+ * absent.
+ * @param path - the path to inspect; relative paths resolve against `opts.cwd`.
+ * @param opts - `cwd` overrides the backend's default base for relative paths.
+ * @param signal - aborts the metadata round-trip.
+ * @returns metadata only, never content; undefined for an absent path.
+ */
 abstract lstat(path: string, opts?: { cwd?: string }, signal?: AbortSignal): Promise<FsPathInfo | undefined>
 ```
 
@@ -58,6 +87,12 @@ Return path metadata without following the final path component when it is a sym
 ### ctx.fs.readText(target, signal?)
 
 ```ts website-api
+/**
+ * Read the whole regular text file as a single decoded string.
+ * @param target - the resolved target to read.
+ * @param signal - aborts the read.
+ * @returns the full decoded UTF-8 content.
+ */
 abstract readText(target: FsTarget, signal?: AbortSignal): Promise<string>
 ```
 
@@ -73,6 +108,15 @@ Read the whole regular text file as a single decoded string.
 ### ctx.fs.streamText(target, signal?)
 
 ```ts website-api
+/**
+ * Stream the whole regular text file as decoded text chunks (same text
+ * semantics as {@link readText}, for large files). The backend owns
+ * cross-chunk UTF-8 decoding and binary rejection so the policy layer never
+ * touches raw bytes.
+ * @param target - the resolved target to read.
+ * @param signal - aborts the stream, including between chunks.
+ * @returns the chunk iterable, decoded and validated like {@link readText}.
+ */
 abstract streamText(target: FsTarget, signal?: AbortSignal): Promise<AsyncIterable<string>>
 ```
 
@@ -88,6 +132,13 @@ Stream the whole regular text file as decoded text chunks (same text semantics a
 ### ctx.fs.listDir(target, signal?)
 
 ```ts website-api
+/**
+ * List direct children of a directory in stable name order. Returns resolved
+ * child targets plus cheap metadata only; never reads file contents.
+ * @param target - the resolved directory target.
+ * @param signal - aborts the listing.
+ * @returns one entry per direct child, in stable name order.
+ */
 abstract listDir(target: FsTarget, signal?: AbortSignal): Promise<FsDirEntry[]>
 ```
 
@@ -103,6 +154,15 @@ List direct children of a directory in stable name order. Returns resolved child
 ### ctx.fs.writeText(target, content, expected?, signal?)
 
 ```ts website-api
+/**
+ * Atomically create or replace UTF-8 text. `expected` guards intent and
+ * staleness; omission allows unconditional overwrite.
+ * @param target - the resolved target to write.
+ * @param content - the full new file content.
+ * @param expected - the write intent guarding the write; omit for unconditional.
+ * @param signal - aborts before the atomic rename takes effect.
+ * @returns the outcome, including the version the write produced.
+ */
 abstract writeText(target: FsTarget, content: string, expected?: FsWriteIntent, signal?: AbortSignal): Promise<FsWriteOutcome>
 ```
 
@@ -120,6 +180,16 @@ Atomically create or replace UTF-8 text. `expected` guards intent and staleness;
 ### ctx.fs.editText(target, edit, expected?, signal?)
 
 ```ts website-api
+/**
+ * Atomically edit literal text. When supplied, the version guard is checked
+ * before matching so stale content reports `FS_STALE_VERSION`; omission edits
+ * the current content without a freshness precondition.
+ * @param target - the resolved target to edit.
+ * @param edit - the literal search/replace request.
+ * @param expected - the version guard; omit for an unconditional edit.
+ * @param signal - aborts before the atomic rename takes effect.
+ * @returns the outcome, including the version the edit produced.
+ */
 abstract editText(target: FsTarget, edit: FsEditRequest, expected?: { version: FsVersion }, signal?: AbortSignal): Promise<FsEditOutcome>
 ```
 
diff --git a/website/zh-CN/api/harness/llm.md b/website/zh-CN/api/harness/llm.md
index a70d5bd478..f762857881 100644
--- a/website/zh-CN/api/harness/llm.md
+++ b/website/zh-CN/api/harness/llm.md
@@ -11,6 +11,14 @@ The abstract `llm` service: an adapter registry plus a streaming model-call surf
 ### ctx.llm.registerAdapter(providers, adapter)
 
 ```ts website-api
+/**
+ * Register an adapter for the given provider routes. Throws `LlmError` with code
+ * `DUPLICATE_ADAPTER` if any provider already has an adapter (all-or-nothing).
+ * Disposed with the fiber.
+ * @param providers - every provider route this adapter should serve.
+ * @param adapter - the adapter that streams calls for those providers.
+ * @returns the disposer that unregisters all of them.
+ */
 registerAdapter(providers: string[], adapter: LlmAdapter): () => void
 ```
 
@@ -26,6 +34,10 @@ Register an adapter for the given provider routes. Throws `LlmError` with code `
 ### ctx.llm.listProviders()
 
 ```ts website-api
+/**
+ * Describe provider routes with a registered adapter.
+ * @returns detached provider metadata in registration order.
+ */
 listProviders(): LlmProviderInfo[]
 ```
 
@@ -38,6 +50,12 @@ Describe provider routes with a registered adapter.
 ### ctx.llm.listModels(provider)
 
 ```ts website-api
+/**
+ * Discover models advertised by one registered provider. Catalog membership
+ * is advisory and never changes routing or request validation.
+ * @param provider - registered provider route to inspect.
+ * @returns detached model metadata in adapter-preferred order.
+ */
 async listModels(provider: string): Promise<LlmModelInfo[]>
 ```
 
@@ -52,6 +70,15 @@ Discover models advertised by one registered provider. Catalog membership is adv
 ### ctx.llm.stream(options)
 
 ```ts website-api
+/**
+ * Stream one model call as raw chunks (token-level deltas). Throws
+ * `LlmError` with code `NO_ADAPTER` if no adapter is registered for
+ * `options.provider`. Replay state is retained only when the same adapter
+ * instance owns its historical provider and the target provider. Dispatches
+ * through the `llm/stream` waterfall.
+ * @param options - the full request; `options.provider` selects the adapter.
+ * @returns the chunk stream, possibly wrapped by `llm/stream` listeners.
+ */
 stream(options: GenerateOptions): AsyncIterable<StreamChunk>
 ```
 
diff --git a/website/zh-CN/api/harness/permission.md b/website/zh-CN/api/harness/permission.md
index fe05ef3a61..c9f99adbf1 100644
--- a/website/zh-CN/api/harness/permission.md
+++ b/website/zh-CN/api/harness/permission.md
@@ -11,6 +11,10 @@ Owns the deployment's permission presets and their write path. Requires a confin
 ### ctx.permission.names
 
 ```ts website-api
+/**
+ * The advertised preset names, in the preset table's declaration order.
+ * @returns every switchable preset name.
+ */
 get names(): readonly string[]
 ```
 
@@ -21,6 +25,13 @@ The advertised preset names, in the preset table's declaration order.
 ### ctx.permission.current(events)
 
 ```ts website-api
+/**
+ * Resolve the preset matching the effective knob values. A still-matching
+ * last selection wins shared-bundle ties; otherwise the first table match
+ * wins, or {@link CUSTOM_PRESET} when no entry matches.
+ * @param events - the session's events in log order.
+ * @returns the effective preset name, or `custom` when nothing matches.
+ */
 current(events: readonly SessionEvent[]): string
 ```
 
@@ -35,6 +46,12 @@ Resolve the preset matching the effective knob values. A still-matching last sel
 ### ctx.permission.resolve(name)
 
 ```ts website-api
+/**
+ * Resolve a preset's knob bundle.
+ * @param name - the preset name to resolve.
+ * @returns the configured bundle.
+ * @throws when `name` is not in the table.
+ */
 resolve(name: string): PresetSpec
 ```
 
@@ -49,6 +66,13 @@ Resolve a preset's knob bundle.
 ### ctx.permission.optionOf(name)
 
 ```ts website-api
+/**
+ * Build the client option for a table entry or {@link CUSTOM_PRESET}. A
+ * missing label falls back to the table key.
+ * @param name - a table key, or `custom`.
+ * @returns the option a client renders.
+ * @throws when `name` is neither a table key nor `custom`.
+ */
 optionOf(name: string): PresetOption
 ```
 
@@ -63,6 +87,12 @@ Build the client option for a table entry or CUSTOM_PRESET. A missing label fall
 ### ctx.permission.set(session, name)
 
 ```ts website-api
+/**
+ * Record a changed preset, then update each changed knob through its own
+ * setter. Selecting the effective preset again appends nothing.
+ * @param session - the session the switch belongs to.
+ * @param name - the preset to switch to; unknown names throw.
+ */
 set(session: Session, name: string): void
 ```
 
diff --git a/website/zh-CN/api/harness/sandbox.md b/website/zh-CN/api/harness/sandbox.md
index bc5b1d38a5..45187e9d31 100644
--- a/website/zh-CN/api/harness/sandbox.md
+++ b/website/zh-CN/api/harness/sandbox.md
@@ -11,6 +11,17 @@ Abstract process-sandbox service. confine must return enforcing argv or fail clo
 ### ctx.sandbox.confine(argv, policy)
 
 ```ts website-api
+/**
+ * Wrap `argv` so it executes confined under `policy` on this host; the
+ * caller spawns the returned argv in place of its own.
+ * @param argv - the exact argv the caller is about to spawn (program plus
+ *   arguments), NOT a shell string — a shell-shaped consumer passes
+ *   `['bash', '-c', command]`.
+ * @param policy - the file-effect policy this execution runs under,
+ *   carried per call (see {@link SandboxPolicy}).
+ * @returns the argv to spawn instead, plus the enforcement completeness
+ *   the selected backend achieves for it.
+ */
 abstract confine(argv: readonly string[], policy: SandboxPolicy): ConfinedArgv
 ```
 
diff --git a/website/zh-CN/api/harness/session-persistence.md b/website/zh-CN/api/harness/session-persistence.md
index e382a2f4a4..f200cb1801 100644
--- a/website/zh-CN/api/harness/session-persistence.md
+++ b/website/zh-CN/api/harness/session-persistence.md
@@ -11,6 +11,13 @@ Durable append-only session storage. Implementations preserve contiguous, lossle
 ### ctx.sessionPersistence.locate(meta)
 
 ```ts website-api
+/**
+ * Resolve this backend's independent local artifact for a session without
+ * reading, creating, flushing, or otherwise materializing it. Backends such
+ * as SQLite that do not own one artifact per session return `undefined`.
+ * @param meta - the immutable session header whose artifact is requested.
+ * @returns the backend-specific absolute location, when one exists.
+ */
 abstract locate(meta: SessionHeader): SessionLocation | undefined
 ```
 
@@ -25,6 +32,13 @@ Resolve this backend's independent local artifact for a session without reading,
 ### ctx.sessionPersistence.create(meta)
 
 ```ts website-api
+/**
+ * Register a new session's metadata. A backend MAY defer the physical write
+ * until the first {@link append} (lazy materialization), in which case a
+ * created-but-never-appended session is absent from {@link list}
+ * — abandoned sessions leave nothing behind.
+ * @param meta - the immutable header (id, version, cwd, lineage) to record.
+ */
 abstract create(meta: SessionHeader): Promise<void>
 ```
 
@@ -37,6 +51,15 @@ Register a new session's metadata. A backend MAY defer the physical write until
 ### ctx.sessionPersistence.append(id, events)
 
 ```ts website-api
+/**
+ * Durably persist a batch of events (called from the write-behind drain at
+ * the `session/flush` checkpoint). Honors the append-only and contiguous-seq
+ * contracts: the first event's `seq` MUST equal the stored next-seq (after
+ * `load` has durably closed any interrupted turn). Rejects non-JSON-
+ * serializable `event.data` with an error naming the offending event type.
+ * @param id - the session the batch belongs to.
+ * @param events - the contiguous batch to persist, in seq order.
+ */
 abstract append(id: SessionId, events: readonly SessionEvent[]): Promise<void>
 ```
 
@@ -50,6 +73,14 @@ Durably persist a batch of events (called from the write-behind drain at the `se
 ### ctx.sessionPersistence.load(id)
 
 ```ts website-api
+/**
+ * Load a header and balanced contiguous log. A complete interrupted final
+ * turn is preserved and durably closed with missing tool errors plus any open
+ * step and turn boundaries; only a torn final record is discarded. Unknown
+ * versions and corruption in the committed prefix reject.
+ * @param id - the persisted session to reload.
+ * @returns the header and a log ending on a balanced `turn/end`.
+ */
 abstract load(id: SessionId): Promise<{ meta: SessionHeader; events: SessionEvent[] }>
 ```
 
@@ -64,6 +95,10 @@ Load a header and balanced contiguous log. A complete interrupted final turn is
 ### ctx.sessionPersistence.list()
 
 ```ts website-api
+/**
+ * Lightweight listing from metadata, without a full-log parse.
+ * @returns one header per materialized session.
+ */
 abstract list(): Promise<SessionHeader[]>
 ```
 
diff --git a/website/zh-CN/api/harness/session-query.md b/website/zh-CN/api/harness/session-query.md
index f081950aa7..cc826c7af4 100644
--- a/website/zh-CN/api/harness/session-query.md
+++ b/website/zh-CN/api/harness/session-query.md
@@ -11,6 +11,10 @@ Live-preferred logical-corpus exact-read and relationship-tracing service.
 ### ctx.sessionQuery.listSessions()
 
 ```ts website-api
+/**
+ * List the complete logical corpus using live-preferred records.
+ * @returns deterministic newest-first cloned session records.
+ */
 listSessions(): Promise<SessionRecord[]>
 ```
 
@@ -23,6 +27,11 @@ List the complete logical corpus using live-preferred records.
 ### ctx.sessionQuery.listEvents(sessionId)
 
 ```ts website-api
+/**
+ * List lightweight raw-log event records for one logical session.
+ * @param sessionId - live-preferred session id to read.
+ * @returns event records in ascending seq order.
+ */
 async listEvents(sessionId: SessionId): Promise<SessionEventRecord[]>
 ```
 
@@ -37,6 +46,12 @@ List lightweight raw-log event records for one logical session.
 ### ctx.sessionQuery.traceSession(sessionId)
 
 ```ts website-api
+/**
+ * Trace known ancestry and descendants from one corpus observation.
+ * @param sessionId - logical session id to trace.
+ * @returns a complete lineage or an explicit unresolved parent boundary.
+ * @throws when corpus resolution fails, the target is absent, or its known ancestry cycles.
+ */
 async traceSession(sessionId: SessionId): Promise<SessionLineageTrace>
 ```
 
@@ -51,6 +66,12 @@ Trace known ancestry and descendants from one corpus observation.
 ### ctx.sessionQuery.traceEvent(request)
 
 ```ts website-api
+/**
+ * Trace one event's direct positional and provenance relationships.
+ * @param request - target session id and event seq.
+ * @returns direct links plus the target's positional replacement chain.
+ * @throws when source resolution fails, the target is absent, or surface/provenance validation fails.
+ */
 async traceEvent(request: SessionEventTraceRequest): Promise<SessionEventTrace>
 ```
 
@@ -65,6 +86,11 @@ Trace one event's direct positional and provenance relationships.
 ### ctx.sessionQuery.readEvent(request)
 
 ```ts website-api
+/**
+ * Read one full event plus a bounded raw-log context window.
+ * @param request - target session/seq and context sizes.
+ * @returns cloned target and neighboring events.
+ */
 async readEvent(request: SessionEventReadRequest): Promise<SessionEventWindow>
 ```
 
diff --git a/website/zh-CN/api/harness/sessions.md b/website/zh-CN/api/harness/sessions.md
index 712852fc49..f59001009d 100644
--- a/website/zh-CN/api/harness/sessions.md
+++ b/website/zh-CN/api/harness/sessions.md
@@ -12,6 +12,27 @@ Persistence is intentionally not implemented here — persistence plugins subscr
 ### ctx.sessions.create(id?, options?)
 
 ```ts website-api
+/**
+ * Create a session owned by the calling fiber: disposing that fiber stops
+ * event notification and removes the session from the store. `options.seed`
+ * populates the session with a copy of those events (replay/fork);
+ * `options.meta` attaches creation metadata (validated absolute `cwd`,
+ * `parentSession` lineage) as the immutable {@link SessionHeader} (the store
+ * fills `version`/`id`/`createdAt`).
+ *
+ * For an agent whose session must be torn down IN ORDER with its loop (so the
+ * loop's final flush is captured before the store attachment ends), do NOT use this
+ * — fold the session lifecycle into the agent's own effect via
+ * {@link prepare} + {@link enter} + {@link announce} (see
+ * `dsh-agent-loop`'s creation transaction).
+ *
+ * @param id - the session id; omitted, the store mints `session-<n>`.
+ * @param options - seed events and/or creation metadata for the header.
+ * @returns the live session, already entered and announced.
+ * @throws if a session with `id` already exists, metadata is not a plain
+ *   lossless-JSON record with valid scalar fields, or `meta.cwd` is a
+ *   non-absolute path (storage backends key directories off it).
+ */
 create(id?: SessionId, options?: CreateSessionOptions): Session
 ```
 
@@ -28,6 +49,22 @@ For an agent whose session must be torn down IN ORDER with its loop (so the loop
 ### ctx.sessions.prepare(id?, options?)
 
 ```ts website-api
+/**
+ * Build a session WITHOUT entering it into the store — validate the id/cwd and
+ * construct the {@link Session} (with its immutable {@link SessionHeader}).
+ * Pairs with {@link enter} + {@link announce}: a caller that owns a composite
+ * `ctx.effect` (the agent factory) folds the session lifecycle into that ONE
+ * effect so a fiber unload tears the session + agent down as a single ORDERED
+ * chain rather than as racing sibling effects — which would remove the publication hooks
+ * before the loop's closing `session/flush`, dropping the closing events.
+ *
+ * @param id - the session id; omitted, the store mints `session-<n>`.
+ * @param options - seed events and/or creation metadata for the header.
+ * @returns the constructed session, NOT yet in the store.
+ * @throws if a session with `id` already exists, metadata is not a plain
+ *   lossless-JSON record with valid scalar fields, or `meta.cwd` is a
+ *   non-absolute path.
+ */
 prepare(id?: SessionId, options?: CreateSessionOptions): Session
 ```
 
@@ -43,6 +80,28 @@ Build a session WITHOUT entering it into the store — validate the id/cwd and c
 ### ctx.sessions.enter(session)
 
 ```ts website-api
+/**
+ * Enter a {@link prepare}d session into the store: install the module-private
+ * append publication hooks and add it to the store. Returns the DETACH
+ * disposer (hooks + store removal). Does NOT emit `session/created` —
+ * the caller yields this disposer inside its effect and THEN calls
+ * {@link announce}, so a throwing `session/created` listener rolls the attach
+ * back instead of leaking it.
+ *
+ * Re-checks the id for a duplicate: `prepare` and `enter` are public
+ * cross-package primitives and a caller may interleave arbitrary work (or
+ * another create) between them, so a stale prepared session must NOT overwrite
+ * a live store entry of the same id — its detach disposer would later delete
+ * the REAL session. The {@link create} convenience and the agent factory call
+ * the two back-to-back so they never trip this, but the public seam cannot
+ * assume that.
+ *
+ * @param session - a {@link prepare}d session not yet in the store.
+ * @returns the detach disposer (publication hooks + store removal). When called from
+ *   a synchronous `session/created` listener, removal and disposal wait until
+ *   that creation dispatch unwinds.
+ * @throws if a session with this id is already in the store.
+ */
 enter(session: Session): () => void
 ```
 
@@ -58,6 +117,13 @@ Re-checks the id for a duplicate: `prepare` and `enter` are public cross-package
 ### ctx.sessions.announce(session)
 
 ```ts website-api
+/** Emit `session/created` exactly once for an {@link enter}ed session (with
+ * the carrier {@link enter} captured). Separate from {@link enter} so the
+ * caller can yield the detach disposer first (rollback safety — see
+ * {@link enter}).
+ * @param session - the entered session to announce to listeners.
+ * @throws if the session is not live or its announcement already began,
+ *   including a reentrant call from a creation listener. */
 announce(session: Session): void
 ```
 
@@ -70,6 +136,17 @@ Emit `session/created` exactly once for an entered session (with the carrier ent
 ### ctx.sessions.flush(session)
 
 ```ts website-api
+/**
+ * Dispatch the awaited `session/flush` durability checkpoint for `session`,
+ * with the carrier captured at {@link enter}. THE flush entry point: the
+ * store owns the carrier, so callers (the loop's turn-end checkpoint, idle
+ * injection, teardown drains) must come through here rather than dispatch a
+ * raw `ctx.parallel('session/flush', …)` — one owner, one spelling, and the
+ * scoped-dispatch invariant can pin it.
+ * @param session - the session whose buffered events must reach durable storage.
+ * @returns resolves when every flush listener has settled; after all settle,
+ *   rejects with the first registered listener failure if any listener failed.
+ */
 async flush(session: Session): Promise<void>
 ```
 
@@ -84,6 +161,11 @@ Dispatch the awaited `session/flush` durability checkpoint for `session`, with t
 ### ctx.sessions.get(id)
 
 ```ts website-api
+/**
+ * Look up a live session.
+ * @param id - the session id to look up.
+ * @returns the session, or undefined when no live session has that id.
+ */
 get(id: SessionId): Session | undefined
 ```
 
@@ -98,6 +180,10 @@ Look up a live session.
 ### ctx.sessions.list()
 
 ```ts website-api
+/**
+ * All live sessions, in creation order.
+ * @returns a fresh array; mutating it does not affect the store.
+ */
 list(): Session[]
 ```
 
@@ -110,6 +196,19 @@ All live sessions, in creation order.
 ### ctx.sessions.fork(source, boundary?, childSessionId?)
 
 ```ts website-api
+/**
+ * Create a live child session from a turn-enclosed prefix of a live source.
+ * `boundary` is an inclusive source event seq; omitted means the source's
+ * current last event. A non-empty selected slice must end at `turn/end`.
+ *
+ * @param source - Live source session object or id.
+ * @param boundary - Inclusive source event seq to fork through; omitted means
+ *   the source's current last event, and omitted on an empty source forks an
+ *   empty child.
+ * @param childSessionId - Optional child session id; omitted delegates to
+ *   `SessionStore`'s id policy.
+ * @returns The created live child session.
+ */
 fork(source: SessionForkSource, boundary?: number, childSessionId?: SessionId): Session
 ```
 
diff --git a/website/zh-CN/api/harness/skills.md b/website/zh-CN/api/harness/skills.md
index 32c4d1b825..31ab6cd1d9 100644
--- a/website/zh-CN/api/harness/skills.md
+++ b/website/zh-CN/api/harness/skills.md
@@ -11,6 +11,14 @@ Registry of skill providers. It merges provider catalogs with stable first-wins
 ### ctx.skills.registerProvider(provider)
 
 ```ts website-api
+/**
+ * Register a borrowed same-process provider synchronously during plugin apply. Duplicate and
+ * reserved names throw; remote initialization belongs in `list()`. Fiber disposal unregisters
+ * the provider and invalidates catalog caches.
+ * @param provider - the provider to register by `provider.name`.
+ * @returns the exact Cordis effect disposer that unregisters this provider;
+ *   composite effects may yield it directly to preserve teardown ordering.
+ */
 registerProvider(provider: SkillProvider): () => void
 ```
 
@@ -25,6 +33,13 @@ Register a borrowed same-process provider synchronously during plugin apply. Dup
 ### ctx.skills.register(skill)
 
 ```ts website-api
+/**
+ * Register a borrowed readonly runtime skill. Project entries outrank runtime entries, which
+ * outrank user entries. Same-name runtime entries are first-wins; a duplicate logs a warning and
+ * receives a no-op disposer so it cannot remove the winner.
+ * @param skill - the complete skill definition to expose for discovery.
+ * @returns the exact Cordis effect disposer, preserving composite teardown order and invalidating caches.
+ */
 register(skill: SkillRegistration): () => void
 ```
 
@@ -39,6 +54,13 @@ Register a borrowed readonly runtime skill. Project entries outrank runtime entr
 ### ctx.skills.list(options?)
 
 ```ts website-api
+/**
+ * List model-invocable skill summaries for a workspace. Lookup options and
+ * provider candidates are readonly same-process values borrowed throughout
+ * discovery.
+ * @param options - lookup options; `cwd` selects project roots and `signal` cancels discovery.
+ * @returns sorted summaries, excluding skills disabled for model invocation.
+ */
 async list(options: SkillLookupOptions = {}): Promise<SkillSummary[]>
 ```
 
@@ -53,6 +75,14 @@ List model-invocable skill summaries for a workspace. Lookup options and provide
 ### ctx.skills.get(name, options?)
 
 ```ts website-api
+/**
+ * Load and validate the winning candidate, passing its opaque discovery locator back to the
+ * provider. Cancellation is rechecked after selection, including cache hits, and raced against
+ * loading so an uncooperative provider cannot hang the caller.
+ * @param name - kebab-case skill name.
+ * @param options - lookup options; `cwd` selects workspace-sensitive skills and `signal` cancels work.
+ * @returns the full skill, including body content, or `undefined`.
+ */
 async get(name: string, options: SkillLookupOptions = {}): Promise<SkillDefinition | undefined>
 ```
 
diff --git a/website/zh-CN/api/harness/spill-store.md b/website/zh-CN/api/harness/spill-store.md
index b7fd81c934..942e811c6b 100644
--- a/website/zh-CN/api/harness/spill-store.md
+++ b/website/zh-CN/api/harness/spill-store.md
@@ -15,6 +15,11 @@ Semantics every implementation must honor:
 ### ctx.spillStore.saveText(input)
 
 ```ts website-api
+/**
+ * Persist `input.content` to a session-scoped spill artifact.
+ * @param input - the owner, provenance, suggested name, and full text to save.
+ * @returns the saved artifact's {@link SpillRef}; rejects on a storage failure.
+ */
 abstract saveText(input: SaveTextSpill): Promise<SpillRef>
 ```
 
diff --git a/website/zh-CN/api/harness/subagents.md b/website/zh-CN/api/harness/subagents.md
index 52632e820d..de71a5effe 100644
--- a/website/zh-CN/api/harness/subagents.md
+++ b/website/zh-CN/api/harness/subagents.md
@@ -11,6 +11,13 @@ Named provider registry and capability-checked start surface.
 ### ctx.subagents.registerProvider(provider)
 
 ```ts website-api
+/**
+ * Register a provider under its name. Registration is effect-scoped and HMR
+ * safe; removing a provider blocks new starts but does not revoke runs that
+ * were already returned to their holders.
+ * @param provider - the trusted provider implementation.
+ * @returns the exact Cordis effect disposer.
+ */
 registerProvider(provider: SubagentProvider): () => void
 ```
 
@@ -25,6 +32,11 @@ Register a provider under its name. Registration is effect-scoped and HMR safe;
 ### ctx.subagents.getProvider(name)
 
 ```ts website-api
+/**
+ * Look up a provider by name.
+ * @param name - the provider name.
+ * @returns the provider, or undefined when absent.
+ */
 getProvider(name: string): SubagentProvider | undefined
 ```
 
@@ -39,6 +51,10 @@ Look up a provider by name.
 ### ctx.subagents.list()
 
 ```ts website-api
+/**
+ * List registered provider names in insertion order.
+ * @returns the registered names.
+ */
 list(): string[]
 ```
 
@@ -51,6 +67,15 @@ List registered provider names in insertion order.
 ### ctx.subagents.start(name, request)
 
 ```ts website-api
+/**
+ * Establish a ready child on the named provider. Capability and semantic
+ * checks run before delegation. Provider ownership lasts until its promise
+ * fulfills; a rejection therefore has no run for the caller to dispose and
+ * emits no run lifecycle events.
+ * @param name - the provider to use.
+ * @param request - child prompt, parent, signal, and optional capabilities.
+ * @returns the ready holder-owned run.
+ */
 async start(name: string, request: SubagentStartRequest): Promise<SubagentRun>
 ```
 
diff --git a/website/zh-CN/api/harness/system-prompt.md b/website/zh-CN/api/harness/system-prompt.md
index 56537ac407..ac22619752 100644
--- a/website/zh-CN/api/harness/system-prompt.md
+++ b/website/zh-CN/api/harness/system-prompt.md
@@ -11,6 +11,14 @@ Registry service for the prompt inputs assembled before each model step.
 ### ctx.systemPrompt.section(section)
 
 ```ts website-api
+/**
+ * Register an ordered prompt section in the calling context's scope. A scoped
+ * section shadows a global section with the same name; duplicates within one
+ * layer and non-finite orders throw. Registration and disposal emit
+ * `system-prompt/change`.
+ * @param section - the section to register.
+ * @returns the exact Cordis effect disposer.
+ */
 section(section: PromptSection): () => void
 ```
 
@@ -25,6 +33,13 @@ Register an ordered prompt section in the calling context's scope. A scoped sect
 ### ctx.systemPrompt.tools(provider)
 
 ```ts website-api
+/**
+ * Register a tool-schema provider in the calling context's scope. Global and
+ * matching scoped providers both contribute; returning the reserved
+ * {@link TOOL_ORDER_REST} name makes assembly fail.
+ * @param provider - evaluated for each assembly with its context.
+ * @returns the exact Cordis effect disposer.
+ */
 tools(provider: (context: AssembleContext) => ToolProviderResult): () => void
 ```
 
@@ -39,6 +54,14 @@ Register a tool-schema provider in the calling context's scope. Global and match
 ### ctx.systemPrompt.variable(name, provider)
 
 ```ts website-api
+/**
+ * Register a prompt variable in the calling context's scope. Scoped values
+ * shadow globals; invalid or duplicate names throw. A provider may return
+ * `undefined`, but rendering a section that references that value then fails.
+ * @param name - the `[a-z][a-z0-9_]*` reference name.
+ * @param provider - evaluated for each assembly.
+ * @returns the exact Cordis effect disposer.
+ */
 variable(name: string, provider: (context: AssembleContext) => string | undefined): () => void
 ```
 
@@ -54,6 +77,13 @@ Register a prompt variable in the calling context's scope. Scoped values shadow
 ### ctx.systemPrompt.assemble(context?)
 
 ```ts website-api
+/**
+ * Assemble global and scoped providers, detach tool parameters, apply
+ * canonical ordering, then run the assembly waterfall. Scoped sections and
+ * variables shadow globals; the returned waterfall value is authoritative.
+ * @param context - the optional scope and plugin-defined assembly fields.
+ * @returns the authoritative post-waterfall assembly.
+ */
 async assemble(context: AssembleContext = {}): Promise<PromptAssembly>
 ```
 
diff --git a/website/zh-CN/api/harness/tasks.md b/website/zh-CN/api/harness/tasks.md
index 5ec3061471..1a43639871 100644
--- a/website/zh-CN/api/harness/tasks.md
+++ b/website/zh-CN/api/harness/tasks.md
@@ -11,6 +11,14 @@ The `tasks` service: the runtime-global background task registry. See the module
 ### ctx.tasks.start(spec)
 
 ```ts website-api
+/**
+ * Preflight access, validation, and owner cleanup before starting and
+ * atomically registering work. A throwing starter leaves nothing registered;
+ * after it returns, registration cannot fail. Settlement records the outcome,
+ * notifies listeners, and releases waiters.
+ * @param spec - task identity, owner, and synchronous starter.
+ * @returns the registry-issued `<kind>-N` id.
+ */
 start(spec: TaskStart): TaskId
 ```
 
@@ -25,6 +33,12 @@ Preflight access, validation, and owner cleanup before starting and atomically r
 ### ctx.tasks.list(caller?)
 
 ```ts website-api
+/**
+ * List caller-owned and unowned tasks in registration order without exposing
+ * another session's labels.
+ * @param caller - reading agent; a non-agent caller sees only unowned tasks.
+ * @returns fresh snapshots.
+ */
 list(caller?: Agent): TaskSnapshot[]
 ```
 
@@ -39,6 +53,13 @@ List caller-owned and unowned tasks in registration order without exposing anoth
 ### ctx.tasks.get(id, caller?)
 
 ```ts website-api
+/**
+ * Return a non-consuming snapshot without changing its read cursor or notice
+ * state. Throws for an unknown or foreign task.
+ * @param id - task to look up.
+ * @param caller - reading agent checked against the owner.
+ * @returns a fresh snapshot.
+ */
 get(id: TaskId, caller?: Agent): TaskSnapshot
 ```
 
@@ -54,6 +75,14 @@ Return a non-consuming snapshot without changing its read cursor or notice state
 ### ctx.tasks.read(id, caller?)
 
 ```ts website-api
+/**
+ * Read the next stream delta, or the idempotent final output after settlement.
+ * A terminal read marks the task reported. Throws for an unknown or foreign
+ * task.
+ * @param id - task to read.
+ * @param caller - reading agent checked against the owner.
+ * @returns output text and the post-read snapshot.
+ */
 read(id: TaskId, caller?: Agent): TaskRead
 ```
 
@@ -69,6 +98,15 @@ Read the next stream delta, or the idempotent final output after settlement. A t
 ### ctx.tasks.kill(id, caller?, reason?)
 
 ```ts website-api
+/**
+ * Request cancellation, then mark the task stopping and reported. A producer
+ * throw propagates without changing task state. Throws for an unknown or
+ * foreign task.
+ * @param id - task to cancel.
+ * @param caller - killing agent checked against the owner.
+ * @param reason - logged reason forwarded to the producer.
+ * @returns `requested` for live work, otherwise `already-finished`.
+ */
 kill(id: TaskId, caller?: Agent, reason?: string): 'requested' | 'already-finished'
 ```
 
@@ -85,6 +123,18 @@ Request cancellation, then mark the task stopping and reported. A producer throw
 ### ctx.tasks.wait(id, timeoutMs, caller?, signal?)
 
 ```ts website-api
+/**
+ * Wait for settlement or timeout without cancelling the task. Caller abort
+ * rejects only while the task is live; after settlement it returns the
+ * terminal snapshot so a notice suppressed for this waiter is still delivered.
+ * Timed-out and aborted waits detach their resolvers. Throws for invalid,
+ * unknown, or foreign input.
+ * @param id - task to wait for.
+ * @param timeoutMs - positive finite wait bound in milliseconds.
+ * @param caller - waiting agent checked against the owner.
+ * @param signal - optional cancellation of the wait itself.
+ * @returns snapshot at settlement or timeout.
+ */
 async wait(id: TaskId, timeoutMs: number, caller?: Agent, signal?: AbortSignal): Promise<TaskSnapshot>
 ```
 
@@ -102,6 +152,13 @@ Wait for settlement or timeout without cancelling the task. Caller abort rejects
 ### ctx.tasks.onTaskDone(listener)
 
 ```ts website-api
+/**
+ * Register an effect-scoped completion listener. Each listener is contained;
+ * returned promises are observed but not awaited. No listener runs after
+ * service disposal.
+ * @param listener - receives each terminal snapshot and its exact owner.
+ * @returns disposer that unregisters the listener.
+ */
 onTaskDone(listener: TaskDoneListener): () => void
 ```
 
@@ -116,6 +173,12 @@ Register an effect-scoped completion listener. Each listener is contained; retur
 ### ctx.tasks.attachSurface(name)
 
 ```ts website-api
+/**
+ * Attach an effect-scoped surface that can read and stop tasks. {@link start}
+ * refuses work while none is attached.
+ * @param name - diagnostic label; duplicate names remain independent.
+ * @returns disposer that detaches this surface.
+ */
 attachSurface(name: string): () => void
 ```
 
diff --git a/website/zh-CN/api/harness/token-meter.md b/website/zh-CN/api/harness/token-meter.md
index ab4dd8f684..30b83f79d4 100644
--- a/website/zh-CN/api/harness/token-meter.md
+++ b/website/zh-CN/api/harness/token-meter.md
@@ -11,6 +11,7 @@ Replay owner for one service-wide estimator and isolated per-session folds.
 ### ctx.tokenMeter.contextWindow
 
 ```ts website-api
+/** Provider context-window capacity used by pressure consumers. */
 readonly contextWindow: number
 ```
 
@@ -21,6 +22,22 @@ Provider context-window capacity used by pressure consumers.
 ### ctx.tokenMeter.measure(session, requestHeader?)
 
 ```ts website-api
+/**
+ * Measure current request pressure and surface through the durable tail.
+ *
+ * Provider usage is reused only when the latest successful call's canonical
+ * request envelope matches `requestHeader` and its total is no lower than
+ * that call's full heuristic anchor; otherwise the complete envelope and
+ * surface are heuristically repriced.
+ *
+ * `requestHeader` affects request pressure only; surface fields always
+ * describe the current session surface. Every call clones those positional
+ * nodes, so measurement is O(surface).
+ *
+ * @param session - session to replay through its current durable tail.
+ * @param requestHeader - optional effective request envelope replacing the latest logged header.
+ * @returns a detached deeply immutable pressure and surface measurement.
+ */
 measure(session: Session, requestHeader?: EpochHeader): TokenMeasurement
 ```
 
@@ -38,6 +55,11 @@ Provider usage is reused only when the latest successful call's canonical reques
 ### ctx.tokenMeter.estimateMessage(message)
 
 ```ts website-api
+/**
+ * Heuristically price one model-visible message.
+ * @param message - message to price without mutation.
+ * @returns content and role-framing tokens under the fixed service heuristic.
+ */
 estimateMessage(message: Message): number
 ```
 
diff --git a/website/zh-CN/api/harness/tools.md b/website/zh-CN/api/harness/tools.md
index 6ed4ce024d..eb416e8b75 100644
--- a/website/zh-CN/api/harness/tools.md
+++ b/website/zh-CN/api/harness/tools.md
@@ -11,6 +11,12 @@ Tool registry and execution pipeline. Scoped registrations shadow globals; one v
 ### ctx.tools.register(definition)
 
 ```ts website-api
+/**
+ * Register globally or in the calling agent scope. Scoped tools shadow
+ * globals; duplicates within one layer and the reserved `run_code` name fail.
+ * @param definition - the tool schema, execution, and optional presentation functions.
+ * @returns the exact disposer that unregisters the tool.
+ */
 register(definition: ToolDefinition): () => void
 ```
 
@@ -25,6 +31,13 @@ Register globally or in the calling agent scope. Scoped tools shadow globals; du
 ### ctx.tools.restrict(filter)
 
 ```ts website-api
+/**
+ * Restrict global tools for the calling agent scope. Empty filters, unknown
+ * names, scope-local names, and reserved transport names fail. Restrictions
+ * intersect; scoped registrations remain visible.
+ * @param filter - global-surface mask: `allow` (keep only) and/or `deny` (remove).
+ * @returns the exact disposer that lifts this restriction.
+ */
 restrict(filter: ToolRestriction): () => void
 ```
 
@@ -39,6 +52,16 @@ Restrict global tools for the calling agent scope. Empty filters, unknown names,
 ### ctx.tools.guard(guard)
 
 ```ts website-api
+/**
+ * Register a monotonic guard after the extensible `tools/pre-execute`
+ * waterfall. A plain-context guard applies globally; one registered through
+ * `agent.ctx` applies only to that agent. Any matching guard may deny by
+ * returning a reason, while no guard can force-allow a call another guard
+ * denied. The exact effect disposer is returned for ordered ownership and
+ * HMR cleanup.
+ * @param guard - synchronous check; a returned string denies the execution.
+ * @returns the exact disposer that unregisters the guard.
+ */
 guard(guard: ToolGuard): () => void
 ```
 
@@ -53,6 +76,15 @@ Register a monotonic guard after the extensible `tools/pre-execute` waterfall. A
 ### ctx.tools.get(name, scope?)
 
 ```ts website-api
+/**
+ * Look up a tool as one scope sees it (scoped
+ * shadows global; a restricted-away global reads as absent). Presenters pass
+ * the calling agent so the rendered card matches the definition that
+ * actually executed.
+ * @param name - the tool name as registered.
+ * @param scope - the viewing scope (the agent); omitted = the global view.
+ * @returns the definition the scope resolves, or undefined when none is visible.
+ */
 get(name: string, scope?: ScopeKey): ToolDefinition | undefined
 ```
 
@@ -68,6 +100,12 @@ Look up a tool as one scope sees it (scoped shadows global; a restricted-away gl
 ### ctx.tools.schemas(scope?)
 
 ```ts website-api
+/**
+ * Project visible definitions onto the allowlisted model-facing schema fields,
+ * excluding execution and presentation callbacks.
+ * @param scope - the viewing scope (the agent); omitted = the global view.
+ * @returns one deep-cloned schema per visible tool.
+ */
 schemas(scope?: ScopeKey): ToolSchema[]
 ```
 
@@ -82,6 +120,13 @@ Project visible definitions onto the allowlisted model-facing schema fields, exc
 ### ctx.tools.executionMode(exec)
 
 ```ts website-api
+/**
+ * Classify a pending call through the caller's visible tool definition. Only
+ * an exact `true` is parallel; unknown, hidden, undeclared, invalid, or
+ * throwing classifiers are exclusive.
+ * @param exec - call name, parsed arguments, and optional agent scope.
+ * @returns the fail-closed scheduling mode.
+ */
 executionMode(exec: ToolExecutionInput): ToolExecutionMode
 ```
 
@@ -96,6 +141,15 @@ Classify a pending call through the caller's visible tool definition. Only an ex
 ### ctx.tools.execute(exec)
 
 ```ts website-api
+/**
+ * Execute through pre-policy, guards, around-dispatch, post-policy, and final
+ * notification. Tool and listener failures resolve as materialized error
+ * results; an invisible tool reports `UNKNOWN_TOOL`. The returned outcome is
+ * the same lossless, frozen snapshot final observers receive.
+ * @param exec - the typed same-process call input. The registry assigns its
+ *   correlation token before policy begins.
+ * @returns the materialized final result.
+ */
 async execute(exec: ToolExecutionInput): Promise<ToolExecutionResult>
 ```
 
diff --git a/website/zh-CN/api/harness/user-interaction.md b/website/zh-CN/api/harness/user-interaction.md
index 09db0f6107..072087f8ca 100644
--- a/website/zh-CN/api/harness/user-interaction.md
+++ b/website/zh-CN/api/harness/user-interaction.md
@@ -11,6 +11,12 @@
 ### ctx.userInteraction.registerProvider(provider)
 
 ```ts website-api
+/**
+ * Register the UI provider. Only one provider may be active in a context.
+ *
+ * @param provider UI-side implementation that collects answers.
+ * @returns Disposer that unregisters this provider.
+ */
 registerProvider(provider: UserInteractionProvider): () => void
 ```
 
@@ -25,6 +31,12 @@ Register the UI provider. Only one provider may be active in a context.
 ### ctx.userInteraction.ask(request)
 
 ```ts website-api
+/**
+ * Ask the active UI provider and wait for the user's answer.
+ *
+ * @param request Questions, owner agent, and abort signal.
+ * @returns The answer chosen or typed by the human.
+ */
 async ask(request: AskUserQuestionRequest): Promise<AskUserQuestionAnswer>
 ```
 
diff --git a/website/zh-CN/api/harness/web.md b/website/zh-CN/api/harness/web.md
index ca23406caf..5827430261 100644
--- a/website/zh-CN/api/harness/web.md
+++ b/website/zh-CN/api/harness/web.md
@@ -18,6 +18,13 @@ Selection semantics (resolved at execution time, never order-dependent):
 ### ctx.web.registerSearchProvider(provider)
 
 ```ts website-api
+/**
+ * Register a search provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
+ * if its id is already registered for search. Returns a disposer; disposed
+ * with the calling fiber.
+ * @param provider - the provider; its `id` is the registry key.
+ * @returns the disposer that unregisters the provider.
+ */
 registerSearchProvider(provider: WebSearchProvider): () => void
 ```
 
@@ -32,6 +39,13 @@ Register a search provider. Throws WebError `WEB_DUPLICATE_PROVIDER` if its id i
 ### ctx.web.registerFetchProvider(provider)
 
 ```ts website-api
+/**
+ * Register a fetch provider. Throws {@link WebError} `WEB_DUPLICATE_PROVIDER`
+ * if its id is already registered for fetch. Returns a disposer; disposed
+ * with the calling fiber.
+ * @param provider - the provider; its `id` is the registry key.
+ * @returns the disposer that unregisters the provider.
+ */
 registerFetchProvider(provider: WebFetchProvider): () => void
 ```
 
@@ -46,6 +60,15 @@ Register a fetch provider. Throws WebError `WEB_DUPLICATE_PROVIDER` if its id is
 ### ctx.web.search(request, signal?)
 
 ```ts website-api
+/**
+ * Run one search through the selected provider. Resolves the provider at call
+ * time with the selection rules above; throws {@link WebError} when the
+ * capability cannot run. The seam enforces `request.maxResults` on the result:
+ * if the provider over-returns, `sources[]` is truncated and `truncated` set.
+ * @param request - the query plus result-shaping options.
+ * @param signal - optional cancellation signal forwarded to the provider.
+ * @returns the provider's results, capped to `request.maxResults`.
+ */
 async search(request: WebSearchRequest, signal?: AbortSignal): Promise<WebSearchResult>
 ```
 
@@ -61,6 +84,14 @@ Run one search through the selected provider. Resolves the provider at call time
 ### ctx.web.fetch(request, signal?)
 
 ```ts website-api
+/**
+ * Retrieve one URL through the selected provider. Resolves the provider at
+ * call time with the selection rules above; throws {@link WebError} when the
+ * capability cannot run. A non-2xx response is a result, not a throw.
+ * @param request - the URL plus retrieval options.
+ * @param signal - optional cancellation signal forwarded to the provider.
+ * @returns the retrieval outcome; non-2xx responses resolve descriptively.
+ */
 async fetch(request: WebFetchRequest, signal?: AbortSignal): Promise<WebFetchResult>
 ```
 
diff --git a/website/zh-CN/api/harness/workflows.md b/website/zh-CN/api/harness/workflows.md
index 5518f3e564..f34c3d8a6c 100644
--- a/website/zh-CN/api/harness/workflows.md
+++ b/website/zh-CN/api/harness/workflows.md
@@ -11,6 +11,12 @@ Workflow execution seam. Invalid requests throw before publication; a live run i
 ### ctx.workflows.start(request)
 
 ```ts website-api
+/**
+ * Parse and execute a workflow script.
+ * @param request - the script, its `args`, the parent agent, and an
+ *   optional cancel signal.
+ * @returns the live run; its `result` resolves when the script settles.
+ */
 abstract start(request: WorkflowStartRequest): WorkflowRun
 ```
 
diff --git a/website/zh-CN/api/index.md b/website/zh-CN/api/index.md
index 7e1812bd5f..4357fcbfe3 100644
--- a/website/zh-CN/api/index.md
+++ b/website/zh-CN/api/index.md
@@ -1,6 +1,6 @@
 # API 参考
 
-本节是 DeepSeek Harness 的 API 参考。除本页外，`cordis/` 与 `harness/` 下的所有页面**由脚本从源码生成**（`pnpm run gen-website-api`，CI 校验新鲜度），签名与说明永远与代码一致；生成页目前为英文，中文版将随统一翻译流程提供。
+本节是 DeepSeek Harness 的 API 参考。除本页外，`cordis/` 与 `harness/` 下的所有页面**由脚本从源码生成**（`pnpm run gen-website-api`，CI 校验新鲜度）；签名代码块保留源码的原始 JSDoc，签名与说明永远与代码一致。生成页目前为英文，中文版将随统一翻译流程提供。
 
 ## 框架 API