refactor(examples): extract reusable logic into tested packages

Logic that lived under examples/ was outside the per-file 100% coverage
gate (examples/ are not workspaces) and, in the stdio-UI case, duplicated
across two examples. Move it into packages/ so it is gated and de-duped.

- packages/ui-stdio (new): unify the two diverged stdio-chat.ts copies into
  one @deepseek-ai/dsh-ui-stdio plugin (welcome/agent Config). A test-only
  I/O seam (createStdioChat(ctx, config, runtime)) keeps process streams out
  of the serializable config and makes every render/EOF/disposal branch
  unit-testable. Per-file 100%. echo/coding cordis.yml now load the package;
  both src/stdio-chat.ts deleted.
- packages/llm-replay (new): move examples/acp-agent/src/llm-replay.ts (+ its
  spec) here so its derive/parse/replay branches fall under the coverage gate.
  cordis.snapshot.yml + README rewired to the package name; added apply/env
  /assertNever/abort tests to reach per-file 100%.
- examples/{echo,coding}-agent: keyless Loader-path e2e smokes that boot the
  real cordis.yml (no key) — the guard a hand-mounted unit test cannot be for
  the unwrapExports/export-shape class (postmortem 0001). examples/AGENTS.md
  codifies the keyless+with-key smoke convention (keyless-by-nature exception
  for echo-agent).
- AGENTS.md: a scoped, removal-triggered pre-release stance (foundation over
  blast radius). packages/README.md: new rows + a FIXME to later regroup ALL
  packages into a hierarchy. Wiring: tsconfig paths/refs, publint, knip,
  module-graph.

Verified: typecheck, lint, test:coverage (887 tests, 100%), build, hygiene,
doc-sync, test:snapshot (10), test:e2e (6 keyless pass, with-key self-skip).

examples/echo-agent/cordis.yml

@@ -52,4 +52,6 @@
     root: './.sessions'
 
 - id: stdio-chat
-  name: './src/stdio-chat.ts'
+  name: '@deepseek-ai/dsh-ui-stdio'
+  config:
+    welcome: 'echo-agent ready. Type a message ("echo <text>" triggers the tool).'

examples/echo-agent/src/stdio-chat.ts

@@ -1,60 +0,0 @@
-import { createInterface } from 'node:readline'
-import type { Context } from 'cordis'
-import type {} from '@deepseek-ai/dsh-agent'
-
-export const name = 'stdio-chat'
-export const inject = ['agents']
-
-/**
- * Minimal UI plugin: reads lines from stdin → agent.send(); renders the
- * agent's stream chunks and tool activity to stdout. Demonstrates that a UI
- * is "just a plugin" — it only consumes the agent/* event taxonomy.
- */
-export function apply(ctx: Context) {
-  ctx.on('agent/stream-chunk', (_agent, _turn, _step, chunk) => {
-    if (chunk.type === 'text-delta') process.stdout.write(chunk.text)
-  })
-
-  ctx.on('agent/turn-start', (agent, turn) => {
-    process.stdout.write(`\n[${agent.id} turn ${turn}] `)
-  })
-
-  ctx.on('agent/turn-end', () => {
-    process.stdout.write('\n> ')
-  })
-
-  ctx.on('session/event', (_session, event) => {
-    if (event.type === 'tool/call') {
-      const { name: toolName, arguments: args } = event.data
-      process.stdout.write(`\n  [tool call] ${toolName}(${args})`)
-    } else if (event.type === 'tool/result') {
-      const { content } = event.data
-      const text = content.filter(b => b.type === 'text').map(b => b.text).join('')
-      process.stdout.write(`\n  [tool result] ${text}\n  `)
-    }
-  })
-
-  ctx.effect(() => {
-    const reader = createInterface({ input: process.stdin })
-    reader.on('line', (line) => {
-      const text = line.trim()
-      if (!text) return
-      const agent = ctx.agents.get('main')
-      if (!agent) {
-        console.error('agent "main" is not running')
-        return
-      }
-      if (agent.status === 'running') {
-        agent.steer([{ type: 'text', text }])
-      } else {
-        agent.send([{ type: 'text', text }])
-      }
-    })
-    reader.on('close', () => {
-      // allow the process to exit when stdin ends (piped input)
-      setTimeout(() => process.exit(0), 200)
-    })
-    process.stdout.write('echo-agent ready. Type a message ("echo <text>" triggers the tool).\n> ')
-    return () => { reader.close() }
-  }, 'stdio-chat')
-}

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

@@ -0,0 +1,106 @@
+import { spawn, type ChildProcessWithoutNullStreams } from 'node:child_process'
+import { mkdtemp, rm } 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'
+
+/**
+ * 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.
+ *
+ * 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.
+ *
+ * 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))
+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
+// a temp cwd OUTSIDE the repo, so point tsx at the repo tsconfig explicitly
+// (repo root is four levels up from examples/echo-agent/tests).
+const repoTsconfig = fileURLToPath(new URL('../../../tsconfig.json', import.meta.url))
+
+let child: ChildProcessWithoutNullStreams | undefined
+let workdir: string | undefined
+
+afterEach(async () => {
+  if (child !== undefined && child.exitCode === null) child.kill('SIGKILL')
+  child = undefined
+  if (workdir !== undefined) await rm(workdir, { recursive: true, force: true })
+  workdir = undefined
+})
+
+/**
+ * Boot echo-agent, write `lines` to its stdin, close stdin, and resolve with
+ * the full stdout once the process exits (the stdio UI exits on EOF after the
+ * agent settles). Rejects on a non-zero exit or a 10s timeout.
+ */
+async function runEcho(lines: string[]): Promise<{ stdout: string; code: number }> {
+  workdir = await mkdtemp(join(tmpdir(), 'echo-smoke-'))
+  const cwd = workdir
+  return new Promise((resolve, reject) => {
+    const proc = spawn(
+      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],
+      { cwd, env: { ...process.env, TSX_TSCONFIG_PATH: repoTsconfig }, stdio: ['pipe', 'pipe', 'pipe'] },
+    )
+    child = proc
+    let stdout = ''
+    let stderr = ''
+    proc.stdout.setEncoding('utf8')
+    proc.stdout.on('data', (chunk: string) => { stdout += chunk })
+    proc.stderr.setEncoding('utf8')
+    proc.stderr.on('data', (chunk: string) => { stderr += chunk })
+
+    const timer = setTimeout(() => {
+      proc.kill('SIGKILL')
+      reject(new Error(`echo-agent did not exit within 10s. stdout:\n${stdout}\nstderr:\n${stderr}`))
+    }, 10_000)
+
+    proc.on('exit', (code) => {
+      clearTimeout(timer)
+      if (code === 0) resolve({ stdout, code })
+      else reject(new Error(`echo-agent exited ${code}. stderr:\n${stderr}`))
+    })
+    proc.on('error', (err) => { clearTimeout(timer); reject(err) })
+
+    // Feed the script, then EOF so the stdio UI exits after the agent settles.
+    for (const line of lines) proc.stdin.write(`${line}\n`)
+    proc.stdin.end()
+  })
+}
+
+describe('echo-agent keyless smoke (real cordis.yml via the Loader)', () => {
+  it('boots, prints its welcome banner, and exits cleanly on stdin EOF', async () => {
+    const { stdout, code } = await runEcho([])
+    expect(code).toBe(0)
+    expect(stdout).toContain('echo-agent ready.')
+  }, 15_000)
+
+  it('runs the echo tool round-trip for an "echo …" line', async () => {
+    const { stdout } = await runEcho(['echo hello world'])
+    // mock-llm.ts emits a tool-call for the echo tool; echo-tool.ts uppercases.
+    expect(stdout).toContain('[tool call] echo')
+    expect(stdout).toContain('[tool result] ECHO: HELLO WORLD')
+  }, 15_000)
+
+  it('streams a direct canned reply for a non-echo line', async () => {
+    const { stdout } = await runEcho(['just chatting'])
+    // The direct-response branch of mock-llm.ts quotes the input back.
+    expect(stdout).toContain('just chatting')
+    expect(stdout).not.toContain('[tool call]')
+  }, 15_000)
+})