Merge pull request #88 from deepseek-ai/worktree-simplify-extract-examples

refactor(examples): extract the app spine into dsh-agent-core + app packages

.github/workflows/ci.yml

@@ -81,7 +81,7 @@ jobs:
       - name: Demo smoke test
         run: |
           set -euo pipefail
-          out=$(printf 'echo ci smoke\n' | timeout 60 node --expose-internals --import tsx examples/echo-agent/start.ts 2>&1)
+          out=$(printf 'echo ci smoke\n' | timeout 60 pnpm run demo:echo 2>&1)
           echo "$out"
           echo "$out" | grep -q '\[tool call\] echo({"text":"ci smoke"})'
           echo "$out" | grep -q '\[tool result\] ECHO: CI SMOKE'
@@ -89,3 +89,12 @@ jobs:
           # per-run session log named main-session-<uuid>.jsonl. Assert one exists.
           ls .sessions/_no-cwd/main-session-*.jsonl >/dev/null
           rm -rf .sessions
+
+      # The published `bin` is `lib/bin.js`, run under plain `node` by a real
+      # consumer — NOT the tsx dev path the demo smoke and demo:* scripts use.
+      # These keyless smokes boot the BUILT bins (this step runs AFTER the build)
+      # in a temp dir that mirrors a real install, catching a regression in the
+      # published artifact that tsx would mask. They self-skip if lib/ is absent,
+      # so the e2e job (which does not build) does not run them.
+      - name: Built-bin smoke test (published lib/bin.js under node)
+        run: pnpm exec vitest run --config vitest.e2e.config.ts packages/ui/stdio-agent/tests/built-bin.e2e.ts packages/ui/acp-agent/tests/built-bin.e2e.ts

AGENTS.md

@@ -52,6 +52,9 @@ packages/    Harness packages, grouped by role at packages/<group>/<pkg>/.
     tools/          tool registry + tools/execute waterfall
     agent/          Agent interface, registry, agent/* event vocabulary
     agent-loop/     THE concrete plugin: ReactLoopAgent + the loop driver
+    agent-core/     bundle plugin: the providerless/executor-less/UI-less spine
+                    (timer+llm+sessions+system-prompt+tools+agents+invariants+
+                    tool-bash+agent-loop) as code; forwards agent-loop's `agents`
   llm/            LLM capability family
     llm/            abstract LLM service + content-block vocabulary
     llm-deepseek/   DeepSeek API adapter (hand-rolled fetch/SSE)
@@ -67,6 +70,11 @@ packages/    Harness packages, grouped by role at packages/<group>/<pkg>/.
   ui/             product integration surfaces
     acp/            Agent Client Protocol bridge: drive the agent from an ACP
                     editor (Zed) over JSON-RPC stdio
+    stdio-agent/    stdio chat APP: agent-core spine + console logger + readline
+                    UI + a pre-created main agent + a bin (the demo:echo/coding
+                    front door)
+    acp-agent/      ACP server APP: agent-core spine + JSONL persistence + the
+                    acp bridge, NO stdout logger + a bin (the demo:acp front door)
   support/        dev/test/example infrastructure (lower compat expectations)
     invariants/     dev-mode event-contract invariants + session-log freeze
     ui-stdio/       minimal stdio (readline) UI plugin: renders agent/* events,
@@ -76,15 +84,17 @@ packages/    Harness packages, grouped by role at packages/<group>/<pkg>/.
   util/           low-level zero-dependency utilities shared across groups
     brand/          type-only Branded<B> nominal-typing primitive (no runtime
                     code, no harness deps; owns the brand for cross-boundary ids)
-examples/    Runnable demos (not workspaces; see examples/AGENTS.md). echo-agent
-             = mock model + echo tool + stdio UI + JSONL persistence, wired via
-             cordis.yml. coding-agent = the real thing: DeepSeek V4 + bash tools
-             (pnpm run demo:coding, needs DEEPSEEK_API_KEY).
-             acp-agent = the coding agent exposed as an ACP server over
-             JSON-RPC stdio (pnpm run demo:acp, needs DEEPSEEK_API_KEY).
-             base.yml = shared provider/tool core both real demos include
-             (= base-core.yml, the providerless core, + the llm-deepseek adapter;
-             base-core.yml is reused by the acp-agent snapshot-replay config).
+examples/    Runnable demos (not workspaces; see examples/AGENTS.md). Each is a
+             THIN leaf cordis.yml: it picks the swappable backends (an LLM adapter,
+             a bash executor) and loads ONE app package (dsh-stdio-agent or
+             dsh-acp-agent), which bundles the agent-core spine + front-door
+             cluster + boot glue (a bin). No start.ts. echo-agent = mock model +
+             echo tool on dsh-stdio-agent (pnpm run demo:echo, no key).
+             coding-agent = the real thing: DeepSeek V4 + bash tools on the same
+             app (pnpm run demo:coding, needs DEEPSEEK_API_KEY). acp-agent = the
+             coding agent as an ACP server on dsh-acp-agent (pnpm run demo:acp,
+             needs DEEPSEEK_API_KEY). cordis.snapshot.yml = the acp leaf with
+             llm-replay for keyless snapshot replay.
 docs/        architecture.md — the design doc. module-graph.md — generated
              inter-package dependency graph (Mermaid; `pnpm run gen-module-graph`).
              rfc/ — design decisions and proposals, one kind of doc grouped by

docs/architecture.md

@@ -39,7 +39,7 @@ For a catalog of the **data structures** this architecture moves around — the
 └─────────────────────────────────────────────────────────────┘
 ```
 
-Dependency rule: plugins depend on interface packages, never on `dsh-agent-loop`. The loop itself is swappable — UI/hook/tool plugins keep working against the `dsh-agent` vocabulary if the loop is replaced.
+Dependency rule: **extension** plugins depend on interface packages, never on `dsh-agent-loop`. The loop itself is swappable — UI/hook/tool plugins keep working against the `dsh-agent` vocabulary if the loop is replaced. The one sanctioned exception is a **composition/bundle** package whose job IS to assemble the concrete spine: `dsh-agent-core` bundles `dsh-agent-loop` (and the other concrete spine plugins) by design, so it depends on the concrete loop on purpose. The rule constrains plugins that EXTEND the system, not the bundle that COMPOSES it — swapping the loop means publishing a different bundle, not rewiring every extension.
 
 ## Service map
 

docs/cookbook/extension-cookbook.md

@@ -83,4 +83,4 @@ export function apply(ctx: Context) {
 
 ## Runnable wirings
 
-Three complete examples load their plugin trees from `cordis.yml` with HMR: [`examples/echo-agent`](../../examples/echo-agent) (mock model + echo tool — the all-mock skeleton check, `pnpm run demo:echo`), [`examples/coding-agent`](../../examples/coding-agent) (DeepSeek V4 + the bash tool suite — the real thing, `pnpm run demo:coding`), and [`examples/acp-agent`](../../examples/acp-agent) (the same coding agent exposed as an ACP server over JSON-RPC stdio — the client-driver shape, `pnpm run demo:acp`). The two real demos share their provider/tool core via [`examples/base.yml`](../../examples/base.yml).
+Three complete examples load their plugin trees from `cordis.yml`: [`examples/echo-agent`](../../examples/echo-agent) (mock model + echo tool — the all-mock skeleton check, `pnpm run demo:echo`), [`examples/coding-agent`](../../examples/coding-agent) (DeepSeek V4 + the bash tool suite — the real thing, `pnpm run demo:coding`), and [`examples/acp-agent`](../../examples/acp-agent) (the same coding agent exposed as an ACP server over JSON-RPC stdio — the client-driver shape, `pnpm run demo:acp`). Each leaf is now just its swappable backends plus an app-package entry: the stdio demos load [`@deepseek-ai/dsh-stdio-agent`](../../packages/ui/stdio-agent), the ACP demo loads [`@deepseek-ai/dsh-acp-agent`](../../packages/ui/acp-agent), and both app packages share the spine via the [`@deepseek-ai/dsh-agent-core`](../../packages/core/agent-core) bundle.

docs/module-graph.md

@@ -49,6 +49,22 @@ graph TD
   tool-bash --> bash
   tool-bash --> llm
   tool-bash --> tools
+  agent-core --> agent
+  agent-core --> agent-loop
+  agent-core --> invariants
+  agent-core --> llm
+  agent-core --> session
+  agent-core --> system-prompt
+  agent-core --> tool-bash
+  agent-core --> tools
+  acp-agent --> acp
+  acp-agent --> agent-core
+  acp-agent --> session-persistence-jsonl
+  stdio-agent --> agent
+  stdio-agent --> agent-core
+  stdio-agent --> session
+  stdio-agent --> session-persistence-jsonl
+  stdio-agent --> ui-stdio
 ```
 
 | Package | Depends on |
@@ -72,3 +88,6 @@ graph TD
 | `acp` | `agent`, `llm`, `session`, `session-persistence`, `tools` |
 | `agent-loop` | `agent`, `llm`, `session`, `session-persistence`, `system-prompt`, `tools` |
 | `tool-bash` | `agent`, `bash`, `llm`, `tools` |
+| `agent-core` | `agent`, `agent-loop`, `invariants`, `llm`, `session`, `system-prompt`, `tool-bash`, `tools` |
+| `acp-agent` | `acp`, `agent-core`, `session-persistence-jsonl` |
+| `stdio-agent` | `agent`, `agent-core`, `session`, `session-persistence-jsonl`, `ui-stdio` |

docs/rfc/README.md

@@ -58,7 +58,6 @@ Do NOT write one for a mechanical or local choice (a variable name, a one-file r
 |---|---|
 | [Runtime schemas for the event vocabulary (Zod vs the merge-extensible-map pattern)](proposed/architecture/2026-06-16-typed-event-schemas.md) | 2026-06-16 |
 | [Extract a generic long-running tool runtime](proposed/architecture/2026-06-20-generic-long-running-tool-runtime.md) | 2026-06-20 |
-| [Extract example apps into packages](proposed/architecture/2026-06-20-extract-example-app-packages.md) | 2026-06-20 |
 
 ### Process
 
@@ -115,6 +114,7 @@ Do NOT write one for a mechanical or local choice (a variable name, a one-file r
 | [Agent lifecycle and ownership seams](implemented/architecture/2026-06-18-agent-lifecycle-and-ownership-seams.md) | 2026-06-18 |
 | [Reorganize packages into a modular hierarchy](implemented/architecture/2026-06-20-package-hierarchy.md) | 2026-06-20 |
 | [Branded IDs everywhere they belong](implemented/architecture/2026-06-20-branded-ids.md) | 2026-06-20 |
+| [Extract example apps into packages](implemented/architecture/2026-06-20-extract-example-app-packages.md) | 2026-06-20 |
 
 ### Process
 

docs/rfc/implemented/architecture/2026-06-20-extract-example-app-packages.md

@@ -0,0 +1,53 @@
+# RFC: Extract example apps into packages
+
+Status: implemented
+
+## Problem
+
+An example folder is supposed to be *thin* — the variable wiring of a demo, not the demo's machinery. Before this change it was thick. Each example carried a hand-rolled `start.ts` boot bootstrap, an infra preamble (`timer`, and — for the stdio demos — `logger` + `hmr`), nested includes of three shared YAML fragments (`base.yml` / `base-core.yml` / `acp-agent/acp-tail.yml`), and per-example `agent-loop`/persistence/system-prompt config. The actual app — the spine of services every agent needs — was spread across the leaf and those includes.
+
+The deeper problem was a **coupled front-door cluster** that lived at the leaf with nothing enforcing it. Choosing the ACP bridge over `ui-stdio` was not one swappable line: an ACP server must **drop the stdout console logger** (stdout is the JSON-RPC channel — a stray log corrupts the frames) and pre-create **no** agents (ACP `session/new` creates them on demand), whereas the stdio app needs a console logger and a pre-created `main`. (`timer` is the one infra plugin common to both — it writes nothing to stdout — so it belongs in the shared spine, not the cluster.) That coupling was enforced only by prose warnings in the leaf YAML. A leaf that wired a console logger into the ACP config was a one-line, comment-only mistake away — exactly the [stdout-purity footgun](../feature/2026-06-18-acp-terminal-and-tool-rendering.md) the examples guarded by hand. The three `start.ts` files also duplicated the Loader-boot tail, the `.env` loader, and (for ACP) snapshot-mode branching and the stdin-dispose lifecycle.
+
+## What shipped
+
+Each example is now **mostly an invocation of an app package**, splitting the wiring along the existing [interface / implementation / consumer seam](2026-06-13-capability-seams.md): the **app package owns the composition**, the leaf `cordis.yml` owns only the **swappable choices** (which LLM adapter, which bash executor, model, prompt, persistence root).
+
+- **`@deepseek-ai/dsh-agent-core`** ([packages/core/agent-core](../../../../packages/core/agent-core)) — a Cordis bundle plugin for the providerless, executor-less, UI-less spine: `timer` + `llm` + sessions + system-prompt + tools + agents + invariants + `tool-bash` + `agent-loop`, mounted as child plugins inside its `apply(ctx)` via `ctx.plugin(...)`. This is the old `base-core.yml` **minus** `bash-local`, **plus** `timer` and the loop, as code instead of a YAML include. The bundle **forwards** `agent-loop`'s `agents` list as its own config (`export const Config = AgentLoop.Config`, default `[]`, the existing `AgentLoop.Config` shape in [packages/core/agent-loop/src/index.ts](../../../../packages/core/agent-loop/src/index.ts)) — so each app supplies its own pre-created agents. This is precisely the reason the old `base-core.yml` gave for keeping `agent-loop` *out* of the shared core ("the examples disagree — stdio needs a pre-created `main`, acp needs none"); forwarding the config dissolves that objection — the loop is shared, the agents list is per-app. The bundle children register into the root service store, so a leaf-mounted sibling (the adapter, the executor) sees them exactly as a nested `plugin-include` subtree's services were seen before. Depending on the CONCRETE `dsh-agent-loop` (not just the `dsh-agent` interface) is deliberate and is the sanctioned exception to the "extension plugins depend on interfaces, never on the concrete loop" rule (packages/README.md, docs/architecture.md § Layering): the rule constrains plugins that EXTEND the system, whereas this bundle's whole job is to COMPOSE the concrete spine. Swapping the loop means publishing a different bundle, not rewiring every extension.
+- **`@deepseek-ai/dsh-stdio-agent`** ([packages/ui/stdio-agent](../../../../packages/ui/stdio-agent)) and **`@deepseek-ai/dsh-acp-agent`** ([packages/ui/acp-agent](../../../../packages/ui/acp-agent)) — app packages, each consuming `dsh-agent-core` and **baking in its coupled front-door cluster**: stdio = `ui-stdio` + console logger + a pre-created `main`; acp = the `acp` bridge + JSONL persistence + **no stdout logger** + no pre-created agents. The leaf no longer carries the cluster, so it has no logger entry to copy wrong by default — the common stdout-purity mistake loses its foothold. (A leaf can still *add* a sibling logger entry — a package cannot forbid what a leaf author writes — so the rule "never add a stdout logger to an ACP leaf" stays documented at the leaf; what changed is that the default leaf has nothing to get wrong.) They land under the existing `ui` group alongside `acp`, so no new package group (and no `tsconfig`/`packages/README` group plumbing) was needed.
+- **`start.ts` is gone.** Each app package exposes a `bin` (`dsh-stdio-agent` / `dsh-acp-agent`); the `demo:*` scripts invoke it (e.g. `dsh-stdio-agent ./cordis.yml`). The Loader-boot tail, `.env` loading, snapshot-mode selection, and stdin-dispose lifecycle moved into that bin, owned by the app. The `bin.ts` files are coverage-excluded (a self-executing CLI entry, like the old `start.ts`) and driven by the keyless Loader-path tests.
+- **Each leaf `cordis.yml` collapses** to backends + config: the LLM adapter (`llm-deepseek` with apiKey/models, or `llm-replay`), the bash executor (`bash-local`), `hmr` for the stdio demos (see the amendment below), and one app entry carrying the app's config (model, system prompt, persistence root — surfaced as the app package's own `Config`, which routes each value to wherever the app wires it: stdio onto its pre-created agent, acp onto the bridge plugin).
+- **echo-agent folds onto `dsh-stdio-agent`**, swapping the LLM backend to the local `mock-llm` and adding the local `echo-tool` (plus `bash-local`, which the spine's `tool-bash` injects) at the leaf — the clean demonstration of "swap the backend, keep the app". `mock-llm.ts` / `echo-tool.ts` stay as example-local teaching plugins.
+- **`base.yml`, `base-core.yml`, and `acp-agent/acp-tail.yml` are retired** — the spine they shared now lives in `dsh-agent-core`.
+
+`bash-local` and the LLM adapter stay **leaf choices**: the bundle ships `tool-bash` (the consumer schema), the leaf picks the executor implementation, so a sandboxed executor or replay adapter swaps in without touching the app.
+
+### Amendment on implementation: `hmr` stays a leaf entry
+
+The proposal listed `hmr` among the stdio app's baked-in front-door cluster. Validating against the code, baking `hmr` into the `dsh-stdio-agent` package fights cordis in two ways, so it ships as a **leaf `cordis.yml` entry** instead:
+
+1. `@cordisjs/plugin-hmr` is a Loader-only, subprocess-only dev plugin — its constructor throws without `node --expose-internals` + a live `loader` service, so it can only run in the real `demo:*`/bin subprocess, never in the in-process unit/coverage tier.
+2. The in-process test tier (vitest) cannot even *import* the vendored `hmr` module (its class-decorator `@Inject` form fails under Vite's transform), so a package whose `apply` statically imported it could never satisfy the per-file 100% coverage gate on its headline function.
+
+Crucially, `hmr` is **not** a stdout-purity footgun the way the console logger is — a stray `hmr` in the ACP config would not corrupt the JSON-RPC frames — so leaving it at the leaf costs none of the safety the coupling argument is about. The **logger** (the real coupling) stays baked in: the stdio app includes it, the ACP app omits it.
+
+## Why not keep the wiring in shared YAML includes?
+
+The old `base*.yml`/`acp-tail.yml` includes already deduped the *config*, but a YAML include cannot **encapsulate** the front-door coupling — it can only describe it in a comment and trust every leaf to obey. It also cannot own a `bin`, so the boot glue stayed copied across three `start.ts` files. A package turns "the ACP app never logs to stdout" from a prose warning into a property of the artifact: there is no logger entry in the leaf to get wrong.
+
+## Verification
+
+- Each example directory is `cordis.yml` (+ the acp `cordis.snapshot.yml`) + `README.md` + tests only — no `start.ts`, no infra preamble; `base.yml`/`base-core.yml`/`acp-tail.yml` are gone.
+- `demo:echo` / `demo:coding` / `demo:acp` run via the app-package `bin`s.
+- The new packages carry the per-file 100% coverage gate and a README like every `@deepseek-ai/dsh-*`. Each app package has a keyless **real-load-path** smoke that boots it through its `bin` + the cordis Loader (not a hand-built `ctx.plugin({...})` mount), guarding the `unwrapExports` export-shape bug class ([postmortem 0001](../../../postmortem/0001-acp-default-export-drops-inject.md)).
+- The ACP snapshot **replay** transcript is unchanged: the boot restructuring preserved the plugin set + load order, so `pnpm run test:snapshot` stays green against the committed goldens with no re-record.
+
+## What we give up
+
+- **The bare-plugin-tree pedagogy.** echo-agent's inlined `cordis.yml` showed every plugin at once; the spine now lives behind a bundle, so seeing the whole tree means opening `dsh-agent-core`. The app package's README carries that teaching weight.
+- **A layer of indirection.** "What does this demo load?" becomes a package read, not a single YAML scan.
+
+## Related
+
+- Supersedes [Make the shared example base providerless](../../rejected/architecture/2026-06-20-providerless-example-base.md): renaming `base.yml` to the providerless core is moot once the spine moves into `dsh-agent-core` and the `base*.yml` files are deleted.
+- Builds on the [capability-seams](2026-06-13-capability-seams.md) interface/implementation/consumer split — backends and presentation stay leaf choices; the spine is the shared bundle.
+- Complements [Reorganize packages into a modular hierarchy](2026-06-20-package-hierarchy.md): the new app/core packages slot into existing groups under that hierarchy (`core` for the reusable spine bundle, `ui` for the app-specific front doors).

docs/rfc/implemented/testing/2026-06-19-acp-snapshot-tests.md

@@ -46,7 +46,7 @@ Replay is positional: the Nth `stream()` call serves the Nth `ReplayEntry`. This
 
 Recording runs the scenario with the real `llm-deepseek` adapter and the JSONL persistence backend, then copies the produced `.jsonl` into the scenario dir. Per-event appends are durable, but the harness shuts the subprocess down gracefully (close stdin → `await ctx.dispose()`) before harvesting so the final events are flushed. `llm-replay` itself does no recording — it is replay-only.
 
-`examples/base.yml` always loads `@deepseek-ai/dsh-llm-deepseek`, whose `apply` throws when no API key is present ([packages/llm/llm-deepseek/src/index.ts](../../../../packages/llm/llm-deepseek/src/index.ts)). So replay cannot reuse the normal config — it uses a dedicated `examples/acp-agent/cordis.snapshot.yml` that installs `llm-replay` in place of the adapter. To avoid duplicating the rest of the tree, the providerless core is factored into `examples/base-core.yml` (shared by `base.yml = base-core + llm-deepseek` and the replay config = `base-core + llm-replay`), and the agent-loop/persistence/ACP-bridge tail into `examples/acp-agent/acp-tail.yml` (shared by `cordis.yml` and the replay config). Recording reuses the normal `cordis.yml` (real adapter) — its persistence root reads `$DSH_SNAPSHOT_SESSIONS_ROOT` when the harness sets it — so there is no separate record config. In replay mode `start.ts` skips `.env` loading so a stray key cannot trigger a live call.
+The ACP server app loads `@deepseek-ai/dsh-llm-deepseek`, whose `apply` throws when no API key is present ([packages/llm/llm-deepseek/src/index.ts](../../../../packages/llm/llm-deepseek/src/index.ts)). So replay cannot reuse the normal config — it uses a dedicated `examples/acp-agent/cordis.snapshot.yml` that installs `llm-replay` in place of the adapter. The rest of the tree is not duplicated: both the normal `examples/acp-agent/cordis.yml` and the replay config load the same `@deepseek-ai/dsh-acp-agent` app entry (which bundles the agent-core spine + JSONL persistence + the ACP bridge), differing only in the LLM backend (`llm-deepseek` vs `llm-replay`) and the bash executor line. Recording reuses the normal `cordis.yml` (real adapter) — its persistence root reads `$DSH_SNAPSHOT_SESSIONS_ROOT` when the harness sets it — so there is no separate record config. The `dsh-acp-agent` bin selects `cordis.snapshot.yml` for `DSH_SNAPSHOT=replay` and skips `.env` loading in that mode so a stray key cannot trigger a live call.
 
 ### Two surfaces: normalize, then compare
 

docs/rfc/proposed/architecture/2026-06-20-extract-example-app-packages.md

@@ -1,44 +0,0 @@
-# RFC: Extract example apps into packages
-
-Status: proposed
-
-## Problem
-
-An example folder is supposed to be *thin* — the variable wiring of a demo, not the demo's machinery. Today it is thick. Each example carries a hand-rolled `start.ts` boot bootstrap, an infra preamble (`timer`, and — for the stdio demos — `logger` + `hmr`), nested includes of three shared YAML fragments, and per-example `agent-loop`/persistence/system-prompt config. The actual app — the spine of services every agent needs — is spread across the leaf and the [base.yml](../../../../examples/base.yml) / [base-core.yml](../../../../examples/base-core.yml) / [acp-tail.yml](../../../../examples/acp-agent/acp-tail.yml) includes.
-
-The deeper problem is a **coupled front-door cluster** that lives at the leaf with nothing enforcing it. Choosing the ACP bridge over `ui-stdio` is not one swappable line: an ACP server must **drop the stdout console logger** (stdout is the JSON-RPC channel — a stray log corrupts the frames), omit `hmr` (the editor owns the subprocess), and pre-create **no** agents (ACP `session/new` creates them on demand), whereas the stdio app needs a console logger, `hmr`, and a pre-created `main`. (`timer` is the one infra plugin common to both — it writes nothing to stdout — so it belongs in the shared spine, not the cluster.) Today that coupling is enforced only by prose warnings in [acp-agent/cordis.yml](../../../../examples/acp-agent/cordis.yml) and [base-core.yml](../../../../examples/base-core.yml). A leaf that wires a console logger into the ACP config is a one-line, comment-only mistake away — exactly the [stdout-purity footgun](../../implemented/feature/2026-06-18-acp-terminal-and-tool-rendering.md) the examples guard by hand. The three `start.ts` files also duplicate the Loader-boot tail, the `.env` loader, and (for ACP) snapshot-mode branching and the stdin-dispose lifecycle.
-
-## Proposal
-
-Make each example **mostly an invocation of an app package**, splitting the wiring along the existing [interface / implementation / consumer seam](../../implemented/architecture/2026-06-13-capability-seams.md): the **app package owns the composition**, the leaf `cordis.yml` owns only the **swappable choices** (which LLM adapter, which bash executor, model, prompt, persistence root).
-
-- **`@deepseek-ai/dsh-agent-core`** — a Cordis bundle plugin for the providerless, executor-less, UI-less spine: `timer` + `llm` + sessions + system-prompt + tools + agents + invariants + `tool-bash` + `agent-loop`. This is today's [base-core.yml](../../../../examples/base-core.yml) **minus** `bash-local`, **plus** `timer` and the loop, as code instead of a YAML include. The bundle **forwards** `agent-loop`'s `agents` list as its own config (default `[]`, exactly the existing `AgentLoop.Config` shape in [packages/core/agent-loop/src/index.ts](../../../../packages/core/agent-loop/src/index.ts)) — so each app supplies its own pre-created agents. This is precisely the reason [base-core.yml](../../../../examples/base-core.yml) gives today for keeping `agent-loop` *out* of the shared core ("the examples disagree — stdio needs a pre-created `main`, acp needs none"); forwarding the config dissolves that objection — the loop is shared, the agents list is per-app.
-- **`@deepseek-ai/dsh-stdio-agent`** and **`@deepseek-ai/dsh-acp-agent`** — app packages, each consuming `dsh-agent-core` and **baking in its coupled front-door cluster**: stdio = `ui-stdio` + console logger + `hmr` + a pre-created `main`; acp = the `acp` bridge + **no stdout logger** + no `hmr` + no pre-created agents. The coupling becomes structurally unreachable from the leaf.
-- **Drop `start.ts`.** Each app package exposes a `bin`; the `demo:*` scripts invoke it (e.g. `dsh-stdio-agent ./cordis.yml`). The Loader-boot tail, `.env` loading, snapshot-mode selection, and stdin-dispose lifecycle move into that bin, owned by the app.
-- **Collapse each leaf `cordis.yml`** to backends + config: the LLM adapter (`llm-deepseek` with apiKey/models, or `llm-replay`), the bash executor (`bash-local`), and one app-bundle entry carrying the app's config (model, system prompt, persistence root — surfaced as the app package's own `Config`, which routes each value to wherever the app wires it: stdio onto its pre-created agent, acp onto the bridge plugin). A handful of entries, no infra preamble.
-- **Fold echo-agent onto `dsh-stdio-agent`**, swapping the LLM backend to the local `mock-llm` and adding the local `echo-tool` at the leaf — the clean demonstration of "swap the backend, keep the app". `mock-llm.ts` / `echo-tool.ts` stay as example-local teaching plugins.
-- **Retire** [base.yml](../../../../examples/base.yml), [base-core.yml](../../../../examples/base-core.yml), and [acp-tail.yml](../../../../examples/acp-agent/acp-tail.yml) — the spine they shared now lives in `dsh-agent-core`.
-
-`bash-local` and the LLM adapter stay **leaf choices**: the bundle ships `tool-bash` (the consumer schema), the leaf picks the executor implementation, so a sandboxed executor or replay adapter swaps in without touching the app.
-
-## Why not keep the wiring in shared YAML includes?
-
-The `base*.yml`/`acp-tail.yml` includes already dedupe the *config*, but a YAML include cannot **encapsulate** the front-door coupling — it can only describe it in a comment and trust every leaf to obey. It also cannot own a `bin`, so the boot glue stays copied across three `start.ts` files. A package turns "the ACP app never logs to stdout" from a prose warning into a property of the artifact: there is no logger entry in the leaf to get wrong.
-
-## Acceptance criteria
-
-- Each example directory is `cordis.yml` + `README.md` + tests only — no `start.ts`, no infra preamble; `base.yml`/`base-core.yml`/`acp-tail.yml` are gone.
-- `demo:echo` / `demo:coding` / `demo:acp` run via the app-package `bin`s.
-- `pnpm run test`, `pnpm run test:snapshot` (re-recorded), `pnpm run typecheck`, `pnpm run knip`, `pnpm run publint`, and `pnpm run doc-sync` are green; the new packages carry the per-file 100% coverage gate and a README like every `@deepseek-ai/dsh-*`.
-
-## What we give up
-
-- **The bare-plugin-tree pedagogy.** echo-agent's inlined `cordis.yml` showed every plugin at once; the spine now lives behind a bundle, so seeing the whole tree means opening `dsh-agent-core`. The app package's README must carry that teaching weight.
-- **A layer of indirection.** "What does this demo load?" becomes a package read, not a single YAML scan.
-- **Migration cost** (the implementing PR, not this one): three new packages, three leaf rewrites, the boot glue moved into bins, re-recorded ACP snapshots, and rewritten example READMEs + [examples/AGENTS.md](../../../../examples/AGENTS.md).
-
-## Related
-
-- Supersedes [Make the shared example base providerless](../../rejected/architecture/2026-06-20-providerless-example-base.md): renaming `base.yml` to the providerless core is moot once the spine moves into `dsh-agent-core` and the `base*.yml` files are deleted.
-- Builds on the [capability-seams](../../implemented/architecture/2026-06-13-capability-seams.md) interface/implementation/consumer split — backends and presentation stay leaf choices; the spine is the shared bundle.
-- Complements [Reorganize packages into a modular hierarchy](../../implemented/architecture/2026-06-20-package-hierarchy.md): the new app/core packages slot into a group under that hierarchy (a product group for the reusable core bundle, or alongside the examples for app-specific wiring).

docs/rfc/rejected/architecture/2026-06-20-providerless-example-base.md

@@ -1,23 +1,23 @@
 # RFC: Make the shared example base providerless
 
-Status: rejected — superseded by [Extract example apps into packages](../../proposed/architecture/2026-06-20-extract-example-app-packages.md), which moves the spine into a `dsh-agent-core` bundle and deletes the `base*.yml` files, so there is no shared base YAML left to rename.
+Status: rejected — superseded by [Extract example apps into packages](../../implemented/architecture/2026-06-20-extract-example-app-packages.md), which moves the spine into a `dsh-agent-core` bundle and deletes the `base*.yml` files, so there is no shared base YAML left to rename.
 
 ## Problem
 
-The examples have two shared base files: [examples/base-core.yml](../../../../examples/base-core.yml) is providerless, while [examples/base.yml](../../../../examples/base.yml) includes that core plus the real `llm-deepseek` adapter. Snapshot replay needs the providerless core with `llm-replay`, because loading the real adapter without a key throws. The normal demos need the real adapter. The result is a naming inversion: the file named `base.yml` is not the reusable base for all examples, while the true base is `base-core.yml`.
+The examples had two shared base files: `examples/base-core.yml` was providerless, while `examples/base.yml` included that core plus the real `llm-deepseek` adapter. Snapshot replay needs the providerless core with `llm-replay`, because loading the real adapter without a key throws. The normal demos need the real adapter. The result was a naming inversion: the file named `base.yml` was not the reusable base for all examples, while the true base was `base-core.yml`.
 
-The split is understandable, but it makes every config explanation longer. It also leads to awkward test setup like a keyless smoke test carrying a dummy API key so an adapter can boot even though the model is not called.
+The split was understandable, but it made every config explanation longer. It also led to awkward test setup like a keyless smoke test carrying a dummy API key so an adapter could boot even though the model is not called.
 
 ## Proposal
 
-Rename the providerless core to [examples/base.yml](../../../../examples/base.yml) and make adapter selection explicit in each concrete example. The coding and ACP real configs add a tiny `llm-deepseek` include or local block; snapshot config adds `llm-replay`. Delete [examples/base-core.yml](../../../../examples/base-core.yml).
+Rename the providerless core to `examples/base.yml` and make adapter selection explicit in each concrete example. The coding and ACP real configs add a tiny `llm-deepseek` include or local block; snapshot config adds `llm-replay`. Delete `examples/base-core.yml`.
 
 The shared base should contain only provider-neutral services and tools: `llm`, sessions, system prompt, tools, agents, invariants, bash executor, and bash tool schemas. Anything that chooses a model provider belongs at the leaf config.
 
 ## Acceptance criteria
 
-- [examples/base.yml](../../../../examples/base.yml) is providerless.
-- [examples/base-core.yml](../../../../examples/base-core.yml) is deleted.
+- `examples/base.yml` is providerless.
+- `examples/base-core.yml` is deleted.
 - Real demo configs explicitly add the DeepSeek adapter.
 - Snapshot replay config includes the same providerless base and its replay adapter.
 - The [examples README](../../../../examples/README.md), example-specific READMEs, and RFC references stop explaining "base = base-core plus adapter".

examples/AGENTS.md

@@ -2,7 +2,7 @@
 
 Runnable demos that show how the harness is wired. **Examples are NOT workspaces** — each `examples/*/package.json` is a private, dependency-free stub with no build. They are booted as unbuilt `tsx` subprocesses via the cordis Loader reading a `cordis.yml`; the `@deepseek-ai/dsh-*` plugin names in those YAML files resolve through the root `tsconfig.json` `paths` map, not through `node_modules`.
 
-Because examples are not under the `packages/*/src` coverage gate, an example that grows real, reusable *logic* should extract it into a `packages/` package (where it gets the per-file 100% gate and a README). Keep only example-specific glue here: `start.ts`, the `cordis.yml` wiring, demo-only mocks/teaching artifacts, and the e2e/snapshot scenarios.
+Because examples are not under the `packages/*/src` coverage gate, an example that grows real, reusable *logic* should extract it into a `packages/` package (where it gets the per-file 100% gate and a README). Keep only example-specific glue here: the `cordis.yml` wiring, demo-only mocks/teaching artifacts, and the e2e/snapshot scenarios. There is no `start.ts` — the boot glue (Loader tail, `.env` load, snapshot-mode selection, stdin-dispose lifecycle) lives in each app package's `bin` (`@deepseek-ai/dsh-stdio-agent`, `@deepseek-ai/dsh-acp-agent`), which the `demo:*` scripts invoke against the leaf `cordis.yml`.
 
 ## Every example ships e2e smokes (keyless + with-key)
 

examples/README.md

@@ -1,23 +1,26 @@
 # Examples
 
-Runnable demos (not workspaces) that showcase how the harness is wired.
+Runnable demos (not workspaces) that showcase how the harness is wired. Each example is now a **thin leaf**: a `cordis.yml` that picks the swappable backends (an LLM adapter, a bash executor) and loads ONE app package, plus any demo-only mocks. The composition — the spine, the front-door cluster, and the boot glue — lives in the app packages ([`@deepseek-ai/dsh-stdio-agent`](../packages/ui/stdio-agent), [`@deepseek-ai/dsh-acp-agent`](../packages/ui/acp-agent)) and the [`@deepseek-ai/dsh-agent-core`](../packages/core/agent-core) bundle they share. There is no `start.ts`; the `demo:*` scripts invoke each app package's `bin`.
 
 ## echo-agent
 
-A mock model + echo tool + stdio UI + JSONL persistence demo. Demonstrates:
+A mock model + echo tool on the stdio chat app — the all-mock skeleton. The leaf swaps `dsh-stdio-agent`'s LLM backend to a local `mock-echo` adapter and adds a local `echo` tool. Demonstrates:
 
-- Loading plugins from a `cordis.yml` via `@cordisjs/plugin-loader` + `@cordisjs/plugin-include`
+- A thin leaf `cordis.yml` loading the `@deepseek-ai/dsh-stdio-agent` app
 - Registering a mock `LlmAdapter` (streaming scripted responses)
 - Registering a tool via `ctx.tools.register()`
-- Persisting session events to JSONL via the `session/event` + `session/flush` pattern
-- A minimal stdio UI consuming `agent/stream-chunk` and session events
+- "Swap the backend, keep the app" — the only difference from `coding-agent` is the adapter
 
-Run with: `pnpm run demo:echo`
-
-When prompted, type "echo <something>" to trigger a tool call round-trip.
+Run with: `pnpm run demo:echo`. When prompted, type "echo <something>" to trigger a tool call round-trip.
 
 ## coding-agent
 
-The real thing: DeepSeek V4 + the bash tool suite + stdio chat + JSONL persistence, wired from `cordis.yml`. Where echo-agent proves the skeleton with mocks, this is a usable coding assistant.
+The real thing: DeepSeek V4 + the bash tool suite on the same `@deepseek-ai/dsh-stdio-agent` app. Where echo-agent proves the skeleton with mocks, this is a usable coding assistant.
 
 Run with: `pnpm run demo:coding` (needs `DEEPSEEK_API_KEY` in the environment or a gitignored repo-root `.env`). See [coding-agent/README.md](coding-agent/README.md) for details.
+
+## acp-agent
+
+The same coding agent exposed as an **Agent Client Protocol (ACP)** server over JSON-RPC stdio, via the [`@deepseek-ai/dsh-acp-agent`](../packages/ui/acp-agent) app — drive it from Zed or any other ACP client. Also the home of the keyless snapshot tests.
+
+Run with: `pnpm run demo:acp` (needs `DEEPSEEK_API_KEY`). See [acp-agent/README.md](acp-agent/README.md) for the Zed setup and the snapshot-test design.

examples/acp-agent/README.md

@@ -6,11 +6,11 @@ The DeepSeek Harness coding agent exposed as an **Agent Client Protocol (ACP)**
 pnpm run demo:acp          # needs DEEPSEEK_API_KEY (repo-root .env or env)
 ```
 
-This boots `@deepseek-ai/dsh-acp` over the shared provider/tool core (`../base.yml`), with `agent-loop` configured with **no pre-created agents** (ACP `session/new` creates them on demand) and JSONL session persistence (so `session/load` works).
+This example is just a leaf `cordis.yml`: it loads the [`@deepseek-ai/dsh-acp-agent`](../../packages/ui/acp-agent) app (which bundles the [`@deepseek-ai/dsh-agent-core`](../../packages/core/agent-core) spine, JSONL session persistence, and the `@deepseek-ai/dsh-acp` bridge — with **no pre-created agents**, since ACP `session/new` creates them on demand) plus the two swappable backends (`llm-deepseek`, `bash-local`). The app package bakes in the no-stdout-logger cluster, so a leaf has no logger entry to get wrong by default — keeping stdout pure for JSON-RPC.
 
 ## stdout is the protocol
 
-This example loads **no stdout logger** — `stdout` carries the JSON-RPC frames, and any other write corrupts them. Do not add `@cordisjs/plugin-logger-console` or a stdio UI here. Use a stderr exporter if you need logs.
+This example loads **no stdout logger** — `stdout` carries the JSON-RPC frames, and any other write corrupts them. `@deepseek-ai/dsh-acp-agent` includes no logger entry, so this leaf has none to get wrong by default; do not add one (use a stderr exporter if you need logs).
 
 ## Zed configuration
 

examples/acp-agent/acp-tail.yml

@@ -1,33 +0,0 @@
-# The acp-agent "tail" shared by every acp-agent config (the normal demo, the
-# snapshot RECORD path which reuses cordis.yml, and the snapshot REPLAY config):
-# agent-loop (no pre-created agents — ACP session/new creates them on demand),
-# JSONL session persistence, and the ACP bridge with its system prompt. The
-# providerless core + an LLM adapter are included BEFORE this tail by each
-# config; nothing here loads an adapter, so the tail is provider-agnostic.
-#
-# Persistence root: $DSH_SNAPSHOT_SESSIONS_ROOT when the snapshot harness sets
-# it (so it can harvest / isolate the log), else ./.sessions for the demo.
-
-- id: agent-loop
-  name: '@deepseek-ai/dsh-agent-loop'
-  config:
-    agents: []
-
-- id: session-persistence
-  name: '@deepseek-ai/dsh-session-persistence-jsonl'
-  config:
-    root: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions'
-
-- id: acp
-  name: '@deepseek-ai/dsh-acp'
-  config:
-    model: deepseek-v4-flash
-    systemPrompt: |
-      You are a coding assistant driven over the Agent Client Protocol.
-
-      Your only tools are bash (plus bash_output/bash_kill for background
-      tasks). Do ALL file operations through bash: read with cat/sed/head,
-      search with grep, write with heredocs (cat <<'EOF' > file), edit with
-      sed or a rewrite. Each bash call runs in a fresh shell — pass workdir
-      instead of cd. Check the [exit code: N] marker; verify your work. Keep
-      answers brief and factual.

examples/acp-agent/cordis.snapshot.yml

@@ -1,32 +1,39 @@
-# Snapshot-test REPLAY config: the acp-agent plugin tree with the model replaced
-# by llm-replay (serves a recorded session JSONL — no API key, no network).
+# Snapshot-test REPLAY config: the acp-agent plugin tree with the model backend
+# swapped to llm-replay (serves a recorded session JSONL — no API key, no
+# network). The dsh-acp-agent bin selects this file for DSH_SNAPSHOT=replay.
 #
-# It reuses ../base-core.yml (the providerless core) + ./acp-tail.yml (agent-
-# loop + persistence + the ACP bridge), the SAME pieces cordis.yml shares — only
-# the LLM adapter differs: llm-replay here, llm-deepseek there. It can't reuse
-# ../base.yml because that loads llm-deepseek, whose apply() throws without
-# DEEPSEEK_API_KEY, killing a keyless replay run at boot.
+# Same app as cordis.yml (@deepseek-ai/dsh-acp-agent: the agent-core spine +
+# JSONL persistence + the ACP bridge) — only the LLM backend differs: llm-replay
+# here, llm-deepseek there. It can't reuse the real adapter because llm-deepseek's
+# apply() throws without DEEPSEEK_API_KEY, killing a keyless replay run at boot.
 #
-# stdout is reserved for the ACP JSON-RPC protocol — no stdout logger (see
-# cordis.yml). The replay fixture path comes from $DSH_SNAPSHOT_FILE (and an
-# optional $DSH_SNAPSHOT_OVERRIDE sidecar), set by the snapshot harness.
-
-- id: timer
-  name: '@cordisjs/plugin-timer'
-
-# Providerless core (everything base.yml has EXCEPT the llm-deepseek adapter).
-- id: base-core
-  name: '@cordisjs/plugin-include'
-  config:
-    path: '../base-core.yml'
+# stdout is reserved for the ACP JSON-RPC protocol — no stdout logger (the app
+# package omits it). The replay fixture path comes from $DSH_SNAPSHOT_FILE (and
+# an optional $DSH_SNAPSHOT_OVERRIDE sidecar), set by the snapshot harness.
 
 # The replay adapter: short-circuits llm/stream with the recorded log's chunks,
 # in place of llm-deepseek.
 - id: llm-replay
   name: '@deepseek-ai/dsh-llm-replay'
 
-# agent-loop + persistence + the ACP bridge — shared with cordis.yml.
-- id: acp-tail
-  name: '@cordisjs/plugin-include'
+# Local bash executor (the agent's only tool, via agent-core's tool-bash schema).
+- id: bash
+  name: '@deepseek-ai/dsh-bash-local'
   config:
-    path: './acp-tail.yml'
+    timeoutMs: 60000
+
+# The ACP server app — identical to cordis.yml's entry.
+- id: acp-agent
+  name: '@deepseek-ai/dsh-acp-agent'
+  config:
+    model: deepseek-v4-flash
+    persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions'
+    systemPrompt: |
+      You are a coding assistant driven over the Agent Client Protocol.
+
+      Your only tools are bash (plus bash_output/bash_kill for background
+      tasks). Do ALL file operations through bash: read with cat/sed/head,
+      search with grep, write with heredocs (cat <<'EOF' > file), edit with
+      sed or a rewrite. Each bash call runs in a fresh shell — pass workdir
+      instead of cd. Check the [exit code: N] marker; verify your work. Keep
+      answers brief and factual.

examples/acp-agent/cordis.yml

@@ -1,30 +1,48 @@
-# The acp-agent plugin tree, loaded via @cordisjs/plugin-include. Also the
-# snapshot RECORD config (start.ts selects it for DSH_SNAPSHOT=record): a real
-# llm-deepseek run whose persisted log the snapshot harness harvests.
+# The acp-agent plugin tree: the ACP server. Also the snapshot RECORD config
+# (the dsh-acp-agent bin selects it for DSH_SNAPSHOT=record): a real llm-deepseek
+# run whose persisted log the snapshot harness harvests. Just the two swappable
+# backends — the DeepSeek adapter and the local bash executor — plus the ACP
+# server app (@deepseek-ai/dsh-acp-agent), which bundles the agent-core spine,
+# JSONL persistence, and the ACP bridge.
 #
-# CRITICAL: this example loads NO stdout logger (no @cordisjs/plugin-logger-
-# console, no stdio-chat). stdout is reserved for the ACP JSON-RPC protocol —
-# anything else written there corrupts the frames (see packages/acp, RFC 010 §
-# Risks). Use a stderr exporter if you need logging. The timer plugin is loaded
-# (no stdout writes); hmr is omitted (an editor manages the subprocess).
+# CRITICAL: this tree loads NO stdout logger and NO hmr — stdout is reserved for
+# the ACP JSON-RPC protocol (see packages/ui/acp). That guarantee is now a
+# property of @deepseek-ai/dsh-acp-agent (it contains no logger entry), not a
+# leaf convention: there is no logger here to get wrong.
 #
-# Requires DEEPSEEK_API_KEY (and optionally DEEPSEEK_BASE_URL) in the
-# environment — start.ts loads the gitignored repo-root .env first.
+# Requires DEEPSEEK_API_KEY (and optionally DEEPSEEK_BASE_URL) — the
+# dsh-acp-agent bin loads the gitignored repo-root .env first (on STDERR only).
 
-- id: timer
-  name: '@cordisjs/plugin-timer'
+# The DeepSeek adapter.
+- 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:
+      - deepseek-v4-flash
+      - deepseek-v4-pro
 
-# Shared provider/tool core, INCLUDING the real llm-deepseek adapter. Nested
-# include resolved relative to THIS file's directory.
-- id: base
-  name: '@cordisjs/plugin-include'
+# Local bash executor (the agent's only tool, via agent-core's tool-bash schema).
+- id: bash
+  name: '@deepseek-ai/dsh-bash-local'
   config:
-    path: '../base.yml'
+    timeoutMs: 60000
 
-# agent-loop (no pre-created agents) + JSONL persistence + the ACP bridge.
-# Shared with the snapshot REPLAY config (cordis.snapshot.yml) so the three
-# acp-agent configs don't drift.
-- id: acp-tail
-  name: '@cordisjs/plugin-include'
+# The ACP server app: the agent-core spine + JSONL persistence + the ACP bridge.
+# Persistence root: $DSH_SNAPSHOT_SESSIONS_ROOT when the snapshot harness sets it
+# (so it can harvest / isolate the log), else ./.sessions for the demo.
+- id: acp-agent
+  name: '@deepseek-ai/dsh-acp-agent'
   config:
-    path: './acp-tail.yml'
+    model: deepseek-v4-flash
+    persistenceRoot: !!js process.env.DSH_SNAPSHOT_SESSIONS_ROOT ?? './.sessions'
+    systemPrompt: |
+      You are a coding assistant driven over the Agent Client Protocol.
+
+      Your only tools are bash (plus bash_output/bash_kill for background
+      tasks). Do ALL file operations through bash: read with cat/sed/head,
+      search with grep, write with heredocs (cat <<'EOF' > file), edit with
+      sed or a rewrite. Each bash call runs in a fresh shell — pass workdir
+      instead of cd. Check the [exit code: N] marker; verify your work. Keep
+      answers brief and factual.

examples/acp-agent/start.ts

@@ -1,63 +0,0 @@
-import { fileURLToPath, pathToFileURL } from 'node:url'
-import { Context } from 'cordis'
-import Loader from '@cordisjs/plugin-loader'
-
-// Snapshot-test modes (set by the snapshot harness via env):
-//   DSH_SNAPSHOT=replay  — load cordis.snapshot.yml (providerless; llm-replay
-//                          serves a recorded session log). Skip .env so a stray
-//                          key can never trigger a live model call.
-//   DSH_SNAPSHOT=record  — load the normal cordis.yml (the real llm-deepseek
-//                          adapter + persistence) so a real run can be harvested
-//                          (the persistence root is redirected by env).
-// Absent — the normal demo (cordis.yml), driven by a real editor.
-const snapshotMode = process.env.DSH_SNAPSHOT
-const configPath = snapshotMode === 'replay' ? './cordis.snapshot.yml' : './cordis.yml'
-
-// Load DEEPSEEK_API_KEY / DEEPSEEK_BASE_URL from a gitignored repo-root .env
-// (Node native). Absent file is fine — the environment may already carry them.
-// In REPLAY mode we deliberately skip this: replay must never reach the network,
-// so we don't want a present .env to enable a live call.
-//
-// IMPORTANT: this server speaks ACP JSON-RPC on stdout. Do NOT add any
-// stdout logging here or in cordis.yml — it would corrupt the protocol frames.
-// A present-but-unreadable/malformed .env is a real misconfiguration: surface
-// it on STDERR (never stdout) rather than silently running with the wrong env.
-if (snapshotMode !== 'replay') {
-  try {
-    process.loadEnvFile(new URL('../../.env', import.meta.url).pathname)
-  } catch (error) {
-    if ((error as NodeJS.ErrnoException | null)?.code !== 'ENOENT') {
-      process.stderr.write(`acp-agent: failed to load .env: ${String(error)}\n`)
-    }
-    // ENOENT (no .env) is fine — rely on the ambient environment.
-  }
-}
-
-// Resolve relative cordis.yml paths from the repo root no matter where the
-// editor launches this demo command.
-process.chdir(fileURLToPath(new URL('../..', import.meta.url)))
-
-const ctx = new Context()
-ctx.baseUrl = pathToFileURL(import.meta.dirname).href + '/'
-
-await ctx.plugin(Loader)
-await ctx.loader.create({
-  name: '@cordisjs/plugin-include',
-  config: {
-    path: configPath,
-  },
-})
-
-// Graceful shutdown for snapshot runs (both replay and record): when the client
-// closes our stdin (it is done driving the session), dispose the whole context.
-// Disposal awaits the agent-loop teardown and the persistence backend's final
-// `session/flush`, so the session `.jsonl` is fully written before the process
-// exits and the harness harvests it (and the subprocess exits cleanly so the
-// harness's waitForExit resolves). (In a normal editor session stdin stays open
-// for the connection's lifetime; the editor kills the process, so this never
-// fires.)
-if (snapshotMode !== undefined) {
-  process.stdin.on('end', () => {
-    void ctx.fiber.dispose().then(() => { process.exit(0) })
-  })
-}

examples/acp-agent/tests/acp.e2e.ts

@@ -26,7 +26,11 @@ import {
  * WITHOUT a key, since it only needs the server to boot and answer initialize.
  */
 
-const startScript = fileURLToPath(new URL('../start.ts', import.meta.url))
+// The dsh-acp-agent bin (the demo:acp entry) and this example's cordis.yml. The
+// bin resolves its config-path arg from CWD; the subprocess runs from a temp
+// workdir, so pass the example config's ABSOLUTE path.
+const binScript = fileURLToPath(new URL('../../../packages/ui/acp-agent/src/bin.ts', import.meta.url))
+const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url))
 // Resolve tsx's loader to an ABSOLUTE path: the subprocess runs with cwd set to
 // a temp workdir (this test launches there and uses it as the session cwd; the
 // bridge no longer requires cwd === the launch dir, but a temp dir keeps the
@@ -55,7 +59,7 @@ interface Spawned {
 function spawnAcpAgent(cwd: string, env: NodeJS.ProcessEnv = process.env): Spawned {
   const child = spawn(
     process.execPath,
-    ['--import', tsxLoader, startScript],
+    ['--import', tsxLoader, binScript, configPath],
     { cwd, env: { ...env, TSX_TSCONFIG_PATH: repoTsconfig }, stdio: ['pipe', 'pipe', 'pipe'] },
   )
   const stderr: string[] = []
@@ -101,7 +105,7 @@ describe('acp-agent over real stdio (no key required)', () => {
     // A dummy key lets the deepseek adapter APPLY (it only checks the key is
     // present at boot, not valid — the key is used only on a real model call,
     // which this purity test never triggers). So this runs WITHOUT real creds.
-    const child = spawn(process.execPath, ['--import', tsxLoader, startScript], {
+    const child = spawn(process.execPath, ['--import', tsxLoader, binScript, configPath], {
       cwd: workdir,
       env: { ...process.env, DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? 'sk-dummy-for-boot', TSX_TSCONFIG_PATH: repoTsconfig },
       stdio: ['pipe', 'pipe', 'pipe'],

examples/acp-agent/tests/snapshot-harness.ts

@@ -31,7 +31,12 @@ import {
   type SessionNotification,
 } from '@agentclientprotocol/sdk'
 
-const startScript = fileURLToPath(new URL('../start.ts', import.meta.url))
+// The dsh-acp-agent bin (the demo:acp entry) and this example's cordis.yml.
+// The bin resolves its config-path arg from CWD and, under DSH_SNAPSHOT=replay,
+// swaps it for the sibling cordis.snapshot.yml. The child's cwd is a temp dir
+// OUTSIDE the repo, so pass the example config's ABSOLUTE path.
+const binScript = fileURLToPath(new URL('../../../packages/ui/acp-agent/src/bin.ts', import.meta.url))
+const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url))
 const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
 // The repo-root tsconfig: dev/test run UNBUILT and the `@deepseek-ai/dsh-*`
 // imports resolve through its `paths` map. The child's cwd is a temp dir
@@ -130,7 +135,7 @@ export async function runScenario(input: InputScript, opts: RunOptions): Promise
 
     child = spawn(
       process.execPath,
-      ['--import', tsxLoader, startScript],
+      ['--import', tsxLoader, binScript, configPath],
       { cwd, env, stdio: ['pipe', 'pipe', 'pipe'] },
     )
 

examples/base-core.yml

@@ -1,37 +0,0 @@
-# Providerless provider/tool core — everything the model and tools need EXCEPT
-# an LLM adapter. Split out of base.yml so two consumers can share it:
-#   - base.yml = base-core.yml + the real llm-deepseek adapter (the demos).
-#   - acp-agent/cordis.snapshot.yml = base-core.yml + llm-replay (keyless
-#     snapshot replay — base.yml can't be reused there because llm-deepseek's
-#     apply() throws without DEEPSEEK_API_KEY).
-#
-# Plugin entries use package names (resolved from node_modules), so they are
-# insensitive to the baseUrl reset that plugin-include performs per file.
-
-- id: llm
-  name: '@deepseek-ai/dsh-llm'
-
-- id: sessions
-  name: '@deepseek-ai/dsh-session'
-
-- id: system-prompt
-  name: '@deepseek-ai/dsh-system-prompt'
-
-- id: tools
-  name: '@deepseek-ai/dsh-tools'
-
-- id: agents
-  name: '@deepseek-ai/dsh-agent'
-
-# Dev-mode event-contract assertions + session-log freeze (off in prod).
-- id: invariants
-  name: '@deepseek-ai/dsh-invariants'
-
-# Bash execution: the local executor implementation + the tool schemas.
-- id: bash
-  name: '@deepseek-ai/dsh-bash-local'
-  config:
-    timeoutMs: 60000
-
-- id: tool-bash
-  name: '@deepseek-ai/dsh-tool-bash'

examples/base.yml

@@ -1,37 +0,0 @@
-# Shared provider/tool core for the example agents, loaded via a nested
-# @cordisjs/plugin-include from each example's cordis.yml. This is
-# base-core.yml (the providerless core: llm, sessions, system-prompt, tools,
-# agents, invariants, bash-local, tool-bash) PLUS the real llm-deepseek adapter.
-#
-# The providerless core lives in base-core.yml so the keyless snapshot-replay
-# config (acp-agent/cordis.snapshot.yml) can reuse it with llm-replay in place
-# of the adapter — it can't reuse THIS file, because llm-deepseek's apply()
-# throws without DEEPSEEK_API_KEY.
-#
-# Deliberately EXCLUDES:
-#  - the console logger: it writes to stdout, which the acp-agent reserves for
-#    the JSON-RPC protocol (see packages/acp). Each example loads logging itself.
-#  - agent-loop: AgentLoop pre-creates its configured `agents` in its
-#    constructor, and the examples disagree — coding-agent needs a pre-created
-#    `main` (its stdio-chat calls ctx.agents.get('main')), while acp-agent must
-#    pre-create NONE (ACP session/new creates agents on demand). So each example
-#    declares agent-loop with its own `agents` list.
-#
-# Requires DEEPSEEK_API_KEY (and optionally DEEPSEEK_BASE_URL) in the env.
-
-# The providerless core (resolved relative to THIS file's directory).
-- id: base-core
-  name: '@cordisjs/plugin-include'
-  config:
-    path: './base-core.yml'
-
-# 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:
-      - deepseek-v4-flash
-      - deepseek-v4-pro

examples/coding-agent/README.md

@@ -32,15 +32,16 @@ RESUME_SESSION_ID=<prior-session-id> pnpm run demo:coding
 
 The id is wired through `cordis.yml` (`resumeSessionId: !!js process.env.RESUME_SESSION_ID`); unset, the agent starts a new session. A missing/unreadable id is non-fatal — it logs a warning and starts no `main` agent.
 
-## What each plugin demonstrates
+## What each leaf entry demonstrates
+
+This example is a thin leaf `cordis.yml`: it picks the swappable backends and loads one app package. The spine (sessions, system-prompt, tools, agents, invariants, `agent-loop`) and the front-door cluster (console logger, JSONL persistence, readline UI, the pre-created `main` agent) all live inside the [`@deepseek-ai/dsh-stdio-agent`](../../packages/ui/stdio-agent) app and the [`@deepseek-ai/dsh-agent-core`](../../packages/core/agent-core) bundle it loads — so the leaf has only four entries:
 
 | Entry | Demonstrates |
 |---|---|
+| `hmr` (`@cordisjs/plugin-hmr`) | the dev/demo edit-reload loop — a **leaf** entry (not baked into the app) because it is Loader-only and needs `node --expose-internals`, which `demo:coding` passes |
 | `llm-deepseek` | real `LlmAdapter` via config (`!!js process.env.…` secrets); swap one line to `@deepseek-ai/dsh-llm-pi-ai` for the library-backed twin |
-| `bash` (`dsh-bash-local`) + `tool-bash` | the executor seam + tool schemas as separate plugins |
-| `agent-loop` | agent created from config with a coding system prompt |
-| `session-persistence` (`dsh-session-persistence-jsonl`) | durable JSONL persistence (`root: ./.sessions`): append-only event log per session, crash-safe atomic writes — the shared backend, no per-example file |
-| `src/stdio-chat.ts` | UI as a plugin; copied from echo-agent with reasoning-dimming and an exit-on-idle close handler for piped stdin. Example-local on purpose — extract a shared UI package when a third example needs it |
+| `bash` (`dsh-bash-local`) | the executor implementation — the swappable half of the bash seam. The model-facing `bash`/`bash_output`/`bash_kill` tool schemas (`tool-bash`) come from `agent-core`, so only the executor is a leaf choice |
+| `stdio-agent` (`@deepseek-ai/dsh-stdio-agent`) | the app bundle: the agent-core spine + console logger + JSONL persistence + readline UI + a pre-created `main` agent. Its config carries the model, system prompt, `persistenceRoot` (`./.sessions`), and `resumeSessionId` — so persistence and the agent are configured here, not wired as separate leaf plugins |
 
 ## End-to-end tests (`pnpm run test:e2e`, key-gated)
 

examples/coding-agent/cordis.yml

@@ -1,59 +1,59 @@
-# The coding-agent plugin tree, loaded via @cordisjs/plugin-include.
-# Infra (logger/timer/hmr) first, then the shared provider/tool core (nested
-# include of ../base.yml), then this example's agent-loop config + UI.
+# The coding-agent plugin tree: the real coding agent. The two swappable
+# backends — the DeepSeek adapter and the local bash executor — plus `hmr` for
+# the dev/demo reload loop, then the stdio chat app (@deepseek-ai/dsh-stdio-
+# agent), which bundles the whole agent-core spine (timer, llm, sessions,
+# system-prompt, tools, agents, invariants, tool-bash, agent-loop), the console
+# logger, JSONL persistence, the readline UI, and a pre-created `main` agent.
 #
-# Requires DEEPSEEK_API_KEY (and optionally DEEPSEEK_BASE_URL) in the
-# environment — start.ts loads the gitignored repo-root .env first.
-
-- id: logger
-  name: '@cordisjs/plugin-logger-console'
-
-- id: timer
-  name: '@cordisjs/plugin-timer'
+# `hmr` is a leaf entry (not baked into dsh-stdio-agent): it is a Loader-only
+# dev plugin that needs `--expose-internals` — the `demo:coding` script passes
+# it. Requires DEEPSEEK_API_KEY (and optionally DEEPSEEK_BASE_URL) in the
+# environment — the dsh-stdio-agent bin loads the gitignored repo-root .env
+# first. cordis.yml reads them via the `!!js` tag.
 
+# Hot-module reload for the dev/demo loop (needs `node --expose-internals`).
 - id: hmr
   name: '@cordisjs/plugin-hmr'
   config:
     root: ['.']
 
-# Shared provider/tool core (llm, sessions, system-prompt, tools, agents,
-# invariants, llm-deepseek, bash-local, tool-bash). Nested include: the path is
-# resolved relative to THIS file's directory.
-- id: base
-  name: '@cordisjs/plugin-include'
-  config:
-    path: '../base.yml'
-
-# agent-loop is per-example (NOT in base.yml): coding-agent pre-creates a `main`
-# agent its stdio-chat drives via ctx.agents.get('main').
-- id: agent-loop
-  name: '@deepseek-ai/dsh-agent-loop'
+# 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:
-    agents:
-      - id: main
-        model: deepseek-v4-flash
-        # Set RESUME_SESSION_ID to continue a prior persisted session (the ids
-        # live under ./.sessions); unset starts a fresh session each run.
-        resumeSessionId: !!js process.env.RESUME_SESSION_ID
-        systemPrompt: |
-          You are coding-agent, a CLI coding assistant.
-
-          Your only tools are bash (plus bash_output/bash_kill for background
-          tasks). Do ALL file operations through bash: read with cat/sed/head,
-          search with grep, write with heredocs (cat <<'EOF' > file), edit
-          with sed or a rewrite. Each bash call runs in a fresh shell — pass
-          workdir instead of cd, and never rely on shell state between calls.
-
-          Check the [exit code: N] marker on every command; investigate
-          failures before moving on. Verify your work by running the code or
-          tests. Keep answers brief and factual.
-
-- id: session-persistence
-  name: '@deepseek-ai/dsh-session-persistence-jsonl'
+    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    baseURL: !!js process.env.DEEPSEEK_BASE_URL
+    models:
+      - deepseek-v4-flash
+      - deepseek-v4-pro
+
+# Local bash executor (the model's only tool, via agent-core's tool-bash schema).
+- id: bash
+  name: '@deepseek-ai/dsh-bash-local'
   config:
-    root: './.sessions'
+    timeoutMs: 60000
 
-- id: stdio-chat
-  name: '@deepseek-ai/dsh-ui-stdio'
+# The stdio chat app: the whole spine + front-door cluster, configured for a
+# real coding agent driving a pre-created `main` agent.
+- id: stdio-agent
+  name: '@deepseek-ai/dsh-stdio-agent'
   config:
+    model: deepseek-v4-flash
+    # Set RESUME_SESSION_ID to continue a prior persisted session (the ids live
+    # under ./.sessions); unset starts a fresh session each run.
+    resumeSessionId: !!js process.env.RESUME_SESSION_ID
+    persistenceRoot: './.sessions'
     welcome: 'coding-agent ready. Give it a coding task (bash is its only tool).'
+    systemPrompt: |
+      You are coding-agent, a CLI coding assistant.
+
+      Your only tools are bash (plus bash_output/bash_kill for background
+      tasks). Do ALL file operations through bash: read with cat/sed/head,
+      search with grep, write with heredocs (cat <<'EOF' > file), edit
+      with sed or a rewrite. Each bash call runs in a fresh shell — pass
+      workdir instead of cd, and never rely on shell state between calls.
+
+      Check the [exit code: N] marker on every command; investigate
+      failures before moving on. Verify your work by running the code or
+      tests. Keep answers brief and factual.

examples/coding-agent/start.ts

@@ -1,30 +0,0 @@
-import { pathToFileURL } from 'node:url'
-import { Context } from 'cordis'
-import Loader from '@cordisjs/plugin-loader'
-
-// Load DEEPSEEK_API_KEY / DEEPSEEK_BASE_URL from a gitignored repo-root .env
-// (Node >= 21.7 native). Absent file is fine — the environment may already
-// carry the variables; cordis.yml reads them via the `!!js` tag. A
-// present-but-unreadable/malformed .env is a real misconfiguration: surface it
-// rather than silently running with the wrong environment.
-try {
-  process.loadEnvFile(new URL('../../.env', import.meta.url).pathname)
-} catch (error) {
-  if ((error as NodeJS.ErrnoException | null)?.code !== 'ENOENT') {
-    process.stderr.write(`coding-agent: failed to load .env: ${String(error)}\n`)
-  }
-  // ENOENT (no .env) is fine — rely on the ambient environment.
-}
-
-// Boot a Cordis app from this example's cordis.yml — the same shape as the
-// upstream `cordis` bin, pinned to this directory.
-const ctx = new Context()
-ctx.baseUrl = pathToFileURL(import.meta.dirname).href + '/'
-
-await ctx.plugin(Loader)
-await ctx.loader.create({
-  name: '@cordisjs/plugin-include',
-  config: {
-    path: './cordis.yml',
-  },
-})

examples/coding-agent/tests/keyless-smoke.e2e.ts

@@ -7,21 +7,28 @@ import { afterEach, describe, expect, it } from 'vitest'
 
 /**
  * Keyless Loader-path smoke for examples/coding-agent: boot the REAL example
- * through its `cordis.yml` (the cordis Loader, `unwrapExports`, the full plugin
- * tree incl. the extracted `@deepseek-ai/dsh-ui-stdio`), then close stdin with
- * no prompt and assert the ready banner + a clean exit.
+ * through the `@deepseek-ai/dsh-stdio-agent` bin against its `cordis.yml` (the
+ * cordis Loader, `unwrapExports`, the full plugin tree incl. the
+ * `@deepseek-ai/dsh-agent-core` bundle and the extracted
+ * `@deepseek-ai/dsh-ui-stdio`), then close stdin with no prompt and assert the
+ * ready banner + a clean exit.
  *
  * No prompt is ever sent, so the model is NEVER called — this is why it runs
  * without a real key. coding-agent's `cordis.yml` loads `llm-deepseek`, whose
  * `apply()` only requires a key to be PRESENT (it does not validate it and only
  * uses it when a stream actually starts), so a dummy key lets the tree boot
  * while the absence of any prompt guarantees no network call. The value is the
- * real-Loader-path guard for the shared UI plugin's export shape (a broken
- * `export default` that drops `inject` would crash here — see postmortem 0001),
- * complementing coding-agent's with-key e2e suites which prove the real product.
+ * real-Loader-path guard for the app + bundle + UI plugin export shapes (a broken
+ * `export default` that drops `inject`/`Config` would crash here — see postmortem
+ * 0001), complementing coding-agent's with-key e2e suites which prove the real
+ * product.
  */
 
-const startScript = fileURLToPath(new URL('../start.ts', import.meta.url))
+// The dsh-stdio-agent bin (the demo:coding entry) and this example's cordis.yml.
+// The bin resolves its config-path arg from CWD; the test spawns from a temp
+// cwd, so we pass the example config's ABSOLUTE path.
+const binScript = fileURLToPath(new URL('../../../packages/ui/stdio-agent/src/bin.ts', import.meta.url))
+const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url))
 const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
 // Dev/test run UNBUILT: resolve `@deepseek-ai/dsh-*` through the root tsconfig
 // `paths` map; tsx searches UP from cwd, and we spawn from a temp dir outside
@@ -45,7 +52,7 @@ async function bootAndEof(): Promise<{ stdout: string; code: number }> {
     const proc = spawn(
       process.execPath,
       // --expose-internals: cordis.yml loads the HMR plugin (mirrors demo:coding).
-      ['--expose-internals', '--import', tsxLoader, startScript],
+      ['--expose-internals', '--import', tsxLoader, binScript, configPath],
       {
         cwd,
         env: {

examples/echo-agent/README.md

@@ -1,32 +1,32 @@
 # echo-agent
 
-Runnable demo: stdin chat with a scripted mock model and an echo tool.
+Runnable demo: stdin chat with a scripted mock model and an echo tool. The all-mock skeleton — "swap the backend, keep the app".
 
 ## What it shows
 
-- A complete Cordis app loaded from `cordis.yml` — the standard "stack of plugins" pattern
-- `mock-llm.ts` — a mock `LlmAdapter` that streams scripted responses and calls the `echo` tool when the user types "echo <something>"
-- `echo-tool.ts` — a tool registered via `ctx.tools.register()` that echoes text back uppercased
-- `@deepseek-ai/dsh-session-persistence-jsonl` — the durable JSONL persistence backend (loaded from `cordis.yml`, `root: ./.sessions`): append-only event log per session with crash-safe atomic writes, replacing the old write-only example plugin
-- `stdio-chat.ts` — a minimal UI plugin: reads stdin lines and `send`/`steer`s the agent, renders stream deltas, tool calls, and tool results
+This example is just a leaf `cordis.yml`: it loads the [`@deepseek-ai/dsh-stdio-agent`](../../packages/ui/stdio-agent) app (which bundles the whole [`@deepseek-ai/dsh-agent-core`](../../packages/core/agent-core) spine, the console logger, JSONL persistence, the readline UI, and a pre-created `main` agent), and swaps in two example-local backends plus `hmr`:
+
+- `mock-llm.ts` — a mock `LlmAdapter` that streams scripted responses and calls the `echo` tool when the user types "echo <something>". Registered with `ctx.llm.registerAdapter(['mock-echo'], …)`.
+- `echo-tool.ts` — a tool registered via `ctx.tools.register(defineTool(…))` with typed `execute` args; echoes text back uppercased.
+
+Swapping `mock-llm` for the real `llm-deepseek` adapter is all that separates this from `coding-agent` — the same app, a different backend.
 
 ## Plugin files
 
 | File | Role | Key patterns demonstrated |
 |---|---|---|
-| `mock-llm.ts` | `LlmAdapter` registration | `ctx.llm.registerAdapter(['mock-echo'], …)`, streaming chunks with proper `block-start`/`block-end` protocol |
-| `echo-tool.ts` | Tool registration | `ctx.tools.register(defineTool(…))` with typed `execute` args, tool execution returning `ContentBlock[]` |
-| `stdio-chat.ts` | UI | `agent/stream-chunk`, `session/event` (tool/*), stdin→send/steer |
-| `start.ts` | Bootstrap | `Context` + `Loader` + `plugin-include` wired to `cordis.yml` |
+| `src/mock-llm.ts` | `LlmAdapter` registration | `ctx.llm.registerAdapter(['mock-echo'], …)`, streaming chunks with the proper `block-start`/`block-end` protocol |
+| `src/echo-tool.ts` | Tool registration | `ctx.tools.register(defineTool(…))` with typed `execute` args, returning `ContentBlock[]` |
+| `cordis.yml` | Leaf wiring | the two backends + `hmr` + one `@deepseek-ai/dsh-stdio-agent` entry carrying the app config |
 
-Persistence is the shared `@deepseek-ai/dsh-session-persistence-jsonl` plugin (not a per-example file).
+The spine, UI, persistence, and boot glue all live in `@deepseek-ai/dsh-stdio-agent` and the bundle it loads — this folder holds only the demo-specific mocks and the leaf wiring.
 
 ## Run
 
 ```sh
 pnpm run demo:echo
 # or:
-node --expose-internals --import tsx examples/echo-agent/start.ts
+node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/echo-agent/cordis.yml
 ```
 
 Type a message and press Enter. "echo <text>" triggers a tool call round-trip (the mock model requests the `echo` tool, which echoes the text uppercased, and the next model step acknowledges it).

examples/echo-agent/cordis.yml

@@ -1,57 +1,38 @@
-# The echo-agent plugin tree, loaded via @cordisjs/plugin-include.
-# Core services first, then the demo plugins, then the agent itself.
-
-- id: logger
-  name: '@cordisjs/plugin-logger-console'
-
-- id: timer
-  name: '@cordisjs/plugin-timer'
-
+# The echo-agent plugin tree: the stdio chat app with its LLM backend swapped to
+# the local `mock-echo` mock and the local `echo` tool added. The clean
+# demonstration of "swap the backend, keep the app" — every service the agent
+# needs lives in @deepseek-ai/dsh-stdio-agent (which bundles @deepseek-ai/dsh-
+# agent-core); this leaf only picks the backends, `hmr`, and the app config.
+#
+# No API key: the `mock-echo` adapter never touches the network.
+
+# Hot-module reload for the dev/demo loop (a leaf entry, not baked into
+# dsh-stdio-agent — it needs `node --expose-internals`, which `demo:echo` passes).
 - id: hmr
   name: '@cordisjs/plugin-hmr'
   config:
     root: ['.']
 
-- id: llm
-  name: '@deepseek-ai/dsh-llm'
-
-- id: sessions
-  name: '@deepseek-ai/dsh-session'
-
-- id: system-prompt
-  name: '@deepseek-ai/dsh-system-prompt'
-
-- id: tools
-  name: '@deepseek-ai/dsh-tools'
-
-- id: agents
-  name: '@deepseek-ai/dsh-agent'
-
-# Dev-mode event-contract assertions + session-log freeze (off in prod;
-# on here so the demo smoke test exercises the contract).
-- id: invariants
-  name: '@deepseek-ai/dsh-invariants'
-
-- id: agent-loop
-  name: '@deepseek-ai/dsh-agent-loop'
-  config:
-    agents:
-      - id: main
-        model: mock-echo
-        systemPrompt: 'You are echo-agent, a demo agent.'
-
+# The mock model (registers the `mock-echo` adapter) and the demo `echo` tool —
+# example-local teaching plugins, resolved relative to THIS file's directory.
 - id: mock-llm
   name: './src/mock-llm.ts'
 
 - id: echo-tool
   name: './src/echo-tool.ts'
 
-- id: session-persistence
-  name: '@deepseek-ai/dsh-session-persistence-jsonl'
-  config:
-    root: './.sessions'
+# Local bash executor: agent-core ships the `tool-bash` consumer schema, so the
+# leaf provides the executor it runs on (the echo demo doesn't drive bash, but
+# the tool is part of the shared spine).
+- id: bash
+  name: '@deepseek-ai/dsh-bash-local'
 
-- id: stdio-chat
-  name: '@deepseek-ai/dsh-ui-stdio'
+# The stdio chat app: console logger + the agent-core spine (pre-creating the
+# `main` agent on the mock model) + JSONL persistence + the readline UI.
+- id: stdio-agent
+  name: '@deepseek-ai/dsh-stdio-agent'
   config:
+    model: mock-echo
+    systemPrompt: 'You are echo-agent, a demo agent.'
     welcome: 'echo-agent ready. Type a message ("echo <text>" triggers the tool).'
+    persistenceRoot: './.sessions'

examples/echo-agent/start.ts

@@ -1,16 +0,0 @@
-import { pathToFileURL } from 'node:url'
-import { Context } from 'cordis'
-import Loader from '@cordisjs/plugin-loader'
-
-// Boot a Cordis app from this example's cordis.yml — the same shape as the
-// upstream `cordis` bin, pinned to this directory.
-const ctx = new Context()
-ctx.baseUrl = pathToFileURL(import.meta.dirname).href + '/'
-
-await ctx.plugin(Loader)
-await ctx.loader.create({
-  name: '@cordisjs/plugin-include',
-  config: {
-    path: './cordis.yml',
-  },
-})

examples/echo-agent/tests/echo.e2e.ts

@@ -7,22 +7,29 @@ import { afterEach, describe, expect, it } from 'vitest'
 
 /**
  * Keyless Loader-path smoke for examples/echo-agent: boot the REAL example
- * through its `cordis.yml` (the cordis Loader, `unwrapExports`, the whole
- * plugin tree), pipe a script of stdin lines, and assert the rendered stdout.
+ * through the `@deepseek-ai/dsh-stdio-agent` bin against this example's
+ * `cordis.yml` (the cordis Loader, `unwrapExports`, the whole plugin tree),
+ * pipe a script of stdin lines, and assert the rendered stdout.
  *
  * This is the guard the per-file unit suite structurally cannot be: it drives
- * the extracted `@deepseek-ai/dsh-ui-stdio` plugin AND the example-local
- * `mock-llm.ts` / `echo-tool.ts` through their REAL load path, so a broken
- * plugin export shape (a stray `export default` that `unwrapExports` would
- * collapse, dropping `inject`) fails here even though hand-mounted unit tests
- * stay green (see docs/postmortem/0001). It needs no API key — the `mock-echo`
- * adapter never touches the network — so it runs in the default e2e gate.
+ * the `@deepseek-ai/dsh-stdio-agent` app plugin, the `@deepseek-ai/dsh-agent-core`
+ * bundle it loads, the extracted `@deepseek-ai/dsh-ui-stdio` plugin, AND the
+ * example-local `mock-llm.ts` / `echo-tool.ts` through their REAL load path, so
+ * a broken plugin export shape (a stray `export default` that `unwrapExports`
+ * would collapse, dropping `inject`/`Config`) fails here even though hand-mounted
+ * unit tests stay green (see docs/postmortem/0001). It needs no API key — the
+ * `mock-echo` adapter never touches the network — so it runs in the default e2e
+ * gate.
  *
  * Both branches of mock-llm.ts are exercised: an `echo …` line (the tool
  * round-trip → `ECHO: …`) and a plain line (the direct canned reply).
  */
 
-const startScript = fileURLToPath(new URL('../start.ts', import.meta.url))
+// The dsh-stdio-agent bin (the demo:echo entry) and this example's cordis.yml.
+// The bin resolves its config-path arg from CWD; the test spawns from a temp
+// cwd, so we pass the example config's ABSOLUTE path.
+const binScript = fileURLToPath(new URL('../../../packages/ui/stdio-agent/src/bin.ts', import.meta.url))
+const configPath = fileURLToPath(new URL('../cordis.yml', import.meta.url))
 const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
 // Dev/test run UNBUILT: `@deepseek-ai/dsh-*` imports resolve through the root
 // tsconfig `paths` map, which tsx finds by searching UP from cwd. We spawn from
@@ -53,8 +60,8 @@ async function runEcho(lines: string[]): Promise<{ stdout: string; code: number
       process.execPath,
       // --expose-internals: the example's cordis.yml loads the HMR plugin, which
       // requires it (mirrors the `demo:echo` script). The whole point is to boot
-      // the example EXACTLY as it really runs, through the Loader.
-      ['--expose-internals', '--import', tsxLoader, startScript],
+      // the example EXACTLY as it really runs, through the bin + Loader.
+      ['--expose-internals', '--import', tsxLoader, binScript, configPath],
       { cwd, env: { ...process.env, TSX_TSCONFIG_PATH: repoTsconfig }, stdio: ['pipe', 'pipe', 'pipe'] },
     )
     child = proc

knip.json

@@ -28,6 +28,14 @@
     "packages/llm/llm-pi-ai": {
       "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
       "project": ["src/**/*.ts", "tests/**/*.ts"]
+    },
+    "packages/ui/acp-agent": {
+      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
+      "project": ["src/**/*.ts", "tests/**/*.ts"]
+    },
+    "packages/ui/stdio-agent": {
+      "entry": ["tests/**/*.spec.ts", "tests/**/*.e2e.ts"],
+      "project": ["src/**/*.ts", "tests/**/*.ts"]
     }
   }
 }

package.json

@@ -37,9 +37,9 @@
     "constraints": "tsx scripts/check-workspace-constraints.ts",
     "doc-sync": "pnpm run doc-typecheck && pnpm run verify-cordis-catalog && pnpm run verify-md-wrap && pnpm run verify-md-links && pnpm run verify-doc-refs && pnpm run verify-package-paths && pnpm run verify-rfc-classification && pnpm run verify-type-equiv",
     "hygiene": "pnpm run knip && pnpm run publint && pnpm run constraints",
-    "demo:echo": "node --expose-internals --import tsx examples/echo-agent/start.ts",
-    "demo:coding": "node --expose-internals --import tsx examples/coding-agent/start.ts",
-    "demo:acp": "node --expose-internals --import tsx examples/acp-agent/start.ts",
+    "demo:echo": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/echo-agent/cordis.yml",
+    "demo:coding": "node --expose-internals --import tsx packages/ui/stdio-agent/src/bin.ts examples/coding-agent/cordis.yml",
+    "demo:acp": "node --import tsx packages/ui/acp-agent/src/bin.ts examples/acp-agent/cordis.yml",
     "postinstall": "node scripts/install-lefthook.mjs"
   },
   "devDependencies": {

packages/README.md

@@ -37,9 +37,12 @@ dsh-invariants    ← dsh-llm, dsh-session, dsh-agent (dev-mode contract checks)
 dsh-acp           ← dsh-agent, dsh-llm, dsh-session, dsh-session-persistence  (ACP JSON-RPC bridge)
 dsh-ui-stdio      ← dsh-agent, dsh-llm, dsh-session (stdio readline UI plugin)
 dsh-llm-replay    ← dsh-llm, dsh-session            (record/replay adapter for keyless snapshot tests)
+dsh-agent-core    ← timer, dsh-llm, dsh-session, dsh-system-prompt, dsh-tools, dsh-agent, dsh-invariants, dsh-tool-bash, dsh-agent-loop  (the providerless spine, as one bundle plugin)
+dsh-stdio-agent   ← dsh-agent-core, dsh-ui-stdio, dsh-session-persistence-jsonl, dsh-agent, dsh-session  (stdio chat APP + bin)
+dsh-acp-agent     ← dsh-agent-core, dsh-acp, dsh-session-persistence-jsonl     (ACP server APP + bin)
 ```
 
-The rule: plugins depend on interfaces, never on the concrete loop. `dsh-agent-loop` is swappable — UI/hook/tool plugins keep working against the `dsh-agent` vocabulary if the loop is replaced. A swappable capability splits into interface / implementation / consumer packages (the bash trio is the template — see [capability seams](../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)).
+The rule: **extension** plugins depend on interfaces, never on the concrete loop. `dsh-agent-loop` is swappable — UI/hook/tool plugins keep working against the `dsh-agent` vocabulary if the loop is replaced. The sanctioned exception is a **composition/bundle** package like `dsh-agent-core`, whose whole job is to assemble the concrete spine: it depends on `dsh-agent-loop` (and the other concrete spine plugins) on purpose. The rule constrains plugins that EXTEND the system, not the bundle that COMPOSES it — swapping the loop means shipping a different bundle, not rewiring every extension. A swappable capability splits into interface / implementation / consumer packages (the bash trio is the template — see [capability seams](../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)).
 
 ## What goes where
 
@@ -51,6 +54,7 @@ The rule: plugins depend on interfaces, never on the concrete loop. `dsh-agent-l
 | `tools/` | `core` | Tool registry + `tools/execute` waterfall | `ctx.tools` |
 | `agent/` | `core` | Agent interface, registry, `agent/*` event vocabulary | `ctx.agents` |
 | `agent-loop/` | `core` | THE concrete loop plugin: `ReactLoopAgent` + the loop driver | `ctx.agentLoop` |
+| `agent-core/` | `core` | Bundle plugin: the providerless/executor-less/UI-less spine as code (forwards `agent-loop`'s `agents`) | (loads the spine) |
 | `bash/` | `bash` | Abstract bash executor seam (interface + vocabulary) | `ctx.bash` |
 | `bash-local/` | `bash` | Local-subprocess `BashExecutor` implementation | (registers `ctx.bash`) |
 | `tool-bash/` | `bash` | Model-facing `bash`/`bash_output`/`bash_kill` tool schemas | (registers on `ctx.tools`) |
@@ -61,6 +65,8 @@ The rule: plugins depend on interfaces, never on the concrete loop. `dsh-agent-l
 | `session-persistence-sqlite/` | `session-persistence` | SQLite persistence backend | (registers `ctx.sessionPersistence`) |
 | `invariants/` | `support` | Dev-mode event-contract invariants + session-log freeze | (listens on `session/*`, `agent/*`) |
 | `acp/` | `ui` | Agent Client Protocol bridge: serves the agent to an ACP editor over JSON-RPC stdio | (drives `ctx.agents`/`ctx.sessions`) |
+| `stdio-agent/` | `ui` | Terminal stdio chat APP: agent-core spine + console logger + readline UI + a pre-created `main` agent, with a `bin` | (composition + `bin`) |
+| `acp-agent/` | `ui` | ACP server APP: agent-core spine + JSONL persistence + the `acp` bridge (no stdout logger), with a `bin` | (composition + `bin`) |
 | `ui-stdio/` | `support` | Minimal stdio (readline) UI plugin: renders `agent/*` events, feeds stdin lines to the agent | (drives `ctx.agents`) |
 | `llm-replay/` | `support` | Record/replay adapter: short-circuits `llm/stream` with chunks from a recorded session JSONL (keyless snapshot tests) | (listens on `llm/stream`) |
 | `brand/` | `util` | Type-only `Branded<B>` nominal-typing primitive (no runtime code, no harness deps) | (none — type-only) |

packages/core/README.md

@@ -9,5 +9,8 @@ The packages every harness build is assembled from: the session log, the system-
 | `tools/` | Tool registry + `tools/execute` waterfall | `ctx.tools` |
 | `agent/` | Agent interface, registry, `agent/*` event vocabulary | `ctx.agents` |
 | `agent-loop/` | The concrete loop plugin: `ReactLoopAgent` + the loop driver | `ctx.agentLoop` |
+| `agent-core/` | Bundle plugin: the providerless/executor-less/UI-less spine as code | (loads the spine) |
 
 `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-core` is the composition counterpart: one bundle plugin that loads the whole providerless spine (`timer` + `llm` + sessions + system-prompt + tools + agents + invariants + `tool-bash` + `agent-loop`) and forwards `agent-loop`'s `agents` list as its own config. App packages (`ui/stdio-agent`, `ui/acp-agent`) consume it and add only a front door; a leaf adds only the swappable backends. It lives in `core/` because it composes exclusively `core/` + interface packages and ships no provider, executor, or UI of its own.

packages/core/agent-core/README.md

@@ -0,0 +1,44 @@
+# @deepseek-ai/dsh-agent-core
+
+The **providerless, executor-less, UI-less agent spine** as ONE Cordis bundle plugin. It loads the fixed set of services every harness agent needs and forwards the loop's `agents` list as its own config — so an app package composes a working agent by adding only a front door and the swappable backends.
+
+This is the package to read to see **the whole plugin tree at once** — the teaching role the inlined `echo-agent` `cordis.yml` used to play before the spine moved behind this bundle.
+
+## The tree it loads
+
+`apply(ctx, config)` mounts each of these as a child of the bundle fiber:
+
+```
+@cordisjs/plugin-timer            timer service (writes nothing to stdout)
+@deepseek-ai/dsh-llm              abstract LLM service + content-block vocabulary
+@deepseek-ai/dsh-session          event-sourced session log + store
+@deepseek-ai/dsh-system-prompt    prompt-section + tool-schema assembly
+@deepseek-ai/dsh-tools            tool registry + tools/execute waterfall
+@deepseek-ai/dsh-agent            agent registry + agent/* event vocabulary
+@deepseek-ai/dsh-invariants       dev-mode event-contract assertions
+@deepseek-ai/dsh-tool-bash        the model-facing bash/bash_output/bash_kill schemas
+@deepseek-ai/dsh-agent-loop       THE concrete loop (gets the forwarded `agents`)
+```
+
+## What it deliberately leaves OUTSIDE the bundle
+
+The spine is everything COMMON to every front door. The swappable and front-door-coupled pieces stay out, picked by whatever loads the bundle:
+
+- **the LLM adapter** — the bundle ships the abstract `llm` service; the leaf registers a concrete adapter on `ctx.llm` (`llm-deepseek`, `llm-pi-ai`, `llm-replay`).
+- **the bash executor** — the bundle ships `tool-bash` (the consumer schema); the leaf provides `ctx.bash` (`bash-local` or a sandboxed impl).
+- **presentation + per-app infra** — the stdio UI / ACP bridge, a console logger, `hmr`. These form the coupled "front-door cluster" that the app packages ([`dsh-stdio-agent`](../../ui/stdio-agent/README.md), [`dsh-acp-agent`](../../ui/acp-agent/README.md)) bake in. `timer` is in the spine (common to both, stdout-silent); a console logger is NOT (it writes to stdout, which the ACP bridge reserves for JSON-RPC).
+
+This is the [interface/implementation/consumer seam](../../../docs/rfc/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.
+
+## Config
+
+```ts
+import type { Config } from '@deepseek-ai/dsh-agent-core'
+// Config === AgentLoop.Config — the `agents` list, default [].
+```
+
+The bundle FORWARDS `agent-loop`'s `agents` list as its own (default `[]`), so each app supplies its own pre-created agents — a stdio app pre-creates a `main`; the ACP app pre-creates none (it creates agents on demand at `session/new`). Forwarding the list is exactly why the loop can live in the shared spine even though the apps disagree on which agents to pre-create.
+
+## Why a code bundle, not a shared YAML include
+
+A YAML include can dedupe the config, but it cannot OWN a `bin`, and it can only *describe* the front-door coupling in a comment and trust each leaf to obey. Moving the spine into a package, and the front-door cluster into the app packages, means the default leaf for an ACP server has no logger entry to copy wrong — "the ACP app never logs to stdout" stops being a prose warning a leaf must remember and becomes the app package's default shape (a leaf can still add a sibling logger, so the rule stays documented — but it has nothing to get wrong by default). Services register in the root store keyed by their isolate symbol, so a child loaded here is visible to the bundle's siblings (the leaf's adapter and executor) exactly as a nested `plugin-include` subtree's services were — cordis gates every read on `inject`, never on load order.

packages/core/agent-core/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@deepseek-ai/dsh-agent-core",
+  "description": "The providerless/executor-less/UI-less agent spine as one Cordis bundle plugin (timer + llm + sessions + system-prompt + tools + agents + invariants + tool-bash + agent-loop)",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@cordisjs/plugin-timer": "^1.1.2",
+    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-agent-loop": "^0.0.1",
+    "@deepseek-ai/dsh-invariants": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-system-prompt": "^0.0.1",
+    "@deepseek-ai/dsh-tool-bash": "^0.0.1",
+    "@deepseek-ai/dsh-tools": "^0.0.1",
+    "cordis": "^4.0.0-rc.6"
+  },
+  "devDependencies": {
+    "@cordisjs/plugin-timer": "workspace:^",
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-invariants": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-system-prompt": "workspace:^",
+    "@deepseek-ai/dsh-tool-bash": "workspace:^",
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "cordis": "^4.0.0-rc.6"
+  }
+}

packages/core/agent-core/src/index.ts

@@ -0,0 +1,88 @@
+/**
+ * The providerless, executor-less, UI-less agent spine as ONE bundle plugin.
+ *
+ * Loads the fixed set of services every harness agent needs — `timer`, the LLM
+ * service, the session store, system-prompt assembly, the tool registry, the
+ * agent registry, the dev-mode invariants, the model-facing `bash` tool
+ * schemas, and the concrete `agent-loop` — and forwards the loop's `agents`
+ * list as its OWN config (default `[]`), so each app supplies its own
+ * pre-created agents.
+ *
+ * It is deliberately NOT the whole app: the swappable choices stay OUTSIDE the
+ * bundle, picked by whatever loads it.
+ *  - the LLM ADAPTER (`llm-deepseek`/`llm-pi-ai`/`llm-replay`) — the bundle
+ *    ships the abstract `llm` service + `tool-bash` consumer schema; the leaf
+ *    registers a concrete adapter on `ctx.llm`.
+ *  - the bash EXECUTOR (`bash-local` or a sandboxed impl) — the bundle ships
+ *    the `bash` tool consumer; the leaf provides `ctx.bash`.
+ *  - the PRESENTATION (stdio UI / ACP bridge / a logger) and the per-app infra
+ *    (a console logger, `hmr`) — these are the coupled "front-door cluster" the
+ *    app packages ({@link @deepseek-ai/dsh-stdio-agent},
+ *    {@link @deepseek-ai/dsh-acp-agent}) bake in, NOT the shared spine.
+ *
+ * This is the interface/implementation/consumer seam at the composition level:
+ * the bundle owns the shared spine, the leaf owns the backends, the app package
+ * owns the front door. `timer` is in the spine (common to every front door — it
+ * writes nothing to stdout); the console logger is NOT (it writes to stdout,
+ * which the ACP bridge reserves for its JSON-RPC channel).
+ *
+ * Services register in the root store keyed by their isolate symbol, so a child
+ * loaded here via `ctx.plugin(...)` is visible to the bundle's SIBLINGS (the
+ * leaf's adapter and executor) exactly as a nested `plugin-include` subtree's
+ * services were before this bundle existed — cordis gates every read on
+ * `inject`, never on load order, so the fixed child set resolves regardless of
+ * which entry loads first.
+ *
+ * Plugin export shape: named `name`/`Config`/`apply`, NO default export — the
+ * cordis Loader's `unwrapExports` does `exports.default ?? exports`, so a stray
+ * default would collapse the module to the bare `apply` function and drop the
+ * `Config` schema (see docs/postmortem/0001). The keyless Loader-path smokes in
+ * the app packages guard this end-to-end.
+ *
+ * @module @deepseek-ai/dsh-agent-core
+ */
+
+import type { Context } from 'cordis'
+import Timer from '@cordisjs/plugin-timer'
+import LlmService from '@deepseek-ai/dsh-llm'
+import SessionStore from '@deepseek-ai/dsh-session'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import * as invariants from '@deepseek-ai/dsh-invariants'
+import * as toolBash from '@deepseek-ai/dsh-tool-bash'
+import AgentLoop, { type Config as AgentLoopConfig } from '@deepseek-ai/dsh-agent-loop'
+
+export const name = 'agent-core'
+
+/**
+ * Bundle config: the agent-loop `agents` list, forwarded verbatim. Default `[]`
+ * — an app that pre-creates no agents (the ACP bridge creates them on demand at
+ * `session/new`) simply omits it; an app that needs a pre-created `main` (the
+ * stdio chat) supplies one. This IS {@link AgentLoopConfig}, so the schema and
+ * the forwarded shape can never drift.
+ */
+export type Config = AgentLoopConfig
+
+/** Forward the loop's own schema so validation + defaulting stay identical. */
+export const Config = AgentLoop.Config
+
+/**
+ * Load the spine. Each `ctx.plugin(...)` mounts one child of the bundle fiber;
+ * `agent-loop` receives the forwarded `agents` list. Load order is irrelevant
+ * (cordis pends each fiber on its `inject` until the services it needs exist),
+ * but the listing mirrors the dependency layering for readability: the LLM
+ * vocabulary and core registries first, then the dev tripwire and the bash tool
+ * consumer, then the loop that drives them.
+ */
+export function apply(ctx: Context, config: Config): void {
+  ctx.plugin(Timer)
+  ctx.plugin(LlmService)
+  ctx.plugin(SessionStore)
+  ctx.plugin(SystemPrompt)
+  ctx.plugin(ToolRegistry)
+  ctx.plugin(AgentRegistry)
+  ctx.plugin(invariants)
+  ctx.plugin(toolBash)
+  ctx.plugin(AgentLoop, { agents: config.agents })
+}

packages/core/agent-core/tests/agent-core.spec.ts

@@ -0,0 +1,79 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import * as agentCore from '../src/index.ts'
+import { AgentId } from '@deepseek-ai/dsh-agent'
+
+/**
+ * Unit coverage for the @deepseek-ai/dsh-agent-core bundle: mounting it brings
+ * up the whole providerless spine in one `ctx.plugin`, and the forwarded
+ * `agents` config reaches the loop (default `[]`, or a pre-created agent).
+ *
+ * The bundle is exercised through `ctx.plugin(agentCore, …)` — the NAMESPACE
+ * import, the same shape the Loader builds from `unwrapExports`. The real
+ * Loader-path guard (export shape, `unwrapExports`) is the app packages' keyless
+ * bin smokes; here we assert the composition + config forwarding.
+ */
+async function mount(config?: agentCore.Config): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(agentCore, config)
+  // The bundle mounts its children inside apply() (not awaited there); let their
+  // fibers settle so the spine services and any pre-created agent are ready.
+  await new Promise(resolve => setTimeout(resolve, 50))
+  return ctx
+}
+
+describe('dsh-agent-core bundle', () => {
+  it('brings up the full providerless spine', async () => {
+    const ctx = await mount()
+    // One service from each layer of the spine proves the children loaded.
+    expect(ctx.get('timer')).toBeDefined()
+    expect(ctx.get('llm')).toBeDefined()
+    expect(ctx.get('sessions')).toBeDefined()
+    expect(ctx.get('systemPrompt')).toBeDefined()
+    expect(ctx.get('tools')).toBeDefined()
+    expect(ctx.get('agents')).toBeDefined()
+    expect(ctx.get('agentLoop')).toBeDefined()
+    await ctx.fiber.dispose()
+  })
+
+  it('defaults the agents list to empty (no pre-created agents)', async () => {
+    const ctx = await mount()
+    expect(ctx.get('agents')?.get(AgentId('main'))).toBeUndefined()
+    await ctx.fiber.dispose()
+  })
+
+  it('forwards a pre-created agent to the loop', async () => {
+    const ctx = await mount({
+      agents: [{ id: AgentId('main'), model: 'mock', systemPrompt: 'hi' }],
+    })
+    expect(ctx.get('agents')?.get(AgentId('main'))).toBeDefined()
+    await ctx.fiber.dispose()
+  })
+
+  it('re-exports the loop config schema as its own', () => {
+    expect(agentCore.Config).toBeDefined()
+    expect(agentCore.name).toBe('agent-core')
+  })
+
+  it('has the namespace-plugin export shape (no stray default) so the Loader keeps name/Config/apply', () => {
+    // Postmortem 0001 guard: a stray `export default apply` makes the Loader's
+    // `unwrapExports` (`exports.default ?? exports`) collapse the module to the
+    // bare `apply` function, DROPPING the named `name`/`Config`. This package has
+    // no `inject` export (it mounts children that carry their own), so that
+    // collapse would NOT crash at load — the plugin would boot but silently lose
+    // its config schema. This bundle is also never Loader-unwrapped by any smoke
+    // (the apps import it directly; the mount test namespace-mounts it), so this
+    // is its ONLY export-shape guard. Assert directly AND through the real
+    // `unwrapExports` so adding `export default` to src/index.ts fails here.
+    expect('default' in agentCore).toBe(false)
+    expect(typeof agentCore.apply).toBe('function')
+
+    const loader = Object.create(Loader.prototype) as Loader
+    const unwrapped = loader.unwrapExports(agentCore) as Record<string, unknown>
+    expect(unwrapped).toBe(agentCore)
+    expect(unwrapped.name).toBe('agent-core')
+    expect(unwrapped.Config).toBeDefined()
+    expect(typeof unwrapped.apply).toBe('function')
+  })
+})

packages/core/agent-core/tsconfig.json

@@ -0,0 +1,42 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/timer"
+    },
+    {
+      "path": "../../llm/llm"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../core/system-prompt"
+    },
+    {
+      "path": "../../core/tools"
+    },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../core/agent-loop"
+    },
+    {
+      "path": "../../support/invariants"
+    },
+    {
+      "path": "../../bash/tool-bash"
+    }
+  ]
+}

packages/ui/README.md

@@ -5,5 +5,9 @@ Integrations that expose the agent to an external editor or client. These are **
 | Package | Role | ctx key |
 |---|---|---|
 | `acp/` | Agent Client Protocol bridge: serves the agent to an ACP editor (Zed) over JSON-RPC stdio | (drives `ctx.agents`/`ctx.sessions`) |
+| `stdio-agent/` | Terminal stdio chat APP: the agent-core spine + console logger + readline UI + a pre-created `main` agent, with a `bin` | (composition + `bin`) |
+| `acp-agent/` | ACP server APP: the agent-core spine + JSONL persistence + the `acp` bridge (no stdout logger), with a `bin` | (composition + `bin`) |
 
 A UI integration is a client-driver plugin, not a loop change and not a capability seam: it consumes the existing `agent/*` event taxonomy and the `dsh-agent` factory. The readline `ui-stdio` plugin is the unstructured analogue but lives in `support/` because it exists chiefly for the examples and the coverage gate — `ui/` is reserved for surfaces shipped as product.
+
+`stdio-agent` and `acp-agent` are the two **app packages**: each composes the [`core/agent-core`](../core/agent-core/README.md) spine with its coupled front-door cluster (and owns the boot `bin`), so a leaf `cordis.yml` is just the swappable backends plus one app entry. They live in `ui/` because each IS a user-facing front door; the stdout-purity coupling (logger vs. no logger) becomes a property of the artifact rather than a leaf convention.

packages/ui/acp-agent/README.md

@@ -0,0 +1,41 @@
+# @deepseek-ai/dsh-acp-agent
+
+The **ACP server app**: a Cordis app plugin that composes the providerless agent spine ([`@deepseek-ai/dsh-agent-core`](../../core/agent-core/README.md)) with the front-door cluster an [Agent Client Protocol](../acp/README.md) server needs, and a `bin` that boots a leaf `cordis.yml` speaking ACP JSON-RPC on stdio.
+
+It is the structured counterpart to [`@deepseek-ai/dsh-stdio-agent`](../stdio-agent/README.md): both consume the same spine, but this one bakes in the OPPOSITE front-door cluster.
+
+## 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 |
+|---|---|
+| `@deepseek-ai/dsh-agent-core` | the spine, pre-creating **no** agents (ACP `session/new` creates them on demand) |
+| `@deepseek-ai/dsh-session-persistence-jsonl` | durable JSONL session log (the bridge advertises `loadSession`) |
+| `@deepseek-ai/dsh-acp` | the bridge that owns stdout for JSON-RPC |
+| ~~console logger~~ | **omitted** — it writes to stdout and would corrupt the protocol frames ([the stdout-purity footgun](../acp/README.md)) |
+| ~~`hmr`~~ | **omitted** — the editor owns the subprocess |
+
+Because the package wires no logger entry, an ACP leaf has **nothing to get wrong by default**: it only picks backends, so the common mistake — copying a console-logger entry from the stdio config — has no place here. (A leaf author technically *can* still add `@cordisjs/plugin-logger-console` as a sibling entry; the package can't forbid that. So the rule stands: never add a stdout logger to an ACP leaf — stdout is the JSON-RPC channel. Use a stderr exporter if you need logs.)
+
+## Config
+
+| Key | Default | Routed to |
+|---|---|---|
+| `model` | (required) | the per-session agent template the bridge creates agents from |
+| `systemPrompt` | (required) | the per-session agent's system prompt |
+| `persistenceRoot` | `./.sessions` | the JSONL backend's root directory |
+
+The leaf supplies the swappable backends: an LLM adapter (`llm-deepseek` for the real model, `llm-replay` for keyless snapshot replay) and a bash executor (`bash-local`).
+
+## The bin
+
+`dsh-acp-agent [path-to-cordis.yml]` (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.
+
+Run it under `node --expose-internals`: the cordis Loader resolves the config's bare plugin specifiers through its internal module loader, active only under that flag. (`demo:acp` runs under tsx, whose tsconfig `paths` map resolves them instead.)
+
+All diagnostics go to **stderr** — stdout is the protocol.

packages/ui/acp-agent/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@deepseek-ai/dsh-acp-agent",
+  "description": "ACP server app: the agent-core spine + JSONL persistence + the ACP bridge (no stdout logger, no hmr, no pre-created agents), with a bin to boot a leaf cordis.yml over JSON-RPC stdio",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "bin": {
+    "dsh-acp-agent": "lib/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./bin": {
+      "types": "./lib/bin.d.ts",
+      "default": "./lib/bin.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@cordisjs/plugin-include": "^1.0.4",
+    "@cordisjs/plugin-loader": "^1.0.0-rc.4",
+    "@deepseek-ai/dsh-acp": "^0.0.1",
+    "@deepseek-ai/dsh-agent-core": "^0.0.1",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
+    "cordis": "^4.0.0-rc.6",
+    "schemastery": "^3.17.0"
+  },
+  "devDependencies": {
+    "@cordisjs/plugin-include": "workspace:^",
+    "@cordisjs/plugin-loader": "workspace:^",
+    "@deepseek-ai/dsh-acp": "workspace:^",
+    "@deepseek-ai/dsh-agent-core": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
+    "cordis": "^4.0.0-rc.6",
+    "schemastery": "^3.17.0"
+  }
+}

packages/ui/acp-agent/src/bin.ts

@@ -0,0 +1,168 @@
+#!/usr/bin/env node
+/**
+ * The `dsh-acp-agent` bin: boot the ACP server from a leaf `cordis.yml` that
+ * loads the {@link @deepseek-ai/dsh-acp-agent} app plugin (plus an LLM adapter
+ * and a bash executor), speaking ACP JSON-RPC on stdio.
+ *
+ * Owns the ACP-specific boot glue the example's `start.ts` once held:
+ *  - `.env` loading (`DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL`) — SKIPPED in
+ *    snapshot REPLAY so a stray key can never trigger a live model call.
+ *  - snapshot-mode config selection: `DSH_SNAPSHOT=replay` swaps the given
+ *    `cordis.yml` for its sibling `cordis.snapshot.yml` (the keyless replay
+ *    tree: `llm-replay` in place of `llm-deepseek`).
+ *  - the stdin-dispose lifecycle: in a snapshot run the harness closes stdin
+ *    when done, so dispose the context (flushing persistence) and exit cleanly.
+ *
+ * IMPORTANT: stdout is the ACP JSON-RPC channel. This bin writes diagnostics to
+ * STDERR only; the app plugin loads no stdout logger. A stray stdout write
+ * corrupts the protocol frames.
+ *
+ * Usage: `dsh-acp-agent [path-to-cordis.yml]` (default `./cordis.yml`).
+ *
+ * @module @deepseek-ai/dsh-acp-agent/bin
+ */
+
+import { pathToFileURL } from 'node:url'
+import { basename, dirname, resolve } from 'node:path'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+
+/**
+ * Resolve the config to boot, honoring snapshot REPLAY. Given the requested
+ * path, replay mode swaps a `cordis.yml` basename for `cordis.snapshot.yml` in
+ * the SAME directory (the keyless replay tree). Other modes use the path as-is.
+ * Returns an absolute path resolved from the cwd.
+ */
+export function resolveConfigPath(configPath: string, snapshotMode: string | undefined): string {
+  const absolute = resolve(process.cwd(), configPath)
+  if (snapshotMode !== 'replay') return absolute
+  const dir = dirname(absolute)
+  const replayName = basename(absolute).replace(/cordis\.ya?ml$/, 'cordis.snapshot.yml')
+  return resolve(dir, replayName)
+}
+
+/**
+ * Load `DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL` from a gitignored `.env` in the
+ * cwd (Node native). Diagnostics go to STDERR (stdout is the protocol). In
+ * REPLAY mode the caller skips this entirely — replay must never reach the
+ * network, so a present `.env` must not enable a live call.
+ */
+function loadEnv(): void {
+  try {
+    process.loadEnvFile(resolve(process.cwd(), '.env'))
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException | null)?.code !== 'ENOENT') {
+      process.stderr.write(`dsh-acp-agent: failed to load .env: ${String(error)}\n`)
+    }
+    // ENOENT (no .env) is fine — rely on the ambient environment.
+  }
+}
+
+/**
+ * Make a load failure fail loud with a clear message on stderr. Covers the
+ * failure path the entry-tree check below cannot: when the include's
+ * `[Service.init]` throws (e.g. a config FILE missing in a real directory), the
+ * cordis Loader surfaces it as an unhandled promise rejection AFTER `boot()`
+ * resolves — `loader.await()` does NOT rethrow it (`EntryTree.await()` uses
+ * `Promise.allSettled`, which swallows rejections). Node's default handler
+ * already exits non-zero on an unhandled rejection, so this does not change the
+ * exit code; it replaces the noisy stack dump with a single labelled line (on
+ * STDERR — stdout is the ACP JSON-RPC channel) and guarantees `process.exit(1)`.
+ * Install before `boot()`.
+ */
+export function installFailLoud(): void {
+  process.on('unhandledRejection', (err: unknown) => {
+    process.stderr.write(`dsh-acp-agent: fatal load failure: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`)
+    process.exit(1)
+  })
+}
+
+/**
+ * After the tree settles, assert every loader entry actually started. This is
+ * the load-bearing guard against the SILENT-exit-0 bug: a plugin module that
+ * fails to IMPORT (e.g. a config path in a non-existent directory) is caught and
+ * only LOGGED by the cordis Loader (`entry._init`), leaving the entry with no
+ * `fiber` and producing no rejection — so the process would otherwise exit 0. A
+ * started entry has a `fiber`; throw on any entry still missing one so `boot()`
+ * rejects.
+ *
+ * A `disabled` entry is the one legitimate fiber-less state: `Entry.refresh()`
+ * deliberately skips `init()` for it, so it settles without a fiber by design —
+ * a valid "plugin turned off" config, not a failed import. Exclude it.
+ */
+function assertEntriesLoaded(ctx: Context): void {
+  const failed = [...ctx.loader.entries()].filter(entry => entry.fiber === undefined && !entry.disabled)
+  if (failed.length > 0) {
+    const names = failed.map(entry => entry.options.name).join(', ')
+    throw new Error(`dsh-acp-agent: plugin(s) failed to load: ${names} (see the error(s) logged above)`)
+  }
+}
+
+/**
+ * Boot the Loader against `absoluteConfigPath`. The include is handed the
+ * config's ABSOLUTE `file://` URL as its `path`, so resolution never depends on
+ * `ctx.baseUrl` (an absolute URL ignores the base) and can never fall back to
+ * the cwd. `baseUrl` is still pinned to the config's directory so the config's
+ * OWN relative plugin/include paths resolve against it. Returns the root context
+ * once the whole tree has settled.
+ *
+ * The `await ctx.loader.await()` is load-bearing: `loader.create()` returns once
+ * the include ENTRY is registered, but the include then loads its child plugins
+ * asynchronously. Without awaiting the tree, `boot()` would resolve while the ACP
+ * bridge is still mounting — the process would have no stdin handle attached yet
+ * and could exit 0 silently. Awaiting keeps the process alive until the bridge
+ * is up.
+ *
+ * `loader.await()` does NOT rethrow load errors (`EntryTree.await()` uses
+ * `Promise.allSettled`), so failures are surfaced two ways: a plugin that fails
+ * to IMPORT leaves an entry with no fiber, caught here by
+ * {@link assertEntriesLoaded} (this `boot()` rejects); a plugin whose init THROWS
+ * surfaces as an unhandled rejection caught by {@link installFailLoud} (installed
+ * by `main()` before this runs). Together any load failure exits non-zero.
+ *
+ * Bare plugin specifiers in the config (`@deepseek-ai/dsh-*`, npm packages) are
+ * resolved by the cordis Loader's internal module loader, which is only active
+ * under `node --expose-internals`. The `demo:acp` script runs under tsx (whose
+ * tsconfig `paths` map resolves the workspace plugins instead), but a consumer
+ * running the built bin under plain node must pass `--expose-internals` so the
+ * Loader resolves the config's plugins from the config directory rather than
+ * relative to its own module.
+ */
+export async function boot(absoluteConfigPath: string): Promise<Context> {
+  const ctx = new Context()
+  ctx.baseUrl = pathToFileURL(dirname(absoluteConfigPath)).href + '/'
+  await ctx.plugin(Loader)
+  await ctx.loader.create({
+    name: '@cordisjs/plugin-include',
+    config: { path: pathToFileURL(absoluteConfigPath).href },
+  })
+  await ctx.loader.await()
+  assertEntriesLoaded(ctx)
+  return ctx
+}
+
+/**
+ * Entry point. Installs the fail-loud guard, selects the config (snapshot-aware),
+ * loads `.env` outside replay, boots, and — in a snapshot run — disposes the
+ * context on stdin EOF so the session log is fully flushed before exit and the
+ * harness's `waitForExit` resolves. In a normal editor session stdin stays open
+ * for the connection's lifetime (the editor kills the process), so the EOF
+ * handler never fires.
+ */
+export async function main(argv: string[] = process.argv.slice(2)): Promise<void> {
+  installFailLoud()
+  const snapshotMode = process.env.DSH_SNAPSHOT
+  const configPath = resolveConfigPath(argv[0] ?? './cordis.yml', snapshotMode)
+  if (snapshotMode !== 'replay') loadEnv()
+  const ctx = await boot(configPath)
+  if (snapshotMode !== undefined) {
+    process.stdin.on('end', () => {
+      void ctx.fiber.dispose().then(() => { process.exit(0) })
+    })
+  }
+}
+
+/* v8 ignore start -- top-level CLI invocation; the testable core is
+   resolveConfigPath()/boot()/main(), driven by the keyless snapshot + Loader-path tests */
+await main()
+/* v8 ignore stop */

packages/ui/acp-agent/src/index.ts

@@ -0,0 +1,72 @@
+/**
+ * The ACP server app: the providerless agent spine ({@link
+ * @deepseek-ai/dsh-agent-core}) plus the coupled front-door cluster an ACP
+ * server needs — JSONL session persistence and the {@link @deepseek-ai/dsh-acp}
+ * bridge, and DELIBERATELY NOTHING that writes to stdout.
+ *
+ * The cluster is the OPPOSITE of {@link @deepseek-ai/dsh-stdio-agent}'s, and
+ * baking it in is the whole point: an ACP server speaks JSON-RPC on stdout, so
+ * a stray console logger would corrupt the protocol frames (the [stdout-purity
+ * footgun]). This package contains NO console-logger entry, NO `hmr` (the editor
+ * owns the subprocess), and pre-creates NO agents (ACP `session/new` creates
+ * them on demand) — so the default front door has no logger entry to get wrong.
+ * (A leaf `cordis.yml` could still add a sibling `@cordisjs/plugin-logger-console`,
+ * which this app does not prevent — so the rule "never add a stdout logger to an
+ * ACP leaf" still stands; the app just gives the leaf nothing to misconfigure.)
+ *
+ * The leaf supplies only the swappable backends: the LLM adapter (`llm-deepseek`
+ * for the real model, `llm-replay` for keyless snapshot replay) and the bash
+ * executor (`bash-local`). This app's {@link Config} (model, system prompt,
+ * persistence root) routes each value to where it is wired — model/prompt onto
+ * the bridge's per-session agent template, the root onto the JSONL backend.
+ *
+ * Plugin export shape: named `name`/`Config`/`apply`, NO default export — the
+ * cordis Loader's `unwrapExports` does `exports.default ?? exports`, so a stray
+ * default would collapse the module to the bare `apply` and drop the `Config`
+ * namespace (see docs/postmortem/0001 — the exact bug that shipped here once).
+ * The keyless ACP snapshot/Loader-path tests guard this end-to-end.
+ *
+ * @module @deepseek-ai/dsh-acp-agent
+ */
+
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import * as acp from '@deepseek-ai/dsh-acp'
+import * as agentCore from '@deepseek-ai/dsh-agent-core'
+import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
+
+export const name = 'acp-agent'
+
+/**
+ * App config: the swappable per-deployment values. `model`/`systemPrompt`
+ * configure the agent template the ACP bridge creates each session's agent from
+ * (NOT a pre-created agent — ACP creates agents at `session/new`);
+ * `persistenceRoot` is the JSONL backend's directory.
+ */
+export interface Config {
+  /** Model name for ACP-created agents (must have a registered adapter). */
+  model: string
+  /** Per-agent system prompt for ACP-created agents. */
+  systemPrompt: string
+  /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
+  persistenceRoot?: string
+}
+
+export const Config: z<Config> = z.object({
+  model: z.string().required(),
+  systemPrompt: z.string().required(),
+  persistenceRoot: z.string().default('./.sessions'),
+})
+
+/**
+ * Compose the spine with the ACP front door. The agent-core bundle pre-creates
+ * NO agents (its `agents` list defaults to `[]`); the JSONL backend persists
+ * under `persistenceRoot`; the ACP bridge owns stdout for JSON-RPC and creates
+ * one agent per `session/new` from `model`/`systemPrompt`. No logger, no `hmr` —
+ * stdout stays pure.
+ */
+export function apply(ctx: Context, config: Config): void {
+  ctx.plugin(agentCore)
+  ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? './.sessions' })
+  ctx.plugin(acp, { model: config.model, systemPrompt: config.systemPrompt })
+}

packages/ui/acp-agent/tests/acp-agent.spec.ts

@@ -0,0 +1,73 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import * as acpAgent from '../src/index.ts'
+
+/**
+ * In-process unit coverage for the @deepseek-ai/dsh-acp-agent composition:
+ * mounting it brings up the agent-core spine + JSONL persistence + the ACP
+ * bridge in one `ctx.plugin`. Unlike the stdio app, this one loads NO
+ * Loader-only plugin (no hmr), so it mounts in a plain Context.
+ *
+ * The REAL Loader-path guard (export shape via `unwrapExports`, the headline
+ * ACP operations end-to-end) is the keyless bin smoke in `load-path.e2e.ts`;
+ * this spec asserts the composition and the persistenceRoot default branch.
+ */
+async function mount(config: acpAgent.Config): Promise<Context> {
+  const ctx = new 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
+}
+
+describe('dsh-acp-agent composition', () => {
+  it('brings up the spine + persistence + the ACP bridge', async () => {
+    const ctx = await mount({ model: 'mock', systemPrompt: 'hi', persistenceRoot: '/tmp/dsh-acp-agent-test' })
+    expect(ctx.get('agents')).toBeDefined()
+    expect(ctx.get('sessions')).toBeDefined()
+    expect(ctx.get('sessionPersistence')).toBeDefined()
+    expect(ctx.get('agentLoop')).toBeDefined()
+    // No pre-created agents — ACP session/new creates them on demand.
+    expect(ctx.get('agents')!.list()).toHaveLength(0)
+    await ctx.fiber.dispose()
+  })
+
+  it('defaults the persistence root when omitted', async () => {
+    // Exercises the `?? './.sessions'` fallback for a direct-apply caller that
+    // bypasses the schema's `.default(...)`: call `apply` directly (not via
+    // `ctx.plugin`, which validates+defaults the config first) with no
+    // persistenceRoot, so the runtime fallback is the one that fires.
+    const ctx = new Context()
+    acpAgent.apply(ctx, { model: 'mock', systemPrompt: 'hi' })
+    await new Promise(resolve => setTimeout(resolve, 50))
+    expect(ctx.get('sessionPersistence')).toBeDefined()
+    await ctx.fiber.dispose()
+  })
+
+  it('exposes its plugin shape', () => {
+    expect(acpAgent.name).toBe('acp-agent')
+    expect(acpAgent.Config).toBeDefined()
+  })
+
+  it('has the namespace-plugin export shape (no stray default) so the Loader keeps name/Config/apply', () => {
+    // Postmortem 0001 guard: a stray `export default apply` makes the Loader's
+    // `unwrapExports` (`exports.default ?? exports`) collapse the module to the
+    // bare `apply` function, DROPPING the named `name`/`Config`. This package has
+    // no `inject` export, so that collapse would NOT crash at load (the keyless
+    // bin smoke would still answer `initialize`) — it would silently lose its
+    // config schema. So guard the shape directly here: assert no `default`
+    // export, and that the real `unwrapExports` leaves `name`/`Config`/`apply`
+    // intact. Adding `export default` to src/index.ts fails this test.
+    expect('default' in acpAgent).toBe(false)
+    expect(typeof acpAgent.apply).toBe('function')
+
+    const loader = Object.create(Loader.prototype) as Loader
+    const unwrapped = loader.unwrapExports(acpAgent) as Record<string, unknown>
+    expect(unwrapped).toBe(acpAgent)
+    expect(unwrapped.name).toBe('acp-agent')
+    expect(unwrapped.Config).toBeDefined()
+    expect(typeof unwrapped.apply).toBe('function')
+  })
+})

packages/ui/acp-agent/tests/built-bin.e2e.ts

@@ -0,0 +1,195 @@
+import { spawn } from 'node:child_process'
+import { mkdtemp, mkdir, rm, symlink, writeFile, readFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import {
+  ClientSideConnection,
+  ndJsonStream,
+  PROTOCOL_VERSION,
+  type Agent as AcpAgent,
+  type Client,
+  type RequestPermissionRequest,
+  type RequestPermissionResponse,
+  type SessionNotification,
+} from '@agentclientprotocol/sdk'
+import { Readable, Writable } from 'node:stream'
+import { afterEach, describe, expect, it } from 'vitest'
+
+/**
+ * BUILT-ARTIFACT smoke for the published `dsh-acp-agent` bin. `load-path.e2e.ts`
+ * boots `src/bin.ts` under tsx — but the package's `bin` field points at
+ * `lib/bin.js`, run under plain `node` by a real consumer. This runs the REAL
+ * `lib/bin.js` under `node` (NOT tsx) and asserts it answers an `initialize`
+ * JSON-RPC frame, so a regression in the published entry (a settle race that
+ * exits before the bridge attaches, a stdout logger leaking onto the protocol)
+ * fails here.
+ *
+ * It build-gates: SKIPS if `lib/bin.js` is absent (suite run without
+ * `pnpm run build`); CI runs it after the build step. Setup mirrors a real
+ * install (a temp dir whose `node_modules` symlinks the built packages) and runs
+ * `node --expose-internals` (the cordis Loader resolves bare plugin specifiers
+ * via its internal module loader, active only under that flag). KEYLESS:
+ * `initialize` never reaches the model; a dummy key lets `llm-deepseek` boot.
+ */
+
+const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
+const acpBin = join(repoRoot, 'packages/ui/acp-agent/lib/bin.js')
+
+const dshPackages = [
+  'core/agent-core', 'core/agent', 'core/session', 'core/system-prompt',
+  'core/tools', 'core/agent-loop', 'llm/llm', 'llm/llm-deepseek', 'bash/bash',
+  'bash/bash-local', 'bash/tool-bash', 'support/invariants',
+  'session-persistence/session-persistence',
+  'session-persistence/session-persistence-jsonl', 'ui/acp', 'ui/acp-agent',
+]
+const vendorPackages = [
+  'cordis', 'loader', 'include', 'timer', 'hmr', 'logger-console',
+  'schemastery', 'cosmokit',
+]
+// Third-party deps the ACP bridge needs at runtime. They are declared by
+// `dsh-acp` (NOT by `acp-agent`), so they live under `packages/ui/acp/node_modules`
+// and are NOT necessarily hoisted where THIS test file can resolve them — pnpm's
+// strict layout only exposes a package's deps under that package. Resolve each
+// from the `ui/acp` package directory (the one that declares it) so the lookup
+// works regardless of hoisting, then symlink it into the consumer for plain node.
+const npmDeps = ['@agentclientprotocol/sdk', 'zod']
+const acpPkgDir = join(repoRoot, 'packages/ui/acp')
+
+async function pkgName(absDir: string): Promise<string> {
+  const json = JSON.parse(await readFile(join(absDir, 'package.json'), 'utf8')) as { name: string }
+  return json.name
+}
+
+async function link(target: string, name: string, nm: string): Promise<void> {
+  const dest = join(nm, name)
+  await mkdir(dirname(dest), { recursive: true })
+  await symlink(target, dest)
+}
+
+/** Build a temp consumer dir + a minimal acp `cordis.yml`. Returns the dir. */
+async function makeConsumer(): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'acp-built-bin-'))
+  const nm = join(dir, 'node_modules')
+  for (const rel of dshPackages) {
+    const abs = join(repoRoot, 'packages', rel)
+    await link(abs, await pkgName(abs), nm)
+  }
+  for (const v of vendorPackages) {
+    const abs = join(repoRoot, 'vendor', v)
+    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
+    // 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))
+    await link(dirname(resolved), dep, nm)
+  }
+  await writeFile(join(dir, 'cordis.yml'), [
+    '- id: llm-deepseek',
+    '  name: \'@deepseek-ai/dsh-llm-deepseek\'',
+    '  config:',
+    '    apiKey: !!js process.env.DEEPSEEK_API_KEY',
+    '    models: [deepseek-v4-flash]',
+    '- id: bash',
+    '  name: \'@deepseek-ai/dsh-bash-local\'',
+    '- id: acp-agent',
+    '  name: \'@deepseek-ai/dsh-acp-agent\'',
+    '  config:',
+    '    model: deepseek-v4-flash',
+    '    systemPrompt: \'test agent\'',
+    '',
+  ].join('\n'))
+  return dir
+}
+
+let consumer: string | undefined
+let child: ReturnType<typeof spawn> | undefined
+
+afterEach(async () => {
+  if (child !== undefined) { child.kill('SIGKILL'); child = undefined }
+  if (consumer !== undefined) await rm(consumer, { recursive: true, force: true })
+  consumer = undefined
+})
+
+describe.skipIf(!existsSync(acpBin))('dsh-acp-agent BUILT bin (node lib/bin.js, no tsx)', () => {
+  it('boots the published bin and answers an initialize JSON-RPC frame on stdout', async () => {
+    consumer = await makeConsumer()
+    child = spawn(process.execPath, ['--expose-internals', acpBin, './cordis.yml'], {
+      cwd: consumer,
+      // Dummy key: initialize never reaches the model, so it is never used.
+      env: { ...process.env, DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? 'sk-dummy-for-boot' },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+    const stderr: string[] = []
+    child.stderr!.setEncoding('utf8')
+    child.stderr!.on('data', (c: string) => stderr.push(c))
+    // Tee raw stdout for a protocol-purity check, and feed it to the SDK client.
+    const rawOut: string[] = []
+    const passthrough = new Readable({ read() {} })
+    child.stdout!.on('data', (buf: Buffer) => { rawOut.push(buf.toString('utf8')); passthrough.push(buf) })
+    child.stdout!.on('end', () => passthrough.push(null))
+    const stream = ndJsonStream(
+      Writable.toWeb(child.stdin!) as WritableStream<Uint8Array>,
+      Readable.toWeb(passthrough) as ReadableStream<Uint8Array>,
+    )
+    const makeClient = (_a: AcpAgent): Client => ({
+      sessionUpdate(_p: SessionNotification): Promise<void> { return Promise.resolve() },
+      requestPermission(_p: RequestPermissionRequest): Promise<RequestPermissionResponse> {
+        return Promise.resolve({ outcome: { outcome: 'cancelled' } })
+      },
+    })
+    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(stderr.join('')).not.toContain('without inject')
+    // stdout purity: every emitted line is a JSON-RPC frame, no logger leak.
+    for (const line of rawOut.join('').split('\n').filter(l => l.trim().length > 0)) {
+      expect(() => JSON.parse(line) as unknown).not.toThrow()
+    }
+  }, 30_000)
+
+  it('fails LOUD (non-zero exit + stderr) on a config whose directory does not exist', async () => {
+    // A typo'd config path must fail clearly, not exit 0. The include plugin
+    // itself cannot be imported from a non-existent dir; the Loader logs that and
+    // leaves the entry with no fiber, which boot()'s entry-load check throws on.
+    const { code, stderr } = await runBinExpectingExit('/nonexistent/dir/cordis.yml')
+    expect(code).not.toBe(0)
+    expect(stderr).toContain('failed to load')
+  }, 30_000)
+
+  it('fails LOUD (non-zero exit + stderr) on a missing config file in a real directory', async () => {
+    // The directory exists (the include imports), but the file does not — the
+    // include's init throws "config file not found", which surfaces as an
+    // unhandled rejection the fail-loud guard turns into a non-zero exit.
+    consumer = await makeConsumer()
+    const { code, stderr } = await runBinExpectingExit('./does-not-exist.yml', consumer)
+    expect(code).not.toBe(0)
+    expect(stderr).toContain('config file not found')
+  }, 30_000)
+})
+
+/** Spawn the built acp bin against `configArg` and resolve with its exit code + stderr. */
+function runBinExpectingExit(configArg: string, cwd: string = tmpdir()): Promise<{ code: number; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(process.execPath, ['--expose-internals', acpBin, configArg], {
+      cwd,
+      env: { ...process.env, DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? 'sk-dummy-for-boot' },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    })
+    child = proc
+    let stderr = ''
+    proc.stderr.setEncoding('utf8')
+    proc.stderr.on('data', (c: string) => { stderr += c })
+    const timer = setTimeout(() => { proc.kill('SIGKILL'); reject(new Error(`bin did not exit within 25s. stderr:\n${stderr}`)) }, 25_000)
+    proc.on('exit', (code) => { clearTimeout(timer); resolve({ code: code ?? -1, stderr }) })
+    proc.on('error', (err) => { clearTimeout(timer); reject(err) })
+    proc.stdin.end()
+  })
+}

packages/ui/acp-agent/tests/load-path.e2e.ts

@@ -0,0 +1,147 @@
+import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
+import { Readable, Writable } from 'node:stream'
+import { mkdtemp, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterEach, describe, expect, it } from 'vitest'
+import {
+  ClientSideConnection,
+  ndJsonStream,
+  PROTOCOL_VERSION,
+  type Agent as AcpAgent,
+  type Client,
+  type RequestPermissionRequest,
+  type RequestPermissionResponse,
+  type SessionNotification,
+} from '@agentclientprotocol/sdk'
+
+/**
+ * REAL-load-path smoke for @deepseek-ai/dsh-acp-agent: boot the app through its
+ * own `bin` (the demo:acp entry) as a subprocess, driving the cordis Loader and
+ * `unwrapExports` over a minimal `cordis.yml` that loads THIS package. This is
+ * the guard a hand-built `ctx.plugin({...})` mount structurally cannot be — that
+ * bypasses `unwrapExports`, the exact path that once dropped the bridge's
+ * `inject` and shipped (docs/postmortem/0001). It exercises the headline ACP
+ * operations end-to-end: `initialize` → `session/new` → `session/load`.
+ *
+ * KEYLESS: `session/new` and `session/load` reach the agent FACTORY but never
+ * the model (no prompt is sent), so no DEEPSEEK_API_KEY is needed. A dummy key
+ * lets `llm-deepseek`'s `apply()` (key-PRESENT check only) boot the tree.
+ *
+ * The config is written into a temp dir whose cwd IS the session workspace, so
+ * the bash workdir validation passes. We point tsx at the repo-root tsconfig
+ * (TSX_TSCONFIG_PATH) because the child's cwd is outside the repo and the
+ * unbuilt `paths` map is found by searching UP from cwd.
+ */
+
+const binScript = fileURLToPath(new URL('../src/bin.ts', import.meta.url))
+const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
+// Repo root is four levels up from packages/ui/acp-agent/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.
+const CORDIS_YML = `
+- id: llm-deepseek
+  name: '@deepseek-ai/dsh-llm-deepseek'
+  config:
+    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    models: [deepseek-v4-flash]
+- id: bash
+  name: '@deepseek-ai/dsh-bash-local'
+- id: acp-agent
+  name: '@deepseek-ai/dsh-acp-agent'
+  config:
+    model: deepseek-v4-flash
+    systemPrompt: 'You are a test agent.'
+`
+
+interface Spawned {
+  child: ChildProcessWithoutNullStreams
+  client: ClientSideConnection
+  stderr: string[]
+}
+
+let spawned: Spawned | undefined
+let workdir: string | undefined
+
+afterEach(async () => {
+  if (spawned !== undefined) {
+    spawned.child.kill('SIGKILL')
+    spawned = undefined
+  }
+  if (workdir !== undefined) await rm(workdir, { recursive: true, force: true })
+  workdir = undefined
+})
+
+async function boot(): Promise<Spawned & { cwd: string }> {
+  workdir = await mkdtemp(join(tmpdir(), 'acp-agent-pkg-'))
+  const cwd = workdir
+  const configPath = join(cwd, 'cordis.yml')
+  await writeFile(configPath, CORDIS_YML)
+  const child = spawn(
+    process.execPath,
+    ['--import', tsxLoader, binScript, configPath],
+    {
+      cwd,
+      env: {
+        ...process.env,
+        TSX_TSCONFIG_PATH: repoTsconfig,
+        // Key-present check only; no prompt is sent, so the model is never called.
+        DEEPSEEK_API_KEY: process.env.DEEPSEEK_API_KEY ?? 'keyless-acp-agent-smoke',
+      },
+      stdio: ['pipe', 'pipe', 'pipe'],
+    },
+  )
+  const stderr: string[] = []
+  child.stderr.setEncoding('utf8')
+  child.stderr.on('data', (chunk: string) => stderr.push(chunk))
+  const stream = ndJsonStream(
+    Writable.toWeb(child.stdin) as WritableStream<Uint8Array>,
+    Readable.toWeb(child.stdout) as ReadableStream<Uint8Array>,
+  )
+  const makeClient = (_agent: AcpAgent): Client => ({
+    sessionUpdate(_params: SessionNotification): Promise<void> {
+      return Promise.resolve()
+    },
+    requestPermission(_params: RequestPermissionRequest): Promise<RequestPermissionResponse> {
+      return Promise.resolve({ outcome: { outcome: 'cancelled' } })
+    },
+  })
+  const client = new ClientSideConnection(makeClient, stream)
+  spawned = { child, client, stderr }
+  return { ...spawned, cwd }
+}
+
+describe('dsh-acp-agent real-load-path smoke (bin + Loader, keyless)', () => {
+  it('boots via its bin and answers initialize → session/new → session/load', 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.
+    const init = await client.initialize({
+      protocolVersion: PROTOCOL_VERSION,
+      clientCapabilities: {},
+    })
+    expect(init.agentCapabilities?.loadSession).toBe(true)
+
+    // 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"). The bridge consults `sessionPersistence.list()` then
+    // `agents.resume()`, both of which run from the JSON-RPC read loop OUTSIDE
+    // the bridge's inject scope — the exact path postmortem 0001 crashed. A
+    // healthy tree rejects with a not-found error; a broken export shape would
+    // instead throw "cannot get property … without inject" before reaching it.
+    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)
+})

packages/ui/acp-agent/tsconfig.json

@@ -0,0 +1,30 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../../vendor/loader"
+    },
+    {
+      "path": "../acp"
+    },
+    {
+      "path": "../../core/agent-core"
+    },
+    {
+      "path": "../../session-persistence/session-persistence-jsonl"
+    }
+  ]
+}

packages/ui/acp-agent/tsdown.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from 'tsdown'
+
+/**
+ * acp-agent 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 `src/index.ts`, so this override adds `bin.ts`.
+ * Declarations come from `tsc -b` (dts: false), matching every package.
+ */
+export default defineConfig({
+  entry: ['src/index.ts', 'src/bin.ts'],
+  outDir: 'lib',
+  format: ['esm'],
+  platform: 'node',
+  target: 'es2024',
+  fixedExtension: false,
+  dts: false,
+  clean: false,
+})

packages/ui/stdio-agent/README.md

@@ -0,0 +1,60 @@
+# @deepseek-ai/dsh-stdio-agent
+
+The **terminal stdio chat app**: a Cordis app plugin that composes the providerless agent spine ([`@deepseek-ai/dsh-agent-core`](../../core/agent-core/README.md)) with the front-door cluster a terminal chat needs, and a `bin` that boots a leaf `cordis.yml`.
+
+It is the readline counterpart to [`@deepseek-ai/dsh-acp-agent`](../acp-agent/README.md): both consume the same spine, but each bakes in the OPPOSITE front-door cluster.
+
+## What it bakes in
+
+A terminal chat always wants the same cluster, so the package owns it rather than trusting each leaf to re-wire it:
+
+| Plugin | Why it is here |
+|---|---|
+| `@cordisjs/plugin-logger-console` | the console logger — stdout is just the terminal here, so logging to it is correct (the ACP app must NOT have this) |
+| `@deepseek-ai/dsh-agent-core` | the spine, pre-creating a `main` agent from this app's `model`/`systemPrompt` |
+| `@deepseek-ai/dsh-session-persistence-jsonl` | durable JSONL session log under `persistenceRoot` |
+| `@deepseek-ai/dsh-ui-stdio` | the readline UI, bound to the `main` agent |
+
+`@cordisjs/plugin-hmr` (the dev/demo edit-reload loop) is deliberately a **leaf** entry, NOT baked in here: it is a Loader-only, subprocess-only dev plugin — its constructor throws without `node --expose-internals` + a live `loader`, and the in-process test tier cannot even import it (so a package whose `apply` statically pulled it in could never carry the per-file coverage gate). Unlike the console logger, a stray `hmr` is not a stdout-purity footgun, so leaving it at the leaf costs no safety. The `demo:echo` / `demo:coding` leaves load it and pass `--expose-internals`.
+
+The leaf `cordis.yml` supplies only the **swappable backends** — an LLM adapter (`llm-deepseek` for the real model, or the mock `mock-llm` for a demo) and a bash executor (`bash-local`) — `hmr`, plus this app's [`Config`](#config). The whole plugin tree a run loads is therefore: this app's cluster, the spine inside `agent-core`, `hmr`, and the two leaf backends.
+
+## Config
+
+| Key | Default | Routed to |
+|---|---|---|
+| `model` | (required) | the pre-created `main` agent's model |
+| `systemPrompt` | (required) | the `main` agent's system prompt |
+| `persistenceRoot` | `./.sessions` | the JSONL backend's root directory |
+| `welcome` | `ready.` | the stdin-chat banner |
+| `resumeSessionId` | — | resume a persisted session id instead of starting fresh (sourced from an env var in the leaf) |
+
+## The bin
+
+`dsh-stdio-agent [path-to-cordis.yml]` (default `./cordis.yml`) loads a gitignored `.env` from the cwd (`DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL`), then drives the cordis Loader against the config and awaits the whole plugin tree before returning. Run it under `node --expose-internals`: the cordis Loader resolves the config's bare plugin specifiers (`@deepseek-ai/dsh-*`, npm packages) through its internal module loader, which is only active under that flag. The `demo:echo` / `demo:coding` scripts invoke it that way.
+
+## Example leaf `cordis.yml`
+
+```yaml
+# A real coding agent: hmr + the DeepSeek adapter + local bash, then this app.
+- id: hmr
+  name: '@cordisjs/plugin-hmr'
+  config:
+    root: ['.']
+- id: llm-deepseek
+  name: '@deepseek-ai/dsh-llm-deepseek'
+  config:
+    apiKey: !!js process.env.DEEPSEEK_API_KEY
+    models: [deepseek-v4-flash]
+- id: bash
+  name: '@deepseek-ai/dsh-bash-local'
+  config:
+    timeoutMs: 60000
+- id: stdio-agent
+  name: '@deepseek-ai/dsh-stdio-agent'
+  config:
+    model: deepseek-v4-flash
+    systemPrompt: 'You are a CLI coding assistant. Your only tools are bash…'
+```
+
+Swap `llm-deepseek` for a `mock-llm` leaf plugin and you have the echo demo — "swap the backend, keep the app".

packages/ui/stdio-agent/package.json

@@ -0,0 +1,53 @@
+{
+  "name": "@deepseek-ai/dsh-stdio-agent",
+  "description": "Terminal stdio chat app: the agent-core spine + console logger + readline UI + a pre-created main agent, with a bin to boot a leaf cordis.yml",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/index.d.ts",
+  "bin": {
+    "dsh-stdio-agent": "lib/bin.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./bin": {
+      "types": "./lib/bin.d.ts",
+      "default": "./lib/bin.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@cordisjs/plugin-include": "^1.0.4",
+    "@cordisjs/plugin-loader": "^1.0.0-rc.4",
+    "@cordisjs/plugin-logger-console": "^1.0.0",
+    "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-agent-core": "^0.0.1",
+    "@deepseek-ai/dsh-session": "^0.0.1",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
+    "@deepseek-ai/dsh-ui-stdio": "^0.0.1",
+    "cordis": "^4.0.0-rc.6",
+    "schemastery": "^3.17.0"
+  },
+  "devDependencies": {
+    "@cordisjs/plugin-include": "workspace:^",
+    "@cordisjs/plugin-loader": "workspace:^",
+    "@cordisjs/plugin-logger-console": "workspace:^",
+    "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-agent-core": "workspace:^",
+    "@deepseek-ai/dsh-session": "workspace:^",
+    "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",
+    "@deepseek-ai/dsh-ui-stdio": "workspace:^",
+    "cordis": "^4.0.0-rc.6",
+    "schemastery": "^3.17.0"
+  }
+}

packages/ui/stdio-agent/src/bin.ts

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+/**
+ * The `dsh-stdio-agent` bin: boot a Cordis app from a leaf `cordis.yml` that
+ * loads the {@link @deepseek-ai/dsh-stdio-agent} app plugin (plus a backend LLM
+ * adapter and a bash executor). Owns the boot glue the three `examples/*` once
+ * duplicated in their `start.ts`: load the gitignored repo-root `.env`, then
+ * drive the cordis Loader against the config path (default `./cordis.yml`).
+ *
+ * Usage: `dsh-stdio-agent [path-to-cordis.yml]`. The `demo:echo` / `demo:coding`
+ * scripts invoke it with the example's config.
+ *
+ * @module @deepseek-ai/dsh-stdio-agent/bin
+ */
+
+import { pathToFileURL } from 'node:url'
+import { dirname, resolve } from 'node:path'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+
+/**
+ * Load `DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL` from a gitignored `.env` in the
+ * CURRENT WORKING DIRECTORY (Node native `process.loadEnvFile`). An absent file
+ * is fine — the environment may already carry the variables; the leaf
+ * `cordis.yml` reads them via the `!!js` tag. A present-but-unreadable/malformed
+ * `.env` is a real misconfiguration: surface it on stderr rather than silently
+ * running with the wrong environment. The mock-model demo (echo) ships no key
+ * and simply has no `.env`.
+ */
+function loadEnv(): void {
+  try {
+    process.loadEnvFile(resolve(process.cwd(), '.env'))
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException | null)?.code !== 'ENOENT') {
+      process.stderr.write(`dsh-stdio-agent: failed to load .env: ${String(error)}\n`)
+    }
+    // ENOENT (no .env) is fine — rely on the ambient environment.
+  }
+}
+
+/**
+ * Make a load failure fail loud with a clear message on stderr. Covers the
+ * failure path the entry-tree check below cannot: when the include's
+ * `[Service.init]` throws (e.g. a config FILE that does not exist in a real
+ * directory), the cordis Loader surfaces it as an unhandled promise rejection
+ * AFTER `boot()` has resolved — `loader.await()` does NOT rethrow it, because
+ * `EntryTree.await()` uses `Promise.allSettled`, which swallows rejections.
+ * Node's default handler already exits non-zero on an unhandled rejection, so
+ * this does not change the exit code; it replaces Node's noisy stack dump with a
+ * single labelled line and guarantees `process.exit(1)`. Install before `boot()`.
+ */
+export function installFailLoud(): void {
+  process.on('unhandledRejection', (err: unknown) => {
+    process.stderr.write(`dsh-stdio-agent: fatal load failure: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`)
+    process.exit(1)
+  })
+}
+
+/**
+ * After the tree settles, assert every loader entry actually started. This is
+ * the load-bearing guard against the SILENT-exit-0 bug: when a plugin module
+ * fails to IMPORT (e.g. a config path in a non-existent directory, so the include
+ * plugin itself cannot be resolved), the cordis Loader catches the import error
+ * and only LOGS it (`entry._init`), leaving the entry with no `fiber` and
+ * producing no rejection — so the process would otherwise exit 0 with a usable
+ * config typo reported only as a log line. A started entry has a `fiber`; an
+ * entry with `fiber === undefined` after the tree settled never loaded. Throw on
+ * any such entry so `boot()` rejects (and the top-level `await` fails the process
+ * non-zero) instead of returning a half-empty context.
+ *
+ * A `disabled` entry is the one legitimate fiber-less state: `Entry.refresh()`
+ * deliberately skips `init()` for it, so it settles without a fiber by design.
+ * That is a valid config (a consumer turning an optional plugin off), not a
+ * failed import — exclude it so the guard catches only real load failures.
+ */
+function assertEntriesLoaded(ctx: Context): void {
+  const failed = [...ctx.loader.entries()].filter(entry => entry.fiber === undefined && !entry.disabled)
+  if (failed.length > 0) {
+    const names = failed.map(entry => entry.options.name).join(', ')
+    throw new Error(`dsh-stdio-agent: plugin(s) failed to load: ${names} (see the error(s) logged above)`)
+  }
+}
+
+/**
+ * Boot the Loader against `configPath` (resolved from the CWD). The include is
+ * handed the config's ABSOLUTE `file://` URL as its `path`, so resolution never
+ * depends on `ctx.baseUrl` (an absolute URL ignores the base) and can never fall
+ * back to the cwd. `baseUrl` is still pinned to the config's directory so the
+ * config's OWN relative plugin/include paths (e.g. `./src/mock-llm.ts`) resolve
+ * against it. Returns the root context once the whole tree has settled.
+ *
+ * The `await ctx.loader.await()` is load-bearing: `loader.create()` returns once
+ * the include ENTRY is registered, but the include then loads its child plugins
+ * asynchronously. Without awaiting the tree, `boot()` (and `main()`) would
+ * resolve while the app plugins — the stdin reader, the agent loop — are still
+ * mounting, and a CLI process with no attached handles yet exits 0 silently.
+ * Awaiting the tree keeps the process alive until the app's handles are attached.
+ *
+ * `loader.await()` does NOT, however, rethrow load errors (`EntryTree.await()`
+ * uses `Promise.allSettled`), so failures are surfaced two ways: a plugin that
+ * fails to IMPORT leaves an entry with no fiber, caught here by
+ * {@link assertEntriesLoaded} (this `boot()` rejects); a plugin whose init
+ * THROWS surfaces as an unhandled rejection caught by {@link installFailLoud}
+ * (installed by `main()` before this runs). Together they make any load failure
+ * exit non-zero with a clear message.
+ *
+ * Bare plugin specifiers in the config (`@deepseek-ai/dsh-*`, npm packages) are
+ * resolved by the cordis Loader's internal module loader, which is only active
+ * under `node --expose-internals` (the flag the `demo:echo`/`demo:coding` scripts
+ * pass). Without it the Loader falls back to resolving relative to its own module
+ * and cannot find the config's plugins, so a consumer running the built bin must
+ * pass `--expose-internals` (or install the plugins where node hoists them).
+ */
+export async function boot(configPath: string): Promise<Context> {
+  const absolute = resolve(process.cwd(), configPath)
+  const ctx = new Context()
+  ctx.baseUrl = pathToFileURL(dirname(absolute)).href + '/'
+  await ctx.plugin(Loader)
+  await ctx.loader.create({
+    name: '@cordisjs/plugin-include',
+    config: { path: pathToFileURL(absolute).href },
+  })
+  await ctx.loader.await()
+  assertEntriesLoaded(ctx)
+  return ctx
+}
+
+/**
+ * Entry point: install the fail-loud guard, load `.env`, then boot the config
+ * named on argv (default `./cordis.yml`). Awaited at the module top level by the
+ * published bin (`#!/usr/bin/env node` shebang via the package's `bin` field).
+ */
+export async function main(argv: string[] = process.argv.slice(2)): Promise<void> {
+  installFailLoud()
+  loadEnv()
+  await boot(argv[0] ?? './cordis.yml')
+}
+
+/* v8 ignore start -- top-level CLI invocation; the testable core is boot()/main(), driven by the keyless Loader-path smoke */
+await main()
+/* v8 ignore stop */

packages/ui/stdio-agent/src/index.ts

@@ -0,0 +1,98 @@
+/**
+ * The stdio chat app: the providerless agent spine ({@link
+ * @deepseek-ai/dsh-agent-core}) plus the coupled front-door cluster a terminal
+ * chat needs — a console logger, the readline `ui-stdio` UI, JSONL session
+ * persistence, and a pre-created `main` agent the UI drives.
+ *
+ * The cluster is BAKED IN, not left to the leaf: a stdio app always logs to the
+ * console (stdout is just the terminal) and always pre-creates the `main` agent
+ * `ui-stdio` sends to. The leaf supplies only the swappable backends (the LLM
+ * adapter, the bash executor), the optional `hmr` dev-reload plugin, and this
+ * app's {@link Config} (model, prompt, persistence root, welcome banner).
+ *
+ * `hmr` is deliberately a LEAF entry, not baked in here: it is a Loader-only,
+ * subprocess-only dev plugin (its constructor throws without `--expose-internals`
+ * + a live `loader`, and the in-process test tier cannot even import it), so a
+ * package whose `apply` statically pulled it in could never be unit-tested or
+ * carry the per-file coverage gate. Unlike the console logger, a stray `hmr` is
+ * not a stdout-purity footgun — so leaving it at the leaf costs no safety, while
+ * baking the LOGGER in (the real coupling) keeps stdout-vs-no-stdout a property
+ * of the artifact.
+ *
+ * Counterpart to {@link @deepseek-ai/dsh-acp-agent}, which bakes in the OPPOSITE
+ * cluster (no stdout logger, no pre-created agents — the ACP bridge reserves
+ * stdout for JSON-RPC and creates agents on demand). Splitting the two front
+ * doors into two packages makes each cluster a property of the artifact: there
+ * is no logger entry in the ACP leaf to get wrong.
+ *
+ * Plugin export shape: named `name`/`Config`/`apply`, NO default export — the
+ * cordis Loader's `unwrapExports` does `exports.default ?? exports`, so a stray
+ * default would collapse the module to the bare `apply` and drop the `Config`
+ * namespace (see docs/postmortem/0001). The keyless Loader-path smoke in the
+ * echo example guards this end-to-end.
+ *
+ * @module @deepseek-ai/dsh-stdio-agent
+ */
+
+import type { Context } from 'cordis'
+import ConsoleExporter from '@cordisjs/plugin-logger-console'
+import z from 'schemastery'
+import { AgentId } from '@deepseek-ai/dsh-agent'
+import { SessionId } from '@deepseek-ai/dsh-session'
+import * as agentCore from '@deepseek-ai/dsh-agent-core'
+import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
+import * as uiStdio from '@deepseek-ai/dsh-ui-stdio'
+
+export const name = 'stdio-agent'
+
+/**
+ * App config: the swappable per-demo values, each routed to where the app wires
+ * it. `model`/`systemPrompt`/`resumeSessionId` configure the pre-created `main`
+ * agent (through {@link @deepseek-ai/dsh-agent-core}'s forwarded `agents` list);
+ * `persistenceRoot` is the JSONL backend's directory; `welcome` is the UI banner.
+ */
+export interface Config {
+  /** Model name for the `main` agent (must have a registered adapter). */
+  model: string
+  /** System prompt for the `main` agent. */
+  systemPrompt: string
+  /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
+  persistenceRoot?: string
+  /** stdin-chat banner printed once on start. Defaults to `'ready.'`. */
+  welcome?: string
+  /**
+   * If set, the `main` agent RESUMES this persisted session id instead of
+   * starting fresh. Sourced from an env var in the leaf `cordis.yml`
+   * (`resumeSessionId: !!js process.env.RESUME_SESSION_ID`).
+   */
+  resumeSessionId?: string
+}
+
+export const Config: z<Config> = z.object({
+  model: z.string().required(),
+  systemPrompt: z.string().required(),
+  persistenceRoot: z.string().default('./.sessions'),
+  welcome: z.string().default('ready.'),
+  resumeSessionId: z.string(),
+})
+
+/**
+ * Compose the spine with the stdio front door. The console logger comes first
+ * (infra), then the agent-core bundle pre-creating the `main` agent from this
+ * app's `model`/`systemPrompt`/`resumeSessionId`, then the JSONL backend, then
+ * the `ui-stdio` UI bound to `main`. The `hmr` dev-reload plugin is a leaf
+ * concern (see the module doc), so it is not mounted here.
+ */
+export function apply(ctx: Context, config: Config): void {
+  ctx.plugin(ConsoleExporter)
+  ctx.plugin(agentCore, {
+    agents: [{
+      id: AgentId('main'),
+      model: config.model,
+      systemPrompt: config.systemPrompt,
+      ...config.resumeSessionId !== undefined ? { resumeSessionId: SessionId(config.resumeSessionId) } : {},
+    }],
+  })
+  ctx.plugin(SessionPersistenceJsonl, { root: config.persistenceRoot ?? './.sessions' })
+  ctx.plugin(uiStdio, { welcome: config.welcome ?? 'ready.', agent: 'main' })
+}

packages/ui/stdio-agent/tests/built-bin.e2e.ts

@@ -0,0 +1,186 @@
+import { spawn } from 'node:child_process'
+import { cp, mkdtemp, mkdir, rm, symlink, writeFile, readFile } from 'node:fs/promises'
+import { existsSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterEach, describe, expect, it } from 'vitest'
+
+/**
+ * BUILT-ARTIFACT smoke for the published `dsh-stdio-agent` bin. The other smokes
+ * boot `src/bin.ts` under tsx — but the package's `bin` field points at
+ * `lib/bin.js`, run under plain `node` by a real consumer. tsx masks two failure
+ * modes the built bin had: (1) `boot()` returned before the loader tree settled,
+ * so the process exited 0 with no output and load errors surfaced as unhandled
+ * rejections AFTER boot; (2) config-path resolution could fall back to the cwd.
+ * This test runs the REAL `lib/bin.js` under `node` (NOT tsx) and asserts the
+ * banner + echo round-trip, so a regression in the published entry fails here.
+ *
+ * It build-gates: if `lib/bin.js` is absent (suite run without `pnpm run build`)
+ * the test SKIPS with a note. CI runs it after the build step. Setup mirrors a
+ * real install: a temp dir whose `node_modules/@deepseek-ai/*` (and the vendored
+ * `cordis`/`@cordisjs/*`) are symlinked to the built packages, a `cordis.yml`
+ * that loads the app + the example's mock backend, and `node --expose-internals`
+ * (the cordis Loader resolves bare plugin specifiers via its internal module
+ * loader, active only under that flag — the same flag `demo:echo` passes).
+ */
+
+const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
+const stdioBin = join(repoRoot, 'packages/ui/stdio-agent/lib/bin.js')
+
+// Workspace packages the stdio app's tree needs, by repo-relative path. Each is
+// symlinked into the temp consumer's node_modules under its package name, so
+// plain `node` resolves the bare `@deepseek-ai/dsh-*` specifiers in cordis.yml
+// to the built `lib/` (package.json `main`), exactly as an installed dep would.
+const dshPackages = [
+  'core/agent-core', 'core/agent', 'core/session', 'core/system-prompt',
+  'core/tools', 'core/agent-loop', 'llm/llm', 'bash/bash', 'bash/bash-local',
+  'bash/tool-bash', 'support/invariants', 'support/ui-stdio',
+  'session-persistence/session-persistence',
+  'session-persistence/session-persistence-jsonl', 'ui/stdio-agent',
+]
+const vendorPackages = [
+  'cordis', 'loader', 'include', 'timer', 'hmr', 'logger-console',
+  '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 temp consumer dir: `node_modules` with the workspace + vendor packages
+ * symlinked in, a `src/` carrying the example mock backend, and a `cordis.yml`
+ * that wires them onto the stdio app. Returns the dir (caller removes it).
+ *
+ * `disabledBrokenEntry` appends an entry that points at a non-existent plugin but
+ * is marked `disabled: true`. The Loader leaves a disabled entry fiber-less by
+ * design, so it exercises that the fail-loud entry-load guard does NOT mistake a
+ * valid disabled entry for a failed import.
+ */
+async function makeConsumer(welcome: string, disabledBrokenEntry = false): Promise<string> {
+  const dir = await mkdtemp(join(tmpdir(), 'stdio-built-bin-'))
+  const nm = join(dir, 'node_modules')
+  for (const rel of dshPackages) {
+    const abs = join(repoRoot, 'packages', rel)
+    const name = await pkgName(abs)
+    const target = join(nm, name)
+    await mkdir(dirname(target), { recursive: true })
+    await symlink(abs, target)
+  }
+  for (const v of vendorPackages) {
+    const abs = join(repoRoot, 'vendor', v)
+    const name = await pkgName(abs)
+    const target = join(nm, name)
+    await mkdir(dirname(target), { recursive: true })
+    await symlink(abs, target)
+  }
+  // The example's mock model + echo tool are example-local TS plugins (Node 24+
+  // strips types natively, so plain `node` loads them); they import the workspace
+  // packages the symlinked node_modules now provides.
+  await cp(join(repoRoot, 'examples/echo-agent/src'), join(dir, 'src'), { recursive: true })
+  await writeFile(join(dir, 'cordis.yml'), [
+    '- id: mock-llm',
+    '  name: \'./src/mock-llm.ts\'',
+    '- id: echo-tool',
+    '  name: \'./src/echo-tool.ts\'',
+    '- id: bash',
+    '  name: \'@deepseek-ai/dsh-bash-local\'',
+    '- id: stdio-agent',
+    '  name: \'@deepseek-ai/dsh-stdio-agent\'',
+    '  config:',
+    '    model: mock-echo',
+    '    systemPrompt: \'demo\'',
+    `    welcome: '${welcome}'`,
+    ...disabledBrokenEntry
+      ? ['- id: off', '  name: \'./src/does-not-exist.ts\'', '  disabled: true']
+      : [],
+    '',
+  ].join('\n'))
+  return dir
+}
+
+/** Run the built bin in `cwd` against `configArg` with one stdin line; resolve with stdout/stderr + exit code. */
+function runBuiltBin(cwd: string, configArg: string, line: string): Promise<{ stdout: string; code: number; stderr: string }> {
+  return new Promise((resolve, reject) => {
+    // --expose-internals: the cordis Loader resolves bare plugin specifiers via
+    // its internal module loader (active only under this flag); demo:echo passes
+    // it too. NO tsx — this is the published `node lib/bin.js` path.
+    const child = spawn(process.execPath, ['--expose-internals', stdioBin, configArg], {
+      cwd,
+      // Mock model: never calls the network, so no key needed.
+      env: { ...process.env },
+      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.write(`${line}\n`)
+    child.stdin.end()
+  })
+}
+
+let consumer: string | undefined
+
+afterEach(async () => {
+  if (consumer !== undefined) await rm(consumer, { recursive: true, force: true })
+  consumer = undefined
+})
+
+describe.skipIf(!existsSync(stdioBin))('dsh-stdio-agent BUILT bin (node lib/bin.js, no tsx)', () => {
+  it('boots the published bin, prints its banner, and runs the echo tool round-trip', async () => {
+    consumer = await makeConsumer('BUILT-BIN-OK ready.')
+    const { stdout, code, stderr } = await runBuiltBin(consumer, './cordis.yml', 'echo hi')
+    expect(stderr).not.toContain('UNHANDLED')
+    expect(stderr).not.toContain('without inject')
+    // The banner proves boot() awaited the tree (the settle-race regression would
+    // exit 0 with empty stdout); the round-trip proves the whole app mounted.
+    expect(stdout).toContain('BUILT-BIN-OK ready.')
+    expect(stdout).toContain('[tool call] echo')
+    expect(stdout).toContain('[tool result] ECHO: HI')
+    expect(code).toBe(0)
+  }, 30_000)
+
+  it('boots cleanly when the config disables an (otherwise unresolvable) entry', async () => {
+    // A `disabled: true` entry settles without a fiber by design; the fail-loud
+    // entry-load guard must NOT mistake it for a failed import. Even though its
+    // plugin path does not exist, the app boots and the round-trip works.
+    consumer = await makeConsumer('DISABLED-OK ready.', true)
+    const { stdout, code, stderr } = await runBuiltBin(consumer, './cordis.yml', 'echo hi')
+    expect(stderr).not.toContain('failed to load')
+    expect(stdout).toContain('DISABLED-OK ready.')
+    expect(stdout).toContain('[tool result] ECHO: HI')
+    expect(code).toBe(0)
+  }, 30_000)
+
+  it('fails LOUD (non-zero exit + stderr) on a config whose directory does not exist', async () => {
+    // A consumer who typos the config path must get a clear failure, not silent
+    // success. This dir does not exist, so the include PLUGIN itself fails to
+    // import; the cordis Loader logs that and leaves the entry with no fiber (no
+    // rejection), which `boot()`'s entry-load check turns into a thrown error.
+    consumer = await makeConsumer('unused')
+    const { code, stderr } = await runBuiltBin(consumer, '/nonexistent/dir/cordis.yml', '')
+    expect(code).not.toBe(0)
+    expect(stderr).toContain('failed to load')
+  }, 30_000)
+
+  it('fails LOUD (non-zero exit + stderr) on a missing config file in a real directory', async () => {
+    // The config DIRECTORY exists (the include plugin imports), but the file does
+    // not — the include's init throws "config file not found", which surfaces as
+    // an unhandled rejection the fail-loud guard turns into a non-zero exit.
+    consumer = await makeConsumer('unused')
+    const { code, stderr } = await runBuiltBin(consumer, './does-not-exist.yml', '')
+    expect(code).not.toBe(0)
+    expect(stderr).toContain('config file not found')
+  }, 30_000)
+})

packages/ui/stdio-agent/tests/stdio-agent.spec.ts

@@ -0,0 +1,92 @@
+import { describe, it, expect } from 'vitest'
+import { Context } from 'cordis'
+import Loader from '@cordisjs/plugin-loader'
+import { AgentId } from '@deepseek-ai/dsh-agent'
+import * as stdioAgent from '../src/index.ts'
+
+/**
+ * Unit coverage for the @deepseek-ai/dsh-stdio-agent app plugin: mounting it
+ * composes the console logger, the agent-core spine (pre-creating the `main`
+ * agent from the app config), the JSONL backend, and the readline UI in one
+ * `ctx.plugin`. The forwarded `model`/`systemPrompt` reach the pre-created
+ * agent; `persistenceRoot`/`welcome`/`resumeSessionId` route to their backends.
+ *
+ * `hmr` is NOT part of this plugin (it is a leaf entry — a Loader-only dev
+ * plugin the in-process tier cannot import); the REAL Loader-path guard (export
+ * shape, `unwrapExports`, the whole subprocess tree incl. `hmr`) is the keyless
+ * echo smoke in `examples/echo-agent`. Here we assert the composition + config
+ * forwarding the unit tier can reach.
+ */
+async function mount(config: stdioAgent.Config): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(stdioAgent, config)
+  // The app mounts its children inside apply() (not awaited there); let their
+  // fibers settle so the spine services + the pre-created agent are ready.
+  await new Promise(resolve => setTimeout(resolve, 80))
+  return ctx
+}
+
+describe('dsh-stdio-agent app', () => {
+  it('composes the spine + front-door cluster and pre-creates the main agent', async () => {
+    const ctx = await mount({ model: 'mock', systemPrompt: 'hi', persistenceRoot: '/tmp/dsh-stdio-agent-spec' })
+    // The spine services (brought up by the agent-core bundle) are all present.
+    expect(ctx.get('agents')).toBeDefined()
+    expect(ctx.get('agentLoop')).toBeDefined()
+    expect(ctx.get('sessionPersistence')).toBeDefined()
+    // The pre-created `main` agent the UI drives.
+    expect(ctx.get('agents')?.get(AgentId('main'))).toBeDefined()
+    await ctx.fiber.dispose()
+  })
+
+  it('defaults persistenceRoot and welcome when omitted', async () => {
+    // Direct apply (NOT via ctx.plugin, which validates+defaults the config
+    // first) so the runtime `?? './.sessions'` / `?? 'ready.'` fallbacks on
+    // apply()'s last two lines are the ones that fire — covering a
+    // schema-bypassing direct-mount caller.
+    const ctx = new Context()
+    stdioAgent.apply(ctx, { model: 'mock', systemPrompt: 'hi' })
+    await new Promise(resolve => setTimeout(resolve, 80))
+    expect(ctx.get('sessionPersistence')).toBeDefined()
+    expect(ctx.get('agents')?.get(AgentId('main'))).toBeDefined()
+    await ctx.fiber.dispose()
+  })
+
+  it('forwards resumeSessionId onto the pre-created agent when set', async () => {
+    // A resume id defers agent creation until persistence loads; with no backing
+    // session the resume is contained + logged, so no `main` agent registers —
+    // the branch that maps resumeSessionId through is what this covers.
+    const ctx = await mount({
+      model: 'mock',
+      systemPrompt: 'hi',
+      persistenceRoot: '/tmp/dsh-stdio-agent-spec-resume',
+      resumeSessionId: 'no-such-session',
+    })
+    expect(ctx.get('agents')?.get(AgentId('main'))).toBeUndefined()
+    await ctx.fiber.dispose()
+  })
+
+  it('exposes its name and Config schema', () => {
+    expect(stdioAgent.name).toBe('stdio-agent')
+    expect(stdioAgent.Config).toBeDefined()
+  })
+
+  it('has the namespace-plugin export shape (no stray default) so the Loader keeps name/Config/apply', () => {
+    // Postmortem 0001 guard: a stray `export default apply` makes the Loader's
+    // `unwrapExports` (`exports.default ?? exports`) collapse the module to the
+    // bare `apply` function, DROPPING the named `name`/`Config`. This package has
+    // no `inject` export, so that collapse would NOT crash at load (the keyless
+    // echo smoke would still boot the tree) — it would silently lose its config
+    // schema. So guard the shape directly here: assert no `default` export, and
+    // that the real `unwrapExports` leaves `name`/`Config`/`apply` intact. Adding
+    // `export default` to src/index.ts fails this test.
+    expect('default' in stdioAgent).toBe(false)
+    expect(typeof stdioAgent.apply).toBe('function')
+
+    const loader = Object.create(Loader.prototype) as Loader
+    const unwrapped = loader.unwrapExports(stdioAgent) as Record<string, unknown>
+    expect(unwrapped).toBe(stdioAgent)
+    expect(unwrapped.name).toBe('stdio-agent')
+    expect(unwrapped.Config).toBeDefined()
+    expect(typeof unwrapped.apply).toBe('function')
+  })
+})

packages/ui/stdio-agent/tsconfig.json

@@ -0,0 +1,39 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/schemastery"
+    },
+    {
+      "path": "../../../vendor/loader"
+    },
+    {
+      "path": "../../../vendor/logger-console"
+    },
+    {
+      "path": "../../core/agent"
+    },
+    {
+      "path": "../../core/session"
+    },
+    {
+      "path": "../../core/agent-core"
+    },
+    {
+      "path": "../../session-persistence/session-persistence-jsonl"
+    },
+    {
+      "path": "../../support/ui-stdio"
+    }
+  ]
+}

packages/ui/stdio-agent/tsdown.config.ts

@@ -0,0 +1,18 @@
+import { defineConfig } from 'tsdown'
+
+/**
+ * stdio-agent 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 `src/index.ts`, so this override adds `bin.ts`.
+ * Declarations come from `tsc -b` (dts: false), matching every package.
+ */
+export default defineConfig({
+  entry: ['src/index.ts', 'src/bin.ts'],
+  outDir: 'lib',
+  format: ['esm'],
+  platform: 'node',
+  target: 'es2024',
+  fixedExtension: false,
+  dts: false,
+  clean: false,
+})

pnpm-lock.yaml

@@ -133,6 +133,39 @@ importers:
         specifier: ^4.0.0-rc.6
         version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4)
 
+  packages/core/agent-core:
+    devDependencies:
+      '@cordisjs/plugin-timer':
+        specifier: workspace:^
+        version: link:../../../vendor/timer
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../agent
+      '@deepseek-ai/dsh-agent-loop':
+        specifier: workspace:^
+        version: link:../agent-loop
+      '@deepseek-ai/dsh-invariants':
+        specifier: workspace:^
+        version: link:../../support/invariants
+      '@deepseek-ai/dsh-llm':
+        specifier: workspace:^
+        version: link:../../llm/llm
+      '@deepseek-ai/dsh-session':
+        specifier: workspace:^
+        version: link:../session
+      '@deepseek-ai/dsh-system-prompt':
+        specifier: workspace:^
+        version: link:../system-prompt
+      '@deepseek-ai/dsh-tool-bash':
+        specifier: workspace:^
+        version: link:../../bash/tool-bash
+      '@deepseek-ai/dsh-tools':
+        specifier: workspace:^
+        version: link:../tools
+      cordis:
+        specifier: ^4.0.0-rc.6
+        version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4)
+
   packages/core/agent-loop:
     dependencies:
       schemastery:
@@ -377,6 +410,63 @@ importers:
         specifier: ^4.0.0-rc.6
         version: 4.0.0-rc.6(@cordisjs/plugin-include@1.0.4)(@cordisjs/plugin-loader@1.0.0-rc.4)
 
+  packages/ui/acp-agent:
+    devDependencies:
+      '@cordisjs/plugin-include':
+        specifier: workspace:^
+        version: link:../../../vendor/include
+      '@cordisjs/plugin-loader':
+        specifier: workspace:^
+        version: link:../../../vendor/loader
+      '@deepseek-ai/dsh-acp':
+        specifier: workspace:^
+        version: link:../acp
+      '@deepseek-ai/dsh-agent-core':
+        specifier: workspace:^
+        version: link:../../core/agent-core
+      '@deepseek-ai/dsh-session-persistence-jsonl':
+        specifier: workspace:^
+        version: link:../../session-persistence/session-persistence-jsonl
+      cordis:
+        specifier: ^4.0.0-rc.6
+        version: 4.0.0-rc.6(@cordisjs/plugin-include@vendor+include)(@cordisjs/plugin-loader@vendor+loader)
+      schemastery:
+        specifier: ^3.17.0
+        version: 3.18.0
+
+  packages/ui/stdio-agent:
+    devDependencies:
+      '@cordisjs/plugin-include':
+        specifier: workspace:^
+        version: link:../../../vendor/include
+      '@cordisjs/plugin-loader':
+        specifier: workspace:^
+        version: link:../../../vendor/loader
+      '@cordisjs/plugin-logger-console':
+        specifier: workspace:^
+        version: link:../../../vendor/logger-console
+      '@deepseek-ai/dsh-agent':
+        specifier: workspace:^
+        version: link:../../core/agent
+      '@deepseek-ai/dsh-agent-core':
+        specifier: workspace:^
+        version: link:../../core/agent-core
+      '@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-ui-stdio':
+        specifier: workspace:^
+        version: link:../../support/ui-stdio
+      cordis:
+        specifier: ^4.0.0-rc.6
+        version: 4.0.0-rc.6(@cordisjs/plugin-include@vendor+include)(@cordisjs/plugin-loader@vendor+loader)
+      schemastery:
+        specifier: ^3.17.0
+        version: 3.18.0
+
   packages/util/brand:
     devDependencies:
       cordis:
@@ -3893,6 +3983,14 @@ snapshots:
       '@cordisjs/plugin-include': 1.0.4(@cordisjs/plugin-loader@1.0.0-rc.4)(cordis@4.0.0-rc.6)
       '@cordisjs/plugin-loader': 1.0.0-rc.4(cordis@4.0.0-rc.6)
 
+  cordis@4.0.0-rc.6(@cordisjs/plugin-include@vendor+include)(@cordisjs/plugin-loader@vendor+loader):
+    dependencies:
+      '@standard-schema/spec': 1.1.0
+      cosmokit: 1.8.1
+    optionalDependencies:
+      '@cordisjs/plugin-include': link:vendor/include
+      '@cordisjs/plugin-loader': link:vendor/loader
+
   cosmokit@1.8.1: {}
 
   cross-spawn@7.0.6:

scripts/verify-package-paths.ts

@@ -28,6 +28,13 @@
  * Scope mirrors the other doc gates plus repo-authored TypeScript: Markdown
  * across README/docs/packages/AGENTS, and `.ts` under packages/** and
  * examples/** (excluding built `lib/`, `*.d.ts`, and vendored upstream source).
+ * A reference to a package's build OUTPUT (`packages/<group>/<pkg>/lib/…`,
+ * e.g. `packages/ui/acp-agent/lib/bin.js` cited by a built-bin smoke) is also
+ * skipped — it is emitted only by `pnpm run build`, which CI runs AFTER this
+ * gate, so flagging it would be a false positive on a path that is correct but
+ * not yet on disk. That skip is scoped to a REAL package root: a stale
+ * group-less `packages/acp-agent/lib/bin.js` is still flagged (its root does not
+ * exist — exactly the moved-package drift this gate catches).
  *
  * Run: `tsx scripts/verify-package-paths.ts`.
  */
@@ -111,6 +118,17 @@ function findViolations(absPath: string): Violation[] {
       // class may have swallowed (`packages/core/tools.` / `…/tools/`).
       const ref = m[0].replace(/[./]+$/, '')
       if (existsSync(resolve(root, ref))) continue
+      // A reference INTO a package's built `lib/` is a build OUTPUT, not an
+      // authored-source location: it does not exist until `pnpm run build` emits
+      // it, and CI runs this gate BEFORE the build step. Skip it — but ONLY when
+      // the `packages/<group>/<pkg>` ROOT it sits under is real and on disk, so
+      // `packages/ui/acp-agent/lib/bin.js` (correct, just not yet built) is
+      // exempt while a stale `packages/acp-agent/lib/bin.js` (group-less, the
+      // exact moved-package drift this gate exists to catch) still flags. A bare
+      // `lib` segment is not a blanket escape hatch.
+      const parts = ref.split('/')
+      const libAt = parts.indexOf('lib')
+      if (libAt === 3 && existsSync(resolve(root, parts.slice(0, 3).join('/')))) continue
       // Only a stale path to a REAL (moved) package is a violation; a segment
       // matching a live package name is the drift signal.
       const segments = ref.split('/').slice(1)

tsconfig.build.json

@@ -20,6 +20,7 @@
     { "path": "./packages/core/agent" },
     { "path": "./packages/core/tools" },
     { "path": "./packages/core/agent-loop" },
+    { "path": "./packages/core/agent-core" },
     { "path": "./packages/bash/bash" },
     { "path": "./packages/llm/llm-deepseek" },
     { "path": "./packages/llm/llm-pi-ai" },
@@ -27,6 +28,8 @@
     { "path": "./packages/bash/tool-bash" },
     { "path": "./packages/support/invariants" },
     { "path": "./packages/ui/acp" },
+    { "path": "./packages/ui/acp-agent" },
+    { "path": "./packages/ui/stdio-agent" },
     { "path": "./packages/support/ui-stdio" },
     { "path": "./packages/support/llm-replay" }
   ]

vitest.config.ts

@@ -26,7 +26,12 @@ export default defineConfig({
       // executable code; vendor/ and examples/ are out of scope (examples are
       // exercised by the demo smoke test instead).
       include: ['packages/*/*/src/**/*.ts'],
-      exclude: ['packages/*/*/src/types.ts'],
+      // Types-only files carry no executable code. `bin.ts` files are
+      // self-executing CLI entrypoints (a top-level `await main()`): a spec
+      // can't import one without booting it, so they are driven by the keyless
+      // Loader-path smoke (a real subprocess) instead of the in-process unit
+      // suite — the same reason `examples/start.ts` sat out of coverage scope.
+      exclude: ['packages/*/*/src/types.ts', 'packages/*/*/src/bin.ts'],
       // 100% or it doesn't merge (AGENTS.md: excessive tests are welcome).
       // Per-file so a well-covered big file can't subsidize a bare one.
       // Every v8 ignore comment must carry a reason — see AGENTS.md.