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

Implements docs/rfc/.../2026-06-20-extract-example-app-packages.md. Each
example was thick — a hand-rolled start.ts, an infra preamble, nested
base.yml/base-core.yml/acp-tail.yml includes, and a coupled front-door
cluster enforced only by prose. This moves the composition into packages so
each example is a thin leaf cordis.yml: pick the swappable backends, load one
app package.

New packages:
  - @deepseek-ai/dsh-agent-core (packages/core/agent-core): one bundle plugin
    that loads the providerless/executor-less/UI-less spine (timer + llm +
    sessions + system-prompt + tools + agents + invariants + tool-bash +
    agent-loop) via ctx.plugin(...) inside apply(), and forwards agent-loop's
    `agents` list as its own Config (export const Config = AgentLoop.Config,
    default []).
  - @deepseek-ai/dsh-stdio-agent (packages/ui/stdio-agent): terminal chat APP —
    agent-core + console logger + readline UI + a pre-created `main` agent, with
    a bin. The demo:echo/coding front door.
  - @deepseek-ai/dsh-acp-agent (packages/ui/acp-agent): ACP server APP —
    agent-core + JSONL persistence + the acp bridge, NO stdout logger, with a
    bin. The stdout-purity footgun is structurally unreachable from the leaf.

Amendment to the RFC: hmr stays a LEAF cordis.yml entry, not baked into
dsh-stdio-agent. hmr is a Loader-only dev plugin (throws without
--expose-internals; the in-process test tier can't even import its decorator
form), so a package statically importing it 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. With hmr out, all three new
packages carry in-process unit specs at 100%.

Boot glue (Loader tail, .env load, snapshot-mode selection, stdin-dispose
lifecycle) moves into each app's bin; start.ts and base.yml/base-core.yml/
acp-tail.yml are deleted. Each app package gets a keyless real-load-path test
that boots through its bin + the cordis Loader (guarding the unwrapExports
export-shape bug class, postmortem 0001). ACP snapshot replay stays green
against the existing committed goldens (pure boot restructuring). RFC moved
proposed->implemented with the amendment recorded; package/example/architecture
docs and the module graph updated.

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,39 @@
+# @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 there is no logger entry in the package, the footgun is **structurally unreachable from the leaf**: a leaf author cannot wire a stdout logger into the ACP config, because the leaf only picks backends, not the front door.
+
+## 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.
+
+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,100 @@
+#!/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.
+  }
+}
+
+/**
+ * Boot the Loader against `absoluteConfigPath`. `baseUrl` is pinned to the
+ * config's directory and the include gets only the basename, so the config's
+ * relative plugin/include paths resolve as the upstream `cordis` bin does.
+ * Returns the root context.
+ */
+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: `./${basename(absoluteConfigPath)}` },
+  })
+  return ctx
+}
+
+/**
+ * Entry point. 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> {
+  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,70 @@
+/**
+ * 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 footgun is structurally unreachable from the leaf:
+ * there is no logger entry to get wrong.
+ *
+ * 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,52 @@
+import { describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+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()
+  })
+})

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 — the boot glue the `examples/*/start.ts` files once each duplicated. The `demo:echo` / `demo:coding` scripts invoke it.
+
+## 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,70 @@
+#!/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 { basename, 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.
+  }
+}
+
+/**
+ * Boot the Loader against `configPath` (resolved from the CWD). `baseUrl` is
+ * pinned to the config's directory and the include is handed only the basename,
+ * so the config's relative plugin/include paths resolve exactly as the upstream
+ * `cordis` bin does. Returns the root context (the process owns its lifetime).
+ */
+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: `./${basename(absolute)}` },
+  })
+  return ctx
+}
+
+/**
+ * Entry point: 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> {
+  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/stdio-agent.spec.ts

@@ -0,0 +1,71 @@
+import { describe, it, expect } from 'vitest'
+import { Context } from 'cordis'
+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()
+  })
+})

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,
+})