Merge remote-tracking branch 'origin/master' into simpl-e-acp-trim

# Conflicts:
#	docs/rfc/README.md

packages/ui/README.md

@@ -7,7 +7,8 @@ Integrations that expose the agent to an external editor or client. These are **
 | `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`) |
+| `app-boot/` | Shared boot glue for the two app bins: `.env` loading, fail-loud Loader guards, snapshot-aware config resolution, the settle-the-tree boot sequence | (library for the bins) |
 
-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.
+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 is the unstructured analogue of the `acp` bridge and lives INSIDE the stdio app (the `stdio-chat` module of [`stdio-agent/`](stdio-agent/README.md)): it is scaffolding for that one front door, not an independently swappable integration, so it carries no package boundary of its own.
 
 `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 the swappable backends plus one app entry plus any optional product tools. 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/package.json

@@ -32,6 +32,7 @@
   "peerDependencies": {
     "@cordisjs/plugin-include": "^1.0.4",
     "@cordisjs/plugin-loader": "^1.0.0-rc.4",
+    "@deepseek-ai/dsh-app-boot": "^0.0.1",
     "@deepseek-ai/dsh-acp": "^0.0.1",
     "@deepseek-ai/dsh-agent-core": "^0.0.1",
     "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
@@ -41,6 +42,7 @@
   "devDependencies": {
     "@cordisjs/plugin-include": "workspace:^",
     "@cordisjs/plugin-loader": "workspace:^",
+    "@deepseek-ai/dsh-app-boot": "workspace:^",
     "@deepseek-ai/dsh-acp": "workspace:^",
     "@deepseek-ai/dsh-agent-core": "workspace:^",
     "@deepseek-ai/dsh-session-persistence-jsonl": "workspace:^",

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

@@ -2,167 +2,45 @@
 /**
  * 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.
+ * and a bash executor), speaking ACP JSON-RPC on stdio. The shared boot glue —
+ * `.env` loading, the fail-loud Loader guards, snapshot-aware config
+ * resolution, the settle-the-tree boot sequence — lives in
+ * {@link @deepseek-ai/dsh-app-boot}; this bin owns only the ACP-specific
+ * lifecycle:
  *
- * 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.
+ *  - `.env` loading is SKIPPED in snapshot REPLAY so a stray key can never
+ *    trigger a live model call.
+ *  - `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`).
+ *  - In a snapshot run the harness closes stdin when done, so dispose the
+ *    context (flushing persistence) and exit cleanly. In a normal editor
+ *    session stdin stays open for the connection's lifetime (the editor kills
+ *    the process), so the EOF handler never fires.
  *
  * 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.
+ * STDERR only (the app plugin loads no stdout logger, and the shared guards
+ * write to stderr); 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'
+import { boot, installFailLoud, loadEnv, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
 
-/**
- * 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)
-}
+const NAME = 'dsh-acp-agent'
 
-/**
- * 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)
+/* v8 ignore start -- thin self-executing composition over the unit-tested
+   dsh-app-boot helpers; exercised end-to-end by the snapshot suite and the
+   built-bin smoke */
+installFailLoud(NAME)
+const snapshotMode = process.env['DSH_SNAPSHOT']
+if (snapshotMode !== 'replay') loadEnv(NAME)
+const ctx = await boot(NAME, resolveConfigPath(process.argv[2] ?? './cordis.yml', snapshotMode))
+if (snapshotMode !== undefined) {
+  process.stdin.on('end', () => {
+    void ctx.fiber.dispose().then(() => { process.exit(0) })
   })
 }
-
-/**
- * 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/tests/built-bin.e2e.ts

@@ -40,7 +40,7 @@ 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',
+  'bash/bash-local', 'bash/tool-bash', 'support/invariants', 'ui/app-boot',
   'session-persistence/session-persistence',
   'session-persistence/session-persistence-jsonl', 'ui/acp', 'ui/acp-agent',
 ]

packages/ui/acp-agent/tsconfig.json

@@ -17,6 +17,9 @@
     {
       "path": "../../../vendor/loader"
     },
+    {
+      "path": "../app-boot"
+    },
     {
       "path": "../acp"
     },

packages/ui/acp/src/codec.ts

@@ -69,8 +69,8 @@ export function turnEndToStopReason(reason: TurnEndReason): StopReason {
  * client as message content. Today only `text` maps; `resource_link` is an
  * ACP prompt-only input rendered into text by {@link acpPromptToText};
  * `reasoning` is surfaced via `agent_thought_chunk`
- * streaming rather than as a message block, and `tool-call`/`tool-result`/
- * `image` are handled by the tool-call update path or not advertised.
+ * streaming rather than as a message block, and `tool-call`/`tool-result`
+ * are handled by the tool-call update path.
  */
 export function harnessBlockToAcpContent(block: ContentBlock): AcpContentBlock | undefined {
   switch (block.type) {
@@ -78,7 +78,7 @@ export function harnessBlockToAcpContent(block: ContentBlock): AcpContentBlock |
       return { type: 'text', text: block.text }
     // reasoning → streamed as agent_thought_chunk, not a message block
     // tool-call / tool-result → the tool_call / tool_call_update path
-    // image → not advertised
+    // plugin-added block types → not surfaced
     default:
       return undefined
   }

packages/ui/acp/tests/codec.spec.ts

@@ -1,4 +1,5 @@
 import { describe, expect, it } from 'vitest'
+import type { ContentBlock } from '@deepseek-ai/dsh-llm'
 import type { TurnEndReason } from '@deepseek-ai/dsh-session'
 import type { ContentBlock as AcpContentBlock } from '@agentclientprotocol/sdk'
 import {
@@ -33,9 +34,9 @@ describe('harnessBlockToAcpContent', () => {
     expect(harnessBlockToAcpContent({ type: 'text', text: 'hi' })).toEqual({ type: 'text', text: 'hi' })
   })
 
-  it('returns undefined for non-text blocks (reasoning/tool/image)', () => {
+  it('returns undefined for non-text blocks (reasoning / plugin-added)', () => {
     expect(harnessBlockToAcpContent({ type: 'reasoning', text: 'think' })).toBeUndefined()
-    expect(harnessBlockToAcpContent({ type: 'image', url: 'https://x/y.png', mimeType: 'image/png' })).toBeUndefined()
+    expect(harnessBlockToAcpContent({ type: 'chart', data: 'x' } as unknown as ContentBlock)).toBeUndefined()
   })
 })
 

packages/ui/acp/tests/stream-update.spec.ts

@@ -93,7 +93,7 @@ describe('streamSessionEventUpdate', () => {
   it('drops non-text tool-result content (text-only)', () => {
     const update = updatesFor(evt('tool/result', {
       turn: 1, step: 1, callId: CallId('c1'),
-      content: [{ type: 'image', url: 'https://x/y.png' }],
+      content: [{ type: 'reasoning', text: 'private' }],
       isError: false,
     }))[0]
     expect((update as { content: unknown[] }).content).toEqual([])

packages/ui/app-boot/README.md

@@ -0,0 +1,15 @@
+# `@deepseek-ai/dsh-app-boot`
+
+Shared boot glue for the app bins ([`dsh-stdio-agent`](../stdio-agent/README.md), [`dsh-acp-agent`](../acp-agent/README.md)): each bin is a thin self-executing composition over these helpers, parameterized by its diagnostic prefix, so the loader-failure lore lives once — under the per-file coverage gate — instead of drifting between two published artifacts.
+
+| Export | Role |
+|---|---|
+| `resolveConfigPath(path, snapshotMode, cwd?)` | Absolute config path; `snapshotMode === 'replay'` swaps a `cordis.yml`/`.yaml` basename for its sibling `cordis.snapshot.yml` |
+| `loadEnv(binName, dir?, warn?)` | Load the gitignored `.env` (Node `process.loadEnvFile`); absent file is fine, an unloadable one warns a single labelled line (default: stderr) |
+| `installFailLoud(binName, proc?)` | Turn a post-`boot()` unhandled Loader rejection into one labelled stderr line + `exit(1)`; returns the uninstaller (for tests) |
+| `assertEntriesLoaded(ctx, binName)` | Throw when a settled tree holds an enabled entry with no fiber (a plugin module that failed to import) |
+| `boot(binName, absoluteConfigPath)` | Mount the Loader, include the config by absolute `file://` URL, await the whole tree, assert entries loaded, return the root context |
+
+Two failure classes the guards handle: `loader.await()` swallows init rejections (`Promise.allSettled`) — Node still exits non-zero on the resulting unhandled rejection, and `installFailLoud` replaces the noisy dump with one labelled line and a guaranteed `exit(1)`; a failed plugin IMPORT is only logged by the Loader (the process would otherwise exit 0 on a usable config typo), leaving a fiber-less entry that `assertEntriesLoaded` turns into a `boot()` rejection.
+
+Bare plugin specifiers in a config (`@deepseek-ai/dsh-*`) resolve through the cordis Loader's internal module loader, active only under `node --expose-internals`; the bins' subprocess smokes exercise that path, while this package's unit suite drives `boot()` in-process against configs with relative specifiers.

packages/ui/app-boot/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@deepseek-ai/dsh-app-boot",
+  "description": "Shared boot glue for the app bins: .env loading, fail-loud Loader guards, snapshot-aware config resolution, and the Loader boot sequence",
+  "version": "0.0.1",
+  "private": true,
+  "type": "module",
+  "main": "lib/index.js",
+  "types": "lib/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./lib/types/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib/index.js",
+    "lib/types/**/*.d.ts",
+    "lib/types/**/*.d.ts.map",
+    "src"
+  ],
+  "license": "BSD-3-Clause",
+  "peerDependencies": {
+    "@cordisjs/plugin-include": "^1.0.4",
+    "@cordisjs/plugin-loader": "^1.0.0-rc.4",
+    "cordis": "^4.0.0-rc.6"
+  },
+  "devDependencies": {
+    "@cordisjs/plugin-include": "workspace:^",
+    "@cordisjs/plugin-loader": "workspace:^",
+    "cordis": "^4.0.0-rc.6"
+  }
+}

packages/ui/app-boot/src/index.ts

@@ -0,0 +1,154 @@
+/**
+ * Shared boot glue for the app bins (`dsh-stdio-agent`, `dsh-acp-agent`): load
+ * the gitignored `.env`, install the fail-loud Loader guards, resolve the
+ * config path (snapshot-aware), and drive the cordis Loader against a leaf
+ * `cordis.yml` until the whole tree has settled. Each bin stays a thin
+ * self-executing composition over these helpers, parameterized by its
+ * diagnostic prefix; the loader-failure lore lives here, once, under the
+ * per-file coverage gate.
+ *
+ * Two failure classes the guards handle:
+ *
+ * - `loader.await()` does NOT rethrow a load error (`EntryTree.await()` uses
+ *   `Promise.allSettled`, which swallows rejections). A plugin whose
+ *   `[Service.init]` throws surfaces as an unhandled rejection AFTER `boot()`
+ *   resolves — Node's default handler already exits non-zero, and
+ *   {@link installFailLoud} replaces the noisy dump with one labelled stderr
+ *   line and a guaranteed `exit(1)`.
+ * - A plugin module that fails to IMPORT is caught and only LOGGED by the
+ *   cordis Loader (`entry._init`), leaving the entry with no `fiber` and
+ *   producing no rejection — the process would otherwise exit 0 with a usable
+ *   config typo reported only as a log line; {@link assertEntriesLoaded} makes
+ *   `boot()` reject on any such entry instead of returning a half-empty
+ *   context.
+ *
+ * @module @deepseek-ai/dsh-app-boot
+ */
+
+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 — including no
+ * snapshot mode at all — use the path as-is. Returns an absolute path resolved
+ * from `cwd`.
+ */
+export function resolveConfigPath(
+  configPath: string, snapshotMode: string | undefined, cwd: string = process.cwd(),
+): string {
+  const absolute = resolve(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
+ * `dir` (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 `.env` is a real
+ * misconfiguration: surface it via `warn` (one line, default stderr) rather
+ * than silently running with the wrong environment.
+ */
+export function loadEnv(
+  binName: string, dir: string = process.cwd(),
+  warn: (line: string) => void = line => void process.stderr.write(line),
+): void {
+  try {
+    process.loadEnvFile(resolve(dir, '.env'))
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException | null)?.code !== 'ENOENT') {
+      warn(`${binName}: failed to load .env: ${String(error)}\n`)
+    }
+    // ENOENT (no .env) is fine — rely on the ambient environment.
+  }
+}
+
+/**
+ * The slice of `process` {@link installFailLoud} needs — injectable so tests
+ * exercise the handler without registering on (or exiting) the real process.
+ */
+export interface FailLoudProcess {
+  on(event: 'unhandledRejection', handler: (err: unknown) => void): unknown
+  off(event: 'unhandledRejection', handler: (err: unknown) => void): unknown
+  stderr: { write(chunk: string): unknown }
+  exit(code: number): void
+}
+
+/**
+ * Make a load failure fail loud with a clear message on stderr. Covers the
+ * failure path {@link assertEntriesLoaded} cannot: an include whose
+ * `[Service.init]` throws (e.g. a config FILE that does not exist in a real
+ * directory) surfaces as an unhandled promise rejection AFTER `boot()`
+ * resolves. Node's default handler already exits non-zero on an unhandled
+ * rejection; this replaces the noisy stack dump with a single labelled line on
+ * STDERR (never stdout — for the ACP bin that channel carries JSON-RPC) and
+ * guarantees `exit(1)`. Install before `boot()`. Returns the uninstaller
+ * (tests use it; the bins run until exit and never do).
+ */
+export function installFailLoud(binName: string, proc: FailLoudProcess = process): () => void {
+  const handler = (err: unknown): void => {
+    proc.stderr.write(`${binName}: fatal load failure: ${err instanceof Error ? err.stack ?? err.message : String(err)}\n`)
+    proc.exit(1)
+  }
+  proc.on('unhandledRejection', handler)
+  return () => void proc.off('unhandledRejection', handler)
+}
+
+/**
+ * After the tree settles, assert every loader entry actually started. A
+ * started entry has a `fiber`; an entry with `fiber === undefined` after the
+ * tree settled never loaded (its module failed to import), so throw and let
+ * `boot()` reject instead of returning a half-empty context. A `disabled`
+ * entry is the one legitimate fiber-less state: `Entry.refresh()` deliberately
+ * skips `init()` for it — a valid "plugin turned off" config, not a failed
+ * import — so it is excluded.
+ */
+export function assertEntriesLoaded(ctx: Context, binName: string): 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(`${binName}: plugin(s) failed to load: ${names} (see the error(s) logged above)`)
+  }
+}
+
+/**
+ * Boot the Loader against `absoluteConfigPath` and return the root context
+ * once the whole tree has settled. 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.
+ *
+ * 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 app's plugins are still mounting, and a CLI process with no
+ * attached handles yet exits 0 silently. Failures surface two ways: an entry
+ * whose module failed to import is caught here by {@link assertEntriesLoaded}
+ * (this `boot()` rejects); an init that THROWS surfaces as an unhandled
+ * rejection caught by {@link installFailLoud} (installed by the bin first).
+ *
+ * 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`; a consumer running a built bin must
+ * pass that flag (or install the plugins where node hoists them). Relative
+ * specifiers resolve against the config directory with no flag.
+ */
+export async function boot(binName: string, 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, binName)
+  return ctx
+}

packages/ui/app-boot/tests/app-boot.spec.ts

@@ -0,0 +1,178 @@
+import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join, resolve, sep } from 'node:path'
+import { describe, expect, it, vi } from 'vitest'
+import type { Context } from 'cordis'
+import {
+  assertEntriesLoaded, boot, installFailLoud, loadEnv, resolveConfigPath,
+  type FailLoudProcess,
+} from '../src/index.ts'
+
+const NAME = 'dsh-test-bin'
+
+const tmp = (): string => mkdtempSync(join(tmpdir(), 'dsh-app-boot-'))
+
+describe('resolveConfigPath', () => {
+  it('resolves relative to the given cwd outside replay mode', () => {
+    expect(resolveConfigPath('./cordis.yml', undefined, `${sep}base`)).toBe(resolve(`${sep}base`, 'cordis.yml'))
+    expect(resolveConfigPath('conf/app.yaml', 'record', `${sep}base`)).toBe(resolve(`${sep}base`, 'conf/app.yaml'))
+  })
+
+  it('swaps a cordis.yml/.yaml basename for cordis.snapshot.yml in replay mode', () => {
+    expect(resolveConfigPath('./cordis.yml', 'replay', `${sep}base`)).toBe(resolve(`${sep}base`, 'cordis.snapshot.yml'))
+    expect(resolveConfigPath('deep/cordis.yaml', 'replay', `${sep}base`)).toBe(resolve(`${sep}base`, 'deep/cordis.snapshot.yml'))
+  })
+
+  it('leaves a non-cordis basename alone in replay mode and defaults cwd to the process cwd', () => {
+    expect(resolveConfigPath('custom.yml', 'replay', `${sep}base`)).toBe(resolve(`${sep}base`, 'custom.yml'))
+    expect(resolveConfigPath('./x.yml', undefined)).toBe(resolve(process.cwd(), 'x.yml'))
+  })
+})
+
+describe('loadEnv', () => {
+  it('loads variables from .env in the given dir', () => {
+    const dir = tmp()
+    writeFileSync(join(dir, '.env'), 'DSH_APP_BOOT_SPEC_VAR=loaded\n')
+    const warn = vi.fn()
+    loadEnv(NAME, dir, warn)
+    expect(process.env['DSH_APP_BOOT_SPEC_VAR']).toBe('loaded')
+    expect(warn).not.toHaveBeenCalled()
+    delete process.env['DSH_APP_BOOT_SPEC_VAR']
+  })
+
+  it('stays silent when no .env exists (ambient environment wins)', () => {
+    const warn = vi.fn()
+    loadEnv(NAME, tmp(), warn)
+    expect(warn).not.toHaveBeenCalled()
+  })
+
+  it('warns (labelled, single line) when .env exists but cannot be loaded', () => {
+    const dir = tmp()
+    mkdirSync(join(dir, '.env')) // a directory named .env: present, unreadable as a file
+    const warn = vi.fn()
+    loadEnv(NAME, dir, warn)
+    expect(warn).toHaveBeenCalledTimes(1)
+    expect(warn.mock.calls[0]?.[0]).toMatch(new RegExp(`^${NAME}: failed to load \\.env: `))
+  })
+
+  it('defaults dir to the process cwd and warn to a stderr write', () => {
+    const dir = tmp()
+    writeFileSync(join(dir, '.env'), 'DSH_APP_BOOT_SPEC_DEFAULTS=yes\n')
+    const previous = process.cwd()
+    process.chdir(dir)
+    try {
+      loadEnv(NAME) // happy path: the default warn sink is never invoked
+    } finally {
+      process.chdir(previous)
+    }
+    expect(process.env['DSH_APP_BOOT_SPEC_DEFAULTS']).toBe('yes')
+    delete process.env['DSH_APP_BOOT_SPEC_DEFAULTS']
+    // The default warn sink itself: point it at a broken .env with stderr
+    // spied, so the arrow body runs without polluting the test output.
+    const broken = tmp()
+    mkdirSync(join(broken, '.env'))
+    const write = vi.spyOn(process.stderr, 'write').mockImplementation(() => true)
+    let written: string[]
+    try {
+      loadEnv(NAME, broken)
+      written = write.mock.calls.map(call => String(call[0]))
+    } finally {
+      write.mockRestore()
+    }
+    expect(written).toHaveLength(1)
+    expect(written[0]).toContain(`${NAME}: failed to load .env: `)
+  })
+})
+
+describe('installFailLoud', () => {
+  function fakeProc(): FailLoudProcess & { handlers: Array<(err: unknown) => void>; written: string[]; exits: number[] } {
+    const handlers: Array<(err: unknown) => void> = []
+    const written: string[] = []
+    const exits: number[] = []
+    return {
+      handlers, written, exits,
+      on: (_event, handler) => { handlers.push(handler) },
+      off: (_event, handler) => { handlers.splice(handlers.indexOf(handler), 1) },
+      stderr: { write: (chunk: string) => { written.push(chunk) } },
+      exit: (code: number) => { exits.push(code) },
+    }
+  }
+
+  it('writes one labelled line with the stack and exits 1 on an Error rejection', () => {
+    const proc = fakeProc()
+    installFailLoud(NAME, proc)
+    const error = new Error('boom')
+    proc.handlers[0]!(error)
+    expect(proc.written[0]).toContain(`${NAME}: fatal load failure: `)
+    expect(proc.written[0]).toContain(error.stack)
+    expect(proc.exits).toEqual([1])
+  })
+
+  it('stringifies a non-Error rejection and an Error without a stack falls back to its message', () => {
+    const proc = fakeProc()
+    installFailLoud(NAME, proc)
+    proc.handlers[0]!('plain failure')
+    expect(proc.written[0]).toContain('plain failure')
+    const stackless = new Error('no stack')
+    delete (stackless as { stack?: string }).stack
+    proc.handlers[0]!(stackless)
+    expect(proc.written[1]).toContain('no stack')
+    expect(proc.exits).toEqual([1, 1])
+  })
+
+  it('returns an uninstaller that removes the handler (and defaults to the real process)', () => {
+    const proc = fakeProc()
+    const uninstall = installFailLoud(NAME, proc)
+    expect(proc.handlers).toHaveLength(1)
+    uninstall()
+    expect(proc.handlers).toHaveLength(0)
+    // Default-proc arm: install on the real process, then immediately uninstall
+    // so the suite leaks no handler and can never exit the runner.
+    const before = process.listenerCount('unhandledRejection')
+    const uninstallReal = installFailLoud(NAME)
+    expect(process.listenerCount('unhandledRejection')).toBe(before + 1)
+    uninstallReal()
+    expect(process.listenerCount('unhandledRejection')).toBe(before)
+  })
+})
+
+describe('assertEntriesLoaded', () => {
+  const ctxWith = (entries: Array<{ fiber?: unknown; disabled?: boolean; options: { name?: string } }>): Context =>
+    ({ loader: { entries: () => entries } }) as unknown as Context
+
+  it('passes when every enabled entry has a fiber', () => {
+    expect(() => { assertEntriesLoaded(ctxWith([
+      { fiber: {}, options: { name: 'a' } },
+      { disabled: true, options: { name: 'off' } },
+    ]), NAME) }).not.toThrow()
+  })
+
+  it('throws naming every enabled fiber-less entry', () => {
+    expect(() => { assertEntriesLoaded(ctxWith([
+      { fiber: {}, options: { name: 'ok' } },
+      { options: { name: 'broken-a' } },
+      { options: { name: 'broken-b' } },
+    ]), NAME) }).toThrow(`${NAME}: plugin(s) failed to load: broken-a, broken-b`)
+  })
+})
+
+describe('boot', () => {
+  it('boots a leaf config through the real Loader and settles the tree', async () => {
+    const dir = tmp()
+    writeFileSync(join(dir, 'noop.mjs'), 'export const name = "noop"\nexport function apply() {}\n')
+    writeFileSync(join(dir, 'cordis.yml'), '- id: noop\n  name: ./noop.mjs\n')
+    const ctx = await boot(NAME, join(dir, 'cordis.yml'))
+    try {
+      const entries = [...ctx.loader.entries()]
+      expect(entries.some(entry => entry.options.name === './noop.mjs' && entry.fiber !== undefined)).toBe(true)
+    } finally {
+      await ctx.fiber.dispose()
+    }
+  })
+
+  it('rejects (never exits 0 half-empty) when a config names a plugin that cannot be imported', async () => {
+    const dir = tmp()
+    writeFileSync(join(dir, 'cordis.yml'), '- id: ghost\n  name: ./missing.mjs\n')
+    await expect(boot(NAME, join(dir, 'cordis.yml'))).rejects.toThrow(`${NAME}: plugin(s) failed to load: ./missing.mjs`)
+  })
+})

packages/ui/app-boot/tsconfig.json

@@ -0,0 +1,21 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": [
+    "src"
+  ],
+  "references": [
+    {
+      "path": "../../../vendor/cordis"
+    },
+    {
+      "path": "../../../vendor/loader"
+    },
+    {
+      "path": "../../../vendor/include"
+    }
+  ]
+}

packages/ui/stdio-agent/README.md

@@ -13,7 +13,7 @@ A terminal chat always wants the same cluster, so the package owns it rather tha
 | `@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 |
+| `stdio-chat` (in-package module) | 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:repl` leaves load it and pass `--expose-internals`.
 

packages/ui/stdio-agent/package.json

@@ -32,24 +32,26 @@
   "peerDependencies": {
     "@cordisjs/plugin-include": "^1.0.4",
     "@cordisjs/plugin-loader": "^1.0.0-rc.4",
+    "@deepseek-ai/dsh-app-boot": "^0.0.1",
     "@cordisjs/plugin-logger-console": "^1.0.0",
     "@deepseek-ai/dsh-agent": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^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:^",
+    "@deepseek-ai/dsh-app-boot": "workspace:^",
     "@cordisjs/plugin-logger-console": "workspace:^",
     "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-llm": "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

@@ -2,139 +2,24 @@
 /**
  * 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`).
+ * adapter and a bash executor). The boot glue — `.env` loading, the fail-loud
+ * Loader guards, the settle-the-tree boot sequence — lives in
+ * {@link @deepseek-ai/dsh-app-boot}, shared with the ACP bin.
  *
- * Usage: `dsh-stdio-agent [path-to-cordis.yml]`. The `demo:echo` / `demo:repl`
- * scripts invoke it with the example's config.
+ * Usage: `dsh-stdio-agent [path-to-cordis.yml]` (default `./cordis.yml`). The
+ * `demo:echo` / `demo:repl` 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'
+import { boot, installFailLoud, loadEnv, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'
 
-/**
- * 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.
-  }
-}
+const NAME = 'dsh-stdio-agent'
 
-/**
- * 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:repl` 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 start -- thin self-executing composition over the unit-tested
+   dsh-app-boot helpers; exercised end-to-end by the keyless Loader-path and
+   built-bin smokes */
+installFailLoud(NAME)
+loadEnv(NAME)
+await boot(NAME, resolveConfigPath(process.argv[2] ?? './cordis.yml', undefined))
 /* v8 ignore stop */

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

@@ -1,12 +1,13 @@
 /**
  * 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
+ * chat needs — a console logger, the readline UI (the in-package `stdio-chat`
+ * module), 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 the swappable backends (the LLM
+ * the readline UI sends to. The leaf supplies the swappable backends (the LLM
  * adapter, the bash executor), optional product tools, the optional `hmr`
  * dev-reload plugin, and this app's {@link Config} (model, prompt, persistence
  * root, welcome banner).
@@ -29,8 +30,10 @@
  * 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.
+ * namespace (see docs/postmortem/0001). This app carries no `inject`, so a
+ * collapsed shape would BOOT rather than crash a smoke — the shape is pinned by
+ * the explicit `unwrapExports` assertion in this package's unit suite, and the
+ * keyless echo smoke proves the composed tree runs through the real Loader.
  *
  * @module @deepseek-ai/dsh-stdio-agent
  */
@@ -42,7 +45,7 @@ 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'
+import * as uiStdio from './stdio-chat.ts'
 
 export const name = 'stdio-agent'
 
@@ -81,7 +84,7 @@ export const Config: z<Config> = z.object({
  * 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
+ * the readline 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 {

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

@@ -0,0 +1,225 @@
+/**
+ * The stdio app's readline UI: reads lines from stdin → `agent.send()`/
+ * `steer()`, and renders the durable transcript to stdout. A UI is "just a
+ * plugin" — it consumes the `session/event` feed (the assistant token stream,
+ * turn/step boundaries, tool activity, todos) plus a few `agent/*` control
+ * events (`agent/status`, `agent/created`/`agent/disposed`) and the `agents`
+ * service. Dimmed chain-of-thought rendering plus robust piped-stdin EOF→idle
+ * exit handling, configured via {@link Config}.
+ *
+ * An internal module of the stdio app, not a package of its own: the app's
+ * front-door cluster always includes this UI, and nothing else composes it.
+ * The export shape stays named `name`/`inject`/`Config`/`apply` — the plugin
+ * contract the app's `ctx.plugin(uiStdio, …)` mount consumes.
+ *
+ * @module @deepseek-ai/dsh-stdio-agent/stdio-chat
+ */
+
+import { createInterface } from 'node:readline'
+import type { Readable, Writable } from 'node:stream'
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import { AgentId } from '@deepseek-ai/dsh-agent'
+
+export const name = 'ui-stdio'
+export const inject = ['agents']
+
+/** Serializable plugin configuration (cordis-native, schemastery). */
+export interface Config {
+  /** Banner printed once on start, before the first `> ` prompt. */
+  welcome?: string
+  /** Id of the agent stdin drives (`send`/`steer`) and whose status gates the EOF exit; rendering is global. Defaults to `'main'`. */
+  agent?: string
+}
+
+export const Config: z<Config> = z.object({
+  welcome: z.string().default('ready.'),
+  agent: z.string().default('main'),
+})
+
+/**
+ * Process-I/O seam — the side-effecting handles the plugin would otherwise
+ * reach for as globals. Defaulted to the real `process` streams in
+ * {@link apply}; injected by tests so the EOF, render, and disposal branches
+ * are exercised without hijacking globals. Deliberately NOT part of the
+ * serializable {@link Config} (streams/functions don't belong in YAML config).
+ */
+export interface StdioRuntime {
+  /** Line source (default `process.stdin`). */
+  input: Readable
+  /** Render sink (default `process.stdout`). */
+  output: Writable
+  /** Process-exit hook (default `process.exit`); called once on stdin EOF. */
+  exit: (code: number) => void
+}
+
+function isTTYPair(input: Readable, output: Writable): boolean {
+  return Boolean((input as { isTTY?: boolean }).isTTY && (output as { isTTY?: boolean }).isTTY)
+}
+
+/**
+ * The plugin body, parameterized over its I/O runtime. `apply` is the thin
+ * production wrapper that binds the real `process` streams; tests call this
+ * directly with fakes. Returns nothing — all registration is via `ctx.on`/
+ * `ctx.effect`, so fiber disposal tears every listener and the readline
+ * interface down.
+ */
+export function createStdioChat(ctx: Context, config: Config, runtime: StdioRuntime): void {
+  // Default here too (not just via schemastery's `.default()`): this helper is
+  // exported and called directly by tests / programmatic consumers that bypass
+  // Loader validation, so it must be self-contained rather than trusting the
+  // cast — `config.welcome as string` would otherwise be `undefined` on `{}`.
+  const welcome = config.welcome ?? 'ready.'
+  const agentId = AgentId(config.agent ?? 'main')
+  const { input, output, exit } = runtime
+
+  // Render label lookup: the `turn/start` session event carries only the turn
+  // number, so to print the short agent id (`[main turn 1]`) we map the
+  // session's id to its agent's id. The session id is not reliably the agent id
+  // (a session can be created with an explicit/client-supplied id), so build the
+  // map from `agent/created` rather than parsing the id string. Seed from the
+  // registry's current agents first: an agent registered before this plugin
+  // installed (e.g. the pre-created `main` agent, or any agent surviving an HMR
+  // reload of just this fiber) already fired its `agent/created`, so the live
+  // listener alone would miss it and its turns would fall back to the raw
+  // session id.
+  const labelBySession = new Map<string, string>()
+  for (const agent of ctx.agents.list()) labelBySession.set(agent.session.header.id, agent.id)
+  ctx.on('agent/created', (agent) => { labelBySession.set(agent.session.header.id, agent.id) })
+  ctx.on('agent/disposed', (agent) => { labelBySession.delete(agent.session.header.id) })
+
+  // Transcript rendering off the durable `session/event` feed — the assistant
+  // token stream, turn/step boundaries, tool activity, and todos all come from
+  // the one canonical stream (no agent/* mirrors). A single listener over the
+  // append order keeps `inReasoning` transitions deterministic across chunk and
+  // boundary events.
+  let inReasoning = false
+  ctx.on('session/event', (session, event) => {
+    if (event.type === 'assistant/chunk') {
+      const { chunk } = event.data
+      if (chunk.type === 'reasoning-delta') {
+        // Dim the chain-of-thought so the final answer stands out.
+        if (!inReasoning) output.write('\x1B[2m')
+        inReasoning = true
+        output.write(chunk.text)
+      } else if (chunk.type === 'text-delta') {
+        if (inReasoning) output.write('\x1B[0m\n')
+        inReasoning = false
+        output.write(chunk.text)
+      }
+    } else if (event.type === 'turn/start') {
+      const label = labelBySession.get(session.header.id) ?? session.header.id
+      output.write(`\n[${label} turn ${event.data.turn}] `)
+    } else if (event.type === 'turn/end') {
+      if (inReasoning) output.write('\x1B[0m')
+      inReasoning = false
+      output.write('\n> ')
+    } else if (event.type === 'tool/call') {
+      const { name: toolName, arguments: args } = event.data
+      if (inReasoning) output.write('\x1B[0m')
+      inReasoning = false
+      output.write(`\n  [tool call] ${toolName}(${args})`)
+    } else if (event.type === 'tool/result') {
+      const { content } = event.data
+      const text = content.filter(block => block.type === 'text').map(block => block.text).join('')
+      output.write(`\n  [tool result] ${text}\n  `)
+    } else if (event.type === 'todo/write') {
+      if (inReasoning) output.write('\x1B[0m')
+      inReasoning = false
+      const glyph = (status: string): string =>
+        status === 'completed' ? '[x]' : status === 'in_progress' ? '[~]' : '[ ]'
+      const lines = event.data.todos.map(todo => `    ${glyph(todo.status)} ${todo.content}`).join('\n')
+      output.write(`\n  [todos]\n${lines}\n  `)
+    }
+  })
+
+  ctx.effect(() => {
+    const reader = createInterface({ input, output, terminal: isTTYPair(input, output) })
+    // Piped-input exit, once stdin reaches EOF:
+    //  - If no line ever submitted work (empty stdin, blank-only lines), exit
+    //    immediately — no turn will ever start, so there is nothing to wait
+    //    for. (Gating on an observed 'running' here would hang forever.)
+    //  - If work WAS submitted, exit the next time the agent settles to idle
+    //    AFTER having run. Two subtleties this handles: the loop batches
+    //    several queued messages into ONE turn (one idle), so we don't count
+    //    sends; and agent.send() does NOT synchronously flip status to
+    //    'running', so requiring an observed 'running' first (`sawRunning`)
+    //    avoids exiting in the gap before the turn starts and dropping work.
+    let stdinClosed = false
+    let disposed = false
+    let submittedWork = false
+    let sawRunning = false
+    let exitTimer: ReturnType<typeof setTimeout> | undefined
+
+    const maybeExit = (): void => {
+      if (disposed || !stdinClosed) return
+      // No work submitted: nothing will ever run, exit straight away.
+      // Work submitted: wait until a turn has run and the agent is idle.
+      if (submittedWork) {
+        if (!sawRunning) return
+        const agent = ctx.agents.get(agentId)
+        if (agent && agent.status !== 'idle') return // a turn is still running
+      }
+      // Let any final output flush, then exit. The handle is tracked so the
+      // disposer can cancel it — a dispose within the flush window must not let
+      // the process exit out from under HMR. Re-entrant `maybeExit` calls (e.g.
+      // repeated idle signals) coalesce onto the one pending timer.
+      if (exitTimer !== undefined) {
+        return // exit already scheduled — coalesce re-entrant calls
+      }
+      exitTimer = setTimeout(() => { exit(0) }, 200)
+    }
+
+    const disposeStatusListener = ctx.on('agent/status', (subject, status) => {
+      if (subject.id !== agentId) return
+      if (status === 'running') sawRunning = true
+      if (status === 'idle') maybeExit()
+    })
+
+    reader.on('line', (line) => {
+      const text = line.trim()
+      if (!text) return
+      const agent = ctx.agents.get(agentId)
+      if (!agent) {
+        ctx.logger.error('ui-stdio: agent "%s" is not running', agentId)
+        return
+      }
+      submittedWork = true
+      if (agent.status === 'running') {
+        agent.steer([{ type: 'text', text }])
+      } else {
+        agent.send([{ type: 'text', text }])
+      }
+    })
+    reader.on('close', () => {
+      // Fires for BOTH stdin EOF and plugin disposal (reader.close() below);
+      // `disposed` guards teardown so HMR/dispose never exits the process.
+      stdinClosed = true
+      maybeExit()
+    })
+    output.write(`${welcome}\n> `)
+    return () => {
+      disposed = true
+      if (exitTimer !== undefined) clearTimeout(exitTimer)
+      disposeStatusListener()
+      reader.close()
+    }
+  }, 'ui-stdio')
+}
+
+/**
+ * Cordis entry point. Binds the real `process` streams and delegates to
+ * {@link createStdioChat}; the indirection keeps the side-effecting handles out
+ * of the testable core, which is why the unit suite drives `createStdioChat`
+ * directly. This thin wrapper is exercised end-to-end by the keyless
+ * Loader-path e2e smoke in `examples/echo-agent` (the real product entry).
+ */
+/* v8 ignore start -- production stdio wiring; testable core is createStdioChat() (covered), exercised e2e by echo-agent keyless smoke */
+export function apply(ctx: Context, config: Config): void {
+  createStdioChat(ctx, config, {
+    input: process.stdin,
+    output: process.stdout,
+    exit: code => process.exit(code),
+  })
+}
+/* v8 ignore stop */

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

@@ -35,7 +35,7 @@ const stdioBin = join(repoRoot, 'packages/ui/stdio-agent/lib/bin.js')
 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',
+  'bash/tool-bash', 'support/invariants', 'ui/app-boot',
   'session-persistence/session-persistence',
   'session-persistence/session-persistence-jsonl', 'ui/stdio-agent',
 ]

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

@@ -0,0 +1,53 @@
+import { EventEmitter } from 'node:events'
+import type { Readable, Writable } from 'node:stream'
+import { describe, expect, it, vi } from 'vitest'
+import type { Context } from 'cordis'
+import type { StdioRuntime } from '../src/stdio-chat.ts'
+
+const createInterface = vi.hoisted(() => vi.fn(() => {
+  const reader = new EventEmitter() as EventEmitter & { close(): void }
+  reader.close = vi.fn()
+  return reader
+}))
+
+vi.mock('node:readline', () => ({ createInterface }))
+
+function fakeContext(): Context {
+  return {
+    on: vi.fn(() => vi.fn()),
+    effect: vi.fn((callback: () => () => void) => callback()),
+    // The UI seeds its label map from the registry at install; this suite only
+    // exercises readline terminal-mode selection, so an empty roster suffices.
+    agents: { list: vi.fn(() => []) },
+  } as unknown as Context
+}
+
+function fakeRuntime(inputIsTTY: boolean, outputIsTTY: boolean): StdioRuntime {
+  return {
+    input: { isTTY: inputIsTTY } as Readable & { isTTY: boolean },
+    output: { isTTY: outputIsTTY, write: vi.fn(() => true) } as unknown as Writable & { isTTY: boolean },
+    exit: vi.fn(),
+  }
+}
+
+describe('createStdioChat readline mode', () => {
+  it('enables terminal editing only when both stdio streams are TTYs', async () => {
+    const { createStdioChat } = await import('../src/stdio-chat.ts')
+
+    const tty = fakeRuntime(true, true)
+    createStdioChat(fakeContext(), {}, tty)
+    expect(createInterface).toHaveBeenLastCalledWith({
+      input: tty.input,
+      output: tty.output,
+      terminal: true,
+    })
+
+    const piped = fakeRuntime(true, false)
+    createStdioChat(fakeContext(), {}, piped)
+    expect(createInterface).toHaveBeenLastCalledWith({
+      input: piped.input,
+      output: piped.output,
+      terminal: false,
+    })
+  })
+})

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

@@ -12,9 +12,11 @@ import * as stdioAgent from '../src/index.ts'
  * 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
+ * plugin the in-process tier cannot import); the keyless echo smoke in
+ * `examples/echo-agent` proves the whole subprocess tree (incl. `hmr`) boots
+ * through the real Loader, while the export SHAPE is pinned by this suite's
+ * explicit `unwrapExports` assertion (an inject-less app would boot past a
+ * stray default rather than crash). Here we assert the composition + config
  * forwarding the unit tier can reach.
  */
 async function mount(config: stdioAgent.Config): Promise<Context> {

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

@@ -0,0 +1,437 @@
+import { Readable } from 'node:stream'
+import { describe, expect, it, vi } from 'vitest'
+import { Context } from 'cordis'
+import type { Agent, AgentStatus } from '@deepseek-ai/dsh-agent'
+import AgentRegistry from '@deepseek-ai/dsh-agent'
+import type { ContentBlock, StreamChunk } from '@deepseek-ai/dsh-llm'
+import type { Session, SessionEvent } from '@deepseek-ai/dsh-session'
+import { createStdioChat, type Config, type StdioRuntime } from '../src/stdio-chat.ts'
+
+/**
+ * Unit tests for the stdio UI plugin. They drive the REAL plugin body
+ * (`createStdioChat`) with an injected {@link StdioRuntime} so every render,
+ * input, EOF, and disposal branch runs without touching the real `process`
+ * streams — the I/O seam is what makes the per-file gate reachable. The
+ * `agents` service is real (`@deepseek-ai/dsh-agent`); a minimal fake `Agent`
+ * stands in for the loop, since the loop is the genuinely expensive collaborator
+ * and we only need its `status` + `send`/`steer` surface here.
+ */
+
+/** A controllable stdin: a Readable we push lines into and can end on demand. */
+function makeInput(): Readable & { feed(line: string): void; finish(): void } {
+  const stream = new Readable({ read() {} }) as Readable & { feed(line: string): void; finish(): void }
+  stream.feed = (line: string) => stream.push(`${line}\n`)
+  stream.finish = () => stream.push(null)
+  return stream
+}
+
+/** A stdout sink that accumulates everything written, for assertions. */
+function makeOutput(): { write: (s: string) => boolean; text: () => string } {
+  let buf = ''
+  return { write: (s: string) => { buf += s; return true }, text: () => buf }
+}
+
+function makeRuntime(over: Partial<StdioRuntime> = {}): {
+  runtime: StdioRuntime
+  input: ReturnType<typeof makeInput>
+  out: ReturnType<typeof makeOutput>
+  exit: ReturnType<typeof vi.fn>
+} {
+  const input = makeInput()
+  const out = makeOutput()
+  const exit = vi.fn()
+  return { runtime: { input, output: { write: out.write } as never, exit, ...over }, input, out, exit }
+}
+
+/** A minimal Agent fake exposing the surface the UI touches. */
+function makeAgent(id: string, status: AgentStatus = 'idle'): Agent & {
+  status: AgentStatus
+  sent: ContentBlock[][]
+  steered: ContentBlock[][]
+} {
+  const sent: ContentBlock[][] = []
+  const steered: ContentBlock[][] = []
+  return {
+    id: id as Agent['id'],
+    status,
+    sent,
+    steered,
+    // A minimal session stub: the UI reads only `session.header.id` (to map the
+    // session back to its agent id for the turn-boundary label).
+    session: { header: { id: `${id}-session` } },
+    send: (content: ContentBlock[]) => void sent.push(content),
+    steer: (content: ContentBlock[]) => void steered.push(content),
+  } as never
+}
+
+/** A session stub whose `header.id` matches an agent's, for `session/event` emits. */
+function makeSession(agentId: string): Session {
+  return { header: { id: `${agentId}-session` } } as Session
+}
+
+/** An `assistant/chunk` session event carrying one raw stream chunk. */
+function chunkEvent(chunk: StreamChunk): SessionEvent {
+  return { type: 'assistant/chunk', seq: 0, time: 0, data: { turn: 1, step: 0, chunk } }
+}
+
+const CONFIG: Config = { welcome: 'hi there', agent: 'main' }
+
+async function setup(config: Config = CONFIG, runtimeOver: Partial<StdioRuntime> = {}) {
+  const ctx = new Context()
+  await ctx.plugin(AgentRegistry)
+  const { runtime, input, out, exit } = makeRuntime(runtimeOver)
+  const fiber = await ctx.plugin(Object.assign((inner: Context) => {
+    createStdioChat(inner, config, runtime)
+  }, { inject: ['agents'] }))
+  return { ctx, fiber, input, out, exit }
+}
+
+/** Drive a fake idle timer past the 200ms flush delay. */
+function flushExit(): Promise<void> {
+  return new Promise(resolve => setTimeout(resolve, 250))
+}
+
+describe('createStdioChat rendering', () => {
+  it('writes the welcome banner and prompt on start', async () => {
+    const { out } = await setup()
+    expect(out.text()).toBe('hi there\n> ')
+  })
+
+  it('falls back to default welcome/agent when called with empty config', async () => {
+    // createStdioChat is exported and may be driven directly (bypassing the
+    // Loader's schemastery validation), so it must default welcome/agent itself.
+    const { out } = await setup({})
+    expect(out.text()).toBe('ready.\n> ')
+    // And it drives the default agent id 'main'.
+  })
+
+  it('renders text-delta chunks verbatim', async () => {
+    const { ctx, out } = await setup()
+    ctx.emit('session/event', makeSession('main'), chunkEvent({ type: 'text-delta', index: 0, text: 'hello' }))
+    expect(out.text()).toContain('hello')
+  })
+
+  it('wraps reasoning-delta in the dim SGR and resets on the following text-delta', async () => {
+    const { ctx, out } = await setup()
+    const session = makeSession('main')
+    ctx.emit('session/event', session, chunkEvent({ type: 'reasoning-delta', index: 0, text: 'think' }))
+    ctx.emit('session/event', session, chunkEvent({ type: 'reasoning-delta', index: 0, text: 'more' }))
+    ctx.emit('session/event', session, chunkEvent({ type: 'text-delta', index: 0, text: 'answer' }))
+    expect(out.text()).toContain('\x1B[2mthinkmore\x1B[0m\nanswer')
+  })
+
+  it('ignores stream-chunk types it does not render', async () => {
+    const { ctx, out } = await setup()
+    const before = out.text()
+    ctx.emit('session/event', makeSession('main'), chunkEvent({ type: 'block-start', index: 0, blockType: 'text' }))
+    expect(out.text()).toBe(before)
+  })
+
+  it('renders turn/start and turn/end markers from the session feed', async () => {
+    const { ctx, out } = await setup()
+    const agent = makeAgent('main')
+    // agent/created populates the session-id → agent-id label map.
+    ctx.emit('agent/created', agent)
+    const session = makeSession('main')
+    ctx.emit('session/event', session, {
+      type: 'turn/start', seq: 1, time: 0, data: { turn: 3, trigger: { kind: 'message' } },
+    } as SessionEvent)
+    expect(out.text()).toContain('[main turn 3] ')
+    ctx.emit('session/event', session, {
+      type: 'turn/end', seq: 2, time: 0, data: { turn: 3, reason: { kind: 'completed' } },
+    } as SessionEvent)
+    expect(out.text()).toContain('\n> ')
+  })
+
+  it('falls back to the session id as the label when no agent is mapped', async () => {
+    const { ctx, out } = await setup()
+    // No agent/created emitted, so the label map is empty — the header id shows.
+    ctx.emit('session/event', makeSession('orphan'), {
+      type: 'turn/start', seq: 1, time: 0, data: { turn: 1, trigger: { kind: 'message' } },
+    } as SessionEvent)
+    expect(out.text()).toContain('[orphan-session turn 1] ')
+  })
+
+  it('seeds labels for agents already registered before the UI installs', async () => {
+    // The pre-created `main` agent (and any agent surviving an HMR reload of just
+    // this fiber) fired its `agent/created` before the UI's listener existed, so
+    // the live listener alone would miss it. Seeding from `ctx.agents.list()` at
+    // install time is what keeps its turn header showing `[main turn N]` instead
+    // of the raw session id.
+    const ctx = new Context()
+    await ctx.plugin(AgentRegistry)
+    const agent = makeAgent('main')
+    ctx.agents.register(agent) // registered BEFORE the UI plugin below
+    const { runtime, out } = makeRuntime()
+    await ctx.plugin(Object.assign((inner: Context) => {
+      createStdioChat(inner, CONFIG, runtime)
+    }, { inject: ['agents'] }))
+    ctx.emit('session/event', makeSession('main'), {
+      type: 'turn/start', seq: 1, time: 0, data: { turn: 5, trigger: { kind: 'message' } },
+    } as SessionEvent)
+    expect(out.text()).toContain('[main turn 5] ')
+  })
+
+  it('resets dim styling at turn/end if a turn ends mid-reasoning', async () => {
+    const { ctx, out } = await setup()
+    const session = makeSession('main')
+    ctx.emit('session/event', session, chunkEvent({ type: 'reasoning-delta', index: 0, text: 'mid' }))
+    ctx.emit('session/event', session, {
+      type: 'turn/end', seq: 1, time: 0, data: { turn: 1, reason: { kind: 'completed' } },
+    } as SessionEvent)
+    expect(out.text()).toContain('\x1B[2mmid\x1B[0m')
+  })
+
+  it('drops the label mapping on agent/disposed', async () => {
+    const { ctx, out } = await setup()
+    const agent = makeAgent('main')
+    ctx.emit('agent/created', agent)
+    ctx.emit('agent/disposed', agent)
+    // After disposal the map no longer resolves the agent id — fall back to the
+    // session header id.
+    ctx.emit('session/event', makeSession('main'), {
+      type: 'turn/start', seq: 1, time: 0, data: { turn: 1, trigger: { kind: 'message' } },
+    } as SessionEvent)
+    expect(out.text()).toContain('[main-session turn 1] ')
+  })
+
+  it('renders tool/call and tool/result session events', async () => {
+    const { ctx, out } = await setup()
+    const session = {} as Session
+    const callEvent = {
+      type: 'tool/call', seq: 1, time: 0,
+      data: { turn: 1, step: 0, callId: 'c1', name: 'bash', arguments: '{"command":"ls"}' },
+    } as SessionEvent
+    ctx.emit('session/event', session, callEvent)
+    expect(out.text()).toContain('[tool call] bash({"command":"ls"})')
+
+    const resultEvent = {
+      type: 'tool/result', seq: 2, time: 0,
+      data: { turn: 1, step: 0, callId: 'c1', content: [{ type: 'text', text: 'file.txt' }], isError: false },
+    } as SessionEvent
+    ctx.emit('session/event', session, resultEvent)
+    expect(out.text()).toContain('[tool result] file.txt')
+  })
+
+  it('renders a todo/write session event as a glyphed checklist', async () => {
+    const { ctx, out } = await setup()
+    const session = {} as Session
+    ctx.emit('session/event', session, {
+      type: 'todo/write', seq: 1, time: 0,
+      data: { todos: [
+        { content: 'read the code', status: 'completed' },
+        { content: 'write the fix', status: 'in_progress' },
+        { content: 'run the tests', status: 'pending' },
+      ] },
+    } as SessionEvent)
+    const text = out.text()
+    expect(text).toContain('[todos]')
+    expect(text).toContain('[x] read the code')
+    expect(text).toContain('[~] write the fix')
+    expect(text).toContain('[ ] run the tests')
+  })
+
+  it('resets dim styling when a todo/write interrupts reasoning', async () => {
+    const { ctx, out } = await setup()
+    ctx.emit('session/event', {} as Session, chunkEvent({ type: 'reasoning-delta', index: 0, text: 'r' }))
+    ctx.emit('session/event', {} as Session, {
+      type: 'todo/write', seq: 1, time: 0,
+      data: { todos: [{ content: 'a task', status: 'pending' }] },
+    } as SessionEvent)
+    expect(out.text()).toContain('\x1B[2mr\x1B[0m')
+  })
+
+  it('resets dim styling when a tool/call interrupts reasoning', async () => {
+    const { ctx, out } = await setup()
+    const session = {} as Session
+    ctx.emit('session/event', session, chunkEvent({ type: 'reasoning-delta', index: 0, text: 'r' }))
+    ctx.emit('session/event', session, {
+      type: 'tool/call', seq: 1, time: 0,
+      data: { turn: 1, step: 0, callId: 'c1', name: 'bash', arguments: '{}' },
+    } as SessionEvent)
+    expect(out.text()).toContain('\x1B[2mr\x1B[0m')
+  })
+
+  it('ignores session events it does not render', async () => {
+    const { ctx, out } = await setup()
+    const before = out.text()
+    ctx.emit('session/event', {} as Session, {
+      type: 'user/message', seq: 1, time: 0,
+      data: { content: [{ type: 'text', text: 'hi' }], source: { kind: 'user' } },
+    } as SessionEvent)
+    expect(out.text()).toBe(before)
+  })
+})
+
+describe('createStdioChat input', () => {
+  it('sends a typed line to an idle agent', async () => {
+    const { ctx, input } = await setup()
+    const agent = makeAgent('main', 'idle')
+    ctx.agents.register(agent)
+    input.feed('do a thing')
+    await new Promise(r => setImmediate(r))
+    expect(agent.sent).toEqual([[{ type: 'text', text: 'do a thing' }]])
+    expect(agent.steered).toEqual([])
+  })
+
+  it('steers a typed line into a running agent', async () => {
+    const { ctx, input } = await setup()
+    const agent = makeAgent('main', 'running')
+    ctx.agents.register(agent)
+    input.feed('steer me')
+    await new Promise(r => setImmediate(r))
+    expect(agent.steered).toEqual([[{ type: 'text', text: 'steer me' }]])
+    expect(agent.sent).toEqual([])
+  })
+
+  it('ignores blank lines', async () => {
+    const { ctx, input } = await setup()
+    const agent = makeAgent('main')
+    ctx.agents.register(agent)
+    input.feed('   ')
+    await new Promise(r => setImmediate(r))
+    expect(agent.sent).toEqual([])
+  })
+
+  it('logs and drops a line when the target agent is not running', async () => {
+    const { ctx, input } = await setup()
+    const spy = vi.spyOn(ctx.logger, 'error').mockImplementation(() => {})
+    input.feed('nobody home')
+    await new Promise(r => setImmediate(r))
+    expect(spy).toHaveBeenCalledWith('ui-stdio: agent "%s" is not running', 'main')
+  })
+
+  it('drives the agent named in config, not a hardcoded id', async () => {
+    const { ctx, input } = await setup({ welcome: 'w', agent: 'worker' })
+    const agent = makeAgent('worker')
+    ctx.agents.register(agent)
+    input.feed('hi')
+    await new Promise(r => setImmediate(r))
+    expect(agent.sent).toHaveLength(1)
+  })
+})
+
+describe('createStdioChat EOF exit', () => {
+  it('exits immediately on EOF when no work was submitted', async () => {
+    const { input, exit } = await setup()
+    input.finish()
+    await flushExit()
+    expect(exit).toHaveBeenCalledWith(0)
+  })
+
+  it('waits for the agent to settle idle after running before exiting', async () => {
+    const { ctx, input, exit } = await setup()
+    const agent = makeAgent('main', 'idle')
+    ctx.agents.register(agent)
+    input.feed('work')
+    await new Promise(r => setImmediate(r))
+    input.finish()
+    await new Promise(r => setImmediate(r))
+    // Work submitted but no 'running' observed yet — must NOT exit.
+    expect(exit).not.toHaveBeenCalled()
+    // The turn starts, then settles.
+    ctx.emit('agent/status', agent, 'running')
+    ;(agent as { status: AgentStatus }).status = 'idle'
+    ctx.emit('agent/status', agent, 'idle')
+    await flushExit()
+    expect(exit).toHaveBeenCalledWith(0)
+  })
+
+  it('schedules the exit only once when idle fires repeatedly', async () => {
+    const { ctx, input, exit } = await setup()
+    const agent = makeAgent('main', 'running')
+    ctx.agents.register(agent)
+    input.feed('work')
+    await new Promise(r => setImmediate(r))
+    ctx.emit('agent/status', agent, 'running') // sawRunning = true
+    input.finish()
+    await new Promise(r => setImmediate(r)) // let readline 'close' set stdinClosed
+    ;(agent as { status: AgentStatus }).status = 'idle'
+    // Two idle signals while stdin is already closed: the first arms the timer,
+    // the second must hit the already-scheduled guard, not arm a second.
+    ctx.emit('agent/status', agent, 'idle')
+    ctx.emit('agent/status', agent, 'idle')
+    await flushExit()
+    expect(exit).toHaveBeenCalledTimes(1)
+  })
+
+  it('does not exit on an idle transition for a different agent', async () => {
+    const { ctx, input, exit } = await setup()
+    const agent = makeAgent('main', 'idle')
+    ctx.agents.register(agent)
+    input.feed('work')
+    await new Promise(r => setImmediate(r))
+    input.finish()
+    const other = makeAgent('other')
+    ctx.emit('agent/status', other, 'running')
+    ctx.emit('agent/status', other, 'idle')
+    await flushExit()
+    expect(exit).not.toHaveBeenCalled()
+  })
+
+  it('does not exit while a turn is still running at EOF', async () => {
+    const { ctx, input, exit } = await setup()
+    const agent = makeAgent('main', 'idle')
+    ctx.agents.register(agent)
+    input.feed('work')
+    await new Promise(r => setImmediate(r))
+    ctx.emit('agent/status', agent, 'running')
+    ;(agent as { status: AgentStatus }).status = 'running'
+    input.finish()
+    // sawRunning is true, but the agent is still running — the idle gate holds.
+    ctx.emit('agent/status', agent, 'idle') // a stale/duplicate signal while status stays 'running'
+    await flushExit()
+    expect(exit).not.toHaveBeenCalled()
+  })
+})
+
+describe('createStdioChat disposal (HMR safety)', () => {
+  it('never exits the process when EOF arrives after fiber dispose', async () => {
+    const { fiber, input, exit } = await setup()
+    await fiber.dispose()
+    // A late EOF after disposal (reader.close() also fires 'close') must not exit.
+    input.finish()
+    await flushExit()
+    expect(exit).not.toHaveBeenCalled()
+  })
+
+  it('cancels a scheduled exit if disposed within the flush window', async () => {
+    const { fiber, input, exit } = await setup()
+    // EOF with no work submitted schedules the 200ms flush-then-exit timer.
+    input.finish()
+    await new Promise(r => setImmediate(r))
+    expect(exit).not.toHaveBeenCalled() // not yet — still inside the window
+    // Dispose BEFORE the timer fires: the tracked handle must be cleared.
+    await fiber.dispose()
+    await flushExit()
+    expect(exit).not.toHaveBeenCalled()
+  })
+
+  it('stops handling input after dispose', async () => {
+    const { ctx, fiber, input } = await setup()
+    const agent = makeAgent('main')
+    ctx.agents.register(agent)
+    await fiber.dispose()
+    // The readline interface is closed on dispose; a late line reaches no handler.
+    input.feed('too late')
+    await new Promise(r => setImmediate(r))
+    expect(agent.sent).toEqual([])
+  })
+
+  it('removes the agent/status listener on dispose', async () => {
+    const { ctx, fiber, input, exit } = await setup()
+    const agent = makeAgent('main', 'idle')
+    ctx.agents.register(agent)
+    input.feed('work')
+    await new Promise(r => setImmediate(r))
+    await fiber.dispose()
+    // After dispose, status transitions must neither throw nor schedule an exit
+    // (the listener and the EOF-exit path are both torn down).
+    expect(() => {
+      ctx.emit('agent/status', agent, 'running')
+      ctx.emit('agent/status', agent, 'idle')
+    }).not.toThrow()
+    await flushExit()
+    expect(exit).not.toHaveBeenCalled()
+  })
+})

packages/ui/stdio-agent/tsconfig.json

@@ -17,6 +17,9 @@
     {
       "path": "../../../vendor/loader"
     },
+    {
+      "path": "../app-boot"
+    },
     {
       "path": "../../../vendor/logger-console"
     },
@@ -31,9 +34,6 @@
     },
     {
       "path": "../../session-persistence/session-persistence-jsonl"
-    },
-    {
-      "path": "../../support/ui-stdio"
     }
   ]
 }