Merge remote-tracking branch 'origin/master' into xtr/agent-loop-message-machine

# Conflicts: # .agents/notes/implemented/feature/2026-06-14-acp-agent-client-protocol.md # .agents/notes/implemented/feature/2026-06-14-acp-agent-client-protocol.zh.md # .agents/notes/implemented/feature/2026-06-30-hook-bridges.i18n.yaml # .agents/notes/implemented/feature/2026-06-30-interception-seams.i18n.yaml # .agents/notes/implemented/feature/2026-07-06-sandbox.i18n.yaml # .agents/notes/implemented/feature/2026-07-06-sandbox.md # .agents/notes/implemented/feature/2026-07-06-sandbox.zh.md # .agents/notes/implemented/feature/2026-07-19-model-facing-goal-tools.i18n.yaml # .agents/notes/implemented/feature/2026-07-19-same-session-goal-round-driver.i18n.yaml # .agents/notes/implemented/feature/2026-07-25-workspace-ui-product-flow.i18n.yaml # .agents/notes/implemented/simplification/2026-07-02-remove-stream-chunk-mirror.i18n.yaml # docs/architecture.i18n.yaml # docs/cookbook/adding-a-tool.i18n.yaml # docs/cookbook/extension-cookbook.i18n.yaml # docs/core-data-structures/llm-streaming.i18n.yaml # docs/core-data-structures/session.i18n.yaml # docs/core-data-structures/tools.i18n.yaml # docs/event-producer-consumer.md # docs/persistence-catalog.md # examples/acp-agent/tests/snapshots/cordis-inspect-jsdoc/stdout.expected.jsonl # examples/acp-agent/tests/snapshots/escalation-approved/session.jsonl # examples/acp-agent/tests/snapshots/escalation-rejected/session.jsonl # examples/acp-agent/tests/snapshots/fs-escalation-approved/session.jsonl # examples/acp-agent/tests/snapshots/hook-cc-pretool-ask/session.jsonl # examples/acp-agent/tests/snapshots/permission-switching/session.jsonl # examples/acp-agent/tests/snapshots/plan-mode-reject/session.jsonl # examples/acp-agent/tests/snapshots/plan-mode/session.jsonl # examples/acp-agent/tests/snapshots/session-sandbox-root/session.jsonl # packages/context/session-reference/README.md # packages/core/agent-loop/tests/agent.spec.ts # packages/hooks/hooks-claude/tests/coverage-cases.ts # packages/host/runtime/tests/host-runtime.spec.ts # packages/llm/llm-retry/tests/retry.spec.ts # packages/session-persistence/session-persistence/src/coordinator.ts # packages/support/acp-snapshot/README.md # packages/support/acp-snapshot/src/normalize.ts # packages/ui/acp/acp-feature-support.md # packages/ui/acp/src/codec.ts # packages/ui/acp/src/index.ts # packages/ui/acp/tests/bridge.spec.ts # packages/ui/acp/tests/codec.spec.ts # packages/ui/acp/tests/config-options.spec.ts # packages/ui/acp/tests/dispose.spec.ts # packages/ui/acp/tests/edges.spec.ts # packages/ui/acp/tests/stream-update.spec.ts # packages/ui/acp/tests/turns.spec.ts
2026-07-26 14:05:33 +08:00
parent af3311e1f6 3ccdf4ac46
commit 57d90c343d
1062 changed files with 33621 additions and 30750 deletions
--- a/packages/examples/README.md
+++ b/packages/examples/README.md
@@ -5,14 +5,14 @@ Pre-composed plugin bundles a thin leaf `cordis.yml` loads instead of assembling
 | Package | npm name | Role |
 |---|---|---|
 | `agent-spine-demo/` | `@deepseek-ai/dsh-agent-spine-demo` | The executor-less/UI-less agent spine as one bundle plugin, with fallback session titles and an opt-in persisted-goal stack |
-| `tui-demo/` | `@deepseek-ai/dsh-tui-demo` | Full-screen terminal app: the spine + persisted goals + `/goal` command + JSONL persistence + `dsh-tui` + a pre-created `main` agent, with a boot `bin` |
+| `tui-demo/` | `@deepseek-ai/dsh-tui-demo` | Full-screen terminal app bundle: the spine + persisted goals + `/goal` command + JSONL persistence + `dsh-tui` + a pre-created `main` agent; no bin, booted by the [`dsh`](../../apps/cli/README.md) CLI |
 | `cli-demo/` | `@deepseek-ai/dsh-cli-demo` | Headless one-shot app: the spine + JSONL persistence + a pre-created `main` agent, with text and DSH-native JSON output |
-| `acp-demo/` | `@deepseek-ai/dsh-acp-demo` | ACP server app: the spine + persisted goals + `/goal` command + JSONL persistence + the [`acp`](../ui/acp/README.md) bridge (no stdout logger), with a boot `bin` |
+| `acp-demo/` | `@deepseek-ai/dsh-acp-demo` | ACP automation server app: the spine + persisted goals + JSONL persistence + the [`acp`](../acp/acp/README.md) bridge (no stdout logger), with a boot `bin` |
 | `jsonrpc-demo/` | `@deepseek-ai/dsh-jsonrpc-demo` | Bin-only runtime that boots an external `cordis.yml` for the stdio JSON-RPC SDK client |

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

-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.
+These are **not** product API. The spine pieces they bundle live in [`core/`](../core/README.md), human/SDK channels and boot glue in [`ui/`](../ui/README.md), the automation transport in [`acp/`](../acp/README.md), and swappable backends in their capability groups; a demo bundle just picks one concrete composition of them. Swap or fork one freely.

 Do not confuse this group with the repo-root [`examples/`](../../examples/AGENTS.md): that directory holds the runnable `cordis.yml` **leaves**; this group holds the **bundles** those leaves load.

--- a/packages/examples/acp-demo/README.md
+++ b/packages/examples/acp-demo/README.md
@@ -1,77 +1,57 @@
 # @deepseek-ai/dsh-acp-demo

-The **ACP server app**: a Cordis app plugin that composes the default agent spine ([`@deepseek-ai/dsh-agent-spine-demo`](../agent-spine-demo/README.md)) with the front-door cluster an [Agent Client Protocol](../../ui/acp/README.md) server needs, and a `bin` that boots a leaf `cordis.yml` speaking ACP JSON-RPC on stdio.
+ACP automation server app: the default agent spine, client-created agents through [`@deepseek-ai/dsh-acp`](../../acp/acp/README.md), JSONL persistence, and semantic checkpointing behind one JSON-RPC stdio bin. Programmatic clients create fresh sessions; this package mounts no human UI.

-It is the structured counterpart to [`@deepseek-ai/dsh-tui-demo`](../tui-demo/README.md): both consume the same spine, but ACP creates sessions from its client and reserves stdout for its wire protocol.
+## Composition

-## What it bakes in — and what it deliberately omits
-
-stdout is the ACP JSON-RPC channel, so the cluster is defined as much by what it LEAVES OUT as what it includes:
-
-| Plugin | Why |
+| Plugin | Role |
 |---|---|
-| `@deepseek-ai/dsh-agent-spine-demo` | the spine, pre-creating **no** agents (ACP `session/new` creates them on demand) |
-| `@deepseek-ai/dsh-commands` | the human-command registry used for ACP discovery and direct slash dispatch |
-| `@deepseek-ai/dsh-command-goal` | the discoverable direct `/goal` producer; the app enables the spine's persisted-goal stack with it |
-| `@deepseek-ai/dsh-user-interaction` | the human question/answer seam used by clients that can complete ACP elicitation requests |
-| `@deepseek-ai/dsh-session-persistence-jsonl` | durable JSONL session log (the bridge advertises `loadSession`) |
-| `@deepseek-ai/dsh-session-query-sqlite` + `@deepseek-ai/dsh-session-reference` | combined exact/FTS session queries and bounded `dsh-session:` snapshots |
-| `@deepseek-ai/dsh-session-checkpoint-policy` | semantic durability barriers before model requests and top-level tool effects, plus completed-step checkpoints |
-| `@deepseek-ai/dsh-acp` | the bridge that owns stdout for JSON-RPC and provides ACP-backed user answers when a leaf explicitly exposes a user-question tool |
-| ~~`@deepseek-ai/dsh-tool-ask-user`~~ | **omitted by default** — ACP elicitation support is still client-dependent, so leaves must opt in deliberately |
-| ~~`@deepseek-ai/dsh-user-approval`~~ | **omitted by default** — permission policy is deployment-specific; sandbox/approval leaves opt in and the ACP bridge then supplies the answerer |
-| ~~console logger~~ | **omitted** — it writes to stdout and would corrupt the protocol frames ([the stdout-purity footgun](../../ui/acp/README.md)) |
-| ~~`hmr`~~ | **omitted** — the editor owns the subprocess |
+| `@deepseek-ai/dsh-agent-spine-demo` | Providerless agent spine with no pre-created agents; `session/new` creates each agent. |
+| `@deepseek-ai/dsh-session-persistence-jsonl` | Durable session logs used by checkpointing, observability, and snapshot replay. |
+| `@deepseek-ai/dsh-session-checkpoint-policy` | Durability barriers before model calls and top-level tool effects, plus completed-step checkpoints. |
+| `@deepseek-ai/dsh-session-query-sqlite` | Derived exact/FTS session-query service, opened before the ACP transport so leaf consumers are ready for the first model request. |
+| `@deepseek-ai/dsh-acp` | Automation-only ACP transport over stdin/stdout. |

-The app owns this cluster through one ordered Cordis effect. Teardown drains the ACP bridge before removing the checkpoint policy or persistence backend, so a graceful disconnect persists the real closing `step/end` and `turn/end` events rather than leaving crash recovery to synthesize them. Because the package wires no logger entry, an ACP leaf has **nothing to get wrong by default**: it only picks backends. A leaf author can still add `@cordisjs/plugin-logger-console` as a sibling entry, so the rule remains: never add a stdout logger to an ACP leaf; use a stderr exporter instead.
+The app does not install commands, user interaction, session navigation, configuration pickers, or a stdout logger. It owns these plugins through one ordered effect so the query service is ready before ACP accepts work and ACP sessions quiesce before checkpointing and persistence detach. Leaf configurations supply LLM, executor, sandbox, approval, filesystem, and model-facing tool plugins.

 ## Config

 | Key | Default | Routed to |
 |---|---|---|
-| `provider` | (required) | the initial provider route for each per-session agent the bridge creates; ACP model selection may replace it per session |
-| `model` | (required) | the initial model for each per-session agent; ACP clients may switch among adapter-advertised models |
-| `maxParallelToolCalls` | agent-loop default | positive-integer concurrent tool-call cap shared by the bundled loop's agents; `1` is serial |
-| `persona` | — | the deployment persona template (may reference `{{provider}}`/`{{model}}`/`{{cwd}}`), routed to `dsh-system-prompt` |
-| `toolOrder` | — | explicit model-facing tool order (a name list with one `'<unlisted-tools>'` rest entry; absent — lexicographic; an unregistered name fails each turn at prompt assembly), routed to `dsh-system-prompt` |
-| `dshHome` | `$DSH_HOME` or `~/.dsh` | Harness home exposed to model bash and used by local skill discovery |
-| `sessionTitle` | spine example limits | fallback title word/byte limits routed through `dsh-agent-spine-demo` |
-| `tools` | `{ mode: 'native' }` | tool-registry presentation config (`native` / `code` / `both`), routed through `dsh-agent-spine-demo` |
-| `workspaceContext` | (required) | workspace-instruction byte budget/config, or `false`; routed to the providerless-safe `dsh-workspace-context` plugin |
-| `skills` | owner defaults | registry-cache, local-provider, and model-facing skill-tool config, routed through `dsh-agent-spine-demo` |
-| `toolBash` | owner defaults | model-facing bash config routed through `dsh-agent-spine-demo`, including bash's producer-local `enableRunInBackground` |
-| `toolTasks` | owner defaults | generic `task_output` wait bounds routed through `dsh-agent-spine-demo` |
-| `goals` | owner defaults | persisted goal-domain and model-tool config; `false` removes the goal stack and `/goal` producer |
-| `llmRetry` | owner defaults | bounded transient model-request retry policy routed through `dsh-agent-spine-demo` |
-| `persistenceRoot` | `./.sessions` | the JSONL backend's root directory and the parent of the derived `session-query.db` index |
-| `packChunks` | `false` | write delta-chunk runs as packed storage rows (the JSONL backend's `packChunks`) |
-| `persistenceCompression` | `'zstd'` | JSONL artifact encoding (`'zstd'` or raw `'none'`) |
-| `sessionReferences` | service defaults | cross-session candidate and snapshot limits routed to `dsh-session-reference` |
+| `provider` | required | Provider route for each ACP-created agent. |
+| `model` | required | Model for each ACP-created agent. |
+| `maxParallelToolCalls` | agent-loop default | Positive-integer tool-call concurrency cap; `1` is serial. |
+| `persona` | — | Deployment persona template for `dsh-system-prompt`. |
+| `toolOrder` | lexicographic | Explicit model-facing tool order for `dsh-system-prompt`. |
+| `tools` | `{ mode: 'native' }` | Native, Code Mode, or combined model tool transport. |
+| `dshHome` | `$DSH_HOME` or `~/.dsh` | Harness home shared by bash and local skill discovery. |
+| `sessionTitle` | spine example limits | Durable fallback-title limits; titles remain off the ACP wire. |
+| `persistenceRoot` | `./.sessions` | JSONL backend root and parent directory of the derived `session-query.db` index. |
+| `packChunks` | `false` | Pack consecutive delta-chunk events in storage. |
+| `persistenceCompression` | `zstd` | Checksummed Zstandard frames or raw `none`. |
+| `workspaceContext` | required | Workspace-instruction byte budget/config, or `false`. |
+| `skills` | owner defaults | Skill registry, local provider, and model-facing skill tool. |
+| `toolBash` | owner defaults | Model-facing bash tool config. |
+| `toolTasks` | owner defaults | Generic background-task control config, or `false`. |
+| `goals` | owner defaults | Persisted same-session goal domain and model tools, or `false`. |
+| `llmRetry` | owner defaults | Bounded transient model-request retry policy. |

-The leaf supplies the swappable backends: an LLM adapter (`llm-deepseek` for the real model, `llm-replay` for keyless snapshot replay), a bash executor, and optionally a `ctx.fs` provider. Workspace context becomes a no-op without `ctx.fs`; the shipped [`examples/acp-agent/cordis.yml`](../../../examples/acp-agent/cordis.yml) selects `dsh-sandbox-policy`, `dsh-fs-sandbox`, `dsh-fs-policy`, and `dsh-tool-fs` so baseline instructions and model-facing `read`/`write`/`edit` share one provider, sandbox mode, workspace root, and observed-version policy.
+The shipped [`examples/acp-agent/cordis.yml`](../../../examples/acp-agent/cordis.yml) adds the DeepSeek adapter, sandboxed bash and filesystem providers, one-shot approval policy, compaction, subagents, workflows, hooks, and model-facing tools. The app supplies the derived session-query index, while the model-facing query consumer remains an explicit leaf opt-in. Snapshot overlays replace only nondeterministic providers or policy values.

-## The bin
+## Bin

-`dsh-acp-demo [--config path-to-cordis.yml]` (short form `-c`; default `./cordis.yml`):
-
- loads a gitignored `.env` from the cwd — **skipped** in snapshot REPLAY so a stray key can never trigger a live call;
- honors `DSH_SNAPSHOT=replay` by booting the sibling `cordis.snapshot.yml` (the keyless replay tree, `llm-replay` in place of `llm-deepseek`);
- in a snapshot run, disposes the context on stdin EOF so the session log is fully flushed before exit.
-
-The repository installs Loader's optional `node-addon-require-builtin` peer, so the built bin resolves bare plugin specifiers through the internal module loader under plain Node. (`demo:acp` runs under tsx, whose tsconfig `paths` map resolves them instead.)
-
-All diagnostics go to **stderr** — stdout is the protocol.
+`dsh-acp-demo [--config path-to-cordis.yml]` (short form `-c`; default `./cordis.yml`) loads the gitignored `.env`, except in replay mode; `DSH_SNAPSHOT=replay` selects the sibling `cordis.snapshot.yml`; stdin EOF disposes the context and flushes sessions before exit. Loader's installed optional `node-addon-require-builtin` peer resolves bare plugin specifiers for the built bin under plain Node. Diagnostics use stderr because stdout is the ACP wire.

 ## Model Experience

-Indirectly, through `dsh-agent-spine-demo` and `dsh-acp`, which compose each ACP agent's prompt, goal tools, and message history. Direct `/goal` input and output remain outside the model, while accepted mutations append domain-owned model-visible snapshots.
+Indirectly, through `dsh-agent-spine-demo` and the leaf's model-facing plugins. ACP prompt text becomes the ordinary logged user message; protocol metadata and permission choices do not enter the model request.

 #### KV Cache effect

-No direct invalidation; the named consumer owns any request-prefix changes.
+Append-only per session; the app adds no request-prefix content itself.

 ## Known Limitations and Deferred Work

- **JSONL persistence is baked in** — config chooses its root but cannot select a different backend; that requires a sibling entry or differently composed app package.
- **User-question and approval mechanisms are omitted by default** — the bridge can answer both when their services/tools are composed, but this front door does not enable those deployment policies itself.
- **A leaf can still corrupt stdout** — the app mounts no console logger, but it cannot prevent a sibling leaf entry from writing non-protocol bytes to the ACP channel.
+- **JSONL persistence is fixed** — a different backend requires another composition.
+- **Sibling plugins can corrupt stdout** — the app cannot prevent another entry from writing non-protocol bytes.
+- **Fresh automation sessions only** — resume and human interaction belong to other front doors.
--- a/packages/examples/acp-demo/package.json
+++ b/packages/examples/acp-demo/package.json
@@ -1,6 +1,6 @@
 {
  "name": "@deepseek-ai/dsh-acp-demo",
-  "description": "ACP server app: agent spine + human commands + JSONL persistence + ACP bridge (no stdout logger, hmr, or pre-created agents), with a JSON-RPC stdio bin",
+  "description": "ACP automation server app: agent spine + JSONL persistence + ACP transport, with a JSON-RPC stdio bin",
  "version": "0.0.1",
  "private": true,
  "type": "module",
@@ -38,8 +38,6 @@
    "@cordisjs/plugin-include": "^1.0.4",
    "@cordisjs/plugin-loader": "^1.0.0-rc.5",
    "@deepseek-ai/dsh-acp": "^0.0.1",
-    "@deepseek-ai/dsh-commands": "^0.0.1",
-    "@deepseek-ai/dsh-command-goal": "^0.0.1",
    "@deepseek-ai/dsh-agent-spine-demo": "^0.0.1",
    "@deepseek-ai/dsh-app-boot": "^0.0.1",
    "@deepseek-ai/dsh-invariants": "^0.0.1",
@@ -47,9 +45,7 @@
    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
    "@deepseek-ai/dsh-session-query": "^0.0.1",
    "@deepseek-ai/dsh-session-query-sqlite": "^0.0.1",
-    "@deepseek-ai/dsh-session-reference": "^0.0.1",
    "@deepseek-ai/dsh-tools": "^0.0.1",
-    "@deepseek-ai/dsh-user-interaction": "^0.0.1",
    "@deepseek-ai/dsh-workspace-context": "^0.0.1",
    "cordis": "^4.0.0-rc.7",
    "schemastery": "^3.17.0"
@@ -58,8 +54,6 @@
    "@cordisjs/plugin-include": "workspace:^",
    "@cordisjs/plugin-loader": "workspace:^",
    "@deepseek-ai/dsh-acp": "workspace:^",
-    "@deepseek-ai/dsh-commands": "workspace:^",
-    "@deepseek-ai/dsh-command-goal": "workspace:^",
    "@deepseek-ai/dsh-agent": "workspace:^",
    "@deepseek-ai/dsh-agent-spine-demo": "workspace:^",
    "@deepseek-ai/dsh-app-boot": "workspace:^",
@@ -68,10 +62,8 @@
    "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
    "@deepseek-ai/dsh-session-query": "workspace:^",
    "@deepseek-ai/dsh-session-query-sqlite": "workspace:^",
-    "@deepseek-ai/dsh-session-reference": "workspace:^",
    "@deepseek-ai/dsh-system-prompt": "workspace:^",
    "@deepseek-ai/dsh-tools": "workspace:^",
-    "@deepseek-ai/dsh-user-interaction": "workspace:^",
    "@deepseek-ai/dsh-workspace-context": "workspace:^",
    "cordis": "^4.0.0-rc.7",
    "schemastery": "^3.17.0"
--- a/packages/examples/acp-demo/src/bin.ts
+++ b/packages/examples/acp-demo/src/bin.ts
@@ -5,7 +5,7 @@
 * loading, Loader guards, snapshot config selection, and settled-tree boot live
 * in dsh-app-boot. Replay skips `.env` and selects sibling
 * `cordis.snapshot.yml` so a stray key cannot trigger a model call. EOF disposes
- * and flushes snapshot runs; editors normally own process lifetime. Stdout is
+ * and flushes snapshot runs; the calling automation owns process lifetime. Stdout is
 * reserved for JSON-RPC, so diagnostics go only to stderr.
 * @module @deepseek-ai/dsh-acp-demo/bin
 */
--- a/packages/examples/acp-demo/src/index.ts
+++ b/packages/examples/acp-demo/src/index.ts
@@ -1,7 +1,7 @@
 /**
- * The ACP server app: the default agent spine ({@link @deepseek-ai/dsh-agent-spine-demo}),
- * human-command registry, JSONL session persistence, and the
- * {@link @deepseek-ai/dsh-acp} bridge. The app owns those plugins through one
+ * The ACP automation server app: the default agent spine
+ * ({@link @deepseek-ai/dsh-agent-spine-demo}), JSONL session persistence, and
+ * the {@link @deepseek-ai/dsh-acp} bridge. The app owns those plugins through one
 * ordered lifecycle so ACP sessions quiesce before persistence detaches. It
 * writes nothing to stdout.
 * It pre-creates no agents and leaves adapters, executors, and optional tools to
@@ -15,8 +15,6 @@ import type { Context } from 'cordis'
 import { join } from 'node:path'
 import z from 'schemastery'
 import * as acp from '@deepseek-ai/dsh-acp'
-import CommandService from '@deepseek-ai/dsh-commands'
-import * as commandGoal from '@deepseek-ai/dsh-command-goal'
 import * as agentCore from '@deepseek-ai/dsh-agent-spine-demo'
 import * as workspaceContext from '@deepseek-ai/dsh-workspace-context'
 import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools'
@@ -25,17 +23,14 @@ import SessionPersistenceJsonl, {
  type JsonlCompression,
 } from '@deepseek-ai/dsh-session-persistence-jsonl'
 import * as sessionCheckpointPolicy from '@deepseek-ai/dsh-session-checkpoint-policy'
-import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import SessionQuerySqlite from '@deepseek-ai/dsh-session-query-sqlite'
-import SessionReferenceService, { type Config as SessionReferenceConfig } from '@deepseek-ai/dsh-session-reference'

 export const name = 'acp-demo'
 const DEFAULT_PERSISTENCE_ROOT = './.sessions'

 /**
- * App config: the swappable per-deployment values. `provider` and `model` configure the
- * agent template the ACP bridge creates each session's agent from (NOT a
- * pre-created agent — ACP creates agents at `session/new`); `persona` is the
+ * App config: the swappable per-deployment values. `provider` and `model` configure
+ * each agent the ACP bridge creates at `session/new`; `persona` is the
 * deployment persona (forwarded to the system-prompt plugin); `toolOrder` is
 * the explicit model-facing tool order (forwarded to the system-prompt plugin);
 * `tools` is the tool registry's config (its presentation `mode`, forwarded
@@ -64,8 +59,6 @@ export interface Config {
  packChunks?: boolean
  /** JSONL artifact encoding; defaults to checksummed Zstandard frames. */
  persistenceCompression?: JsonlCompression
-  /** Cross-session reference discovery and snapshot byte budgets. */
-  sessionReferences?: SessionReferenceConfig
  /** Controls automatic AGENTS.md/CLAUDE.md loading; configure a byte budget or set `false`. */
  workspaceContext: agentCore.Config['workspaceContext']
  /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-spine-demo. */
@@ -74,7 +67,7 @@ export interface Config {
  toolBash?: NonNullable<agentCore.Config['toolBash']>
  /** Generic background-task controls forwarded through agent-core; set false to omit their tool surface. */
  toolTasks?: NonNullable<agentCore.Config['toolTasks']>
-  /** Persisted same-session goals; owner defaults enable them, or false disables the stack and command. */
+  /** Persisted same-session goals; owner defaults enable them, or false disables the stack and tools. */
  goals?: agentCore.GoalConfig | false
  /** Bounded transient model-request retry policy forwarded through agent-core. */
  llmRetry?: NonNullable<agentCore.Config['llmRetry']>
@@ -98,7 +91,6 @@ export const Config: z<Config> = z.object({
  persistenceRoot: z.string().default(DEFAULT_PERSISTENCE_ROOT),
  packChunks: z.boolean().default(false),
  persistenceCompression: JsonlCompressionSchema,
-  sessionReferences: SessionReferenceService.Config,
  workspaceContext: z.union([z.const(false), workspaceContext.Config]).required(),
  skills: agentCore.SkillConfigSchema,
  toolBash: agentCore.ToolBashConfigSchema,
@@ -109,7 +101,7 @@ export const Config: z<Config> = z.object({
 /* jscpd:ignore-end */

 /**
- * Compose the spine with the ACP front door. The agent-spine-demo bundle pre-creates
+ * Compose the spine with the ACP automation transport. The agent-spine-demo bundle pre-creates
 * NO agents (its `agents` list defaults to `[]`) and carries the deployment
 * `persona`; the JSONL backend and derived query index persist under
 * `persistenceRoot`; the ACP bridge owns stdout for JSON-RPC and creates one
@@ -118,26 +110,32 @@ export const Config: z<Config> = z.object({
 * attached until ACP agents have flushed their closing events. No logger, no
 * `hmr` — stdout stays pure.
 */
-export function apply(ctx: Context, config: Config): void {
+export async function apply(ctx: Context, config: Config): Promise<void> {
  const goals = config.goals ?? {}
  const persistenceRoot = config.persistenceRoot ?? DEFAULT_PERSISTENCE_ROOT
-  ctx.effect(function* () {
-    yield ctx.plugin(CommandService).dispose
-    if (goals !== false) yield ctx.plugin(commandGoal).dispose
-    yield ctx.plugin(agentCore, { ...agentCore.pickSpineConfig(config), goals }).dispose
-    yield ctx.plugin(UserInteractionService).dispose
+  await ctx.effect(async function* () {
+    const spine = ctx.plugin(agentCore, { ...agentCore.pickSpineConfig(config), goals })
+    await spine
+    yield spine.dispose
    // Same rationale as the Config schema above: each front door forwards its own
    // persistence passthroughs rather than sharing a facade with stdio-demo.
    /* jscpd:ignore-start */
-    yield ctx.plugin(SessionPersistenceJsonl, {
+    const persistence = ctx.plugin(SessionPersistenceJsonl, {
      root: persistenceRoot,
      ...config.packChunks !== undefined ? { packChunks: config.packChunks } : {},
      ...(config.persistenceCompression === undefined ? {} : { compression: config.persistenceCompression }),
-    }).dispose
+    })
+    await persistence
+    yield persistence.dispose
    /* jscpd:ignore-end */
-    yield ctx.plugin(sessionCheckpointPolicy).dispose
-    yield ctx.plugin(SessionQuerySqlite, { path: join(persistenceRoot, 'session-query.db') }).dispose
-    yield ctx.plugin(SessionReferenceService, config.sessionReferences ?? {}).dispose
-    yield ctx.plugin(acp, { provider: config.provider, model: config.model }).dispose
+    const checkpoint = ctx.plugin(sessionCheckpointPolicy)
+    await checkpoint
+    yield checkpoint.dispose
+    const query = ctx.plugin(SessionQuerySqlite, { path: join(persistenceRoot, 'session-query.db') })
+    await query
+    yield query.dispose
+    const transport = ctx.plugin(acp, { provider: config.provider, model: config.model })
+    await transport
+    yield transport.dispose
  }, 'acp-demo.composition')
 }
--- a/packages/examples/acp-demo/tests/acp-agent.spec.ts
+++ b/packages/examples/acp-demo/tests/acp-agent.spec.ts
@@ -5,10 +5,10 @@ import { join } from 'node:path'
 import { tmpdir } from 'node:os'
 import { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
-import { agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
-import { SessionId } from '@deepseek-ai/dsh-session'
+import { agentEvents } from '@deepseek-ai/dsh-agent'
 import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
 import type { Message } from '@deepseek-ai/dsh-llm'
+import { SessionId } from '@deepseek-ai/dsh-session'
 import * as acpAgent from '../src/index.ts'

 /**
@@ -32,9 +32,6 @@ async function mount(config: acpAgent.Config, withBash = false): Promise<Context
    })
  }
  await ctx.plugin(acpAgent, config)
-  // The bundle mounts its children inside apply() (not awaited there); let their
-  // fibers settle so the spine services are ready.
-  await new Promise(resolve => setTimeout(resolve, 50))
  return ctx
 }

@@ -82,7 +79,6 @@ describe('dsh-acp-demo composition', () => {
      persona: 'hi',
      persistenceRoot: '/tmp/dsh-acp-demo-test',
      persistenceCompression: 'none',
-      sessionReferences: { candidateLimit: 1 },
      skills: await isolatedSkillsConfig(),
      workspaceContext: false,
    })
@@ -90,24 +86,20 @@ describe('dsh-acp-demo composition', () => {
    expect(ctx.get('sessions')).toBeDefined()
    expect(ctx.get('sessionPersistence')).toBeDefined()
    expect(ctx.get('sessionQuery')).toBeDefined()
-    expect(ctx.get('sessionReferences')).toBeDefined()
+    expect(ctx.get('sessionReferences')).toBeUndefined()
    expect((ctx.get('sessionPersistence') as unknown as { config: { compression?: string } }).config.compression).toBe('none')
    expect(ctx.get('agentLoop')).toBeDefined()
-    expect(ctx.get('userInteraction')).toBeDefined()
+    expect(ctx.get('userInteraction')).toBeUndefined()
+    expect(ctx.get('commands')).toBeUndefined()
    expect(ctx.get('tools')?.get('ask_user_question')).toBeUndefined()
    expect(ctx.get('goals')).toBeDefined()
    expect(ctx.get('tools')?.get('get_goal')).toBeDefined()
-    const target = ctx.sessions.create(SessionId('candidate-target'))
-    ctx.sessions.create(SessionId('candidate-one'))
-    ctx.sessions.create(SessionId('candidate-two'))
-    await expect(ctx.sessionReferences.listCandidates({ id: target.id, session: target } as Agent))
-      .resolves.toHaveLength(1)
    // No pre-created agents — ACP session/new creates them on demand.
    expect(ctx.get('agents')!.list()).toHaveLength(0)
    await ctx.fiber.dispose()
  })

-  it('can explicitly omit the persisted-goal stack and its command', async () => {
+  it('can explicitly omit the persisted-goal stack', async () => {
    const ctx = await mount({
      provider: 'mock',
      model: 'mock',
@@ -115,12 +107,7 @@ describe('dsh-acp-demo composition', () => {
      workspaceContext: false,
    })
    expect(ctx.get('goals')).toBeUndefined()
-    const handle = await ctx.agents.create({
-      sessionId: 'disabled-goals' as import('@deepseek-ai/dsh-session').SessionId,
-      agentOptions: { provider: 'mock', model: 'mock' },
-    })
-    expect(ctx.commands.find(handle.agent, 'goal')).toBeUndefined()
-    await handle.dispose()
+    expect(ctx.get('tools')?.get('get_goal')).toBeUndefined()
    await ctx.fiber.dispose()
  })

@@ -131,8 +118,12 @@ describe('dsh-acp-demo composition', () => {
    // persistenceRoot, so the runtime fallback is the one that fires.
    const ctx = new Context()
    // No persona: covers the omitted-persona forwarding branch too.
-    acpAgent.apply(ctx, { provider: 'mock', model: 'mock', skills: await isolatedSkillsConfig(), workspaceContext: false })
-    await new Promise(resolve => setTimeout(resolve, 50))
+    await acpAgent.apply(ctx, {
+      provider: 'mock',
+      model: 'mock',
+      skills: await isolatedSkillsConfig(),
+      workspaceContext: false,
+    })
    expect(ctx.get('sessionPersistence')).toBeDefined()
    await ctx.fiber.dispose()
  })
@@ -153,8 +144,7 @@ describe('dsh-acp-demo composition', () => {
  it('uses default skill config when apply is called directly without skills', async () => {
    await withIsolatedSkillHomes(async () => {
      const ctx = new Context()
-      acpAgent.apply(ctx, { provider: 'mock', model: 'mock', workspaceContext: false })
-      await new Promise(resolve => setTimeout(resolve, 50))
+      await acpAgent.apply(ctx, { provider: 'mock', model: 'mock', workspaceContext: false })
      expect(ctx.skills).toBeDefined()
      expect(await ctx.skills.list()).toEqual([])
      await ctx.fiber.dispose()
--- a/packages/examples/acp-demo/tests/built-bin.e2e.ts
+++ b/packages/examples/acp-demo/tests/built-bin.e2e.ts
@@ -18,7 +18,6 @@ import { Readable, Writable } from 'node:stream'
 import { promisify } from 'node:util'
 import { zstdDecompress } from 'node:zlib'
 import { afterEach, describe, expect, it } from 'vitest'
-import { ACP_SESSION_REFERENCE_META_KEY } from '@deepseek-ai/dsh-acp'

 /**
 * Published-entry smoke: run `lib/bin.js` under plain Node in a symlinked external consumer and
@@ -36,8 +35,7 @@ const dshPackages = [
  'bash/bash-local', 'bash/tool-bash', 'context/workspace-context', 'support/invariants', 'ui/app-boot',
  'session-persistence/session-persistence',
  'session-persistence/session-checkpoint-policy', 'session-persistence/session-persistence-jsonl',
-  'session-query/session-query', 'session-query/session-query-sqlite',
-  'context/session-reference', 'ui/acp', 'examples/acp-demo', 'util/paths',
+  'acp/acp', 'examples/acp-demo', 'util/paths',
 ]
 const vendorPackages = [
  'cordis', 'loader', 'include', 'timer', 'hmr', 'logger-console',
@@ -45,8 +43,8 @@ const vendorPackages = [
 ]
 // Resolve ACP's declared third-party dependencies from that package, not this test: pnpm's strict
 // layout need not hoist them. Symlink those exact paths into the plain-Node consumer.
-const npmDeps = ['@agentclientprotocol/sdk', 'zod']
-const acpPkgDir = join(repoRoot, 'packages/ui/acp')
+const npmDeps = ['@agentclientprotocol/sdk']
+const acpPkgDir = join(repoRoot, 'packages/acp/acp')

 async function pkgName(absDir: string): Promise<string> {
  const json = JSON.parse(await readFile(join(absDir, 'package.json'), 'utf8')) as { name: string }
@@ -72,7 +70,7 @@ async function makeConsumer(): Promise<string> {
    await link(abs, await pkgName(abs), nm)
  }
  for (const dep of npmDeps) {
-    // Resolve from `ui/acp`'s package.json URL (the package that declares the
+    // Resolve from ACP's package.json URL (the package that declares the
    // dep), not this test file's location — `acp-agent` does not depend on these.
    const fromAcp = pathToFileURL(join(acpPkgDir, 'package.json')).href
    const resolved = fileURLToPath(import.meta.resolve(`${dep}/package.json`, fromAcp))
@@ -154,8 +152,12 @@ describe.skipIf(!existsSync(acpBin))('dsh-acp-demo BUILT bin (node lib/bin.js, n
      Writable.toWeb(child.stdin!) as WritableStream<Uint8Array>,
      Readable.toWeb(passthrough) as ReadableStream<Uint8Array>,
    )
+    const updates: SessionNotification['update'][] = []
    const makeClient = (_a: AcpAgent): Client => ({
-      sessionUpdate(_p: SessionNotification): Promise<void> { return Promise.resolve() },
+      sessionUpdate(params: SessionNotification): Promise<void> {
+        updates.push(params.update)
+        return Promise.resolve()
+      },
      requestPermission(_p: RequestPermissionRequest): Promise<RequestPermissionResponse> {
        return Promise.resolve({ outcome: { outcome: 'cancelled' } })
      },
@@ -163,33 +165,17 @@ describe.skipIf(!existsSync(acpBin))('dsh-acp-demo BUILT bin (node lib/bin.js, n
    const client = new ClientSideConnection(makeClient, stream)

    const init = await client.initialize({ protocolVersion: PROTOCOL_VERSION, clientCapabilities: {} })
-    // A response at all proves the built bin booted the bridge (the settle-race
-    // regression would exit before answering); loadSession proves the real app
-    // mounted, not a collapsed export shape.
-    expect(init.agentCapabilities?.loadSession).toBe(true)
-    expect(init.agentCapabilities?.sessionCapabilities?.list).toEqual({})
+    expect(init.agentCapabilities).toEqual({
+      promptCapabilities: { image: false, audio: false, embeddedContext: false },
+    })
    const sessionCwd = consumer
    const { sessionId } = await client.newSession({ cwd: sessionCwd, mcpServers: [] })
    const result = await client.prompt({ sessionId, prompt: [{ type: 'text', text: 'reply' }] })
    expect(result.stopReason).toBe('end_turn')
-    await expect.poll(async () => {
-      return (await client.listSessions({ cwd: sessionCwd })).sessions.find(candidate => candidate.sessionId === sessionId)
-    }).toMatchObject({
-      sessionId,
-      cwd: sessionCwd,
-      title: 'reply',
-    })
-    const listed = await client.listSessions({ cwd: sessionCwd })
-    const reference = listed.sessions.find(candidate => candidate.sessionId === sessionId)
-      ?._meta?.[ACP_SESSION_REFERENCE_META_KEY]
-    expect(reference).toBeTypeOf('object')
-    expect(reference).not.toBeNull()
-    expect(reference).toHaveProperty('uri')
-    if (typeof reference !== 'object' || reference === null || !('uri' in reference)) {
-      throw new Error('expected session reference metadata')
-    }
-    expect(reference.uri).toBeTypeOf('string')
-    expect(reference.uri).toMatch(/^dsh-session:[A-Za-z0-9_-]+$/u)
+    await expect.poll(() => updates).toEqual([{
+      sessionUpdate: 'agent_message_chunk',
+      content: { type: 'text', text: 'ACP BUILT OK' },
+    }])
    const sessionsRoot = join(sessionCwd, '.sessions')
    let log: string | undefined
    await expect.poll(async () => {
--- a/packages/examples/acp-demo/tests/load-path.e2e.ts
+++ b/packages/examples/acp-demo/tests/load-path.e2e.ts
@@ -17,11 +17,10 @@ import {
 } from '@agentclientprotocol/sdk'

 /**
- * Source-path Loader smoke through the package's own bin, covering initialize, session/new, and
- * session/load across the `unwrapExports` path implicated by postmortem 0001. Session creation and
- * unknown-id loading reach factories but not the model, so a dummy key is sufficient. The temp cwd
- * is also the session workspace, and an explicit root tsconfig keeps unbuilt path aliases resolvable
- * when the child starts outside the repository.
+ * Source-path Loader smoke through the package's own bin, covering the
+ * automation server's initialize and fresh-session path across the
+ * `unwrapExports` shape implicated by postmortem 0001. Session creation reaches
+ * the factory but not the model, so a dummy key is sufficient.
 */

 const binScript = fileURLToPath(new URL('../src/bin.ts', import.meta.url))
@@ -29,8 +28,8 @@ const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
 // Repo root is four levels up from packages/examples/acp-demo/tests.
 const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))

-// A minimal leaf that loads this app + the two backends — the same shape as
-// examples/acp-agent/cordis.yml, inlined so the package test owns its fixture.
+// A minimal opt-in leaf that loads this app + the two backends and the optional
+// session-query consumer/policies, inlined so the package test owns its fixture.
 const CORDIS_YML = `
 - id: llm-deepseek
  name: '@deepseek-ai/dsh-llm-deepseek'
@@ -45,6 +44,16 @@ const CORDIS_YML = `
    model: deepseek-v4-flash
    persona: 'You are a test agent.'
    workspaceContext: false
+- id: tool-session-query
+  name: '@deepseek-ai/dsh-tool-session-query'
+- id: timeout-policy
+  name: '@deepseek-ai/dsh-timeout-policy'
+- id: spill-local
+  name: '@deepseek-ai/dsh-spill-local'
+- id: spill-policy
+  name: '@deepseek-ai/dsh-spill-policy'
+  config:
+    maxInlineBytes: 50000
 `

 interface Spawned {
@@ -107,7 +116,7 @@ async function boot(): Promise<Spawned & { cwd: string }> {
 }

 describe('dsh-acp-demo real-load-path smoke (bin + Loader, keyless)', () => {
-  it('boots via its bin and answers initialize → session/new → session/load', async () => {
+  it('boots via its bin and exposes only fresh text sessions', async () => {
    const { client, cwd, stderr } = await boot()
    // initialize: a broken export shape (collapsed bridge plugin, dropped inject)
    // crashes the tree on the first service read here — see postmortem 0001.
@@ -115,22 +124,14 @@ describe('dsh-acp-demo real-load-path smoke (bin + Loader, keyless)', () => {
      protocolVersion: PROTOCOL_VERSION,
      clientCapabilities: {},
    })
-    expect(init.agentCapabilities?.loadSession).toBe(true)
+    expect(init.agentCapabilities).toEqual({
+      promptCapabilities: { image: false, audio: false, embeddedContext: false },
+    })

    // session/new reaches the agent FACTORY (create) without the model.
    const { sessionId } = await client.newSession({ cwd, mcpServers: [] })
    expect(sessionId).toBeTruthy()

-    // session/load reaches the resume FACTORY + persistence without the model: load an UNKNOWN
-    // id (loading the live `sessionId` would correctly reject as "already loaded"). Persistence
-    // and resume run from the JSON-RPC loop outside bridge injection; a healthy tree reaches
-    // not-found, while a collapsed export would fail earlier with missing injection.
-    const unknownId = '00000000-0000-4000-8000-000000000000'
-    await client.loadSession({ sessionId: unknownId, cwd, mcpServers: [] }).then(
-      () => { throw new Error('expected session/load of an unknown id to reject') },
-      (error: unknown) => { expect(String(error)).not.toContain('without inject') },
-    )
-
    expect(stderr.join('')).not.toContain('without inject')
  }, 30_000)
 })
--- a/packages/examples/acp-demo/tsconfig.json
+++ b/packages/examples/acp-demo/tsconfig.json
@@ -21,7 +21,10 @@
      "path": "../../ui/app-boot"
    },
    {
-      "path": "../../ui/acp"
+      "path": "../../acp/acp"
+    },
+    {
+      "path": "../../core/agent"
    },
    {
      "path": "../../session-query/session-query"
@@ -29,30 +32,12 @@
    {
      "path": "../../session-query/session-query-sqlite"
    },
-    {
-      "path": "../../context/session-reference"
-    },
-    {
-      "path": "../../ui/commands"
-    },
-    {
-      "path": "../../goal/command-goal"
-    },
-    {
-      "path": "../../core/agent"
-    },
    {
      "path": "../agent-spine-demo"
    },
    {
      "path": "../../context/workspace-context"
    },
-    {
-      "path": "../../ui/user-interaction"
-    },
-    {
-      "path": "../../ui/tool-ask-user"
-    },
    {
      "path": "../../session-persistence/session-checkpoint-policy"
    },
--- a/packages/examples/agent-spine-demo/README.md
+++ b/packages/examples/agent-spine-demo/README.md
@@ -45,7 +45,7 @@ The spine is everything COMMON to every front door. The swappable and front-door
 - **model-backed session-title providers** — the bundle mounts the fallback service with overridable example limits (5 words, 40 fallback bytes, 80 accepted-title bytes); a leaf may opt into exactly one first-message or all-messages LLM provider.
 - **the bash executor** — the bundle ships `tool-bash` (the consumer schema); the leaf provides `ctx.bash` (`bash-local` or a sandboxed impl).
 - **non-local skill providers** — the bundle ships the skill registry, the local filesystem provider, and the `skill` tool; deployments can add other providers such as embedded or remote catalogs as siblings.
- **presentation + per-app infra** — the terminal TUI or ACP front door and `hmr`. These form the coupled front-door cluster that the app packages ([`dsh-tui-demo`](../tui-demo/README.md), [`dsh-acp-demo`](../acp-demo/README.md)) bake in. `timer` is in the spine because it is common and stdout-silent; front doors own stdout and remain outside.
+- **front-door + per-app infra** — the terminal TUI or ACP automation transport and `hmr`. App packages ([`dsh-tui-demo`](../tui-demo/README.md), [`dsh-acp-demo`](../acp-demo/README.md)) own those choices. `timer` is in the spine because it is common and stdout-silent; front doors own stdout and remain outside.

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

@@ -63,7 +63,7 @@ For example, `{ invariants: { enabled: true, package_allowlist: ['^@deepseek-ai/

 ## Why a code bundle, not a shared YAML include

-A YAML include can deduplicate config but cannot own a bin or provide front-door defaults. App packages make stdout-safe ACP wiring the default, though a leaf can still add an unsafe logger. Bundle children register services in the root isolate-keyed store, so injected leaf siblings see them without load-order coupling.
+A YAML include can deduplicate config but cannot own a bin or provide front-door defaults. The ACP app package makes protocol-pure stdout wiring the default, though a leaf can still add an unsafe logger. Bundle children register services in the root isolate-keyed store, so injected leaf siblings see them without load-order coupling.

 The bounded retry policy may repeat a transiently failed request in a new numbered step. Retry status and failed partial chunks stay outside model history, each provider attempt can still incur billing, front doors derive usage across every logged step, and the reconstructed request preserves the prior prefix for provider cache reuse.

--- a/packages/examples/cli-demo/tsconfig.json
+++ b/packages/examples/cli-demo/tsconfig.json
@@ -3,8 +3,7 @@
  "compilerOptions": {
    "composite": true,
    "rootDir": "src",
-    "outDir": "lib/types",
-    "tsBuildInfoFile": "../../../.typecheck/cli-demo.tsbuildinfo"
+    "outDir": "lib/types"
  },
  "include": ["src/**/*.ts"],
  "references": [
--- a/packages/examples/tui-demo/README.md
+++ b/packages/examples/tui-demo/README.md
@@ -1,8 +1,8 @@
 # @deepseek-ai/dsh-tui-demo

-The full-screen terminal app: a Cordis plugin that composes [`@deepseek-ai/dsh-agent-spine-demo`](../agent-spine-demo/README.md), persisted same-session goals, the human-command registry and `/goal` producer, JSONL persistence, keyboard-backed user interaction, a pre-created `main` agent, and [`@deepseek-ai/dsh-tui`](../../ui/tui/README.md). Its `bin` boots a leaf `cordis.yml`.
+The full-screen terminal app bundle: a Cordis plugin that composes [`@deepseek-ai/dsh-agent-spine-demo`](../agent-spine-demo/README.md), persisted same-session goals, the human-command registry and `/goal` producer, JSONL persistence, keyboard-backed user interaction, a pre-created `main` agent, and [`@deepseek-ai/dsh-tui`](../../ui/tui/README.md). A `cordis.yml` mounts it as one entry; the [`dsh`](../../../apps/cli/README.md) CLI is the front door that boots such a config.

-Use [`@deepseek-ai/dsh-cli-demo`](../cli-demo/README.md) for pipes, scripts, and other non-interactive runs. This package requires a TTY pair and has no line-oriented fallback.
+Use [`@deepseek-ai/dsh-cli-demo`](../cli-demo/README.md) for pipes, scripts, and other non-interactive runs. This bundle requires a TTY pair and has no line-oriented fallback.

 ## What it bakes in

@@ -13,7 +13,7 @@ Use [`@deepseek-ai/dsh-cli-demo`](../cli-demo/README.md) for pipes, scripts, and
 | `@deepseek-ai/dsh-command-goal` | Direct `/goal` status and mutation over the spine's persisted-goal stack |
 | `@deepseek-ai/dsh-session-persistence-jsonl` | Durable session log under `persistenceRoot` |
 | `@deepseek-ai/dsh-session-checkpoint-policy` | Semantic durability barriers before model requests and top-level tool effects, plus completed-step checkpoints |
-| `@deepseek-ai/dsh-session-query-sqlite` + `@deepseek-ai/dsh-session-reference` | Combined exact/FTS session queries and bounded `@session` snapshots consumed by the TUI |
+| `@deepseek-ai/dsh-session-query-sqlite` + `@deepseek-ai/dsh-session-reference` | Combined exact/FTS session queries and bounded `@session` snapshots consumed by the TUI; model-facing query tools remain a leaf opt-in |
 | `@deepseek-ai/dsh-user-interaction` | Provider-neutral human question service |
 | `@deepseek-ai/dsh-tui` | Full-screen transcript, editor, tool cards, plan, and question overlays |
 | `@deepseek-ai/dsh-tool-ask-user` | Model-facing `ask_user_question` tool |
@@ -47,9 +47,9 @@ Swappable LLM, bash, filesystem, and other capability providers remain in the le

 Fresh runs mint a `main-session-<uuid>` session id and pass it to both the TUI and configured agent. Resumed runs bind both components to `resumeSessionId`. The TUI mounts before the spine so it can render a matching config-start failure instead of leaving a blank terminal. The app composes persistence and session query for `/resume`; an embedding host may additionally provide `tuiResumeHost` for in-place process handoff.

-## The bin
+## Front door

-`dsh-tui-demo [path-to-cordis.yml]` defaults to `./cordis.yml`, loads the optional cwd `.env`, boots the Cordis Loader, and waits for the full plugin tree. The repository installs Loader's optional native helper, so bare package specifiers resolve under plain Node.
+This package ships no bin. The [`dsh`](../../../apps/cli/README.md) CLI is the terminal front door: bare `dsh` boots the shipped `examples/tui-agent/cordis.yml` (which mounts this bundle), and `dsh --config <path-to-cordis.yml>` boots an alternate leaf config that mounts it. It loads the optional cwd `.env`, drives the Cordis Loader, and waits for the full plugin tree. The repository installs Loader's optional native helper, so bare package specifiers resolve under plain Node.

 ## Example leaf

--- a/packages/examples/tui-demo/package.json
+++ b/packages/examples/tui-demo/package.json
@@ -1,14 +1,11 @@
 {
  "name": "@deepseek-ai/dsh-tui-demo",
-  "description": "Full-screen terminal app: agent spine + persisted goals + human commands + JSONL persistence + pi-tui front door + pre-created main agent",
+  "description": "Full-screen TUI app bundle plugin: agent spine + persisted goals + human commands + JSONL persistence + pi-tui front door + pre-created main agent (mounted by the dsh CLI's config)",
  "version": "0.0.1",
  "private": true,
  "type": "module",
  "main": "lib/index.js",
  "types": "lib/types/index.d.ts",
-  "bin": {
-    "dsh-tui-demo": "lib/bin.js"
-  },
  "exports": {
    ".": {
      "types": "./lib/types/index.d.ts",
@@ -18,26 +15,19 @@
      "types": "./lib/types/invariant.d.ts",
      "default": "./lib/invariant.js"
    },
-    "./bin": {
-      "types": "./lib/types/bin.d.ts",
-      "default": "./lib/bin.js"
-    },
    "./src/*": "./src/*",
    "./package.json": "./package.json"
  },
  "files": [
    "lib/index.js",
    "lib/invariant.js",
-    "lib/bin.js",
    "lib/types/**/*.d.ts",
    "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-app-boot": "^0.0.1",
    "@deepseek-ai/dsh-agent": "^0.0.1",
    "@deepseek-ai/dsh-agent-loop": "^0.0.1",
    "@deepseek-ai/dsh-commands": "^0.0.1",
@@ -60,9 +50,7 @@
    "schemastery": "^3.17.0"
  },
  "devDependencies": {
-    "@cordisjs/plugin-include": "workspace:^",
    "@cordisjs/plugin-loader": "workspace:^",
-    "@deepseek-ai/dsh-app-boot": "workspace:^",
    "@deepseek-ai/dsh-agent": "workspace:^",
    "@deepseek-ai/dsh-agent-loop": "workspace:^",
    "@deepseek-ai/dsh-commands": "workspace:^",
--- a/packages/examples/tui-demo/src/bin.ts
+++ b/packages/examples/tui-demo/src/bin.ts
@@ -1,27 +0,0 @@
-#!/usr/bin/env node
-/**
- * Boot a TUI app from a leaf `cordis.yml`; usage is `dsh-tui-demo [config]`, defaulting to the
- * cwd file. Shared `.env` loading, fail-loud Loader guards, and settled-tree boot live in
- * dsh-app-boot. The tui-agent and cordis-agent demos invoke this bin with their own leaf configs.
- * @module @deepseek-ai/dsh-tui-demo/bin
- */
-
-import { boot, installFailLoud, loadEnv, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
-
-const NAME = 'dsh-tui-demo'
-
-/* v8 ignore start -- thin self-executing composition over the unit-tested
-   dsh-app-boot helpers; exercised end-to-end by the tui-agent PTY smoke and
-   the built-bin fail-loud smoke */
-// Refuse pipes BEFORE booting: a compose-time throw inside the Loader tree is
-// logged per-entry rather than rethrown, so a piped launch would otherwise
-// settle into an idle UI-less process instead of exiting nonzero.
-if (!process.stdin.isTTY || !process.stdout.isTTY) {
-  process.stderr.write(`${NAME}: the TUI requires stdin and stdout to be interactive TTYs; `
-    + 'use the one-shot dsh-cli-demo bin for pipes and automation\n')
-  process.exit(1)
-}
-installFailLoud(NAME)
-loadEnv(NAME)
-await boot(NAME, resolveConfigPath(process.argv[2] ?? './cordis.yml', undefined))
-/* v8 ignore stop */
--- a/packages/examples/tui-demo/src/index.ts
+++ b/packages/examples/tui-demo/src/index.ts
@@ -64,8 +64,8 @@ export interface Config {
  /**
   * Shell command template the TUI prints on exit and lists under `/resume`,
   * with `{session}` replaced by the live session id (forwarded to the front
-   * door). Set it to a command that resumes via this app's env var, e.g.
-   * `RESUME_SESSION_ID={session} dsh`.
+   * door). Set it to a command that resumes the session, e.g.
+   * `dsh --resume {session}`.
   */
  resumeCommand?: string
  /** Full-screen TUI presentation settings. */
--- a/packages/examples/tui-demo/tests/built-bin.e2e.ts
+++ b/packages/examples/tui-demo/tests/built-bin.e2e.ts
@@ -1,98 +0,0 @@
-import { spawn } from 'node:child_process'
-import { existsSync } from 'node:fs'
-import { mkdtemp, mkdir, rm, symlink, readFile } 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'
-
-/**
- * Published-entry smoke: run `lib/bin.js` under plain Node in a symlinked external consumer.
- * The TUI app owns no non-TTY fallback, so the piped subprocess must refuse to boot with a
- * nonzero exit and a stderr pointer at the one-shot CLI — the bin guards BEFORE the Loader
- * because a compose-time throw inside the tree is logged per-entry, not rethrown. The consumer
- * links only the bin's import chain (dsh-app-boot and its vendored Loader stack): the refusal
- * fires before any config is read, so no plugin tree is needed. Missing-config fail-loud and
- * full-boot coverage for the shared dsh-app-boot glue live in cli-demo's built-bin suite; it
- * skips before build, and interactive TTY behavior is PTY-covered by examples/tui-agent (the
- * one sanctioned PTY surface).
- */
-
-const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
-const tuiBin = join(repoRoot, 'packages/examples/tui-demo/lib/bin.js')
-
-// Symlink each package the bin imports at module load by package name so plain
-// Node resolves its built `main`, matching an installed dependency rather than
-// tsconfig paths.
-const dshPackages = ['examples/tui-demo', 'ui/app-boot']
-const vendorPackages = ['cordis', 'loader', 'include', 'schemastery', 'cosmokit']
-
-async function pkgName(absDir: string): Promise<string> {
-  const json = JSON.parse(await readFile(join(absDir, 'package.json'), 'utf8')) as { name: string }
-  return json.name
-}
-
-/** Build a temporary external consumer with built workspace/vendor links. */
-async function makeConsumer(): Promise<string> {
-  const dir = await mkdtemp(join(tmpdir(), 'tui-built-bin-'))
-  const nm = join(dir, 'node_modules')
-  for (const rel of dshPackages) {
-    const abs = join(repoRoot, 'packages', rel)
-    const target = join(nm, await pkgName(abs))
-    await mkdir(dirname(target), { recursive: true })
-    await symlink(abs, target)
-  }
-  for (const v of vendorPackages) {
-    const abs = join(repoRoot, 'vendor', v)
-    const target = join(nm, await pkgName(abs))
-    await mkdir(dirname(target), { recursive: true })
-    await symlink(abs, target)
-  }
-  return dir
-}
-
-/** Run the built bin in `cwd` with PIPED stdio; resolve with output + exit code. */
-function runBuiltBin(cwd: string): Promise<{ stdout: string; code: number; stderr: string }> {
-  return new Promise((resolve, reject) => {
-    // NO tsx — this is the published `node lib/bin.js` path; the guard fires
-    // before the Loader resolves the config tree.
-    const child = spawn(process.execPath, [tuiBin, './cordis.yml'], {
-      cwd,
-      env: { ...process.env, DSH_HOME: join(cwd, '.dsh'), DSH_AGENTS_HOME: join(cwd, '.agents') },
-      stdio: ['pipe', 'pipe', 'pipe'],
-    })
-    let stdout = ''
-    let stderr = ''
-    child.stdout.setEncoding('utf8')
-    child.stdout.on('data', (c: string) => { stdout += c })
-    child.stderr.setEncoding('utf8')
-    child.stderr.on('data', (c: string) => { stderr += c })
-    const timer = setTimeout(() => {
-      child.kill('SIGKILL')
-      reject(new Error(`built bin did not exit within 25s. stdout:\n${stdout}\nstderr:\n${stderr}`))
-    }, 25_000)
-    child.on('exit', (code) => { clearTimeout(timer); resolve({ stdout, code: code ?? -1, stderr }) })
-    child.on('error', (err) => { clearTimeout(timer); reject(err) })
-    child.stdin.end()
-  })
-}
-
-let consumer: string | undefined
-
-afterEach(async () => {
-  // Windows can briefly retain released handles after exit; retry removal.
-  if (consumer !== undefined) await rm(consumer, { recursive: true, force: true, maxRetries: 10, retryDelay: 100 })
-  consumer = undefined
-})
-
-describe.skipIf(!existsSync(tuiBin))('dsh-tui-demo BUILT bin (node lib/bin.js, no tsx)', () => {
-  it('refuses pipes LOUD (non-zero exit + stderr) before booting the Loader', async () => {
-    consumer = await makeConsumer()
-    const { stdout, code, stderr } = await runBuiltBin(consumer)
-    expect(code).not.toBe(0)
-    expect(stderr).toContain('requires stdin and stdout to be interactive TTYs')
-    expect(stderr).toContain('dsh-cli-demo')
-    // The refusal happens before any plugin mounts: stdout stays silent.
-    expect(stdout).toBe('')
-  }, 30_000)
-})
--- a/packages/examples/tui-demo/tests/tui-agent.spec.ts
+++ b/packages/examples/tui-demo/tests/tui-agent.spec.ts
@@ -1,4 +1,5 @@
 import { describe, expect, it } from 'vitest'
+import { join } from 'node:path'
 import type { Context } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
 import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
@@ -60,7 +61,7 @@ describe('dsh-tui-demo app', () => {
    ])
    expect(calls[0]?.config).toBeUndefined()
    expect(calls[2]?.config).toEqual({ root: '/tmp/tui-sessions', compression: 'none' })
-    expect(calls[4]?.config).toEqual({ path: '/tmp/tui-sessions/session-query.db' })
+    expect(calls[4]?.config).toEqual({ path: join('/tmp/tui-sessions', 'session-query.db') })
    expect(calls[5]?.config).toEqual({
      maxReferences: 2,
      candidateLimit: 7,
--- a/packages/examples/tui-demo/tsconfig.json
+++ b/packages/examples/tui-demo/tsconfig.json
@@ -14,12 +14,6 @@
    {
      "path": "../../../vendor/schemastery"
    },
-    {
-      "path": "../../../vendor/loader"
-    },
-    {
-      "path": "../../ui/app-boot"
-    },
    {
      "path": "../../core/agent"
    },
--- a/packages/examples/tui-demo/tsdown.config.ts
+++ b/packages/examples/tui-demo/tsdown.config.ts
@@ -1,14 +1,14 @@
 import { defineConfig } from 'tsdown'

 /**
- * tui-demo ships two entries: the plugin (`index`) and the CLI `bin`
- * (`bin`), the latter referenced by package.json `bin`/`exports["./bin"]`.
- * The root tsdown builds only `lib/types/index.js`, so this override adds
- * `lib/types/bin.js`. Declarations come from `tsc -b` (dts: false),
- * matching every package.
+ * tui-demo ships the plugin (`index`) and its invariant companion; the CLI
+ * front door is `dsh` (apps/cli), which mounts this bundle through its config.
+ * The root tsdown builds only `lib/types/index.js`, so this override adds the
+ * invariant entry. Declarations come from `tsc -b` (dts: false), matching
+ * every package.
 */
 export default defineConfig({
-  entry: ['lib/types/index.js', 'lib/types/invariant.js', 'lib/types/bin.js'],
+  entry: ['lib/types/index.js', 'lib/types/invariant.js'],
  outDir: 'lib',
  format: ['esm'],
  platform: 'node',