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/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' })
+}