Merge remote-tracking branch 'origin/master' into codex/project-instruction-files

# Conflicts: # AGENTS.md # docs/config-catalog.md # docs/module-graph.md # examples/echo-agent/composition.md # packages/README.md # packages/core/README.md # packages/examples/acp-demo/package.json # packages/examples/acp-demo/src/index.ts # packages/examples/acp-demo/tests/acp-agent.spec.ts # packages/examples/acp-demo/tests/built-bin.e2e.ts # packages/examples/acp-demo/tsconfig.json # packages/examples/agent-spine-demo/README.md # packages/examples/agent-spine-demo/package.json # packages/examples/agent-spine-demo/tests/agent-core.spec.ts # packages/examples/stdio-demo/package.json # packages/examples/stdio-demo/src/index.ts # packages/examples/stdio-demo/tests/built-bin.e2e.ts # packages/examples/stdio-demo/tests/stdio-agent.spec.ts # packages/examples/stdio-demo/tsconfig.json # pnpm-lock.yaml # python/sdk-runtime/README.i18n.yaml # python/sdk-runtime/src/deepseek_harness_runtime/runtime/cordis.yml # python/sdk/tests/test_bundled_runtime.py
2026-07-15 17:04:16 +08:00
parent 2f268cb47d 5ee9217146
commit ff3d893f74
185 changed files with 4140 additions and 825 deletions
--- a/packages/README.md
+++ b/packages/README.md
@@ -28,7 +28,8 @@ Packages are grouped by role at `packages/<group>/<pkg>/`. Group directories hav
 | [`hooks/`](hooks/README.md) | Hook bridges + the shared Claude Code / Codex wire-protocol library | Product — stable surface |
 | [`session-persistence/`](session-persistence/README.md) | Persistence capability family: the seam + JSONL/SQLite backends | Product — stable surface |
 | [`session-query/`](session-query/README.md) | Session retrieval family: logical corpus, surface records, and bounded exact reads | Product — stable surface |
-| [`ui/`](ui/README.md) | Editor/client integration surfaces: ACP bridge, JSON-RPC SDK server, app packages, user-approval and user-interaction seams, ask-user tool | Product — stable surface |
+| [`ui/`](ui/README.md) | Editor/client integration surfaces: ACP bridge, JSON-RPC SDK server, user-approval/user-interaction seams, ask-user tool | Product — stable surface |
+| [`examples/`](examples/README.md) | Demo bundles (agent-spine + stdio/ACP/JSON-RPC bins) the leaves load | Support — example infra |
 | [`support/`](support/README.md) | Support infrastructure (invariants, replay, Loader smokes, subagent mock) | Support — lower compatibility expectations |
 | [`util/`](util/README.md) | Low-level zero-dependency utilities shared across groups (`Branded<B>`, path helpers) | Support — small, stable, harness-dep-free |

@@ -38,6 +39,6 @@ The split is the point: a package's group says whether it is part of the product

 The inter-package dependency graph is generated: [docs/module-graph.md](../docs/module-graph.md) (`pnpm run gen-module-graph`, freshness-gated in CI).

-The rule it must obey: **extension plugins depend on interfaces, never on the concrete loop.** `dsh-agent-loop` is swappable — UI/hook/tool plugins keep working against the `dsh-agent` vocabulary if the loop is replaced. The sanctioned exception is a **composition/bundle** package like `dsh-agent-core`, whose whole job is to assemble the concrete spine: it depends on `dsh-agent-loop` (and the other concrete spine plugins) on purpose. The rule constrains plugins that EXTEND the system, not the bundle that COMPOSES it. A swappable capability splits into interface / implementation / consumer packages (the bash trio is the template — see [capability seams](../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)).
+The rule it must obey: **extension plugins depend on interfaces, never on the concrete loop.** `dsh-agent-loop` is swappable — UI/hook/tool plugins keep working against the `dsh-agent` vocabulary if the loop is replaced. The sanctioned exception is a **composition/bundle** package like `dsh-agent-spine-demo`, whose whole job is to assemble the concrete spine: it depends on `dsh-agent-loop` (and the other concrete spine plugins) on purpose. The rule constrains plugins that EXTEND the system, not the bundle that COMPOSES it. A swappable capability splits into interface / implementation / consumer packages (the bash trio is the template — see [capability seams](../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md)).

 Package READMEs cover purpose, APIs, extension points, and [Model Experience](../docs/cookbook/adding-a-package.md#4-write-the-package-readme) unless on the model-agnostic [omission allowlist](../scripts/verify-package-readme-model-experience.ts). They also carry `## Known Limitations and Deferred Work` or use its [allowlist](../scripts/verify-package-readme-limitations.ts).
--- a/packages/bash/tool-bash/tests/tools.spec.ts
+++ b/packages/bash/tool-bash/tests/tools.spec.ts
@@ -288,9 +288,17 @@ describe('bash tool', () => {

  it('contributes the exit-code habit as its prompt section (guidance the descriptions cannot carry)', async () => {
    const ctx = await setup()
+    ctx.systemPrompt.section({ name: 'test:before-bash', order: 104, text: 'before' })
+    ctx.systemPrompt.section({ name: 'test:after-bash', order: 106, text: 'after' })
    const assembly = await ctx.systemPrompt.assemble()
    const section = assembly.sections.find(s => s.name === 'tool:bash')
-    expect(section?.order).toBe(105)
+    expect(assembly.sections.map(s => s.name)).toEqual([
+      'harness:identity',
+      'deployment:persona',
+      'test:before-bash',
+      'tool:bash',
+      'test:after-bash',
+    ])
    expect(section?.text).toContain('[exit code: N]')
  })

--- a/packages/code-runtime/code-runtime-worker/README.md
+++ b/packages/code-runtime/code-runtime-worker/README.md
@@ -23,7 +23,7 @@ Every field is validated (positive numbers) and defaulted; there are no other tu
 - **Type-strip host-side, in execution context** — the program is wrapped in an async-function shell, stripped with `node:module`'s `stripTypeScriptTypes` (erasable syntax only — `enum`/namespaces are rejected as a program `exception` and no worker spawns), and sliced back out byte-positioned; it then executes as the body of an `AsyncFunction`, so top-level `await`/`return` work.
 - **The port assumes a hostile peer** — model code can reach `parentPort` and forge traffic, so every inbound message is shape-validated and REBUILT before anything reads it (`null`, primitives, junk types, and malformed payloads drop without a throw; forged extra fields never ride along), the host answers each call id at most once, resolves binding names as OWN properties only (a forged `constructor` cannot walk a prototype chain), drops post-settlement replies, and converts a non-cloneable binding resolution into an error reply. Forged `log`/`done` messages cannot bypass the caps: one host-side ledger bounds everything that lands in `logs`, and the completion value is re-capped host-side. Worker-side namespaces are null-prototype with `defineProperty`, so `__proto__`-shaped binding names are ordinary keys.
 - **Two independent budgets, because the peer is hostile** — `computeMs` meters the worker's MEASURED busy time (`worker.performance.eventLoopUtilization()` polling): a hot loop cannot hide behind a pending decoy dispatch, and a program awaiting a slow tool accrues nothing. `maxWallMs` backstops what busy time cannot see (awaiting a promise nobody resolves). Both funnel into `worker.terminate()`, which ends hot synchronous loops too; heap overflow surfaces as the worker's OOM exit (`kind: 'worker-exit'`).
- **Logs stream eagerly** — console/stdout/stderr entries cross the port as they happen, so a timed-out or killed program still shows what it printed. ONE shared `maxLogBytes` ledger bounds everything: streamed entries, forged port traffic, and pipe bytes that bypass the patched streams (appended after), with the overflow marked in-band once.
+- **Logs stream eagerly** — console/stdout/stderr text crosses the port in emission order, so a timed-out or killed program still shows what it printed. ONE shared `maxLogBytes` ledger bounds everything: streamed text, forged port traffic, and pipe bytes that bypass the patched streams (appended after), with the overflow marked in-band once.
 - **Empty environment** — the worker gets `env: {}` and `execArgv: []`: no ambient credentials (stronger than the scrubbed-env rule for spawned commands) and no inherited loader flags.
 - **Dispose to quiescence** — teardown fails in-flight runs as `abort` and AWAITS each worker's exit before resolving.

@@ -31,6 +31,8 @@ Every field is validated (positive numbers) and defaulted; there are no other tu

 Source mode loads erasable-only `src/worker.ts` through Node's native type stripping. Built mode passes the sibling `lib/worker.cjs` as a filesystem path because pkg's VFS Worker hook expects CommonJS; the same path works under ordinary Node. `tests/built-lib.e2e.ts` pins the real load path required by [docs/testing.md](../../../docs/testing.md).

+The SDK surface is the default/named `WorkerCodeRuntime` class plus `Config`. The operational `./worker` subpath exists only as the packaged spawn entry; the wire protocol and bootstrap helpers are source-private implementation details.
+
 ## Model Experience

 Indirectly, through Code Mode in [`dsh-tools`](../../core/tools/README.md), which renders this worker's capped printed or returned data and exact `[dsh-code-runtime-worker] log capture truncated at <maxLogBytes> bytes` and `… [truncated]` markers into a retained `run_code` result. Binding traffic and worker internals stay outside context.
--- a/packages/code-runtime/code-runtime-worker/package.json
+++ b/packages/code-runtime/code-runtime-worker/package.json
@@ -15,7 +15,6 @@
      "types": "./lib/types/worker.d.ts",
      "default": "./lib/worker.cjs"
    },
-    "./src/*": "./src/*",
    "./package.json": "./package.json"
  },
  "files": [
--- a/packages/code-runtime/code-runtime-worker/src/bootstrap.ts
+++ b/packages/code-runtime/code-runtime-worker/src/bootstrap.ts
@@ -7,7 +7,6 @@

 import { inspect } from 'node:util'
 import { serialize } from 'node:v8'
-import type { CodeLogEntry } from '@deepseek-ai/dsh-code-runtime'
 import { logTruncationMarker } from './protocol.ts'
 import type { DoneMessage, ReplyMessage, WorkerBootData, WorkerToHost } from './protocol.ts'

@@ -28,12 +27,12 @@ export interface PatchableStream {
 }

 /**
- * Ordered log capture under one shared byte budget, delivered to a sink as
- * each entry lands (the real sink streams entries over the port eagerly, so
+ * Ordered text capture under one shared byte budget, delivered to a sink as
+ * each item lands (the real sink streams text over the port eagerly, so
 * captured output survives a mid-run termination). Once the budget is
- * exhausted it emits exactly one in-band marker entry (on the `stderr`
- * diagnostics channel) and silently drops everything after — the cap is a
- * blast-radius bound, so "how much was lost" intentionally stays unmeasured.
+ * exhausted it emits exactly one in-band marker and silently drops everything
+ * after. The cap is a blast-radius bound, so "how much was lost" intentionally
+ * stays unmeasured.
 */
 export class LogBuffer {
  private remaining: number
@@ -42,28 +41,28 @@ export class LogBuffer {
  // under Node's native strip-only mode, which rejects non-erasable syntax —
  // and parameter properties are non-erasable.
  private readonly maxBytes: number
-  private readonly sink: (entry: CodeLogEntry) => void
+  private readonly sink: (text: string) => void

-  constructor(maxBytes: number, sink: (entry: CodeLogEntry) => void) {
+  constructor(maxBytes: number, sink: (text: string) => void) {
    this.maxBytes = maxBytes
    this.sink = sink
    this.remaining = maxBytes
  }

  /**
-   * Emit one entry to the sink, charging its text against the budget (drops + marks once exhausted).
-   * @param entry - the log entry to deliver.
+   * Emit text to the sink, charging it against the budget (drops + marks once exhausted).
+   * @param text - the captured text to deliver.
   */
-  push(entry: CodeLogEntry): void {
+  push(text: string): void {
    if (this.truncated) return
-    const cost = Buffer.byteLength(entry.text, 'utf8')
+    const cost = Buffer.byteLength(text, 'utf8')
    if (cost > this.remaining) {
      this.truncated = true
-      this.sink({ source: 'stderr', text: logTruncationMarker(this.maxBytes) })
+      this.sink(logTruncationMarker(this.maxBytes))
      return
    }
    this.remaining -= cost
-    this.sink(entry)
+    this.sink(text)
  }
 }

@@ -84,7 +83,7 @@ export function makeConsoleShim(logs: LogBuffer): Record<(typeof CONSOLE_LEVELS)
    args.map(arg => typeof arg === 'string' ? arg : inspect(arg, INSPECT_OPTIONS)).join(' ')
  const shim = Object.create(null) as Record<(typeof CONSOLE_LEVELS)[number], (...args: unknown[]) => void>
  for (const level of CONSOLE_LEVELS) {
-    shim[level] = (...args: unknown[]) => { logs.push({ source: 'console', level, text: render(args) }) }
+    shim[level] = (...args: unknown[]) => { logs.push(render(args)) }
  }
  return shim
 }
@@ -98,17 +97,16 @@ export function makeConsoleShim(logs: LogBuffer): Record<(typeof CONSOLE_LEVELS)
 *
 * @param logs - the buffer captured writes are pushed into.
 * @param stream - the stream whose `write` slot is patched.
- * @param source - the log source the captured writes are attributed to.
 * @returns the restore function (the in-process tests un-patch; the real
 *   worker never needs to).
 */
-export function captureStreamWrites(logs: LogBuffer, stream: PatchableStream, source: 'stdout' | 'stderr'): () => void {
+export function captureStreamWrites(logs: LogBuffer, stream: PatchableStream): () => void {
  // The slot's VALUE is stored for restore and reassigned — never invoked
  // detached, so the unbound-method concern does not apply.
  // eslint-disable-next-line @typescript-eslint/unbound-method
  const original = stream.write
  stream.write = (chunk: unknown, ...rest: unknown[]): boolean => {
-    logs.push({ source, text: typeof chunk === 'string' ? chunk : String(chunk) })
+    logs.push(typeof chunk === 'string' ? chunk : String(chunk))
    // Node's optional-encoding shape: the callback is whichever of the next
    // two positions holds a function (a non-function there is the encoding).
    const callback = [rest[0], rest[1]].find(
@@ -256,9 +254,9 @@ export async function runWorkerMain(
  data: WorkerBootData,
  streams: { stdout: PatchableStream; stderr: PatchableStream },
 ): Promise<void> {
-  const logs = new LogBuffer(data.maxLogBytes, (entry) => { port.postMessage({ type: 'log', entry }) })
-  captureStreamWrites(logs, streams.stdout, 'stdout')
-  captureStreamWrites(logs, streams.stderr, 'stderr')
+  const logs = new LogBuffer(data.maxLogBytes, (text) => { port.postMessage({ type: 'log', text }) })
+  captureStreamWrites(logs, streams.stdout)
+  captureStreamWrites(logs, streams.stderr)

  const pending = new Map<number, PendingCall>()
  wireReplies(port, pending)
--- a/packages/code-runtime/code-runtime-worker/src/index.ts
+++ b/packages/code-runtime/code-runtime-worker/src/index.ts
@@ -12,14 +12,11 @@ import { fileURLToPath } from 'node:url'
 import { Context } from 'cordis'
 import z from 'schemastery'
 import { CodeRuntime } from '@deepseek-ai/dsh-code-runtime'
-import type { CodeBindingFunction, CodeLogEntry, CodeRunFailure, CodeRunRequest, CodeRunResult } from '@deepseek-ai/dsh-code-runtime'
+import type { CodeBindingFunction, CodeRunFailure, CodeRunRequest, CodeRunResult } from '@deepseek-ai/dsh-code-runtime'
 import { prepareValue, truncateUtf8Bytes } from './bootstrap.ts'
 import { logTruncationMarker } from './protocol.ts'
 import type { ReplyMessage, WorkerBootData, WorkerToHost } from './protocol.ts'

-export type { BootstrapPort, PatchableStream } from './bootstrap.ts'
-export type { CallMessage, DoneMessage, ReplyMessage, WorkerBootData, WorkerToHost } from './protocol.ts'
-
 /** Plugin config: every execution cap, changeable from `cordis.yml` (no hardcoded tunables). */
 export interface Config {
  /**
@@ -112,10 +109,6 @@ function messageOf(error: unknown): string {
  return error instanceof Error ? error.message : String(error)
 }

-/** The log sources / console levels the seam vocabulary admits, as runtime sets for inbound-message validation. */
-const LOG_SOURCES = new Set<string>(['console', 'stdout', 'stderr'])
-const LOG_LEVELS = new Set<string>(['log', 'info', 'warn', 'error', 'debug'])
-
 /**
 * Runtime shape gate for inbound port traffic. The peer runs MODEL CODE and
 * can post anything — `null`, primitives, objects with poisoned fields — so
@@ -134,20 +127,8 @@ function parseWorkerMessage(raw: unknown): WorkerToHost | undefined {
      return { type: 'call', id: m.id, global: m.global, name: m.name, args: m.args }
    }
    case 'log': {
-      const entry = m.entry
-      if (typeof entry !== 'object' || entry === null) return undefined
-      const e = entry as Record<string, unknown>
-      if (typeof e.text !== 'string') return undefined
-      if (typeof e.source !== 'string' || !LOG_SOURCES.has(e.source)) return undefined
-      if (e.level !== undefined && (typeof e.level !== 'string' || !LOG_LEVELS.has(e.level))) return undefined
-      return {
-        type: 'log',
-        entry: {
-          source: e.source as CodeLogEntry['source'],
-          ...e.level !== undefined ? { level: e.level as Exclude<CodeLogEntry['level'], undefined> } : {},
-          text: e.text,
-        },
-      }
+      if (typeof m.text !== 'string') return undefined
+      return { type: 'log', text: m.text }
    }
    case 'done': {
      if (m.error === undefined) return { type: 'done', ...m.value !== undefined ? { value: m.value } : {} }
@@ -291,33 +272,33 @@ export class WorkerCodeRuntime extends CodeRuntime {
    return new Promise<CodeRunResult>((resolve) => {
      let settled = false
      const answered = new Set<number>()
-      const logs: CodeLogEntry[] = []
-      const strayLogs: CodeLogEntry[] = []
+      const logs: string[] = []
+      const strayLogs: string[] = []

      // One host-side budget covers normal, forged, and stray-pipe log entries. The first
      // overflow emits the shared in-band marker and drops everything after it.
      let logBudget = this.config.maxLogBytes
      let logsTruncated = false
-      const admit = (entry: CodeLogEntry, sink: CodeLogEntry[]): void => {
+      const admit = (text: string, sink: string[]): void => {
        if (logsTruncated) return
-        const cost = Buffer.byteLength(entry.text, 'utf8')
+        const cost = Buffer.byteLength(text, 'utf8')
        if (cost > logBudget) {
          logsTruncated = true
-          sink.push({ source: 'stderr', text: logTruncationMarker(this.config.maxLogBytes) })
+          sink.push(logTruncationMarker(this.config.maxLogBytes))
          return
        }
        logBudget -= cost
-        sink.push(entry)
+        sink.push(text)
      }

      // No settled guard: `finish` snapshots the arrays when it resolves, so
      // a chunk flushing after settlement mutates only the discarded buffers,
      // and the ledger bounds that growth until the pipes close.
-      const captureStray = (source: 'stdout' | 'stderr') => (chunk: Buffer) => {
-        admit({ source, text: chunk.toString('utf8') }, strayLogs)
+      const captureStray = (chunk: Buffer): void => {
+        admit(chunk.toString('utf8'), strayLogs)
      }
-      worker.stdout.on('data', captureStray('stdout'))
-      worker.stderr.on('data', captureStray('stderr'))
+      worker.stdout.on('data', captureStray)
+      worker.stderr.on('data', captureStray)

      // Exactly one outcome wins. Every path cleans up, terminates, and awaits the worker;
      // logs captured before timeout, abort, or failure remain in the result.
@@ -386,7 +367,7 @@ export class WorkerCodeRuntime extends CodeRuntime {
        // this listener would crash the host process. Junk drops silently.
        const message = parseWorkerMessage(raw)
        if (!message) return
-        if (message.type === 'log' && !settled) admit(message.entry, logs)
+        if (message.type === 'log' && !settled) admit(message.text, logs)
        onCall(message)
        onDone(message)
      })
--- a/packages/code-runtime/code-runtime-worker/src/protocol.ts
+++ b/packages/code-runtime/code-runtime-worker/src/protocol.ts
@@ -5,8 +5,6 @@
 * @module @deepseek-ai/dsh-code-runtime-worker/src/protocol
 */

-import type { CodeLogEntry } from '@deepseek-ai/dsh-code-runtime'
-
 /** What the host hands the worker at spawn, via `workerData`. */
 export interface WorkerBootData {
  /** The type-stripped (plain JS) program body. */
@@ -20,7 +18,7 @@ export interface WorkerBootData {
 }

 /** Worker → host: one bridged binding call. */
-export interface CallMessage {
+interface CallMessage {
  type: 'call'
  /** Worker-issued correlation id; the host answers each id at most once and ignores duplicates. */
  id: number
@@ -32,10 +30,10 @@ export interface CallMessage {
  args: unknown
 }

-/** Worker → host: one captured log entry, streamed eagerly so output survives a mid-run termination (timeout, abort, OOM). */
-export interface LogMessage {
+/** Worker → host: captured text, streamed eagerly so output survives a mid-run termination (timeout, abort, OOM). */
+interface LogMessage {
  type: 'log'
-  entry: CodeLogEntry
+  text: string
 }

 /**
--- a/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts
+++ b/packages/code-runtime/code-runtime-worker/tests/bootstrap.spec.ts
@@ -1,9 +1,8 @@
 import { describe, expect, it } from 'vitest'
 import { EventEmitter } from 'node:events'
-import { LogBuffer, makeConsoleShim, makeNamespaces, captureStreamWrites, prepareValue, runWorkerMain, truncateUtf8Bytes, wireReplies } from '@deepseek-ai/dsh-code-runtime-worker/src/bootstrap.ts'
-import type { BootstrapPort, PatchableStream, PendingCall } from '@deepseek-ai/dsh-code-runtime-worker/src/bootstrap.ts'
-import type { ReplyMessage, WorkerToHost } from '@deepseek-ai/dsh-code-runtime-worker/src/protocol.ts'
-import type { CodeLogEntry } from '@deepseek-ai/dsh-code-runtime'
+import { LogBuffer, makeConsoleShim, makeNamespaces, captureStreamWrites, prepareValue, runWorkerMain, truncateUtf8Bytes, wireReplies } from '../src/bootstrap.ts'
+import type { BootstrapPort, PatchableStream, PendingCall } from '../src/bootstrap.ts'
+import type { ReplyMessage, WorkerToHost } from '../src/protocol.ts'

 /**
 * An in-process stand-in for the worker's parentPort: the test plays the
@@ -31,8 +30,8 @@ class FakePort implements BootstrapPort {
    this.emitter.emit('message', message)
  }

-  logs(): CodeLogEntry[] {
-    return this.sent.filter(message => message.type === 'log').map(message => message.entry)
+  logs(): string[] {
+    return this.sent.filter(message => message.type === 'log').map(message => message.text)
  }

  done(): WorkerToHost | undefined {
@@ -48,12 +47,12 @@ const BOOT = { maxLogBytes: 65_536, maxValueBytes: 32_768 }

 describe('LogBuffer', () => {
  it('streams entries to the sink until the byte budget, then emits one marker and drops the rest', () => {
-    const seen: CodeLogEntry[] = []
-    const buffer = new LogBuffer(10, entry => seen.push(entry))
-    buffer.push({ source: 'console', level: 'log', text: '12345' })
-    buffer.push({ source: 'console', level: 'log', text: '123456' })
-    buffer.push({ source: 'console', level: 'log', text: 'dropped' })
-    expect(seen.map(entry => entry.text)).toEqual([
+    const seen: string[] = []
+    const buffer = new LogBuffer(10, text => seen.push(text))
+    buffer.push('12345')
+    buffer.push('123456')
+    buffer.push('dropped')
+    expect(seen).toEqual([
      '12345',
      '[dsh-code-runtime-worker] log capture truncated at 10 bytes',
    ])
@@ -61,40 +60,37 @@ describe('LogBuffer', () => {
 })

 describe('makeConsoleShim', () => {
-  it('captures the five levels and renders non-strings inspect-style', () => {
-    const seen: CodeLogEntry[] = []
-    const shim = makeConsoleShim(new LogBuffer(1_000, entry => seen.push(entry)))
+  it('captures the five methods and renders non-strings inspect-style', () => {
+    const seen: string[] = []
+    const shim = makeConsoleShim(new LogBuffer(1_000, text => seen.push(text)))
    shim.log('plain', { a: 1 })
    shim.info('i')
    shim.warn('w')
    shim.error('e')
    shim.debug('d')
-    expect(seen.map(entry => entry.level)).toEqual(['log', 'info', 'warn', 'error', 'debug'])
-    expect(seen[0]?.text).toBe('plain { a: 1 }')
-    expect(seen.every(entry => entry.source === 'console')).toBe(true)
+    expect(seen).toEqual(['plain { a: 1 }', 'i', 'w', 'e', 'd'])
  })
 })

 describe('captureStreamWrites', () => {
  it('redirects writes into the buffer and restores on request', () => {
-    const seen: CodeLogEntry[] = []
-    const buffer = new LogBuffer(1_000, entry => seen.push(entry))
+    const seen: string[] = []
+    const buffer = new LogBuffer(1_000, text => seen.push(text))
    let underlying = ''
    const stream: PatchableStream = { write: (chunk: unknown) => { underlying += String(chunk); return true } }
-    const restore = captureStreamWrites(buffer, stream, 'stdout')
+    const restore = captureStreamWrites(buffer, stream)
    stream.write('captured', 'utf8')
    stream.write(Buffer.from('bytes'))
    restore()
    stream.write('after')
-    expect(seen.map(entry => entry.text)).toEqual(['captured', 'bytes'])
-    expect(seen[0]).toMatchObject({ source: 'stdout' })
+    expect(seen).toEqual(['captured', 'bytes'])
    expect(underlying).toBe('after')
  })

  it('invokes the write callback asynchronously, in both optional-encoding shapes', async () => {
    const buffer = new LogBuffer(1_000, () => {})
    const stream: PatchableStream = { write: () => true }
-    captureStreamWrites(buffer, stream, 'stdout')
+    captureStreamWrites(buffer, stream)
    const calls: (Error | null | undefined)[] = []
    stream.write('two-arg', (error?: Error | null) => calls.push(error))
    stream.write('three-arg', 'utf8', (error?: Error | null) => calls.push(error))
@@ -107,7 +103,7 @@ describe('captureStreamWrites', () => {
  it('still fires the callback for a write the exhausted budget drops', async () => {
    const buffer = new LogBuffer(4, () => {})
    const stream: PatchableStream = { write: () => true }
-    captureStreamWrites(buffer, stream, 'stdout')
+    captureStreamWrites(buffer, stream)
    stream.write('this write overflows the budget and is dropped')
    await new Promise<void>(resolve => stream.write('also dropped', resolve))
  })
@@ -210,7 +206,7 @@ describe('runWorkerMain', () => {
      code: 'const doubled = await tools.double({ n: 21 }); console.log("got", doubled); return { doubled };',
      namespaces: [{ global: 'tools', names: ['double'] }],
    }, fakeStreams())
-    expect(port.logs()).toEqual([{ source: 'console', level: 'log', text: 'got 42' }])
+    expect(port.logs()).toEqual(['got 42'])
    expect(port.done()).toEqual({ type: 'done', value: { doubled: 42 } })
  })

@@ -268,6 +264,6 @@ describe('runWorkerMain', () => {
    // The patch stays installed for the worker's lifetime; writes during the
    // program landed in order. Here the program wrote nothing via streams, so
    // only the post-run write above went through the patched slot.
-    expect(port.logs().at(-1)).toMatchObject({ source: 'stdout' })
+    expect(port.logs().at(-1)).toBe('never seen — already restored? no: patch persists in worker')
  })
 })
--- a/packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts
+++ b/packages/code-runtime/code-runtime-worker/tests/built-lib.e2e.ts
@@ -38,9 +38,9 @@ describe.skipIf(!built)('built lib real load path (plain node)', () => {

    expect(exitCode, `stderr:\n${stderr}`).toBe(0)
    const lastLine = stdout.trim().split('\n').at(-1) ?? ''
-    const result = JSON.parse(lastLine) as { value?: unknown; logs: { source: string; level?: string; text: string }[]; error?: unknown }
+    const result = JSON.parse(lastLine) as { value?: unknown; logs: string[]; error?: unknown }
    expect(result.error).toBeUndefined()
    expect(result.value).toBe(42)
-    expect(result.logs).toContainEqual({ source: 'console', level: 'log', text: 'halfway 42' })
+    expect(result.logs).toContain('halfway 42')
  })
 })
--- a/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts
+++ b/packages/code-runtime/code-runtime-worker/tests/runtime.spec.ts
@@ -28,7 +28,7 @@ describe('WorkerCodeRuntime — programs and bindings (real workers)', () => {
    expect(runtime.isolation).toBe('worker-thread')
  })

-  it('runs TypeScript (erasable syntax), captures console/stdout in order, returns the value', async () => {
+  it('runs TypeScript (erasable syntax), captures output in order, returns the value', async () => {
    const { runtime } = await setup()
    const result = await runtime.run({
      program: `
@@ -43,12 +43,7 @@ describe('WorkerCodeRuntime — programs and bindings (real workers)', () => {
    })
    expect(result.error).toBeUndefined()
    expect(result.value).toBe(3)
-    expect(result.logs.map(entry => [entry.source, entry.level ?? null])).toEqual([
-      ['console', 'log'],
-      ['stdout', null],
-      ['console', 'warn'],
-    ])
-    expect(result.logs[0]?.text).toBe('point { x: 1, y: 2 }')
+    expect(result.logs).toEqual(['point { x: 1, y: 2 }', 'raw-out\n', 'careful'])
  })

  it('bridges binding calls both ways and rejects the program-side call on a host rejection', async () => {
@@ -115,7 +110,7 @@ describe('WorkerCodeRuntime — programs and bindings (real workers)', () => {
      bindings: [],
    })
    expect(result.error?.kind).toBe('exception')
-    expect(result.logs.map(entry => entry.text)).toContain('before')
+    expect(result.logs).toContain('before')
  })
 })

@@ -210,8 +205,8 @@ describe('WorkerCodeRuntime — budgets and containment (real workers)', () => {
      program: 'for (let i = 0; i < 1000; i++) console.log("spam line", i); return 1',
      bindings: [],
    })
-    expect(result.logs.at(-1)?.text).toContain('truncated at 300 bytes')
-    const total = result.logs.reduce((sum, entry) => sum + Buffer.byteLength(entry.text, 'utf8'), 0)
+    expect(result.logs.at(-1)).toContain('truncated at 300 bytes')
+    const total = result.logs.reduce((sum, text) => sum + Buffer.byteLength(text, 'utf8'), 0)
    expect(total).toBeLessThan(1_000)
  })

@@ -241,7 +236,7 @@ describe('WorkerCodeRuntime — budgets and containment (real workers)', () => {
    })
    expect(result.error).toBeUndefined()
    expect(result.value).toBe('done')
-    expect(result.logs).toContainEqual({ source: 'stdout', text: 'flushed' })
+    expect(result.logs).toContain('flushed')
  })

  it('caps a huge container whose bounded rendering is small (wire size, not rendering, is what counts)', async () => {
@@ -268,8 +263,8 @@ describe('WorkerCodeRuntime — budgets and containment (real workers)', () => {
      bindings: [],
    })
    expect(result.error).toBeUndefined()
-    expect(result.logs).toContainEqual({ source: 'stdout', text: 'abcd' })
-    expect(result.logs.map(entry => entry.text)).not.toContain('ef')
+    expect(result.logs).toContain('abcd')
+    expect(result.logs).not.toContain('ef')
  }, 15_000)
 })

@@ -304,11 +299,9 @@ describe('WorkerCodeRuntime — hostile programs (real workers)', () => {
          { type: 'call', id: 1e9, global: 7, name: 'real', args: {} },
          { type: 'call', id: 1e9, global: 'tools', name: 7, args: {} },
          { type: 'log' },
-          { type: 'log', entry: null },
-          { type: 'log', entry: { source: 'stdout', text: 7 } },
-          { type: 'log', entry: { source: 'nope', text: 'x' } },
-          { type: 'log', entry: { source: 'console', level: 'nope', text: 'x' } },
-          { type: 'log', entry: { source: 'console', level: 7, text: 'x' } },
+          { type: 'log', text: null },
+          { type: 'log', text: 7 },
+          { type: 'log', text: {} },
          { type: 'done', error: 5 },
          { type: 'done', error: { message: 5 } },
        ]) parentPort.postMessage(junk);
@@ -329,7 +322,7 @@ describe('WorkerCodeRuntime — hostile programs (real workers)', () => {
      // code and an unbounded result.
      program: `
        const { parentPort } = await import('node:worker_threads');
-        for (let i = 0; i < 50; i++) parentPort.postMessage({ type: 'log', entry: { source: 'stdout', text: 'F'.repeat(100), forged: true } });
+        for (let i = 0; i < 50; i++) parentPort.postMessage({ type: 'log', text: 'F'.repeat(100), forged: true });
        parentPort.postMessage({ type: 'done', value: 'V'.repeat(100000) });
        for (;;) {}
      `,
@@ -341,10 +334,9 @@ describe('WorkerCodeRuntime — hostile programs (real workers)', () => {
    expect(value.endsWith('… [truncated]')).toBe(true)
    expect(value.length).toBeLessThan(120)
    const marker = '[dsh-code-runtime-worker] log capture truncated at 200 bytes'
-    const total = result.logs.reduce((sum, entry) => sum + Buffer.byteLength(entry.text, 'utf8'), 0)
+    const total = result.logs.reduce((sum, text) => sum + Buffer.byteLength(text, 'utf8'), 0)
    expect(total).toBeLessThanOrEqual(200 + Buffer.byteLength(marker, 'utf8'))
-    expect(result.logs.at(-1)?.text).toBe(marker)
-    expect(result.logs.every(entry => !('forged' in entry))).toBe(true)
+    expect(result.logs.at(-1)).toBe(marker)
  })

  it('accepts a forged done carrying both value and error (self-sabotage, contained)', async () => {
--- a/packages/code-runtime/code-runtime/README.md
+++ b/packages/code-runtime/code-runtime/README.md
@@ -16,7 +16,7 @@ Semantics every implementation must honor (contract details in the class JSDoc):

 ## Vocabulary

-`CodeRunRequest` (`program`, `bindings`, `signal?`) carries everything the runtime acts on — defaulting (time budgets, output caps) is the implementation's validated config, never a hidden `??` inside `run()`. `bindings` is a list of `CodeBindingNamespace`s (`global` + `functions`), each exposed to the program as one global object of async callables. `CodeRunResult` reports the completion `value?`, the ordered `logs` (`CodeLogEntry`: `console`/`stdout`/`stderr` source, console `level`, capped text), and the `error?` (`CodeRunFailure`: `kind` + model-feedable `message`). See `src/types.ts` for the full contracts.
+`CodeRunRequest` (`program`, `bindings`, `signal?`) carries everything the runtime acts on — defaulting (time budgets, output caps) is the implementation's validated config, never a hidden `??` inside `run()`. `bindings` is a list of `CodeBindingNamespace`s (`global` + `functions`), each exposed to the program as one global object of async callables. `CodeRunResult` reports the completion `value?`, ordered capped `logs: string[]`, and the `error?` (`CodeRunFailure`: `kind` + model-feedable `message`). See `src/types.ts` for the full contracts.

 ## Model Experience

--- a/packages/code-runtime/code-runtime/src/index.ts
+++ b/packages/code-runtime/code-runtime/src/index.ts
@@ -10,7 +10,6 @@ import type { CodeRunRequest, CodeRunResult } from './types.ts'
 export type {
  CodeBindingFunction,
  CodeBindingNamespace,
-  CodeLogEntry,
  CodeRunFailure,
  CodeRunRequest,
  CodeRunResult,
--- a/packages/code-runtime/code-runtime/src/types.ts
+++ b/packages/code-runtime/code-runtime/src/types.ts
@@ -54,20 +54,6 @@ export interface CodeRunRequest {
  signal?: AbortSignal
 }

-/**
- * One captured output entry, in emission order. `source` says which channel
- * produced it: the program's `console` (shimmed by the runtime), or a stray
- * write to the underlying stdout/stderr streams.
- */
-export interface CodeLogEntry {
-  /** Which channel produced the text. */
-  source: 'console' | 'stdout' | 'stderr'
-  /** The console method used; present only when `source` is `'console'`. */
-  level?: 'log' | 'info' | 'warn' | 'error' | 'debug'
-  /** The captured text (possibly truncated by the implementation's caps, marked in-band). */
-  text: string
-}
-
 /**
 * Why a run failed. The kinds are orthogonal outcomes reported independently
 * (per docs/defensive-patterns.md): a budget expiry is not an exception, an
@@ -98,8 +84,8 @@ export interface CodeRunResult {
   * or value-less run leaves this absent.
   */
  value?: unknown
-  /** Everything the program emitted, in order (capped by the implementation). */
-  logs: CodeLogEntry[]
+  /** Text the program emitted, in order (capped by the implementation). */
+  logs: string[]
  /** Present iff the run failed; see {@link CodeRunFailure} for the taxonomy. */
  error?: CodeRunFailure
 }
--- a/packages/code-runtime/code-runtime/tests/service.spec.ts
+++ b/packages/code-runtime/code-runtime/tests/service.spec.ts
@@ -55,7 +55,7 @@ describe('CodeRuntime service seam', () => {
  it('reports a failed run as an error field on a resolved result, never a rejection', async () => {
    const { runtime } = await setup()
    runtime.nextResult = {
-      logs: [{ source: 'console', level: 'error', text: 'boom' }],
+      logs: ['boom'],
      error: { kind: 'exception', message: 'boom' },
    }
    const result = await runtime.run({ program: 'throw new Error("boom")', bindings: [] })
--- a/packages/context/README.md
+++ b/packages/context/README.md
@@ -1,6 +1,6 @@
 # context/ — optional request context

-Opt-in plugins that add bounded model-visible request context without defining a tool or service. The default `dsh-agent-core` bundle excludes them.
+Opt-in plugins that add bounded model-visible request context without defining a tool or service. The default `dsh-agent-spine-demo` bundle excludes them.

 | Package | Role | ctx key |
 |---|---|---|
--- a/packages/context/time-context/README.md
+++ b/packages/context/time-context/README.md
@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-time-context

-Opt-in dynamic system-prompt context with the current zoned time and elapsed time since the latest model-visible message before the turn. `dsh-agent-core` and shipped examples do not mount it. Decision record: [the time-context RFC](../../../docs/rfc/implemented/feature/2026-07-14-time-context-plugin.md).
+Opt-in dynamic system-prompt context with the current zoned time and elapsed time since the latest model-visible message before the turn. `dsh-agent-spine-demo` and shipped examples do not mount it. Decision record: [the time-context RFC](../../../docs/rfc/implemented/feature/2026-07-14-time-context-plugin.md).

 ## Config

--- a/packages/context/time-context/tests/fixtures/cordis.yml
+++ b/packages/context/time-context/tests/fixtures/cordis.yml
@@ -9,7 +9,7 @@
  name: '@deepseek-ai/dsh-time-context'

 - id: stdio-agent
-  name: '@deepseek-ai/dsh-stdio-agent'
+  name: '@deepseek-ai/dsh-stdio-demo'
  config:
    model: mock-echo
    persona: 'Test the time-context plugin.'
--- a/packages/context/time-context/tests/time-context.e2e.ts
+++ b/packages/context/time-context/tests/time-context.e2e.ts
@@ -6,7 +6,7 @@ import { fileURLToPath } from 'node:url'
 import { afterEach, describe, expect, it } from 'vitest'
 import { foldRequestHeader, type SessionEvent } from '@deepseek-ai/dsh-session'

-const binScript = fileURLToPath(new URL('../../../ui/stdio-agent/src/bin.ts', import.meta.url))
+const binScript = fileURLToPath(new URL('../../../examples/stdio-demo/src/bin.ts', import.meta.url))
 const configPath = fileURLToPath(new URL('./fixtures/cordis.yml', import.meta.url))
 const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))
 const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -556,7 +556,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
  },
  {
    name: 'AssembledSection',
-    declaration: 'export interface AssembledSection {\n    name: string;\n    order: number;\n    text: string;\n}',
+    declaration: 'export interface AssembledSection {\n    name: string;\n    text: string;\n}',
  },
  {
    name: 'BashExecRequest',
@@ -610,10 +610,6 @@ export const TYPE_API: readonly TypeApiEntry[] = [
    name: 'CodeBindingNamespace',
    declaration: 'export interface CodeBindingNamespace {\n    global: string;\n    functions: Record<string, CodeBindingFunction>;\n}',
  },
-  {
-    name: 'CodeLogEntry',
-    declaration: 'export interface CodeLogEntry {\n    source: \'console\' | \'stdout\' | \'stderr\';\n    level?: \'log\' | \'info\' | \'warn\' | \'error\' | \'debug\';\n    text: string;\n}',
-  },
  {
    name: 'CodeRunFailure',
    declaration: 'export interface CodeRunFailure {\n    kind: \'exception\' | \'timeout\' | \'abort\' | \'worker-exit\';\n    message: string;\n}',
@@ -624,7 +620,7 @@ export const TYPE_API: readonly TypeApiEntry[] = [
  },
  {
    name: 'CodeRunResult',
-    declaration: 'export interface CodeRunResult {\n    value?: unknown;\n    logs: CodeLogEntry[];\n    error?: CodeRunFailure;\n}',
+    declaration: 'export interface CodeRunResult {\n    value?: unknown;\n    logs: string[];\n    error?: CodeRunFailure;\n}',
  },
  {
    name: 'CollectedOutput',
--- a/packages/core/README.md
+++ b/packages/core/README.md
@@ -10,10 +10,9 @@ The session log, system-prompt assembly, tool registry, agent vocabulary, and co
 | `tools/` | Scoped tool registry + pre-policy, guards, around-dispatch, post-policy, and final-result observation | `ctx.tools` |
 | `agent/` | Agent interface, registry, `agent/*` event vocabulary | `ctx.agents` |
 | `agent-loop/` | The concrete loop plugin: `ReactLoopAgent` + the loop driver | `ctx.agentLoop` |
-| `agent-core/` | Bundle plugin: the default executor-less/UI-less spine as code | (loads the spine) |

 `scope/` is the one non-service package here: a dependency-free library (`createScope`/`scopeOf`/`scopeTarget`) the registries and the loop build per-agent scoping on — it sits below `session/` and `system-prompt/` in the module graph precisely so they can consume it without a cycle.

 `agent-loop` is the one concrete implementation of the `agent` seam and lives here because it is the harness's default product loop; everything else in `core/` is interface/vocabulary. Plugins depend on the `agent` vocabulary, never on `agent-loop` directly, so the loop stays swappable.

-`agent-core` is the composition counterpart: one bundle plugin that loads the control spine plus selected default capabilities (`timer` + `llm` + sessions + system-prompt + tools + agents + invariants + the local [skill family](../skill/README.md) + `tool-bash` + workspace-context + `agent-loop`) and forwards `agent-loop`'s `agents` list as its own config. App packages (`ui/stdio-agent`, `ui/acp-agent`) consume it and add only a front door; a leaf adds the swappable backends plus any optional product tools it wants to expose. It lives in `core/` because it composes the shared control spine while leaving executors, LLM adapters, alternate skill providers, and UI front doors outside the bundle.
+The default composition that wires this spine into a runnable agent lives in [`examples/agent-spine-demo`](../examples/agent-spine-demo/README.md): one bundle plugin that loads the control spine plus selected default capabilities (`timer` + `llm` + sessions + system-prompt + tools + agents + invariants + the local [skill family](../skill/README.md) + `tool-bash` + workspace-context + `agent-loop`) and forwards `agent-loop`'s `agents` list as its own config. It sits in `examples/` — ready-to-run demo/reference bundles — not in `core/`: `core/` ships the swappable spine pieces, while a demo bundle picks one concrete composition of them and adds a front door.
--- a/packages/core/system-prompt/src/index.ts
+++ b/packages/core/system-prompt/src/index.ts
@@ -65,10 +65,6 @@ export interface PromptSection {
 export interface AssembledSection {
  /** The contributing section's unique name. */
  name: string
-  // TODO(assembled-section-order): drop this output field; registry order has
-  // already sorted the array, and no production renderer/listener reads it.
-  /** The contributing section's order (sections arrive sorted ascending). */
-  order: number
  /** The resolved (but not yet interpolated) section text. */
  text: string
 }
@@ -403,12 +399,11 @@ export class SystemPrompt extends Service {
    }
    const assembly: PromptAssembly = {
      sections: [...sectionByName.values()]
+        .sort((a, b) => a.order - b.order)
        .map(section => ({
          name: section.name,
-          order: section.order,
          text: typeof section.text === 'function' ? section.text(context) : section.text,
-        }))
-        .sort((a, b) => a.order - b.order),
+        })),
      tools: orderTools(collected, this.toolOrder, knownNames),
      variables,
    }
--- a/packages/core/system-prompt/tests/scoped.spec.ts
+++ b/packages/core/system-prompt/tests/scoped.spec.ts
@@ -139,7 +139,7 @@ describe('scoped assemble dispatch', () => {
    scope.ctx.on('system-prompt/assemble', async (_assembly: PromptAssembly, context, next: () => Promise<PromptAssembly>) => {
      shaped.push(context.scope)
      const result = await next()
-      result.sections.push({ name: 'listener:extra', order: 999, text: 'listener text' })
+      result.sections.push({ name: 'listener:extra', text: 'listener text' })
      return result
    })

--- a/packages/core/system-prompt/tests/system-prompt.spec.ts
+++ b/packages/core/system-prompt/tests/system-prompt.spec.ts
@@ -21,9 +21,9 @@ describe('SystemPrompt', () => {
      await ctx.plugin(SystemPrompt, { persona: 'You are DeepSeek Harness SDK.' })

      const assembly = await ctx.systemPrompt.assemble()
-      expect(assembly.sections.map(s => [s.name, s.order])).toEqual([
-        ['harness:identity', -100],
-        ['deployment:persona', 0],
+      expect(assembly.sections.map(s => s.name)).toEqual([
+        'harness:identity',
+        'deployment:persona',
      ])
      expect(renderPrompt(assembly)).toBe(`${IDENTITY}\n\nYou are DeepSeek Harness SDK.`)
      // The names are reserved by the plugin — one owner per section.
@@ -183,7 +183,7 @@ describe('SystemPrompt', () => {
    const contexts: AssembleContext[] = []
    ctx.on('system-prompt/assemble', async (assembly: PromptAssembly, context, next) => {
      contexts.push(context)
-      assembly.sections.push({ name: 'from-a', order: 100, text: 'a' })
+      assembly.sections.push({ name: 'from-a', text: 'a' })
      return next()
    })
    // Listener B (registered later, runs after A) sees A's contribution.
@@ -235,8 +235,8 @@ describe('SystemPrompt', () => {
  it('filters out empty section text from renderPrompt', () => {
    const result = renderPrompt({
      sections: [
-        { name: 'empty', order: 0, text: '' },
-        { name: 'real', order: 1, text: 'content' },
+        { name: 'empty', text: '' },
+        { name: 'real', text: 'content' },
      ],
      tools: [],
      variables: {},
@@ -356,13 +356,13 @@ describe('SystemPrompt', () => {
    })

    it('names "(none)" when no variables are registered at all', () => {
-      expect(() => renderPrompt({ sections: [{ name: 's', order: 0, text: '{{x}}' }], tools: [], variables: {} }))
+      expect(() => renderPrompt({ sections: [{ name: 's', text: '{{x}}' }], tools: [], variables: {} }))
        .toThrow('unknown prompt variable "{{x}}" in section "s"; registered variables: (none)')
    })

    it('throws when a referenced variable has no value for this assembly', () => {
      expect(() => renderPrompt({
-        sections: [{ name: 'persona', order: 0, text: 'in {{cwd}}' }],
+        sections: [{ name: 'persona', text: 'in {{cwd}}' }],
        tools: [],
        variables: { cwd: undefined },
      })).toThrow('prompt variable "{{cwd}}" has no value for this assembly (section "persona")')
@@ -370,7 +370,7 @@ describe('SystemPrompt', () => {

    it('throws on a malformed complete reference, e.g. inner spaces', () => {
      expect(() => renderPrompt({
-        sections: [{ name: 's', order: 0, text: 'on {{ model }}' }],
+        sections: [{ name: 's', text: 'on {{ model }}' }],
        tools: [],
        variables: { model: 'm' },
      })).toThrow('malformed prompt variable reference "{{ model }}" in section "s"')
@@ -378,7 +378,7 @@ describe('SystemPrompt', () => {

    it('leaves a lone {{ verbatim only when NO }} follows anywhere after it', () => {
      const text = renderPrompt({
-        sections: [{ name: 's', order: 0, text: 'shell ${X:-{{fallback} stays' }],
+        sections: [{ name: 's', text: 'shell ${X:-{{fallback} stays' }],
        tools: [],
        variables: {},
      })
@@ -390,7 +390,7 @@ describe('SystemPrompt', () => {
      { text: 'x {{a{b}} y {{model}}', label: 'nested brace inside a would-be group' },
    ])('throws on a mangled reference with a }} still following ($label)', ({ text }) => {
      expect(() => renderPrompt({
-        sections: [{ name: 's', order: 0, text }],
+        sections: [{ name: 's', text }],
        tools: [],
        variables: { model: 'm' },
      })).toThrow('malformed prompt variable reference at')
@@ -400,7 +400,7 @@ describe('SystemPrompt', () => {
      // `in` would find Object.prototype.constructor and splice function
      // source into the prompt; Object.hasOwn must reject it instead.
      expect(() => renderPrompt({
-        sections: [{ name: 's', order: 0, text: 'on {{constructor}}' }],
+        sections: [{ name: 's', text: 'on {{constructor}}' }],
        tools: [],
        variables: { model: 'm' },
      })).toThrow('unknown prompt variable "{{constructor}}"')
@@ -416,7 +416,7 @@ describe('SystemPrompt', () => {

    it('never re-scans substituted values (a value containing {{sneaky}} stays literal)', () => {
      const text = renderPrompt({
-        sections: [{ name: 's', order: 0, text: 'v = {{model}}!' }],
+        sections: [{ name: 's', text: 'v = {{model}}!' }],
        tools: [],
        variables: { model: 'literal {{sneaky}} inside' },
      })
--- a/packages/core/tools/src/code-mode.ts
+++ b/packages/core/tools/src/code-mode.ts
@@ -120,14 +120,13 @@ function renderValue(value: unknown): string {
 /** The run_code result's `meta` payload (JSON-serializable; `presentResult` narrows it back). */
 interface RunCodeMeta {
  logs: CodeRunResult['logs']
-  dispatches: number
 }

 /** Soft-narrow a result `meta` back to {@link RunCodeMeta} (replay may carry older shapes; presentation must not throw). */
 function asRunCodeMeta(meta: unknown): RunCodeMeta | undefined {
  if (typeof meta !== 'object' || meta === null) return undefined
  const m = meta as Record<string, unknown>
-  if (!Array.isArray(m.logs) || typeof m.dispatches !== 'number') return undefined
+  if (!Array.isArray(m.logs) || !m.logs.every(log => typeof log === 'string')) return undefined
  return m as unknown as RunCodeMeta
 }

@@ -263,12 +262,12 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () =>
        }

        if (result.error) {
-          const logsText = result.logs.length > 0 ? `\nCaptured output:\n${result.logs.map(entry => entry.text).join('\n')}` : ''
+          const logsText = result.logs.length > 0 ? `\nCaptured output:\n${result.logs.join('\n')}` : ''
          throw new CodeRunFailedError(`code run failed (${result.error.kind}): ${result.error.message}${logsText}`)
        }
        const rendered = renderValue(result.value)
-        const parts = [result.logs.map(entry => entry.text).join('\n'), rendered].filter(part => part.length > 0)
-        const meta: RunCodeMeta = { logs: result.logs, dispatches }
+        const parts = [result.logs.join('\n'), rendered].filter(part => part.length > 0)
+        const meta: RunCodeMeta = { logs: result.logs }
        return {
          content: [{ type: 'text', text: parts.length > 0 ? parts.join('\n') : '(run_code completed with no output)' }],
          meta,
@@ -290,7 +289,7 @@ export function createRunCodeTool(registry: ToolRegistry, requireRuntime: () =>
    presentResult: (_args, result) => {
      const meta = asRunCodeMeta(result.meta)
      if (!meta) return undefined
-      const output = meta.logs.map(entry => entry.text).join('\n')
+      const output = meta.logs.join('\n')
      return {
        card: 'generic',
        ...output.length > 0 ? { content: [{ type: 'text' as const, text: output }] } : {},
--- a/packages/core/tools/tests/code-mode.spec.ts
+++ b/packages/core/tools/tests/code-mode.spec.ts
@@ -329,7 +329,7 @@ describe('the run_code dispatch bridge', () => {
      const tools = request.bindings[0]!.functions
      const first = await tools.echo!({ value: 'one' })
      const second = await tools.echo!({ value: 'two' })
-      return { logs: [{ source: 'console', level: 'log', text: `saw ${String(first)}` }], value: second }
+      return { logs: [`saw ${String(first)}`], value: second }
    }
    const result = await runCode(ctx, 'const …: string = …', { agent })
    expect(result.isError).toBe(false)
@@ -340,7 +340,7 @@ describe('the run_code dispatch bridge', () => {
      { parentCallId: 'call-1', subCallId: 'call-1:code:1', name: 'echo', arguments: { value: 'one' }, isError: false, resultSummary: 'echo:one' },
      { parentCallId: 'call-1', subCallId: 'call-1:code:2', name: 'echo', arguments: { value: 'two' }, isError: false, resultSummary: 'echo:two' },
    ])
-    expect(result.meta).toEqual({ logs: [{ source: 'console', level: 'log', text: 'saw echo:one' }], dispatches: 2 })
+    expect(result.meta).toEqual({ logs: ['saw echo:one'] })
  })

  it('exposes only an opaque parent token to nested result observers', async () => {
@@ -548,7 +548,7 @@ describe('the run_code dispatch bridge', () => {
  it('converts a failed run into a structured isError result carrying kind, message, and captured logs', async () => {
    const { ctx, runtime } = await setup({ mode: 'code' })
    runtime.behavior = () => Promise.resolve({
-      logs: [{ source: 'console', level: 'log', text: 'got this far' }],
+      logs: ['got this far'],
      error: { kind: 'timeout', message: 'compute budget exhausted (300ms busy)' },
    })
    const result = await runCode(ctx, 'program')
@@ -672,7 +672,7 @@ describe('the run_code dispatch bridge', () => {
    const view = tool.presentResult?.({ code: 'return 1' }, {
      content: [{ type: 'text', text: 'model-facing' }],
      isError: false,
-      meta: { logs: [{ source: 'console', level: 'log', text: 'printed' }], dispatches: 1 },
+      meta: { logs: ['printed'] },
    })
    // The result omits the title — an update replaces only provided fields,
    // so the pending card's program title persists through completion.
@@ -681,9 +681,10 @@ describe('the run_code dispatch bridge', () => {
      content: [{ type: 'text', text: 'printed' }],
    })
    // No captured output → no content either; everything pending persists.
-    expect(tool.presentResult?.({ code: 'x' }, { content: [], isError: false, meta: { logs: [], dispatches: 2 } }))
+    expect(tool.presentResult?.({ code: 'x' }, { content: [], isError: false, meta: { logs: [] } }))
      .toEqual({ card: 'generic' })
    // Replay with an unrecognizable meta falls back to the generic rendering.
+    expect(tool.presentResult?.({ code: 'x' }, { content: [], isError: false, meta: { logs: [{ text: 'legacy' }], dispatches: 1 } })).toBeUndefined()
    expect(tool.presentResult?.({ code: 'x' }, { content: [], isError: false, meta: { other: true } })).toBeUndefined()
    expect(tool.presentResult?.({ code: 'x' }, { content: [], isError: false })).toBeUndefined()
  })
--- a/packages/examples/README.md
+++ b/packages/examples/README.md
@@ -0,0 +1,20 @@
+# examples/ — ready-to-run demo bundles
+
+Pre-composed plugin bundles a thin leaf `cordis.yml` loads instead of assembling the spine and a front door by hand. These are **demo / reference** packages — the `-demo` npm suffix marks each one as non-product surface, readable straight off the package name. The runnable leaves under the repo-root [`examples/`](../../examples/AGENTS.md) and the [Python SDK runtime](../../python/sdk-runtime/README.md) are the consumers; each is just its swappable backends plus one bundle entry.
+
+| Package | npm name | Role |
+|---|---|---|
+| `agent-spine-demo/` | `@deepseek-ai/dsh-agent-spine-demo` | The executor-less/UI-less agent spine as one bundle plugin (`timer` + `llm` + sessions + system-prompt + tools + skills + agents + invariants + `tool-bash` + workspace-context + `tool-skill` + `agent-loop`) |
+| `stdio-demo/` | `@deepseek-ai/dsh-stdio-demo` | Terminal stdio chat app: the spine + console logger + readline UI + a pre-created `main` agent, with a boot `bin` |
+| `acp-demo/` | `@deepseek-ai/dsh-acp-demo` | ACP server app: the spine + JSONL persistence + the [`acp`](../ui/acp/README.md) bridge (no stdout logger), with a boot `bin` |
+| `jsonrpc-demo/` | `@deepseek-ai/dsh-jsonrpc-demo` | Bin-only runtime that boots an external `cordis.yml` for the stdio JSON-RPC SDK client |
+
+`agent-spine-demo` is the shared bundle; `stdio-demo` and `acp-demo` compose it with opposite front-door clusters (console logger + readline UI vs the stdout-owning ACP bridge) and own their boot bins. `jsonrpc-demo` mounts no composition of its own — it boots whatever tree the deployment's `cordis.yml` names, and is what the Python SDK runtime launches.
+
+These are **not** product API. The spine pieces they bundle live in [`core/`](../core/README.md), the bridges/channels/boot-glue in [`ui/`](../ui/README.md), and the swappable backends (LLM adapter, bash executor) in their capability groups; a demo bundle just picks one concrete composition of them. Swap or fork one freely.
+
+Do not confuse this group with the repo-root [`examples/`](../../examples/AGENTS.md): that directory holds the runnable `cordis.yml` **leaves**; this group holds the **bundles** those leaves load.
+
+## The jsonrpc bin/exe names are legacy
+
+`jsonrpc-demo` renamed like its siblings, but its bin is still `dsh-jsonrpc-agent` and the single-file executable is still `dsh-jsonrpc-agent-pkg` (referenced across the [Python distribution](../../python/sdk-runtime/README.md)). Those names are the SDK's runtime-startup surface; they are reconciled when the SDK unifies that startup flow, not by this move.
--- a/packages/examples/acp-demo/README.md
+++ b/packages/examples/acp-demo/README.md
@@ -1,8 +1,8 @@
-# @deepseek-ai/dsh-acp-agent
+# @deepseek-ai/dsh-acp-demo

-The **ACP server app**: a Cordis app plugin that composes the default agent spine ([`@deepseek-ai/dsh-agent-core`](../../core/agent-core/README.md)) with the front-door cluster an [Agent Client Protocol](../acp/README.md) server needs, and a `bin` that boots a leaf `cordis.yml` speaking ACP JSON-RPC on stdio.
+The **ACP server app**: a Cordis app plugin that composes the default agent spine ([`@deepseek-ai/dsh-agent-spine-demo`](../../examples/agent-spine-demo/README.md)) with the front-door cluster an [Agent Client Protocol](../../ui/acp/README.md) server needs, and a `bin` that boots a leaf `cordis.yml` speaking ACP JSON-RPC on stdio.

-It is the structured counterpart to [`@deepseek-ai/dsh-stdio-agent`](../stdio-agent/README.md): both consume the same spine, but this one bakes in the OPPOSITE front-door cluster.
+It is the structured counterpart to [`@deepseek-ai/dsh-stdio-demo`](../stdio-demo/README.md): both consume the same spine, but this one bakes in the OPPOSITE front-door cluster.

 ## What it bakes in — and what it deliberately omits

@@ -10,13 +10,13 @@ stdout is the ACP JSON-RPC channel, so the cluster is defined as much by what it

 | Plugin | Why |
 |---|---|
-| `@deepseek-ai/dsh-agent-core` | the spine, pre-creating **no** agents (ACP `session/new` creates them on demand) |
+| `@deepseek-ai/dsh-agent-spine-demo` | the spine, pre-creating **no** agents (ACP `session/new` creates them on demand) |
 | `@deepseek-ai/dsh-user-interaction` | the human question/answer seam used by clients that can complete ACP elicitation requests |
 | `@deepseek-ai/dsh-session-persistence-jsonl` | durable JSONL session log (the bridge advertises `loadSession`) |
 | `@deepseek-ai/dsh-acp` | the bridge that owns stdout for JSON-RPC and provides ACP-backed user answers when a leaf explicitly exposes a user-question tool |
 | ~~`@deepseek-ai/dsh-tool-ask-user`~~ | **omitted by default** — ACP elicitation support is still client-dependent, so leaves must opt in deliberately |
 | ~~`@deepseek-ai/dsh-user-approval`~~ | **omitted by default** — permission policy is deployment-specific; sandbox/approval leaves opt in and the ACP bridge then supplies the answerer |
-| ~~console logger~~ | **omitted** — it writes to stdout and would corrupt the protocol frames ([the stdout-purity footgun](../acp/README.md)) |
+| ~~console logger~~ | **omitted** — it writes to stdout and would corrupt the protocol frames ([the stdout-purity footgun](../../ui/acp/README.md)) |
 | ~~`hmr`~~ | **omitted** — the editor owns the subprocess |

 Because the package wires no logger entry, an ACP leaf has **nothing to get wrong by default**: it only picks backends, so the common mistake — copying a console-logger entry from the stdio config — has no place here. (A leaf author technically *can* still add `@cordisjs/plugin-logger-console` as a sibling entry; the package can't forbid that. So the rule stands: never add a stdout logger to an ACP leaf — stdout is the JSON-RPC channel. Use a stderr exporter if you need logs.)
@@ -28,15 +28,15 @@ Because the package wires no logger entry, an ACP leaf has **nothing to get wron
 | `model` | (required) | the per-session agent template the bridge creates agents from |
 | `persona` | — | the deployment persona template (may reference `{{model}}`/`{{cwd}}`), routed to `dsh-system-prompt` |
 | `toolOrder` | — | explicit model-facing tool order (a name list with one `'<unlisted-tools>'` rest entry; absent — lexicographic; an unregistered name fails each turn at prompt assembly), routed to `dsh-system-prompt` |
-| `tools` | `{ mode: 'native' }` | tool-registry presentation config (`native` / `code` / `both`), routed through `dsh-agent-core` |
-| `skills` | owner defaults | registry-cache, local-provider, and model-facing skill-tool config, routed through `dsh-agent-core` |
+| `tools` | `{ mode: 'native' }` | tool-registry presentation config (`native` / `code` / `both`), routed through `dsh-agent-spine-demo` |
+| `skills` | owner defaults | registry-cache, local-provider, and model-facing skill-tool config, routed through `dsh-agent-spine-demo` |
 | `persistenceRoot` | `./.sessions` | the JSONL backend's root directory |

 The leaf supplies the swappable backends: an LLM adapter (`llm-deepseek` for the real model, `llm-replay` for keyless snapshot replay) and a bash executor.

 ## The bin

-`dsh-acp-agent [--config path-to-cordis.yml]` (short form `-c`; default `./cordis.yml`):
+`dsh-acp-demo [--config path-to-cordis.yml]` (short form `-c`; default `./cordis.yml`):

 - loads a gitignored `.env` from the cwd — **skipped** in snapshot REPLAY so a stray key can never trigger a live call;
 - honors `DSH_SNAPSHOT=replay` by booting the sibling `cordis.snapshot.yml` (the keyless replay tree, `llm-replay` in place of `llm-deepseek`);
@@ -48,7 +48,7 @@ All diagnostics go to **stderr** — stdout is the protocol.

 ## Model Experience

-Indirectly, through `dsh-agent-core` and `dsh-acp`, which compose each ACP agent's prompt, tools, and message history; this app bundle adds no model-bound content itself.
+Indirectly, through `dsh-agent-spine-demo` and `dsh-acp`, which compose each ACP agent's prompt, tools, and message history; this app bundle adds no model-bound content itself.

 ## Known Limitations and Deferred Work

--- a/packages/examples/acp-demo/package.json
+++ b/packages/examples/acp-demo/package.json
@@ -1,13 +1,13 @@
 {
-  "name": "@deepseek-ai/dsh-acp-agent",
-  "description": "ACP server app: the agent-core spine + JSONL persistence + the ACP bridge (no stdout logger, no hmr, no pre-created agents), with a bin to boot a leaf cordis.yml over JSON-RPC stdio",
+  "name": "@deepseek-ai/dsh-acp-demo",
+  "description": "ACP server app: the agent-spine-demo bundle + JSONL persistence + the ACP bridge (no stdout logger, no hmr, no pre-created agents), with a bin to boot a leaf cordis.yml over JSON-RPC stdio",
  "version": "0.0.1",
  "private": true,
  "type": "module",
  "main": "lib/index.js",
  "types": "lib/types/index.d.ts",
  "bin": {
-    "dsh-acp-agent": "lib/bin.js"
+    "dsh-acp-demo": "lib/bin.js"
  },
  "exports": {
    ".": {
@@ -34,7 +34,7 @@
    "@cordisjs/plugin-loader": "^1.0.0-rc.5",
    "@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-agent-spine-demo": "^0.0.1",
    "@deepseek-ai/dsh-workspace-context": "^0.0.1",
    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
    "@deepseek-ai/dsh-tools": "^0.0.1",
@@ -48,7 +48,7 @@
    "@deepseek-ai/dsh-app-boot": "workspace:^",
    "@deepseek-ai/dsh-acp": "workspace:^",
    "@deepseek-ai/dsh-agent": "workspace:^",
-    "@deepseek-ai/dsh-agent-core": "workspace:^",
+    "@deepseek-ai/dsh-agent-spine-demo": "workspace:^",
    "@deepseek-ai/dsh-tools": "workspace:^",
    "@deepseek-ai/dsh-system-prompt": "workspace:^",
    "@deepseek-ai/dsh-workspace-context": "workspace:^",
--- a/packages/examples/acp-demo/src/bin.ts
+++ b/packages/examples/acp-demo/src/bin.ts
@@ -1,19 +1,19 @@
 #!/usr/bin/env node
 /**
 * Boot an ACP stdio server from `cordis.yml`; usage is
- * `dsh-acp-agent [--config path]`, defaulting to `./cordis.yml`. Shared env
+ * `dsh-acp-demo [--config path]`, defaulting to `./cordis.yml`. Shared env
 * loading, Loader guards, snapshot config selection, and settled-tree boot live
 * in dsh-app-boot. Replay skips `.env` and selects sibling
 * `cordis.snapshot.yml` so a stray key cannot trigger a model call. EOF disposes
 * and flushes snapshot runs; editors normally own process lifetime. Stdout is
 * reserved for JSON-RPC, so diagnostics go only to stderr.
- * @module @deepseek-ai/dsh-acp-agent/bin
+ * @module @deepseek-ai/dsh-acp-demo/bin
 */

 import { parseArgs } from 'node:util'
 import { boot, installFailLoud, loadEnv, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'

-const NAME = 'dsh-acp-agent'
+const NAME = 'dsh-acp-demo'

 /* 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
--- a/packages/examples/acp-demo/src/index.ts
+++ b/packages/examples/acp-demo/src/index.ts
@@ -1,24 +1,24 @@
 /**
- * The ACP server app: the default agent spine ({@link @deepseek-ai/dsh-agent-core}),
+ * The ACP server app: the default agent spine ({@link @deepseek-ai/dsh-agent-spine-demo}),
 * JSONL session persistence, and the {@link @deepseek-ai/dsh-acp} bridge. It
 * writes nothing to stdout.
 * It pre-creates no agents and leaves adapters, executors, and optional tools to
 * the leaf, which must likewise avoid stdout loggers. Named exports are
 * required so Loader retains this plugin's `Config` schema (see
 * docs/postmortem/0001).
- * @module @deepseek-ai/dsh-acp-agent
+ * @module @deepseek-ai/dsh-acp-demo
 */

 import type { Context } from 'cordis'
 import z from 'schemastery'
 import * as acp from '@deepseek-ai/dsh-acp'
-import * as agentCore from '@deepseek-ai/dsh-agent-core'
+import * as agentCore from '@deepseek-ai/dsh-agent-spine-demo'
 import * as workspaceContext from '@deepseek-ai/dsh-workspace-context'
 import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'

-export const name = 'acp-agent'
+export const name = 'acp-demo'

 /**
 * App config: the swappable per-deployment values. `model` configures the
@@ -27,7 +27,7 @@ export const name = 'acp-agent'
 * deployment persona (forwarded to the system-prompt plugin); `toolOrder` is
 * the explicit model-facing tool order (forwarded to the system-prompt plugin);
 * `tools` is the tool registry's config (its presentation `mode`, forwarded
- * through agent-core); `persistenceRoot` is the JSONL backend's directory.
+ * through agent-spine-demo); `persistenceRoot` is the JSONL backend's directory.
 */
 export interface Config {
  /** Model name for ACP-created agents (must have a registered adapter). */
@@ -36,13 +36,13 @@ export interface Config {
  persona?: string
  /** Explicit model-facing tool order (the system-prompt plugin's `toolOrder` config; see dsh-system-prompt). */
  toolOrder?: string[]
-  /** Tool-registry config — its presentation `mode` (forwarded through agent-core; see dsh-tools). */
+  /** Tool-registry config — its presentation `mode` (forwarded through agent-spine-demo; see dsh-tools). */
  tools?: ToolsConfig
  /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
  persistenceRoot?: string
  /** Controls automatic AGENTS.md/CLAUDE.md loading; configure a byte budget or set `false`. */
  workspaceContext: agentCore.Config['workspaceContext']
-  /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-core. */
+  /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-spine-demo. */
  skills?: agentCore.SkillConfig
 }

@@ -66,7 +66,7 @@ export const Config: z<Config> = z.object({
 /* jscpd:ignore-end */

 /**
- * Compose the spine with the ACP front door. The agent-core bundle pre-creates
+ * Compose the spine with the ACP front door. The agent-spine-demo bundle pre-creates
 * NO agents (its `agents` list defaults to `[]`) and carries the deployment
 * `persona`; the JSONL backend persists under `persistenceRoot`; the ACP
 * bridge owns stdout for JSON-RPC and creates one agent per `session/new`
--- a/packages/examples/acp-demo/tests/acp-agent.spec.ts
+++ b/packages/examples/acp-demo/tests/acp-agent.spec.ts
@@ -10,8 +10,8 @@ import type { Message } from '@deepseek-ai/dsh-llm'
 import * as acpAgent from '../src/index.ts'

 /**
- * In-process unit coverage for the @deepseek-ai/dsh-acp-agent composition:
- * mounting it brings up the agent-core spine + JSONL persistence + the ACP
+ * In-process unit coverage for the @deepseek-ai/dsh-acp-demo composition:
+ * mounting it brings up the agent-spine-demo spine + JSONL persistence + the ACP
 * bridge in one `ctx.plugin`. Unlike the stdio app, this one loads NO
 * Loader-only plugin (no hmr), so it mounts in a plain Context.
 *
@@ -29,7 +29,7 @@ async function mount(config: acpAgent.Config): Promise<Context> {
 }

 async function isolatedSkillsConfig(catalogDescriptionMaxLength?: number): Promise<NonNullable<acpAgent.Config['skills']>> {
-  const home = await mkdtemp(join(tmpdir(), 'dsh-acp-agent-skills-'))
+  const home = await mkdtemp(join(tmpdir(), 'dsh-acp-demo-skills-'))
  return {
    local: { dshHome: join(home, '.dsh'), agentsHome: join(home, '.agents') },
    ...catalogDescriptionMaxLength !== undefined ? { tool: { catalogDescriptionMaxLength } } : {},
@@ -48,7 +48,7 @@ async function composePrefix(ctx: Context): Promise<Message[]> {
 async function withIsolatedSkillHomes<T>(run: () => Promise<T>): Promise<T> {
  const oldDshHome = process.env.DSH_HOME
  const oldAgentsHome = process.env.DSH_AGENTS_HOME
-  const home = await mkdtemp(join(tmpdir(), 'dsh-acp-agent-default-skills-'))
+  const home = await mkdtemp(join(tmpdir(), 'dsh-acp-demo-default-skills-'))
  process.env.DSH_HOME = join(home, '.dsh')
  process.env.DSH_AGENTS_HOME = join(home, '.agents')
  try {
@@ -67,9 +67,9 @@ async function withIsolatedSkillHomes<T>(run: () => Promise<T>): Promise<T> {
  }
 }

-describe('dsh-acp-agent composition', () => {
+describe('dsh-acp-demo composition', () => {
  it('brings up the spine + persistence + the ACP bridge', async () => {
-    const ctx = await mount({ model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-acp-agent-test', skills: await isolatedSkillsConfig(), workspaceContext: false })
+    const ctx = await mount({ model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-acp-demo-test', skills: await isolatedSkillsConfig(), workspaceContext: false })
    expect(ctx.get('agents')).toBeDefined()
    expect(ctx.get('sessions')).toBeDefined()
    expect(ctx.get('sessionPersistence')).toBeDefined()
@@ -98,7 +98,7 @@ describe('dsh-acp-agent composition', () => {
    const ctx = await mount({
      model: 'mock',
      persona: 'hi',
-      persistenceRoot: '/tmp/dsh-acp-agent-workspace-context',
+      persistenceRoot: '/tmp/dsh-acp-demo-workspace-context',
      workspaceContext: false,
    })
    expect(ctx.get('agents')).toBeDefined()
@@ -117,7 +117,7 @@ describe('dsh-acp-agent composition', () => {
    })
  })

-  it('forwards skill config into agent-core', async () => {
+  it('forwards skill config into agent-spine-demo', async () => {
    const ctx = await mount({ model: 'mock', persona: 'hi', skills: await isolatedSkillsConfig(6), workspaceContext: false })
    ctx.skills.register({ name: 'acp-skill', description: 'ACP skill', source: 'runtime', content: 'body' })
    expect(JSON.stringify(await composePrefix(ctx))).toContain('- `acp-skill`: ACP...')
@@ -125,15 +125,15 @@ describe('dsh-acp-agent composition', () => {
  })

  it('exposes its plugin shape', () => {
-    expect(acpAgent.name).toBe('acp-agent')
+    expect(acpAgent.name).toBe('acp-demo')
    expect(acpAgent.Config).toBeDefined()
  })

-  it('forwards toolOrder through agent-core to the system-prompt assembly', async () => {
+  it('forwards toolOrder through agent-spine-demo to the system-prompt assembly', async () => {
    const ctx = await mount({
      model: 'mock',
      toolOrder: ['zulu', TOOL_ORDER_REST],
-      persistenceRoot: '/tmp/dsh-acp-agent-test-tool-order',
+      persistenceRoot: '/tmp/dsh-acp-demo-test-tool-order',
      workspaceContext: false,
    })
    // The bundle's own bash tools pend on the absent `ctx.bash` executor in
@@ -160,7 +160,7 @@ describe('dsh-acp-agent composition', () => {
    const loader = Object.create(Loader.prototype) as Loader
    const unwrapped = loader.unwrapExports(acpAgent) as Record<string, unknown>
    expect(unwrapped).toBe(acpAgent)
-    expect(unwrapped.name).toBe('acp-agent')
+    expect(unwrapped.name).toBe('acp-demo')
    expect(unwrapped.Config).toBeDefined()
    expect(typeof unwrapped.apply).toBe('function')
  })
--- a/packages/examples/acp-demo/tests/built-bin.e2e.ts
+++ b/packages/examples/acp-demo/tests/built-bin.e2e.ts
@@ -25,14 +25,14 @@ import { afterEach, describe, expect, it } from 'vitest'
 */

 const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
-const acpBin = join(repoRoot, 'packages/ui/acp-agent/lib/bin.js')
+const acpBin = join(repoRoot, 'packages/examples/acp-demo/lib/bin.js')

 const dshPackages = [
-  'core/agent-core', 'core/agent', 'core/session', 'core/system-prompt',
+  'examples/agent-spine-demo', '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', 'prompt/workspace-context', 'support/invariants', 'ui/app-boot',
  'session-persistence/session-persistence',
-  'session-persistence/session-persistence-jsonl', 'ui/acp', 'ui/acp-agent', 'util/paths',
+  'session-persistence/session-persistence-jsonl', 'ui/acp', 'examples/acp-demo', 'util/paths',
 ]
 const vendorPackages = [
  'cordis', 'loader', 'include', 'timer', 'hmr', 'logger-console',
@@ -82,7 +82,7 @@ async function makeConsumer(): Promise<string> {
    '- id: bash',
    '  name: \'@deepseek-ai/dsh-bash-local\'',
    '- id: acp-agent',
-    '  name: \'@deepseek-ai/dsh-acp-agent\'',
+    '  name: \'@deepseek-ai/dsh-acp-demo\'',
    '  config:',
    '    model: deepseek-v4-flash',
    '    persona: \'test agent\'',
@@ -101,7 +101,7 @@ afterEach(async () => {
  consumer = undefined
 })

-describe.skipIf(!existsSync(acpBin))('dsh-acp-agent BUILT bin (node lib/bin.js, no tsx)', () => {
+describe.skipIf(!existsSync(acpBin))('dsh-acp-demo BUILT bin (node lib/bin.js, no tsx)', () => {
  it('boots the published bin and answers an initialize JSON-RPC frame on stdout', async () => {
    consumer = await makeConsumer()
    child = spawn(process.execPath, ['--expose-internals', acpBin, '--config', './cordis.yml'], {
--- a/packages/examples/acp-demo/tests/load-path.e2e.ts
+++ b/packages/examples/acp-demo/tests/load-path.e2e.ts
@@ -26,7 +26,7 @@ import {

 const binScript = fileURLToPath(new URL('../src/bin.ts', import.meta.url))
 const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
-// Repo root is four levels up from packages/ui/acp-agent/tests.
+// Repo root is four levels up from packages/examples/acp-demo/tests.
 const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))

 // A minimal leaf that loads this app + the two backends — the same shape as
@@ -40,7 +40,7 @@ const CORDIS_YML = `
 - id: bash
  name: '@deepseek-ai/dsh-bash-local'
 - id: acp-agent
-  name: '@deepseek-ai/dsh-acp-agent'
+  name: '@deepseek-ai/dsh-acp-demo'
  config:
    model: deepseek-v4-flash
    persona: 'You are a test agent.'
@@ -106,7 +106,7 @@ async function boot(): Promise<Spawned & { cwd: string }> {
  return { ...spawned, cwd }
 }

-describe('dsh-acp-agent real-load-path smoke (bin + Loader, keyless)', () => {
+describe('dsh-acp-demo real-load-path smoke (bin + Loader, keyless)', () => {
  it('boots via its bin and answers initialize → session/new → session/load', async () => {
    const { client, cwd, stderr } = await boot()
    // initialize: a broken export shape (collapsed bridge plugin, dropped inject)
--- a/packages/examples/acp-demo/tsconfig.json
+++ b/packages/examples/acp-demo/tsconfig.json
@@ -18,25 +18,25 @@
      "path": "../../../vendor/loader"
    },
    {
-      "path": "../app-boot"
+      "path": "../../ui/app-boot"
    },
    {
-      "path": "../acp"
+      "path": "../../ui/acp"
    },
    {
      "path": "../../core/agent"
    },
    {
-      "path": "../../core/agent-core"
+      "path": "../agent-spine-demo"
    },
    {
      "path": "../../prompt/workspace-context"
    },
    {
-      "path": "../user-interaction"
+      "path": "../../ui/user-interaction"
    },
    {
-      "path": "../tool-ask-user"
+      "path": "../../ui/tool-ask-user"
    },
    {
      "path": "../../session-persistence/session-persistence-jsonl"
--- a/packages/examples/acp-demo/tsdown.config.ts
+++ b/packages/examples/acp-demo/tsdown.config.ts
--- a/packages/examples/agent-spine-demo/README.md
+++ b/packages/examples/agent-spine-demo/README.md
@@ -1,4 +1,4 @@
-# @deepseek-ai/dsh-agent-core
+# @deepseek-ai/dsh-agent-spine-demo

 The **default executor-less, UI-less agent spine** as ONE Cordis bundle plugin. It loads the fixed set of services every harness agent needs, including the local skill provider, and forwards the loop's `agents` list as its own config — so an app package composes a working agent by adding only a front door and the swappable backends.

@@ -32,14 +32,14 @@ The spine is everything COMMON to every front door. The swappable and front-door
 - **the LLM adapter** — the bundle ships the abstract `llm` service; the leaf registers a concrete adapter on `ctx.llm` (`llm-deepseek`, `llm-pi-ai`, `llm-replay`).
 - **the bash executor** — the bundle ships `tool-bash` (the consumer schema); the leaf provides `ctx.bash` (`bash-local` or a sandboxed impl).
 - **non-local skill providers** — the bundle ships the skill registry, the local filesystem provider, and the `skill` tool; deployments can add other providers such as embedded or remote catalogs as siblings.
- **presentation + per-app infra** — the stdio UI / ACP bridge, a console logger, `hmr`. These form the coupled "front-door cluster" that the app packages ([`dsh-stdio-agent`](../../ui/stdio-agent/README.md), [`dsh-acp-agent`](../../ui/acp-agent/README.md)) bake in. `timer` is in the spine (common to both, stdout-silent); a console logger is NOT (it writes to stdout, which the ACP bridge reserves for JSON-RPC).
+- **presentation + per-app infra** — the stdio UI / ACP bridge, a console logger, `hmr`. These form the coupled "front-door cluster" that the app packages ([`dsh-stdio-demo`](../../examples/stdio-demo/README.md), [`dsh-acp-demo`](../../examples/acp-demo/README.md)) bake in. `timer` is in the spine (common to both, stdout-silent); a console logger is NOT (it writes to stdout, which the ACP bridge reserves for JSON-RPC).

 This is the [interface/implementation/consumer seam](../../../docs/rfc/implemented/architecture/2026-06-13-capability-seams.md) raised to the composition level: the bundle owns the shared spine, the leaf owns the backends, the app package owns the front door.

 ## Config

 ```ts
-import type { Config } from '@deepseek-ai/dsh-agent-core'
+import type { Config } from '@deepseek-ai/dsh-agent-spine-demo'
 // { agents?, persona?, toolOrder?, tools?, skills?, workspaceContext } — workspaceContext requires { maxBytes } or false;
 // so validation and defaulting can never drift from the owners.
 ```
--- a/packages/examples/agent-spine-demo/package.json
+++ b/packages/examples/agent-spine-demo/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "@deepseek-ai/dsh-agent-core",
+  "name": "@deepseek-ai/dsh-agent-spine-demo",
  "description": "The default executor-less/UI-less agent spine as one Cordis bundle plugin (timer + llm + sessions + system-prompt + tools + skills + agents + invariants + tool-bash + tool-skill + workspace-context + agent-loop)",
  "version": "0.0.1",
  "private": true,
--- a/packages/examples/agent-spine-demo/src/index.ts
+++ b/packages/examples/agent-spine-demo/src/index.ts
@@ -5,7 +5,7 @@
 * deployments still choose the LLM adapter, bash executor, and presentation.
 * The plugin intentionally exposes named exports only because Loader default
 * unwrapping would discard its `Config` schema (see docs/postmortem/0001).
- * @module @deepseek-ai/dsh-agent-core
+ * @module @deepseek-ai/dsh-agent-spine-demo
 */

 import type { Context } from 'cordis'
@@ -24,7 +24,7 @@ import * as workspaceContext from '@deepseek-ai/dsh-workspace-context'
 import * as toolSkill from '@deepseek-ai/dsh-tool-skill'
 import AgentLoop, { type Config as AgentLoopConfig } from '@deepseek-ai/dsh-agent-loop'

-export const name = 'agent-core'
+export const name = 'agent-spine-demo'

 /** Skill bundle config forwarded to the registry, local provider, and model-facing consumer. */
 export interface SkillConfig {
--- a/packages/examples/agent-spine-demo/tests/agent-core.spec.ts
+++ b/packages/examples/agent-spine-demo/tests/agent-core.spec.ts
@@ -9,7 +9,7 @@ import * as agentCore from '../src/index.ts'
 import { AgentId, agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import LocalFileSystem from '@deepseek-ai/dsh-fs-local'
-import { MockAdapter, textResponse } from '../../agent-loop/tests/mock-adapter.ts'
+import { MockAdapter, textResponse } from '../../../core/agent-loop/tests/mock-adapter.ts'
 import type { Message } from '@deepseek-ai/dsh-llm'

 async function composePrefix(ctx: Context, cwd: string): Promise<Message[]> {
@@ -22,7 +22,7 @@ async function composePrefix(ctx: Context, cwd: string): Promise<Message[]> {
 }

 /**
- * Unit coverage for the @deepseek-ai/dsh-agent-core bundle: mounting it brings
+ * Unit coverage for the @deepseek-ai/dsh-agent-spine-demo bundle: mounting it brings
 * up the whole default spine in one `ctx.plugin`, and the forwarded
 * `agents` config reaches the loop (default `[]`, or a pre-created agent).
 *
@@ -34,8 +34,8 @@ async function composePrefix(ctx: Context, cwd: string): Promise<Message[]> {
 async function mount(config: agentCore.Config): Promise<Context> {
  const oldDshHome = process.env.DSH_HOME
  const oldAgentsHome = process.env.DSH_AGENTS_HOME
-  process.env.DSH_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-core-home-'))
-  process.env.DSH_AGENTS_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-core-agents-'))
+  process.env.DSH_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-home-'))
+  process.env.DSH_AGENTS_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-agents-'))
  const ctx = new Context()
  try {
    await ctx.plugin(agentCore, config)
@@ -60,8 +60,8 @@ async function mount(config: agentCore.Config): Promise<Context> {
 async function withIsolatedSkillHomes<T>(run: () => Promise<T>): Promise<T> {
  const oldDshHome = process.env.DSH_HOME
  const oldAgentsHome = process.env.DSH_AGENTS_HOME
-  process.env.DSH_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-core-home-'))
-  process.env.DSH_AGENTS_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-core-agents-'))
+  process.env.DSH_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-home-'))
+  process.env.DSH_AGENTS_HOME = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-agents-'))
  try {
    return await run()
  } finally {
@@ -93,7 +93,7 @@ function messageText(message: Message | undefined): string {
  return message?.content.map(block => block.type === 'text' ? block.text : '').join('\n') ?? ''
 }

-describe('dsh-agent-core bundle', () => {
+describe('dsh-agent-spine-demo bundle', () => {
  it('brings up the full default spine', async () => {
    const ctx = await mount({ workspaceContext: false })
    // One service from each layer of the spine proves the children loaded.
@@ -150,7 +150,7 @@ describe('dsh-agent-core bundle', () => {
  })

  it('loads workspace instructions into requests through the bundled spine', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'dsh-agent-core-workspace-context-'))
+    const root = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-workspace-context-'))
    try {
      await mkdir(join(root, '.git'), { recursive: true })
      await writeFile(join(root, 'AGENTS.md'), 'bundled project rule')
@@ -182,7 +182,7 @@ describe('dsh-agent-core bundle', () => {
  })

  it('forwards workspace-context config to the bundled loader', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'dsh-agent-core-workspace-context-disabled-'))
+    const root = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-workspace-context-disabled-'))
    try {
      await mkdir(join(root, '.git'), { recursive: true })
      await writeFile(join(root, 'AGENTS.md'), 'must not be injected')
@@ -208,9 +208,9 @@ describe('dsh-agent-core bundle', () => {
  })

  it('forwards skill config to the registry, local provider, and model-facing consumer', async () => {
-    const home = await mkdtemp(join(tmpdir(), 'dsh-agent-core-skill-home-'))
-    const agentsHome = await mkdtemp(join(tmpdir(), 'dsh-agent-core-skill-agents-'))
-    const custom = await mkdtemp(join(tmpdir(), 'dsh-agent-core-skill-custom-'))
+    const home = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-skill-home-'))
+    const agentsHome = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-skill-agents-'))
+    const custom = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-skill-custom-'))
    await mkdir(custom, { recursive: true })
    await writeFile(join(custom, 'custom-skill.md'), '---\nname: custom-skill\ndescription: Custom skill\n---\n\nCustom body.\n')
    const ctx = await mount({
@@ -232,7 +232,7 @@ describe('dsh-agent-core bundle', () => {
  })

  it('places workspace instructions before the skill catalog in the session prefix', async () => {
-    const root = await mkdtemp(join(tmpdir(), 'dsh-agent-core-prefix-order-'))
+    const root = await mkdtemp(join(tmpdir(), 'dsh-agent-spine-demo-prefix-order-'))
    try {
      await mkdir(join(root, '.git'), { recursive: true })
      await writeFile(join(root, 'AGENTS.md'), 'workspace rule before skills')
@@ -305,7 +305,7 @@ describe('dsh-agent-core bundle', () => {

  it('re-exports the loop config schema as its own', () => {
    expect(agentCore.Config).toBeDefined()
-    expect(agentCore.name).toBe('agent-core')
+    expect(agentCore.name).toBe('agent-spine-demo')
  })

  it('has the namespace-plugin export shape (no stray default) so the Loader keeps name/Config/apply', () => {
@@ -317,7 +317,7 @@ describe('dsh-agent-core bundle', () => {
    const loader = Object.create(Loader.prototype) as Loader
    const unwrapped = loader.unwrapExports(agentCore) as Record<string, unknown>
    expect(unwrapped).toBe(agentCore)
-    expect(unwrapped.name).toBe('agent-core')
+    expect(unwrapped.name).toBe('agent-spine-demo')
    expect(unwrapped.Config).toBeDefined()
    expect(typeof unwrapped.apply).toBe('function')
  })
--- a/packages/examples/agent-spine-demo/tests/gen-config-catalog.spec.ts
+++ b/packages/examples/agent-spine-demo/tests/gen-config-catalog.spec.ts
--- a/packages/examples/agent-spine-demo/tsconfig.json
+++ b/packages/examples/agent-spine-demo/tsconfig.json
--- a/packages/examples/jsonrpc-demo/README.md
+++ b/packages/examples/jsonrpc-demo/README.md
@@ -1,10 +1,10 @@
-# @deepseek-ai/dsh-jsonrpc-agent
+# @deepseek-ai/dsh-jsonrpc-demo

-Bin-only app that boots an external `cordis.yml`; its [`jsonrpc`](../jsonrpc/README.md) entry serves SDK clients over newline-delimited stdio. The config composes the spine, backends, and serving plugin. `lib/bin.js` is also the [single-executable runtime](../../../docs/rfc/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md) entry.
+Bin-only app that boots an external `cordis.yml`; its [`jsonrpc`](../../ui/jsonrpc/README.md) entry serves SDK clients over newline-delimited stdio. The config composes the spine, backends, and serving plugin. `lib/bin.js` is also the [single-executable runtime](../../../docs/rfc/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md) entry.

 ## Config discovery

-The first non-empty channel wins: `$DSH_CORDIS_CONFIG`, then positional `argv[2]`. If neither names an existing file, the bin prints one-line usage to stderr and exits 1; there is no working-directory or built-in fallback. [`dsh-app-boot`](../app-boot/README.md) makes plugin load failures fatal. This protocol does not use `DSH_SNAPSHOT`.
+The first non-empty channel wins: `$DSH_CORDIS_CONFIG`, then positional `argv[2]`. If neither names an existing file, the bin prints one-line usage to stderr and exits 1; there is no working-directory or built-in fallback. [`dsh-app-boot`](../../ui/app-boot/README.md) makes plugin load failures fatal. This protocol does not use `DSH_SNAPSHOT`.

 A config without `dsh-jsonrpc` is valid and serves nothing; the bin does not designate a server plugin.

--- a/packages/examples/jsonrpc-demo/package.json
+++ b/packages/examples/jsonrpc-demo/package.json
@@ -1,5 +1,5 @@
 {
-  "name": "@deepseek-ai/dsh-jsonrpc-agent",
+  "name": "@deepseek-ai/dsh-jsonrpc-demo",
  "description": "Bin that boots an external Cordis config for the stdio JSON-RPC SDK runtime",
  "version": "0.0.1",
  "private": true,
--- a/packages/examples/jsonrpc-demo/src/bin.ts
+++ b/packages/examples/jsonrpc-demo/src/bin.ts
@@ -7,7 +7,7 @@
 * stdin EOF and SIGTERM dispose the root context and exit 0; SIGINT exits 130.
 * Protocol `shutdown` belongs to the server plugin. Stdout is reserved for frames.
 *
- * @module @deepseek-ai/dsh-jsonrpc-agent/bin
+ * @module @deepseek-ai/dsh-jsonrpc-demo/bin
 */

 import { existsSync } from 'node:fs'
--- a/packages/examples/jsonrpc-demo/src/index.ts
+++ b/packages/examples/jsonrpc-demo/src/index.ts
@@ -3,7 +3,7 @@
 * process exit. This module exports no composition plugin; the config chooses
 * whether to load the {@link @deepseek-ai/dsh-jsonrpc} serving plugin.
 *
- * @module @deepseek-ai/dsh-jsonrpc-agent
+ * @module @deepseek-ai/dsh-jsonrpc-demo
 */

 export {}
--- a/packages/examples/jsonrpc-demo/tsconfig.json
+++ b/packages/examples/jsonrpc-demo/tsconfig.json
@@ -15,7 +15,7 @@
      "path": "../../../vendor/loader"
    },
    {
-      "path": "../app-boot"
+      "path": "../../ui/app-boot"
    }
  ]
 }
--- a/packages/examples/jsonrpc-demo/tsdown.config.ts
+++ b/packages/examples/jsonrpc-demo/tsdown.config.ts
--- a/packages/examples/stdio-demo/README.md
+++ b/packages/examples/stdio-demo/README.md
@@ -1,8 +1,8 @@
-# @deepseek-ai/dsh-stdio-agent
+# @deepseek-ai/dsh-stdio-demo

-The **terminal stdio chat app**: a Cordis app plugin that composes the default agent spine ([`@deepseek-ai/dsh-agent-core`](../../core/agent-core/README.md)) with the front-door cluster a terminal chat needs, and a `bin` that boots a leaf `cordis.yml`.
+The **terminal stdio chat app**: a Cordis app plugin that composes the default agent spine ([`@deepseek-ai/dsh-agent-spine-demo`](../../examples/agent-spine-demo/README.md)) with the front-door cluster a terminal chat needs, and a `bin` that boots a leaf `cordis.yml`.

-It is the readline counterpart to [`@deepseek-ai/dsh-acp-agent`](../acp-agent/README.md): both consume the same spine, but each bakes in the OPPOSITE front-door cluster.
+It is the readline counterpart to [`@deepseek-ai/dsh-acp-demo`](../acp-demo/README.md): both consume the same spine, but each bakes in the OPPOSITE front-door cluster.

 ## What it bakes in

@@ -11,7 +11,7 @@ A terminal chat always wants the same cluster, so the package owns it rather tha
 | Plugin | Why it is here |
 |---|---|
 | `@cordisjs/plugin-logger-console` | the console logger — stdout is just the terminal here, so logging to it is correct (the ACP app must NOT have this) |
-| `@deepseek-ai/dsh-agent-core` | the spine, pre-creating a `main` agent from this app's `model` with `process.cwd()` as the fresh session cwd and carrying its `persona` |
+| `@deepseek-ai/dsh-agent-spine-demo` | the spine, pre-creating a `main` agent from this app's `model` with `process.cwd()` as the fresh session cwd and carrying its `persona` |
 | `@deepseek-ai/dsh-session-persistence-jsonl` | durable JSONL session log under `persistenceRoot` |
 | `@deepseek-ai/dsh-user-interaction` | the human question/answer seam used by confirmation tools |
 | `@deepseek-ai/dsh-tool-ask-user` | the model-facing `ask_user_question` tool |
@@ -19,7 +19,7 @@ A terminal chat always wants the same cluster, so the package owns it rather tha

 `@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`.

-The leaf `cordis.yml` supplies only the **swappable backends** — an LLM adapter (`llm-deepseek` for the real model, or the mock `mock-llm` for a demo) and a bash executor (`bash-local`) — `hmr`, plus this app's [`Config`](#config). The whole plugin tree a run loads is therefore: this app's cluster, the spine inside `agent-core`, `hmr`, and the two leaf backends.
+The leaf `cordis.yml` supplies only the **swappable backends** — an LLM adapter (`llm-deepseek` for the real model, or the mock `mock-llm` for a demo) and a bash executor (`bash-local`) — `hmr`, plus this app's [`Config`](#config). The whole plugin tree a run loads is therefore: this app's cluster, the spine inside `agent-spine-demo`, `hmr`, and the two leaf backends.

 ## Config

@@ -28,17 +28,17 @@ The leaf `cordis.yml` supplies only the **swappable backends** — an LLM adapte
 | `model` | (required) | the pre-created `main` agent's model |
 | `persona` | — | the deployment persona template (may reference `{{model}}`/`{{cwd}}`), routed to `dsh-system-prompt` |
 | `toolOrder` | — | explicit model-facing tool order (a name list with one `'<unlisted-tools>'` rest entry; absent — lexicographic; an unregistered name fails each turn at prompt assembly), routed to `dsh-system-prompt` |
-| `tools` | `{ mode: 'native' }` | tool-registry presentation config (`native` / `code` / `both`), routed through `dsh-agent-core` |
-| `skills` | owner defaults | registry-cache, local-provider, and model-facing skill-tool config, routed through `dsh-agent-core` |
+| `tools` | `{ mode: 'native' }` | tool-registry presentation config (`native` / `code` / `both`), routed through `dsh-agent-spine-demo` |
+| `skills` | owner defaults | registry-cache, local-provider, and model-facing skill-tool config, routed through `dsh-agent-spine-demo` |
 | `persistenceRoot` | `./.sessions` | the JSONL backend's root directory |
 | `welcome` | `ready.` | the stdin-chat banner |
 | `resumeSessionId` | — | resume a persisted session id instead of starting fresh (sourced from an env var in the leaf) |

-Fresh stdio sessions use the process launch directory as `session.header.cwd`, so project-scoped features such as skill discovery and default bash workdir follow the directory where `dsh-stdio-agent` was started. Resumed sessions keep the cwd stored in the persisted session header.
+Fresh stdio sessions use the process launch directory as `session.header.cwd`, so project-scoped features such as skill discovery and default bash workdir follow the directory where `dsh-stdio-demo` was started. Resumed sessions keep the cwd stored in the persisted session header.

 ## The bin

-`dsh-stdio-agent [path-to-cordis.yml]` (default `./cordis.yml`) loads a gitignored `.env` from the cwd (`DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL`), then drives the cordis Loader against the config and awaits the whole plugin tree before returning. Run it under `node --expose-internals`, or install the Loader's optional `node-addon-require-builtin` fallback, so the Loader can resolve the config's bare plugin specifiers (`@deepseek-ai/dsh-*`, npm packages). The `demo:echo` / `demo:repl` scripts use `--expose-internals`.
+`dsh-stdio-demo [path-to-cordis.yml]` (default `./cordis.yml`) loads a gitignored `.env` from the cwd (`DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL`), then drives the cordis Loader against the config and awaits the whole plugin tree before returning. Run it under `node --expose-internals`, or install the Loader's optional `node-addon-require-builtin` fallback, so the Loader can resolve the config's bare plugin specifiers (`@deepseek-ai/dsh-*`, npm packages). The `demo:echo` / `demo:repl` scripts use `--expose-internals`.

 ## Example leaf `cordis.yml`

@@ -58,7 +58,7 @@ Fresh stdio sessions use the process launch directory as `session.header.cwd`, s
  config:
    timeoutMs: 60000
 - id: stdio-agent
-  name: '@deepseek-ai/dsh-stdio-agent'
+  name: '@deepseek-ai/dsh-stdio-demo'
  config:
    model: deepseek-v4-flash
    persona: 'You are a coding assistant powered by the {{model}} model.'
@@ -70,7 +70,7 @@ Swap `llm-deepseek` for a `mock-llm` leaf plugin and you have the echo demo —

 ### Composed terminal agent request

-**What the model sees**: Through `dsh-agent-core`, the `main` agent receives the harness identity, configured persona, skill catalog, and visible tools; this app also composes the generated [`ask_user_question` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-ask-user). Each readline submission becomes a user message.
+**What the model sees**: Through `dsh-agent-spine-demo`, the `main` agent receives the harness identity, configured persona, skill catalog, and visible tools; this app also composes the generated [`ask_user_question` schema](../../../docs/tool-catalog.md#deepseek-aidsh-tool-ask-user). Each readline submission becomes a user message.

 **Token effect**: Child prompt and schema costs repeat per request; user input and tool history grow until compaction. The welcome banner, logger output, and rendered transcript are terminal-only and add zero model tokens.

--- a/packages/examples/stdio-demo/package.json
+++ b/packages/examples/stdio-demo/package.json
@@ -1,13 +1,13 @@
 {
-  "name": "@deepseek-ai/dsh-stdio-agent",
-  "description": "Terminal stdio chat app: the agent-core spine + console logger + readline UI + a pre-created main agent, with a bin to boot a leaf cordis.yml",
+  "name": "@deepseek-ai/dsh-stdio-demo",
+  "description": "Terminal stdio chat app: the agent-spine-demo bundle + console logger + readline UI + a pre-created main agent, with a bin to boot a leaf cordis.yml",
  "version": "0.0.1",
  "private": true,
  "type": "module",
  "main": "lib/index.js",
  "types": "lib/types/index.d.ts",
  "bin": {
-    "dsh-stdio-agent": "lib/bin.js"
+    "dsh-stdio-demo": "lib/bin.js"
  },
  "exports": {
    ".": {
@@ -36,7 +36,7 @@
    "@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-agent-spine-demo": "^0.0.1",
    "@deepseek-ai/dsh-workspace-context": "^0.0.1",
    "@deepseek-ai/dsh-session": "^0.0.1",
    "@deepseek-ai/dsh-session-persistence-jsonl": "^0.0.1",
@@ -54,7 +54,7 @@
    "@cordisjs/plugin-logger-console": "workspace:^",
    "@deepseek-ai/dsh-agent": "workspace:^",
    "@deepseek-ai/dsh-llm": "workspace:^",
-    "@deepseek-ai/dsh-agent-core": "workspace:^",
+    "@deepseek-ai/dsh-agent-spine-demo": "workspace:^",
    "@deepseek-ai/dsh-system-prompt": "workspace:^",
    "@deepseek-ai/dsh-workspace-context": "workspace:^",
    "@deepseek-ai/dsh-session": "workspace:^",
--- a/packages/examples/stdio-demo/src/bin.ts
+++ b/packages/examples/stdio-demo/src/bin.ts
@@ -1,14 +1,14 @@
 #!/usr/bin/env node
 /**
- * Boot a stdio app from a leaf `cordis.yml`; usage is `dsh-stdio-agent [config]`, defaulting to the
+ * Boot a stdio app from a leaf `cordis.yml`; usage is `dsh-stdio-demo [config]`, defaulting to the
 * cwd file. Shared `.env` loading, fail-loud Loader guards, and settled-tree boot live in
 * dsh-app-boot. The echo and REPL demos invoke this bin with their own leaf configs.
- * @module @deepseek-ai/dsh-stdio-agent/bin
+ * @module @deepseek-ai/dsh-stdio-demo/bin
 */

 import { boot, installFailLoud, loadEnv, resolveConfigPath } from '@deepseek-ai/dsh-app-boot'

-const NAME = 'dsh-stdio-agent'
+const NAME = 'dsh-stdio-demo'

 /* 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
--- a/packages/examples/stdio-demo/src/index.ts
+++ b/packages/examples/stdio-demo/src/index.ts
@@ -1,12 +1,12 @@
 /**
- * The stdio chat app: the default agent spine ({@link @deepseek-ai/dsh-agent-core}) plus the
+ * The stdio chat app: the default agent spine ({@link @deepseek-ai/dsh-agent-spine-demo}) plus the
 * coupled front-door cluster a terminal chat needs — a console logger, the independently
 * packaged readline UI, JSONL session persistence, the user-interaction seam with its
 * `ask_user_question` tool, and a pre-created `main` agent the UI drives.
 * Swappable adapters, executors, optional tools, and HMR stay in the leaf. This
 * Loader plugin intentionally exposes named exports only; a default export
 * would hide its `Config` schema (see docs/postmortem/0001).
- * @module @deepseek-ai/dsh-stdio-agent
+ * @module @deepseek-ai/dsh-stdio-demo
 */

 import type { Context } from 'cordis'
@@ -15,19 +15,19 @@ import z from 'schemastery'
 import { AgentId } from '@deepseek-ai/dsh-agent'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import ToolRegistry, { type Config as ToolsConfig } from '@deepseek-ai/dsh-tools'
-import * as agentCore from '@deepseek-ai/dsh-agent-core'
+import * as agentCore from '@deepseek-ai/dsh-agent-spine-demo'
 import * as workspaceContext from '@deepseek-ai/dsh-workspace-context'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
 import UserInteractionService from '@deepseek-ai/dsh-user-interaction'
 import * as toolAskUser from '@deepseek-ai/dsh-tool-ask-user'
 import * as uiStdio from '@deepseek-ai/dsh-stdio'

-export const name = 'stdio-agent'
+export const name = 'stdio-demo'

 /**
 * App config: the swappable per-demo values, each routed to where the app wires
 * it. `model`/`resumeSessionId` configure the pre-created `main` agent (through
- * {@link @deepseek-ai/dsh-agent-core}'s forwarded `agents` list); `persona` is
+ * {@link @deepseek-ai/dsh-agent-spine-demo}'s forwarded `agents` list); `persona` is
 * the deployment persona (forwarded to the system-prompt plugin); `toolOrder`
 * is the explicit model-facing tool order (forwarded to the system-prompt plugin);
 * fresh sessions use `process.cwd()` as their workspace cwd; resumed sessions
@@ -41,13 +41,13 @@ export interface Config {
  persona?: string
  /** Explicit model-facing tool order (the system-prompt plugin's `toolOrder` config; see dsh-system-prompt). */
  toolOrder?: string[]
-  /** Tool-registry config — its presentation `mode` (forwarded through agent-core; see dsh-tools). */
+  /** Tool-registry config — its presentation `mode` (forwarded through agent-spine-demo; see dsh-tools). */
  tools?: ToolsConfig
  /** Directory the JSONL session backend writes under. Defaults to `./.sessions`. */
  persistenceRoot?: string
  /** stdin-chat banner printed once on start. Defaults to `'ready.'`. */
  welcome?: string
-  /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-core. */
+  /** Skill registry, local-provider, and model-facing consumer config forwarded to agent-spine-demo. */
  skills?: agentCore.SkillConfig
  /**
   * If set, the `main` agent RESUMES this persisted session id instead of
@@ -78,7 +78,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
+ * (infra), then the agent-spine-demo bundle pre-creating the `main` agent from this
 * app's `model`/`resumeSessionId` with the deployment `persona`, then the JSONL
 * backend, then 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.
--- a/packages/examples/stdio-demo/tests/built-bin.e2e.ts
+++ b/packages/examples/stdio-demo/tests/built-bin.e2e.ts
@@ -14,16 +14,16 @@ import { afterEach, describe, expect, it } from 'vitest'
 */

 const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
-const stdioBin = join(repoRoot, 'packages/ui/stdio-agent/lib/bin.js')
+const stdioBin = join(repoRoot, 'packages/examples/stdio-demo/lib/bin.js')

 // Symlink each required workspace package by package name so plain Node resolves its built `main`,
 // matching an installed dependency rather than tsconfig paths.
 const dshPackages = [
-  'core/agent-core', 'core/agent', 'core/session', 'core/system-prompt',
+  'examples/agent-spine-demo', 'core/agent', 'core/session', 'core/system-prompt',
  'core/tools', 'core/agent-loop', 'llm/llm', 'bash/bash', 'bash/bash-local',
  'bash/tool-bash', 'prompt/workspace-context', 'support/invariants', 'ui/app-boot',
  'session-persistence/session-persistence',
-  'session-persistence/session-persistence-jsonl', 'ui/stdio-agent', 'util/paths',
+  'session-persistence/session-persistence-jsonl', 'examples/stdio-demo', 'util/paths',
  'ui/stdio', 'ui/tool-ask-user', 'ui/user-interaction',
 ]
 const vendorPackages = [
@@ -71,7 +71,7 @@ async function makeConsumer(welcome: string, disabledBrokenEntry = false): Promi
    '- id: bash',
    '  name: \'@deepseek-ai/dsh-bash-local\'',
    '- id: stdio-agent',
-    '  name: \'@deepseek-ai/dsh-stdio-agent\'',
+    '  name: \'@deepseek-ai/dsh-stdio-demo\'',
    '  config:',
    '    model: mock-echo',
    '    persona: \'demo\'',
@@ -121,7 +121,7 @@ afterEach(async () => {
  consumer = undefined
 })

-describe.skipIf(!existsSync(stdioBin))('dsh-stdio-agent BUILT bin (node lib/bin.js, no tsx)', () => {
+describe.skipIf(!existsSync(stdioBin))('dsh-stdio-demo BUILT bin (node lib/bin.js, no tsx)', () => {
  it('boots the published bin, prints its banner, and runs the echo tool round-trip', async () => {
    consumer = await makeConsumer('BUILT-BIN-OK ready.')
    const { stdout, code, stderr } = await runBuiltBin(consumer, './cordis.yml', 'echo hi')
--- a/packages/examples/stdio-demo/tests/stdio-agent.spec.ts
+++ b/packages/examples/stdio-demo/tests/stdio-agent.spec.ts
@@ -11,7 +11,7 @@ import * as stdioAgent from '../src/index.ts'

 /**
 * Unit coverage for app composition and config forwarding: console logger, pre-created main agent,
- * agent-core spine, JSONL backend, and readline UI. HMR is a Loader-only leaf concern covered by the
+ * agent-spine-demo spine, JSONL backend, and readline UI. HMR is a Loader-only leaf concern covered by the
 * keyless echo smoke; this tier pins the export shape because an inject-less app could otherwise
 * survive namespace collapse while silently losing its schema.
 */
@@ -25,7 +25,7 @@ async function mount(config: stdioAgent.Config): Promise<Context> {
 }

 async function isolatedSkillsConfig(catalogDescriptionMaxLength?: number): Promise<NonNullable<stdioAgent.Config['skills']>> {
-  const home = await mkdtemp(join(tmpdir(), 'dsh-stdio-agent-skills-'))
+  const home = await mkdtemp(join(tmpdir(), 'dsh-stdio-demo-skills-'))
  return {
    local: { dshHome: join(home, '.dsh'), agentsHome: join(home, '.agents') },
    ...catalogDescriptionMaxLength !== undefined ? { tool: { catalogDescriptionMaxLength } } : {},
@@ -44,7 +44,7 @@ async function composePrefix(ctx: Context): Promise<Message[]> {
 async function withIsolatedSkillHomes<T>(run: () => Promise<T>): Promise<T> {
  const oldDshHome = process.env.DSH_HOME
  const oldAgentsHome = process.env.DSH_AGENTS_HOME
-  const home = await mkdtemp(join(tmpdir(), 'dsh-stdio-agent-default-skills-'))
+  const home = await mkdtemp(join(tmpdir(), 'dsh-stdio-demo-default-skills-'))
  process.env.DSH_HOME = join(home, '.dsh')
  process.env.DSH_AGENTS_HOME = join(home, '.agents')
  try {
@@ -63,10 +63,10 @@ async function withIsolatedSkillHomes<T>(run: () => Promise<T>): Promise<T> {
  }
 }

-describe('dsh-stdio-agent app', () => {
+describe('dsh-stdio-demo app', () => {
  it('composes the spine + front-door cluster and pre-creates the main agent', async () => {
-    const ctx = await mount({ model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-stdio-agent-spec', skills: await isolatedSkillsConfig(), workspaceContext: false })
-    // The spine services (brought up by the agent-core bundle) are all present.
+    const ctx = await mount({ model: 'mock', persona: 'hi', persistenceRoot: '/tmp/dsh-stdio-demo-spec', skills: await isolatedSkillsConfig(), workspaceContext: false })
+    // The spine services (brought up by the agent-spine-demo bundle) are all present.
    expect(ctx.get('agents')).toBeDefined()
    expect(ctx.get('agentLoop')).toBeDefined()
    expect(ctx.get('sessionPersistence')).toBeDefined()
@@ -97,7 +97,7 @@ describe('dsh-stdio-agent app', () => {
    const ctx = await mount({
      model: 'mock',
      persona: 'hi',
-      persistenceRoot: '/tmp/dsh-stdio-agent-spec-workspace-context',
+      persistenceRoot: '/tmp/dsh-stdio-demo-spec-workspace-context',
      workspaceContext: false,
    })
    expect(ctx.get('agents')?.get(AgentId('main'))).toBeDefined()
@@ -122,7 +122,7 @@ describe('dsh-stdio-agent app', () => {
    const ctx = await mount({
      model: 'mock',
      persona: 'hi',
-      persistenceRoot: '/tmp/dsh-stdio-agent-spec-resume',
+      persistenceRoot: '/tmp/dsh-stdio-demo-spec-resume',
      resumeSessionId: 'no-such-session',
      skills: await isolatedSkillsConfig(),
      workspaceContext: false,
@@ -131,7 +131,7 @@ describe('dsh-stdio-agent app', () => {
    await ctx.fiber.dispose()
  })

-  it('forwards skill config into agent-core', async () => {
+  it('forwards skill config into agent-spine-demo', async () => {
    const ctx = await mount({ model: 'mock', persona: 'hi', skills: await isolatedSkillsConfig(6), workspaceContext: false })
    ctx.skills.register({ name: 'stdio-skill', description: 'Stdio skill', source: 'runtime', content: 'body' })
    expect(JSON.stringify(await composePrefix(ctx))).toContain('- `stdio-skill`: Std...')
@@ -139,15 +139,15 @@ describe('dsh-stdio-agent app', () => {
  })

  it('exposes its name and Config schema', () => {
-    expect(stdioAgent.name).toBe('stdio-agent')
+    expect(stdioAgent.name).toBe('stdio-demo')
    expect(stdioAgent.Config).toBeDefined()
  })

-  it('forwards toolOrder through agent-core to the system-prompt assembly', async () => {
+  it('forwards toolOrder through agent-spine-demo to the system-prompt assembly', async () => {
    const ctx = await mount({
      model: 'mock',
      toolOrder: ['zulu', TOOL_ORDER_REST],
-      persistenceRoot: '/tmp/dsh-stdio-agent-spec-tool-order',
+      persistenceRoot: '/tmp/dsh-stdio-demo-spec-tool-order',
      workspaceContext: false,
    })
    // The bundle's own bash tools pend on the absent `ctx.bash` executor in
@@ -174,7 +174,7 @@ describe('dsh-stdio-agent app', () => {
    const loader = Object.create(Loader.prototype) as Loader
    const unwrapped = loader.unwrapExports(stdioAgent) as Record<string, unknown>
    expect(unwrapped).toBe(stdioAgent)
-    expect(unwrapped.name).toBe('stdio-agent')
+    expect(unwrapped.name).toBe('stdio-demo')
    expect(unwrapped.Config).toBeDefined()
    expect(typeof unwrapped.apply).toBe('function')
  })
--- a/packages/examples/stdio-demo/tsconfig.json
+++ b/packages/examples/stdio-demo/tsconfig.json
@@ -18,7 +18,7 @@
      "path": "../../../vendor/loader"
    },
    {
-      "path": "../app-boot"
+      "path": "../../ui/app-boot"
    },
    {
      "path": "../../../vendor/logger-console"
@@ -30,19 +30,19 @@
      "path": "../../core/session"
    },
    {
-      "path": "../../core/agent-core"
+      "path": "../agent-spine-demo"
    },
    {
      "path": "../../prompt/workspace-context"
    },
    {
-      "path": "../user-interaction"
+      "path": "../../ui/user-interaction"
    },
    {
-      "path": "../stdio"
+      "path": "../../ui/stdio"
    },
    {
-      "path": "../tool-ask-user"
+      "path": "../../ui/tool-ask-user"
    },
    {
      "path": "../../session-persistence/session-persistence-jsonl"
--- a/packages/examples/stdio-demo/tsdown.config.ts
+++ b/packages/examples/stdio-demo/tsdown.config.ts
--- a/packages/mcp/README.md
+++ b/packages/mcp/README.md
@@ -0,0 +1,7 @@
+# MCP — Model Context Protocol
+
+Packages bridging the harness to the MCP ecosystem.
+
+| Package | Role |
+|---|---|
+| `mcp-client/` | MCP client bridge: connects to external MCP servers and registers their tools on `ctx.tools` |
--- a/packages/mcp/mcp-client/README.md
+++ b/packages/mcp/mcp-client/README.md
@@ -0,0 +1,88 @@
+# @deepseek-ai/dsh-mcp-client
+
+MCP client bridge plugin: connects to external [Model Context Protocol](https://modelcontextprotocol.io/) servers and registers their tools on `ctx.tools`, making them available to the model as native tools under server-qualified names (`mcp__<serverName>__<rawName>`).
+
+## Usage
+
+One plugin instance per MCP server in `cordis.yml`:
+
+```yaml
+- id: mcp-github
+  name: '@deepseek-ai/dsh-mcp-client'
+  config:
+    serverName: github
+    transport: stdio
+    command: npx
+    args: ['-y', '@modelcontextprotocol/server-github']
+    env:
+      GITHUB_TOKEN: !!js process.env.GITHUB_TOKEN
+
+- id: mcp-web
+  name: '@deepseek-ai/dsh-mcp-client'
+  config:
+    serverName: web
+    transport: streamable-http
+    url: http://localhost:3000/mcp
+    headers:
+      Authorization: !!js '`Bearer ${process.env.MCP_TOKEN}`'
+```
+
+The model sees `mcp__github__create_issue`, `mcp__web__search`, … — the same server-qualified shape Claude Code and Codex use. HMR hot-swaps: editing the entry triggers disconnect + reconnect without process restart; an unchanged `serverName` reproduces identical tool names.
+
+## Config
+
+| Field | Transport | Required | Description |
+|---|---|---|---|
+| `transport` | both | yes | `"stdio"` or `"streamable-http"` |
+| `serverName` | both | yes | Namespace for this server's model-facing tool names; `[A-Za-z0-9_-]{1,32}`, unique across live instances |
+| `command` | stdio | yes | Executable to spawn |
+| `args` | stdio | no | Arguments passed to the command |
+| `env` | stdio | no | Extra env vars merged on top of scrubbed ambient env |
+| `cwd` | stdio | no | Working directory for the child process |
+| `url` | http | yes | MCP server URL |
+| `headers` | http | no | Extra headers (e.g. auth tokens) |
+| `toolCallTimeoutMs` | both | no | Timeout per `callTool` invocation (default 60000) |
+
+## Tool naming
+
+Every MCP tool has two names: the raw MCP name (sent on the wire in `tools/call`) and the public name `mcp__<serverName>__<rawName>` registered on `ctx.tools`. Public names are normalized to the DeepSeek function-name contract (64 chars, `[A-Za-z0-9_-]`); when replacement or truncation changes the name, a deterministic 12-hex-char hash of `(serverName, rawName)` is appended so distinct tools never collapse into one name. Names are pure functions of `(serverName, rawName)` — connection order, re-syncs, and other servers never rename a tool.
+
+- Two servers publishing the same raw name (e.g. `search`) coexist under their namespaces.
+- A duplicate `serverName` across live instances fails the later plugin instance at load.
+- A server listing the same tool name twice is rejected as an invalid tool list.
+- A foreign registration squatting on this server's namespace rolls back the whole generation (never a partial set), with a loud error.
+
+## Behavior
+
+- On connect: `listTools()` → registers each tool via `ctx.tools.register()` under its public name.
+- Listens for `notifications/tools/list_changed` → re-syncs; a failed re-sync keeps the previous generation registered.
+- Tool execute: `client.callTool({ name: rawName, arguments }, { signal })` with timeout + abort support — the public name is never sent to the server.
+- Image content in results is discarded with a placeholder (the harness has no image block type).
+- On disconnect/crash: all tools are unregistered; no auto-reconnect.
+
+## Services consumed
+
+| Service | Usage |
+|---|---|
+| `ctx.tools` | Register/unregister MCP tools |
+
+## Model Experience
+
+### Discovered MCP tools
+
+**What the model sees**: After initial discovery succeeds, each advertised MCP tool appears as a native tool named `mcp__<serverName>__<rawName>` (or its deterministic normalized form), with the server-provided description and input schema. A successful re-sync replaces the generation; plugin disposal removes it.
+
+**Token effect**: Data-dependent schema cost is paid on every request while the tools are registered. Re-sync replaces rather than accumulates schemas, and the server-qualified name adds tokens to every tool definition and call.
+
+### Tool-call history and results
+
+**What the model sees**: The public tool name and JSON arguments remain in assistant history. Text result blocks are joined with newlines into one retained text result; image, audio, resource, and unsupported blocks become short placeholders, and MCP `isError` results follow the registry's model-visible error path.
+
+**Token effect**: Arguments and mapped text are retained until compaction. Binary and resource payloads are discarded rather than added to context.
+
+## Known Limitations and Deferred Work
+
+- **Initial discovery is asynchronous** — plugin load does not wait for connection and `listTools()`, so a turn started immediately after boot or HMR can assemble before the MCP tools are registered.
+- **Tools are the only bridged MCP capability** — Resources and Prompts have no harness consumption surface and are deferred.
+- **Crash recovery is manual** — transport closure unregisters the server's tools, but reconnect requires an HMR reload or harness restart.
+- **Non-text results are lossy** — image, audio, and resource payloads are replaced with placeholders, and a structured-only result has no model-visible structured representation.
--- a/packages/mcp/mcp-client/package.json
+++ b/packages/mcp/mcp-client/package.json
@@ -0,0 +1,41 @@
+{
+  "name": "@deepseek-ai/dsh-mcp-client",
+  "description": "MCP client bridge: connects to MCP servers and registers their tools on ctx.tools",
+  "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": {
+    "@deepseek-ai/dsh-tools": "^0.0.1",
+    "@deepseek-ai/dsh-llm": "^0.0.1",
+    "cordis": "^4.0.0-rc.7"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "schemastery": "^3.18.0"
+  },
+  "devDependencies": {
+    "@deepseek-ai/dsh-tools": "workspace:^",
+    "@deepseek-ai/dsh-llm": "workspace:^",
+    "@modelcontextprotocol/server-everything": "^2026.7.4",
+    "@modelcontextprotocol/server-filesystem": "^2026.7.4",
+    "cordis": "^4.0.0-rc.7",
+    "zod": "^4.4.3"
+  }
+}
--- a/packages/mcp/mcp-client/src/index.ts
+++ b/packages/mcp/mcp-client/src/index.ts
@@ -0,0 +1,177 @@
+/**
+ * MCP client bridge plugin: connects to an external MCP server and registers
+ * its tools on `ctx.tools` under server-qualified public names
+ * (`mcp__<serverName>__<rawName>`). Each plugin instance connects to one MCP
+ * server; load multiple instances in `cordis.yml` for multiple servers.
+ *
+ * Namespace plugin (named exports, no default export). Lifecycle is
+ * effect-scoped: disposal disconnects from the server, unregisters all tools,
+ * and releases the `serverName` namespace reservation. HMR hot-swaps by
+ * disposing the old instance and creating a new one; identical `serverName`
+ * reproduces identical public tool names.
+ *
+ * @module @deepseek-ai/dsh-mcp-client
+ */
+
+import type { Context } from 'cordis'
+import z from 'schemastery'
+import { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import { ToolListChangedNotificationSchema } from '@modelcontextprotocol/sdk/types.js'
+import { createTransport } from './transport.ts'
+import { syncTools } from './tools.ts'
+// Side-effect type import: declaration-merges `ctx.tools` onto Context.
+import type {} from '@deepseek-ai/dsh-tools'
+
+/** Cordis plugin name used by loader diagnostics. */
+export const name = 'mcp-client'
+
+/** Services required by this plugin. */
+export const inject = ['tools']
+
+/** Default timeout for individual MCP tool calls (ms). */
+const DEFAULT_TOOL_CALL_TIMEOUT_MS = 60_000
+
+/**
+ * Valid `serverName`: 1–32 chars of `[A-Za-z0-9_-]`. Kept well under the
+ * 64-char public-name budget so typical raw tool names survive unhashed.
+ */
+const SERVER_NAME_PATTERN = /^[A-Za-z0-9_-]{1,32}$/
+
+/**
+ * Live `serverName` reservations per app, keyed off `ctx.root` (multiple apps
+ * in one process — tests — must not see each other's names). A duplicate
+ * namespace is a configuration error surfaced at plugin load, never silent
+ * shadowing.
+ */
+const activeServerNames = new WeakMap<Context, Set<string>>()
+
+// ---- Config ----
+
+/** Config for connecting to an MCP server via a spawned child process over stdio. */
+export interface StdioConfig {
+  /** Transport type: spawn a child process and communicate over stdio. */
+  transport: 'stdio'
+  /**
+   * Stable local namespace for this server's model-facing tool names
+   * (`mcp__<serverName>__<rawName>`). Must match `[A-Za-z0-9_-]{1,32}` and be
+   * unique across live mcp-client instances.
+   */
+  serverName: string
+  /** Executable to spawn. */
+  command: string
+  /** Arguments passed to the command. */
+  args: string[]
+  /** Extra env vars merged on top of scrubbed ambient env. */
+  env: Record<string, string>
+  /** Working directory for the child process. */
+  cwd: string
+  /** Timeout per callTool invocation (ms). */
+  toolCallTimeoutMs: number
+}
+
+/** Config for connecting to an MCP server over Streamable HTTP (SSE). */
+export interface StreamableHttpConfig {
+  /** Transport type: connect to an MCP server over Streamable HTTP (SSE). */
+  transport: 'streamable-http'
+  /**
+   * Stable local namespace for this server's model-facing tool names
+   * (`mcp__<serverName>__<rawName>`). Must match `[A-Za-z0-9_-]{1,32}` and be
+   * unique across live mcp-client instances.
+   */
+  serverName: string
+  /** MCP server URL. */
+  url: string
+  /** Extra headers (e.g. auth tokens). */
+  headers: Record<string, string>
+  /** Timeout per callTool invocation (ms). */
+  toolCallTimeoutMs: number
+}
+
+/** Discriminated union of all supported MCP transport configurations. */
+export type Config = StdioConfig | StreamableHttpConfig
+
+export const Config = z.union([
+  z.object({
+    transport: z.const('stdio'),
+    serverName: z.string().required().pattern(SERVER_NAME_PATTERN),
+    command: z.string().required(),
+    args: z.array(String).default([]),
+    env: z.dict(String).default({}),
+    cwd: z.string().default(''),
+    toolCallTimeoutMs: z.number().default(DEFAULT_TOOL_CALL_TIMEOUT_MS),
+  }),
+  z.object({
+    transport: z.const('streamable-http'),
+    serverName: z.string().required().pattern(SERVER_NAME_PATTERN),
+    url: z.string().required(),
+    headers: z.dict(String).default({}),
+    toolCallTimeoutMs: z.number().default(DEFAULT_TOOL_CALL_TIMEOUT_MS),
+  }),
+]) as unknown as z<Config>
+
+// ---- Plugin apply ----
+
+export function apply(ctx: Context, config: Config): void {
+  // Reserve the namespace first: a duplicate `serverName` fails THIS instance
+  // at load with an actionable error and leaves the earlier instance intact.
+  ctx.effect(() => {
+    let names = activeServerNames.get(ctx.root)
+    if (!names) {
+      names = new Set()
+      activeServerNames.set(ctx.root, names)
+    }
+    if (names.has(config.serverName)) {
+      throw new Error(
+        `mcp-client: serverName "${config.serverName}" is already in use by another mcp-client instance — pick a unique serverName in cordis.yml`,
+      )
+    }
+    names.add(config.serverName)
+    return () => void names.delete(config.serverName)
+  }, 'mcp-client.serverName')
+
+  const transport = createTransport(config)
+  const client = new Client(
+    { name: 'dsh-mcp-client', version: '0.0.1' },
+    { capabilities: {} },
+  )
+
+  const opts = {
+    serverName: config.serverName,
+    toolCallTimeoutMs: config.toolCallTimeoutMs,
+  }
+
+  // Connect and set up tools. Errors during connect/first sync are logged,
+  // not thrown (the plugin simply has no tools registered). `ready` resolves
+  // to an accessor for the CURRENT disposer generation, so the effect
+  // disposer below always unregisters the live set, not the first one.
+  const ready = (async () => {
+    await client.connect(transport)
+
+    let disposers = await syncTools(client, ctx, opts, new Map())
+
+    client.setNotificationHandler(
+      ToolListChangedNotificationSchema,
+      async () => {
+        ctx.logger.info(`mcp-client(${config.serverName}): tool list changed, re-syncing`)
+        try {
+          disposers = await syncTools(client, ctx, opts, disposers)
+        } catch (error) {
+          // Fetch-phase failure: the previous generation is still registered
+          // and `disposers` still owns it — keep serving the last good list.
+          ctx.logger.error(`mcp-client(${config.serverName}): tool re-sync failed: ${String(error)}`)
+        }
+      },
+    )
+
+    return () => disposers
+  })().catch((error: unknown) => {
+    ctx.logger.error(`mcp-client(${config.serverName}): failed to connect: ${String(error)}`)
+    return () => new Map<string, () => void>()
+  })
+
+  ctx.effect(() => async () => {
+    const live = await ready
+    for (const dispose of live().values()) dispose()
+    try { await client.close() } catch { /* transport already gone */ }
+  }, 'mcp-client.connection')
+}
--- a/packages/mcp/mcp-client/src/tools.ts
+++ b/packages/mcp/mcp-client/src/tools.ts
@@ -0,0 +1,230 @@
+/**
+ * Tool bridge: discovers MCP tools, registers them on the harness ToolRegistry
+ * under deterministic server-qualified public names, and handles re-sync when
+ * the server's tool list changes.
+ *
+ * Naming contract (see the mcp-client RFC "Naming invariants"): every MCP tool
+ * has the stable identity `(serverName, rawName)`; the model-facing public name
+ * is `mcp__<serverName>__<rawName>`, normalized to the DeepSeek function-name
+ * constraints. The raw name is only ever sent on the wire (`tools/call`); the
+ * public name is never parsed to recover it.
+ *
+ * @module
+ */
+
+import { createHash } from 'node:crypto'
+import type { Client } from '@modelcontextprotocol/sdk/client/index.js'
+import type { Context } from 'cordis'
+import type { ToolDefinition, ToolExecution } from '@deepseek-ai/dsh-tools'
+
+/** Resolved options relevant to tool bridging. */
+export interface ToolBridgeOptions {
+  serverName: string
+  toolCallTimeoutMs: number
+}
+
+/** State for one sync generation: the current set of disposers keyed by public name. */
+export type ToolDisposers = Map<string, () => void>
+
+/**
+ * DeepSeek function-name contract: at most 64 characters. Wire-protocol
+ * constant, not configuration.
+ */
+const MAX_PUBLIC_NAME_LENGTH = 64
+
+/** DeepSeek function-name contract: only `[A-Za-z0-9_-]` is allowed. */
+const INVALID_NAME_CHARS = /[^A-Za-z0-9_-]/g
+
+/** Hex chars of the SHA-256 identity hash appended on lossy normalization. */
+const HASH_LENGTH = 12
+
+/**
+ * Derive the model-facing public name for one MCP tool.
+ *
+ * Deterministic pure function of `(serverName, rawName)`: the clean case is
+ * `mcp__<serverName>__<rawName>` verbatim. When character replacement or
+ * truncation to the DeepSeek function-name contract (64 chars,
+ * `[A-Za-z0-9_-]`) changes the name, a 12-hex-char SHA-256 hash of the
+ * identity is appended so distinct MCP identities never collapse into the
+ * same public name.
+ *
+ * @param serverName - Stable local namespace from plugin config.
+ * @param rawName - The MCP server's own tool name.
+ * @returns The globally unique, model-facing ToolRegistry name.
+ */
+export function publicToolName(serverName: string, rawName: string): string {
+  const joined = `mcp__${serverName}__${rawName}`
+  const normalized = joined.replace(INVALID_NAME_CHARS, '_')
+  if (normalized === joined && normalized.length <= MAX_PUBLIC_NAME_LENGTH) return normalized
+  const hash = createHash('sha256').update(`${serverName}\0${rawName}`).digest('hex').slice(0, HASH_LENGTH)
+  return `${normalized.slice(0, MAX_PUBLIC_NAME_LENGTH - HASH_LENGTH - 1)}_${hash}`
+}
+
+/**
+ * Sync the MCP server's tool list into the harness ToolRegistry.
+ *
+ * Two phases keep the swap safe:
+ *
+ * 1. Fetch: drain `client.listTools()` pagination and build the full next
+ *    generation of `ToolDefinition`s under public names. Any failure here
+ *    (network error, duplicate raw name in the server's list) rejects and
+ *    leaves the previous generation registered untouched.
+ * 2. Swap: dispose the previous generation, register the new one. A registry
+ *    conflict here can only mean a foreign registration squats on this
+ *    server's `mcp__<serverName>__` namespace — the partial generation is
+ *    rolled back (zero tools from this server), the error is logged, and an
+ *    empty map is returned.
+ *
+ * @param client - Connected MCP Client instance used to list and call tools.
+ * @param ctx - Cordis context providing the `tools` service for registration.
+ * @param opts - Bridge options: server namespace and per-call timeout.
+ * @param previous - Disposer map from the prior sync generation; disposed
+ *   during the swap phase (only after the fetch phase succeeded).
+ * @returns A map of registered public tool names to their unregister
+ *   disposers — the exact set of live registrations owned by this server.
+ */
+export async function syncTools(
+  client: Client,
+  ctx: Context,
+  opts: ToolBridgeOptions,
+  previous: ToolDisposers,
+): Promise<ToolDisposers> {
+  // Phase 1: fetch and build the next generation without touching the registry.
+  const definitions = new Map<string, ToolDefinition>()
+  let cursor: string | undefined
+  do {
+    const response = await client.listTools(cursor ? { cursor } : undefined)
+    for (const tool of response.tools) {
+      const publicName = publicToolName(opts.serverName, tool.name)
+      if (definitions.has(publicName)) {
+        throw new Error(
+          `mcp-client(${opts.serverName}): server listed tool "${tool.name}" more than once — invalid tool list`,
+        )
+      }
+      definitions.set(publicName, {
+        name: publicName,
+        description: tool.description ?? '',
+        parameters: tool.inputSchema,
+        execute: createExecutor(client, tool.name, opts),
+      })
+    }
+    cursor = response.nextCursor
+  } while (cursor)
+
+  // Phase 2: swap generations.
+  for (const dispose of previous.values()) dispose()
+  const disposers: ToolDisposers = new Map()
+  try {
+    for (const [publicName, definition] of definitions) {
+      disposers.set(publicName, ctx.tools.register(definition))
+    }
+  } catch (error) {
+    // A conflict on an `mcp__<serverName>__`-qualified name means a foreign
+    // registration occupies this server's namespace. Roll back so the model
+    // sees either the full generation or none of it — never a partial set.
+    for (const dispose of disposers.values()) dispose()
+    ctx.logger.error(`mcp-client(${opts.serverName}): tool registration failed, no tools registered: ${String(error)}`)
+    return new Map()
+  }
+  return disposers
+}
+
+/**
+ * The shape we read from each MCP content block. Intentionally looser than the
+ * SDK's `ContentBlock` type: we're at a network trust boundary (data arrives
+ * from an external MCP server process via JSON-RPC), so fields that the SDK
+ * declares required may be absent at runtime if the server is buggy.
+ */
+interface McpContentBlock {
+  type: string
+  text?: string
+  mimeType?: string
+}
+
+/**
+ * Create an execute function for one MCP tool. The executor closes over the
+ * raw MCP tool name and calls `client.callTool` with it (never the public
+ * name), with abort signal and timeout, then maps the result to harness
+ * ContentBlocks.
+ *
+ * When the MCP server returns `isError: true`, the executor throws so that
+ * the ToolRegistry's catch path produces an `isError` result for the model.
+ */
+function createExecutor(
+  client: Client,
+  rawName: string,
+  opts: ToolBridgeOptions,
+): ToolDefinition['execute'] {
+  return async (args: unknown, exec: ToolExecution) => {
+    // The agent loop passes `JSON.parse(model_arguments)` which is usually an
+    // object, but can be any JSON value if the model misbehaves (outputs a bare
+    // string/number/null). Fallback to {} lets the MCP server produce a
+    // specific "missing required param" error the model can learn from.
+    const argsObj = (typeof args === 'object' && args !== null ? args : {}) as Record<string, unknown>
+    const result = await client.callTool(
+      { name: rawName, arguments: argsObj },
+      undefined,
+      {
+        ...exec.signal ? { signal: exec.signal } : {},
+        timeout: opts.toolCallTimeoutMs,
+      },
+    )
+
+    // The SDK may return a legacy `toolResult` shape; normalize to content array.
+    if (!('content' in result) || !Array.isArray(result.content)) {
+      const text = 'toolResult' in result
+        ? JSON.stringify(result.toolResult)
+        : '(no output)'
+      return [{ type: 'text' as const, text }]
+    }
+
+    // Trust boundary: the SDK's return type erases to `any[]` due to the
+    // union of CallToolResult | CompatibilityCallToolResult. We process each
+    // element defensively in extractText (reading only .type/.text/.mimeType
+    // with optional fallbacks).
+    // eslint-disable-next-line @typescript-eslint/no-unsafe-assignment
+    const content: McpContentBlock[] = result.content
+    const text = extractText(content, rawName)
+
+    // MCP isError → throw so ToolRegistry produces an isError result for the model.
+    if ('isError' in result && result.isError === true) {
+      throw new Error(text)
+    }
+
+    return [{ type: 'text', text }]
+  }
+}
+
+/**
+ * Extract text from an MCP content array into a single string.
+ * - text blocks: join with '\n'
+ * - image/audio/resource blocks: replaced with a placeholder
+ *
+ * Defensive: fields that the MCP spec declares required (mimeType, text) are
+ * guarded with fallbacks because this is a network trust boundary.
+ */
+function extractText(mcpContent: McpContentBlock[], toolName: string): string {
+  const parts: string[] = []
+
+  for (const block of mcpContent) {
+    switch (block.type) {
+      case 'text':
+        if (block.text !== undefined) parts.push(block.text)
+        break
+      case 'image':
+        parts.push(`[image: ${block.mimeType ?? 'unknown'}, content discarded]`)
+        break
+      case 'audio':
+        parts.push(`[audio: ${block.mimeType ?? 'unknown'}, content discarded]`)
+        break
+      case 'resource':
+      case 'resource_link':
+        parts.push('[resource: content discarded]')
+        break
+      default:
+        parts.push(`[unsupported content type: ${block.type}]`)
+    }
+  }
+
+  return parts.join('\n') || `(${toolName} returned no text content)`
+}
--- a/packages/mcp/mcp-client/src/transport.ts
+++ b/packages/mcp/mcp-client/src/transport.ts
@@ -0,0 +1,56 @@
+/**
+ * Transport factory: creates the appropriate MCP transport based on the
+ * plugin's resolved config. Stdio spawns a child process (with credential
+ * scrubbing); Streamable HTTP connects to a URL.
+ *
+ * @module
+ */
+
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js'
+import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js'
+import { StreamableHTTPClientTransport } from '@modelcontextprotocol/sdk/client/streamableHttp.js'
+import type { Config } from './index.ts'
+
+/**
+ * Credential-shaped ambient env vars are NOT forwarded to the child by default
+ * (the parent harness's own secrets must not leak into a spawned process
+ * implicitly). Same pattern as `dsh-subagent-acp`.
+ */
+const SENSITIVE_ENV_PATTERN = /KEY|SECRET|TOKEN/i
+
+/** The ambient env minus credential-shaped vars, plus the spec's explicit env. */
+function buildChildEnv(extra: Record<string, string>): Record<string, string> {
+  const env: Record<string, string> = {}
+  for (const [key, value] of Object.entries(process.env)) {
+    if (value !== undefined && !SENSITIVE_ENV_PATTERN.test(key)) env[key] = value
+  }
+  return { ...env, ...extra }
+}
+
+/**
+ * Create an MCP transport from the resolved plugin config.
+ *
+ * @param config - Resolved plugin config discriminated on `transport`.
+ * @returns A connected-ready MCP Transport (stdio or Streamable HTTP).
+ */
+export function createTransport(config: Config): Transport {
+  switch (config.transport) {
+    case 'stdio':
+      return new StdioClientTransport({
+        command: config.command,
+        args: config.args,
+        env: buildChildEnv(config.env),
+        cwd: config.cwd,
+      })
+    case 'streamable-http':
+      // The MCP SDK's StreamableHTTPClientTransport has optional callback
+      // properties typed without `| undefined` (exactOptionalPropertyTypes
+      // mismatch with the Transport interface). The cast is safe — the SDK
+      // constructed the object, it simply doesn't declare the optionals
+      // strictly enough for our tsconfig.
+      return new StreamableHTTPClientTransport(
+        new URL(config.url),
+        { requestInit: { headers: config.headers } },
+      ) as Transport
+  }
+}
--- a/packages/mcp/mcp-client/tests/apply.spec.ts
+++ b/packages/mcp/mcp-client/tests/apply.spec.ts
@@ -0,0 +1,282 @@
+/**
+ * Tests for the mcp-client plugin's `apply` lifecycle entry point.
+ * Isolated file so vi.mock of the MCP SDK doesn't pollute other test suites.
+ */
+import { describe, expect, it, vi, beforeEach } from 'vitest'
+import { Context } from 'cordis'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import type { Config } from '@deepseek-ai/dsh-mcp-client'
+
+// ---- Mock MCP SDK ----
+
+// vi.mock factories are hoisted above every import/const, so the mock fns and
+// class must be created inside vi.hoisted to exist when the factories run.
+const { mockConnect, mockClose, mockListTools, mockCallTool, mockSetNotificationHandler, MockClient } = vi.hoisted(() => {
+  const mockConnect = vi.fn<() => Promise<void>>()
+  const mockClose = vi.fn<() => Promise<void>>()
+  const mockListTools = vi.fn()
+  const mockCallTool = vi.fn()
+  const mockSetNotificationHandler = vi.fn()
+  class MockClient {
+    connect = mockConnect
+    close = mockClose
+    listTools = mockListTools
+    callTool = mockCallTool
+    setNotificationHandler = mockSetNotificationHandler
+  }
+  return { mockConnect, mockClose, mockListTools, mockCallTool, mockSetNotificationHandler, MockClient }
+})
+
+vi.mock('@modelcontextprotocol/sdk/client/index.js', () => ({
+  Client: MockClient,
+}))
+
+vi.mock('@modelcontextprotocol/sdk/client/stdio.js', () => ({
+  StdioClientTransport: vi.fn(),
+}))
+
+vi.mock('@modelcontextprotocol/sdk/client/streamableHttp.js', () => ({
+  StreamableHTTPClientTransport: vi.fn(),
+}))
+
+// vi.mock is hoisted above static imports, so the module under test sees the
+// mocked SDK even through a static import.
+import { apply, name, inject, Config as ConfigSchema } from '@deepseek-ai/dsh-mcp-client/src/index.ts'
+
+// ---- Helpers ----
+
+async function mountRegistry(): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  return ctx
+}
+
+function sleep(ms: number): Promise<void> {
+  // Annotated binding (not withResolvers<void>()): the tests lint layer runs
+  // no-invalid-void-type with default options, which rejects the explicit
+  // type argument in call position but accepts the inferred form.
+  const gate: PromiseWithResolvers<void> = Promise.withResolvers()
+  setTimeout(gate.resolve, ms)
+  return gate.promise
+}
+
+const stdioConfig: Config = {
+  transport: 'stdio',
+  serverName: 'srv',
+  command: 'echo',
+  args: [],
+  env: {},
+  cwd: '',
+  toolCallTimeoutMs: 60_000,
+}
+
+// ---- Tests ----
+
+describe('mcp-client plugin module exports', () => {
+  it('exports name, inject, and Config', () => {
+    expect(name).toBe('mcp-client')
+    expect(inject).toEqual(['tools'])
+    expect(ConfigSchema).toBeDefined()
+  })
+
+  it('Config schema rejects a missing serverName', () => {
+    expect(() => ConfigSchema({
+      transport: 'stdio',
+      command: 'echo',
+    } as never)).toThrow()
+  })
+
+  it('Config schema rejects an invalid serverName', () => {
+    // schemastery unions wrap branch errors in a generic "expected ... but got"
+    // message, so assert the throw, not the inner pattern text.
+    expect(() => ConfigSchema({
+      transport: 'stdio',
+      serverName: 'bad name!',
+      command: 'echo',
+    } as never)).toThrow()
+    expect(() => ConfigSchema({
+      transport: 'stdio',
+      serverName: 'x'.repeat(33),
+      command: 'echo',
+    } as never)).toThrow()
+  })
+
+  it('Config schema accepts a valid serverName', () => {
+    const resolved = ConfigSchema({
+      transport: 'stdio',
+      serverName: 'github-prod_1',
+      command: 'echo',
+    } as never)
+    expect(resolved.serverName).toBe('github-prod_1')
+  })
+})
+
+describe('apply (plugin lifecycle)', () => {
+  let ctx: Context
+
+  beforeEach(async () => {
+    vi.clearAllMocks()
+    mockConnect.mockResolvedValue(undefined)
+    mockClose.mockResolvedValue(undefined)
+    mockListTools.mockResolvedValue({
+      tools: [{ name: 'remote', description: 'A remote tool', inputSchema: { type: 'object' } }],
+      nextCursor: undefined,
+    })
+    mockCallTool.mockResolvedValue({ content: [{ type: 'text', text: 'ok' }] })
+    ctx = await mountRegistry()
+  })
+
+  it('connects, syncs tools under the namespace, and registers a notification handler', async () => {
+    apply(ctx, stdioConfig)
+    await sleep(50)
+
+    expect(mockConnect).toHaveBeenCalled()
+    expect(mockListTools).toHaveBeenCalled()
+    expect(mockSetNotificationHandler).toHaveBeenCalled()
+    expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
+    expect(ctx.tools.get('remote')).toBeUndefined()
+  })
+
+  it('rejects a duplicate serverName at load and leaves the first instance intact', async () => {
+    apply(ctx, stdioConfig)
+    await sleep(50)
+    expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
+
+    expect(() => { apply(ctx, stdioConfig) }).toThrow(/serverName "srv" is already in use/)
+    // First instance unaffected.
+    expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
+  })
+
+  it('releases the serverName reservation on dispose', async () => {
+    const first = new Context()
+    await first.plugin(SystemPrompt)
+    await first.plugin(ToolRegistry)
+    apply(first, stdioConfig)
+    await sleep(50)
+
+    await first.fiber.dispose()
+    await sleep(50)
+
+    // Same root would conflict; a fresh app root reuses the name freely,
+    // and the disposed instance no longer holds the reservation on its root.
+    const second = new Context()
+    await second.plugin(SystemPrompt)
+    await second.plugin(ToolRegistry)
+    expect(() => { apply(second, stdioConfig) }).not.toThrow()
+  })
+
+  it('scopes serverName reservations per app root', async () => {
+    const other = await mountRegistry()
+
+    apply(ctx, stdioConfig)
+    // Same serverName on a DIFFERENT root is fine.
+    expect(() => { apply(other, stdioConfig) }).not.toThrow()
+    await sleep(50)
+
+    expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
+    expect(other.tools.get('mcp__srv__remote')).toBeDefined()
+  })
+
+  it('logs error and registers no tools when connect fails; dispose is a no-op', async () => {
+    mockConnect.mockRejectedValue(new Error('connection refused'))
+
+    apply(ctx, stdioConfig)
+    await sleep(50)
+
+    expect(mockListTools).not.toHaveBeenCalled()
+    expect(ctx.tools.get('mcp__srv__remote')).toBeUndefined()
+
+    // Disposal exercises the empty fallback accessor: nothing to unregister,
+    // close still attempted, no throw.
+    await ctx.fiber.dispose()
+    await sleep(50)
+    expect(mockClose).toHaveBeenCalled()
+  })
+
+  it('re-syncs tools on ToolListChanged notification', async () => {
+    apply(ctx, stdioConfig)
+    await sleep(50)
+
+    expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
+
+    // Simulate the notification handler being invoked with a new tool list.
+    mockListTools.mockResolvedValue({
+      tools: [{ name: 'updated', inputSchema: { type: 'object' } }],
+      nextCursor: undefined,
+    })
+
+    // Extract and call the notification handler.
+    const handler = mockSetNotificationHandler.mock.calls[0]![1] as () => Promise<void>
+    await handler()
+
+    expect(ctx.tools.get('mcp__srv__remote')).toBeUndefined()
+    expect(ctx.tools.get('mcp__srv__updated')).toBeDefined()
+  })
+
+  it('keeps the previous generation when a re-sync fails', async () => {
+    apply(ctx, stdioConfig)
+    await sleep(50)
+    expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
+
+    mockListTools.mockRejectedValue(new Error('flaky server'))
+    const handler = mockSetNotificationHandler.mock.calls[0]![1] as () => Promise<void>
+    // Must not reject (contained), and must keep the last good generation.
+    await handler()
+
+    expect(ctx.tools.get('mcp__srv__remote')).toBeDefined()
+  })
+
+  it('effect disposer unregisters the CURRENT generation and closes client', async () => {
+    // Load through ctx.plugin so ONLY the plugin's fiber is disposed — the
+    // registry must survive to observe the unregistration.
+    const fiber = ctx.plugin({ name: 'mcp-client', inject: ['tools'], apply }, stdioConfig)
+    await sleep(50)
+
+    // Advance to a second generation first.
+    mockListTools.mockResolvedValue({
+      tools: [{ name: 'updated', inputSchema: { type: 'object' } }],
+      nextCursor: undefined,
+    })
+    const handler = mockSetNotificationHandler.mock.calls[0]![1] as () => Promise<void>
+    await handler()
+    expect(ctx.tools.get('mcp__srv__updated')).toBeDefined()
+
+    await fiber.dispose()
+    await sleep(50)
+
+    expect(mockClose).toHaveBeenCalled()
+    // The live (second) generation was unregistered, not just the first.
+    expect(ctx.tools.get('mcp__srv__updated')).toBeUndefined()
+  })
+
+  it('effect disposer handles client.close failure gracefully', async () => {
+    mockClose.mockRejectedValue(new Error('already closed'))
+
+    apply(ctx, stdioConfig)
+    await sleep(50)
+
+    // Should not throw when dispose is triggered.
+    await ctx.fiber.dispose()
+    await sleep(50)
+
+    expect(mockClose).toHaveBeenCalled()
+  })
+
+  it('uses streamable-http config path', async () => {
+    const httpConfig: Config = {
+      transport: 'streamable-http',
+      serverName: 'web',
+      url: 'http://localhost:3000/mcp',
+      headers: { Authorization: 'Bearer x' },
+      toolCallTimeoutMs: 30_000,
+    }
+
+    apply(ctx, httpConfig)
+    await sleep(50)
+
+    expect(mockConnect).toHaveBeenCalled()
+    expect(ctx.tools.get('mcp__web__remote')).toBeDefined()
+  })
+})
--- a/packages/mcp/mcp-client/tests/fixture-server.ts
+++ b/packages/mcp/mcp-client/tests/fixture-server.ts
@@ -0,0 +1,65 @@
+/**
+ * Minimal MCP server over stdio for e2e testing of the dsh-mcp-client plugin.
+ * Registers controlled tools with predictable behavior for asserting edge cases.
+ *
+ * Run: node --import tsx fixture-server.ts
+ */
+
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { z } from 'zod'
+
+const server = new McpServer(
+  { name: 'fixture-server', version: '1.0.0' },
+  { capabilities: { tools: { listChanged: true } } },
+)
+
+server.registerTool('add', {
+  title: 'Add Tool',
+  description: 'Adds two numbers.',
+  inputSchema: { a: z.number().describe('First number'), b: z.number().describe('Second number') },
+}, async args => ({
+  content: [{ type: 'text', text: String(args.a + args.b) }],
+}))
+
+server.registerTool('greet', {
+  title: 'Greet Tool',
+  description: 'Greets a person by name.',
+  inputSchema: { name: z.string().describe('Name to greet') },
+}, async args => ({
+  content: [{ type: 'text', text: `Hello, ${args.name}!` }],
+}))
+
+server.registerTool('fail', {
+  title: 'Fail Tool',
+  description: 'Always returns an error.',
+  inputSchema: {},
+}, async () => ({
+  content: [{ type: 'text', text: 'Something went wrong' }],
+  isError: true,
+}))
+
+server.registerTool('image', {
+  title: 'Image Tool',
+  description: 'Returns an image content block.',
+  inputSchema: {},
+}, async () => ({
+  content: [
+    { type: 'text', text: 'Here is an image:' },
+    { type: 'image', data: 'iVBORw0KGgo=', mimeType: 'image/png' },
+    { type: 'text', text: 'End of image.' },
+  ],
+}))
+
+// Dotted name: legal in MCP, illegal in the DeepSeek function-name contract.
+// Exercises the bridge's normalize-and-hash public-name path end to end.
+server.registerTool('admin.reset', {
+  title: 'Admin Reset Tool',
+  description: 'Tool with a dotted name (normalization test).',
+  inputSchema: {},
+}, async () => ({
+  content: [{ type: 'text', text: 'reset done' }],
+}))
+
+const transport = new StdioServerTransport()
+await server.connect(transport)
--- a/packages/mcp/mcp-client/tests/load-path.spec.ts
+++ b/packages/mcp/mcp-client/tests/load-path.spec.ts
@@ -0,0 +1,29 @@
+/**
+ * Real-load-path guard for @deepseek-ai/dsh-mcp-client. `mcp-client` is a
+ * NAMESPACE plugin with `inject` — so a stray `export default apply` would
+ * make the cordis Loader's `unwrapExports` (`exports.default ?? exports`)
+ * collapse the module to the bare `apply` function, DROPPING `inject`. The
+ * plugin would then read `ctx.tools` without having injected it and throw
+ * `cannot get property … without inject` the moment it loads (postmortem 0001).
+ *
+ * This test unwraps the module through the REAL `Loader.prototype.unwrapExports`
+ * and verifies the namespace shape is preserved.
+ */
+
+import { describe, expect, it } from 'vitest'
+import Loader from '@cordisjs/plugin-loader'
+import * as mcpClient from '@deepseek-ai/dsh-mcp-client'
+
+describe('dsh-mcp-client real-load-path guard', () => {
+  it('has no default export and keeps name/inject/Config through unwrapExports', () => {
+    expect('default' in mcpClient).toBe(false)
+
+    const loader = Object.create(Loader.prototype) as Loader
+    const unwrapped = loader.unwrapExports(mcpClient) as Record<string, unknown>
+    expect(unwrapped).toBe(mcpClient)
+    expect(unwrapped.name).toBe('mcp-client')
+    expect(unwrapped.inject).toEqual(['tools'])
+    expect(typeof unwrapped.apply).toBe('function')
+    expect(unwrapped.Config).toBeDefined()
+  })
+})
--- a/packages/mcp/mcp-client/tests/mcp-client.e2e.ts
+++ b/packages/mcp/mcp-client/tests/mcp-client.e2e.ts
@@ -0,0 +1,441 @@
+/**
+ * End-to-end tests for dsh-mcp-client. Exercises the REAL MCP protocol against:
+ * 1. A self-written fixture server over stdio (controlled edge cases)
+ * 2. @modelcontextprotocol/server-everything (official integration test server)
+ * 3. @modelcontextprotocol/server-filesystem (real filesystem operations)
+ * 4. An in-process StreamableHTTPServerTransport server over Streamable HTTP
+ *
+ * No API key needed — all servers are local/keyless.
+ */
+
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from 'node:http'
+import { mkdtemp, rm, writeFile, readFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { afterAll, beforeAll, describe, expect, it } from 'vitest'
+import { Context } from 'cordis'
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js'
+import { z } from 'zod'
+import type { Transport } from '@modelcontextprotocol/sdk/shared/transport.js'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import { apply } from '@deepseek-ai/dsh-mcp-client/src/index.ts'
+import { publicToolName } from '@deepseek-ai/dsh-mcp-client/src/tools.ts'
+import type { Config } from '@deepseek-ai/dsh-mcp-client'
+
+const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
+const fixtureServerPath = fileURLToPath(new URL('./fixture-server.ts', import.meta.url))
+const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))
+
+// Resolve package-local .bin for pnpm-hoisted MCP server binaries.
+const packageDir = fileURLToPath(new URL('..', import.meta.url))
+const localBin = join(packageDir, 'node_modules', '.bin')
+
+// ---- Helpers ----
+
+async function mountRegistry(): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  return ctx
+}
+
+/** Apply the MCP client plugin and wait for tools to be registered. */
+async function applyAndWait(ctx: Context, config: Config, timeoutMs = 20_000): Promise<void> {
+  // Annotated bindings (not withResolvers<void>()): the tests lint layer runs
+  // no-invalid-void-type with default options, which rejects the explicit
+  // type argument in call position but accepts the inferred form.
+  const gate: PromiseWithResolvers<void> = Promise.withResolvers()
+  const timer = setTimeout(
+    () => { gate.reject(new Error(`applyAndWait timed out after ${timeoutMs}ms — no tools/change event`)) },
+    timeoutMs,
+  )
+  ctx.on('tools/change', () => { clearTimeout(timer); gate.resolve() })
+  apply(ctx, config)
+  await gate.promise
+}
+
+function sleep(ms: number): Promise<void> {
+  const gate: PromiseWithResolvers<void> = Promise.withResolvers()
+  setTimeout(gate.resolve, ms)
+  return gate.promise
+}
+
+/** Narrow a result content block to its text, failing the test on any other shape. */
+function textOf(block: unknown): string {
+  if (block && typeof block === 'object' && 'text' in block && typeof block.text === 'string') {
+    return block.text
+  }
+  throw new Error(`expected a text content block, got ${JSON.stringify(block)}`)
+}
+
+let callSeq = 0
+function nextCallId(): CallId {
+  return CallId(`e2e-${++callSeq}`)
+}
+
+// ---- Fixture server tests ----
+
+describe('fixture server — controlled scenarios', () => {
+  let ctx: Context
+
+  const fixtureConfig: Config = {
+    transport: 'stdio',
+    serverName: 'fixture',
+    command: process.execPath,
+    args: ['--import', tsxLoader, fixtureServerPath],
+    env: { TSX_TSCONFIG_PATH: repoTsconfig },
+    cwd: packageDir,
+    toolCallTimeoutMs: 15_000,
+  }
+
+  beforeAll(async () => {
+    ctx = await mountRegistry()
+    await applyAndWait(ctx, fixtureConfig)
+  }, 30_000)
+
+  afterAll(async () => {
+    if (ctx) await ctx.fiber.dispose()
+    await sleep(200)
+  })
+
+  it('discovers all fixture tools under the server namespace', () => {
+    const schemas = ctx.tools.schemas()
+    const names = schemas.map(s => s.name)
+    expect(names).toContain('mcp__fixture__add')
+    expect(names).toContain('mcp__fixture__greet')
+    expect(names).toContain('mcp__fixture__fail')
+    expect(names).toContain('mcp__fixture__image')
+    // Raw names are not registered.
+    expect(names).not.toContain('add')
+  })
+
+  it('normalizes the dotted tool name with a deterministic hash suffix', () => {
+    const publicName = publicToolName('fixture', 'admin.reset')
+    expect(publicName).toMatch(/^mcp__fixture__admin_reset_[0-9a-f]{12}$/)
+    expect(ctx.tools.get(publicName)).toBeDefined()
+  })
+
+  it('executes the dotted tool via its normalized public name', async () => {
+    const result = await ctx.tools.execute({
+      callId: nextCallId(), name: publicToolName('fixture', 'admin.reset'), arguments: {},
+    })
+    expect(result.isError).toBe(false)
+    expect(result.content[0]).toEqual({ type: 'text', text: 'reset done' })
+  })
+
+  it('executes add(2, 3) → "5"', async () => {
+    const result = await ctx.tools.execute({
+      callId: nextCallId(), name: 'mcp__fixture__add', arguments: { a: 2, b: 3 },
+    })
+    expect(result.isError).toBe(false)
+    expect(result.content[0]).toEqual({ type: 'text', text: '5' })
+  })
+
+  it('executes greet("World") → "Hello, World!"', async () => {
+    const result = await ctx.tools.execute({
+      callId: nextCallId(), name: 'mcp__fixture__greet', arguments: { name: 'World' },
+    })
+    expect(result.isError).toBe(false)
+    expect(result.content[0]).toEqual({ type: 'text', text: 'Hello, World!' })
+  })
+
+  it('executes fail() → isError result', async () => {
+    const result = await ctx.tools.execute({
+      callId: nextCallId(), name: 'mcp__fixture__fail', arguments: {},
+    })
+    expect(result.isError).toBe(true)
+    expect(result.content[0]).toMatchObject({ type: 'text' })
+  })
+
+  it('executes image() → image placeholder', async () => {
+    const result = await ctx.tools.execute({
+      callId: nextCallId(), name: 'mcp__fixture__image', arguments: {},
+    })
+    expect(result.isError).toBe(false)
+    const text = textOf(result.content[0])
+    expect(text).toContain('Here is an image:')
+    expect(text).toContain('[image: image/png, content discarded]')
+    expect(text).toContain('End of image.')
+  })
+})
+
+describe('fixture server — duplicate serverName', () => {
+  it('rejects a second instance with the same serverName on one root', async () => {
+    const ctx = await mountRegistry()
+    const config: Config = {
+      transport: 'stdio',
+      serverName: 'dup',
+      command: process.execPath,
+      args: ['--import', tsxLoader, fixtureServerPath],
+      env: { TSX_TSCONFIG_PATH: repoTsconfig },
+      cwd: packageDir,
+      toolCallTimeoutMs: 15_000,
+    }
+    await applyAndWait(ctx, config)
+
+    expect(() => { apply(ctx, config) }).toThrow(/serverName "dup" is already in use/)
+
+    await ctx.fiber.dispose()
+    await sleep(200)
+  }, 30_000)
+})
+
+describe('fixture server — disposal', () => {
+  it('disposes cleanly without error', async () => {
+    const ctx = await mountRegistry()
+    await applyAndWait(ctx, {
+      transport: 'stdio',
+      serverName: 'fixture',
+      command: process.execPath,
+      args: ['--import', tsxLoader, fixtureServerPath],
+      env: { TSX_TSCONFIG_PATH: repoTsconfig },
+      cwd: packageDir,
+      toolCallTimeoutMs: 15_000,
+    })
+
+    // Tools are registered before dispose.
+    expect(ctx.tools.get('mcp__fixture__add')).toBeDefined()
+    expect(ctx.tools.schemas().length).toBeGreaterThanOrEqual(4)
+
+    // Dispose should complete without throwing.
+    await ctx.fiber.dispose()
+    await sleep(200)
+  }, 30_000)
+})
+
+// ---- @modelcontextprotocol/server-everything ----
+
+describe('server-everything — official test server', () => {
+  let ctx: Context
+
+  const config: Config = {
+    transport: 'stdio',
+    serverName: 'everything',
+    command: join(localBin, 'mcp-server-everything'),
+    args: ['stdio'],
+    env: {},
+    cwd: '',
+    toolCallTimeoutMs: 30_000,
+  }
+
+  beforeAll(async () => {
+    ctx = await mountRegistry()
+    await applyAndWait(ctx, config)
+  }, 60_000)
+
+  afterAll(async () => {
+    if (ctx) await ctx.fiber.dispose()
+    await sleep(500)
+  })
+
+  it('discovers tools from server-everything', () => {
+    const schemas = ctx.tools.schemas()
+    const names = schemas.map(s => s.name)
+    expect(names).toContain('mcp__everything__echo')
+    expect(names).toContain('mcp__everything__get-sum')
+    expect(names).toContain('mcp__everything__get-tiny-image')
+    expect(names.length).toBeGreaterThanOrEqual(8)
+  })
+
+  it('executes echo({ message: "hello" }) → "Echo: hello"', async () => {
+    const result = await ctx.tools.execute({
+      callId: nextCallId(), name: 'mcp__everything__echo', arguments: { message: 'hello' },
+    })
+    expect(result.isError).toBe(false)
+    expect(textOf(result.content[0])).toBe('Echo: hello')
+  })
+
+  it('executes get-sum({ a: 3, b: 7 }) → contains "10"', async () => {
+    const result = await ctx.tools.execute({
+      callId: nextCallId(), name: 'mcp__everything__get-sum', arguments: { a: 3, b: 7 },
+    })
+    expect(result.isError).toBe(false)
+    expect(textOf(result.content[0])).toContain('10')
+  })
+
+  it('executes get-tiny-image → image placeholder', async () => {
+    const result = await ctx.tools.execute({
+      callId: nextCallId(), name: 'mcp__everything__get-tiny-image', arguments: {},
+    })
+    expect(result.isError).toBe(false)
+    expect(textOf(result.content[0])).toContain('[image: image/png, content discarded]')
+  })
+})
+
+// ---- @modelcontextprotocol/server-filesystem ----
+
+describe('server-filesystem — real filesystem operations', () => {
+  let ctx: Context
+  let tempDir: string
+
+  beforeAll(async () => {
+    tempDir = await mkdtemp(join(tmpdir(), 'mcp-fs-e2e-'))
+
+    ctx = await mountRegistry()
+    const config: Config = {
+      transport: 'stdio',
+      serverName: 'filesystem',
+      command: join(localBin, 'mcp-server-filesystem'),
+      args: [tempDir],
+      env: {},
+      cwd: '',
+      toolCallTimeoutMs: 30_000,
+    }
+    await applyAndWait(ctx, config)
+  }, 60_000)
+
+  afterAll(async () => {
+    if (ctx) await ctx.fiber.dispose()
+    await sleep(500)
+    await rm(tempDir, { recursive: true, force: true })
+  })
+
+  it('discovers filesystem tools', () => {
+    const schemas = ctx.tools.schemas()
+    const names = schemas.map(s => s.name)
+    expect(names).toContain('mcp__filesystem__read_file')
+    expect(names).toContain('mcp__filesystem__write_file')
+    expect(names).toContain('mcp__filesystem__list_directory')
+  })
+
+  it('write_file + read_file round-trip', async () => {
+    const filePath = join(tempDir, 'test.txt')
+    const content = 'Hello from MCP e2e test!'
+
+    // Write via MCP tool
+    const writeResult = await ctx.tools.execute({
+      callId: nextCallId(), name: 'mcp__filesystem__write_file', arguments: { path: filePath, content },
+    })
+    expect(writeResult.isError).toBe(false)
+
+    // Verify file was actually written (world verification)
+    const onDisk = await readFile(filePath, 'utf8')
+    expect(onDisk).toBe(content)
+
+    // Read back via MCP tool
+    const readResult = await ctx.tools.execute({
+      callId: nextCallId(), name: 'mcp__filesystem__read_file', arguments: { path: filePath },
+    })
+    expect(readResult.isError).toBe(false)
+    expect(textOf(readResult.content[0])).toContain(content)
+  })
+
+  it('list_directory shows written file', async () => {
+    // Ensure a file exists
+    await writeFile(join(tempDir, 'listed.txt'), 'listed')
+
+    const result = await ctx.tools.execute({
+      callId: nextCallId(), name: 'mcp__filesystem__list_directory', arguments: { path: tempDir },
+    })
+    expect(result.isError).toBe(false)
+    expect(textOf(result.content[0])).toContain('listed.txt')
+  })
+})
+
+// ---- Streamable HTTP transport ----
+
+describe('streamable-http — in-process MCP server', () => {
+  let ctx: Context
+  let httpServer: Server
+  let baseUrl: string
+  /** Authorization header values observed by the HTTP server, in arrival order. */
+  const seenAuth: Array<string | undefined> = []
+
+  /**
+   * Stateless Streamable HTTP endpoint: a fresh McpServer + server transport
+   * per request (the SDK's documented stateless pattern — no session id, no
+   * SSE stream to keep). The tool set mirrors a minimal fixture server.
+   */
+  async function handleMcpRequest(req: IncomingMessage, res: ServerResponse): Promise<void> {
+    seenAuth.push(req.headers.authorization)
+    const server = new McpServer(
+      { name: 'http-fixture', version: '1.0.0' },
+      { capabilities: { tools: {} } },
+    )
+    server.registerTool('ping', {
+      description: 'Replies pong.',
+      inputSchema: {},
+    }, async () => ({
+      content: [{ type: 'text', text: 'pong' }],
+    }))
+    server.registerTool('shout', {
+      description: 'Upper-cases a message.',
+      inputSchema: { message: z.string().describe('Message to upper-case') },
+    }, async args => ({
+      content: [{ type: 'text', text: args.message.toUpperCase() }],
+    }))
+    // Stateless mode: sessionIdGenerator ABSENT (the runtime treats absent and
+    // explicit-undefined identically; exactOptionalPropertyTypes forbids the
+    // SDK-documented explicit `sessionIdGenerator: undefined` spelling).
+    const transport = new StreamableHTTPServerTransport({})
+    res.on('close', () => { void transport.close(); void server.close() })
+    // Same exactOptionalPropertyTypes mismatch the client transport factory
+    // documents (src/transport.ts): the SDK types optional callbacks without
+    // `| undefined`. The SDK constructed the object; the cast is safe.
+    await server.connect(transport as Transport)
+    await transport.handleRequest(req, res)
+  }
+
+  beforeAll(async () => {
+    httpServer = createServer((req, res) => {
+      handleMcpRequest(req, res).catch((error: unknown) => {
+        res.writeHead(500).end(String(error))
+      })
+    })
+    const listening: PromiseWithResolvers<void> = Promise.withResolvers()
+    httpServer.listen(0, '127.0.0.1', listening.resolve)
+    await listening.promise
+    const address = httpServer.address()
+    if (address === null || typeof address === 'string') throw new Error(`expected a TCP AddressInfo, got ${String(address)}`)
+    baseUrl = `http://127.0.0.1:${address.port}/mcp`
+
+    ctx = await mountRegistry()
+    const config: Config = {
+      transport: 'streamable-http',
+      serverName: 'web',
+      url: baseUrl,
+      headers: { Authorization: 'Bearer e2e-test-token' },
+      toolCallTimeoutMs: 15_000,
+    }
+    await applyAndWait(ctx, config)
+  }, 30_000)
+
+  afterAll(async () => {
+    if (ctx) await ctx.fiber.dispose()
+    await sleep(200)
+    const closed: PromiseWithResolvers<void> = Promise.withResolvers()
+    httpServer.close(() => { closed.resolve() })
+    await closed.promise
+  })
+
+  it('discovers tools under the server namespace over HTTP', () => {
+    const names = ctx.tools.schemas().map(s => s.name)
+    expect(names).toContain('mcp__web__ping')
+    expect(names).toContain('mcp__web__shout')
+  })
+
+  it('executes ping() → "pong" over HTTP', async () => {
+    const result = await ctx.tools.execute({
+      callId: nextCallId(), name: 'mcp__web__ping', arguments: {},
+    })
+    expect(result.isError).toBe(false)
+    expect(result.content[0]).toEqual({ type: 'text', text: 'pong' })
+  })
+
+  it('executes shout({ message }) with args over HTTP', async () => {
+    const result = await ctx.tools.execute({
+      callId: nextCallId(), name: 'mcp__web__shout', arguments: { message: 'quiet' },
+    })
+    expect(result.isError).toBe(false)
+    expect(result.content[0]).toEqual({ type: 'text', text: 'QUIET' })
+  })
+
+  it('sends configured headers on every HTTP request', () => {
+    expect(seenAuth.length).toBeGreaterThan(0)
+    for (const auth of seenAuth) expect(auth).toBe('Bearer e2e-test-token')
+  })
+})
--- a/packages/mcp/mcp-client/tests/mcp-client.spec.ts
+++ b/packages/mcp/mcp-client/tests/mcp-client.spec.ts
@@ -0,0 +1,602 @@
+import { describe, expect, it, vi, beforeEach } from 'vitest'
+import { Context } from 'cordis'
+import { CallId } from '@deepseek-ai/dsh-llm'
+import SystemPrompt from '@deepseek-ai/dsh-system-prompt'
+import ToolRegistry from '@deepseek-ai/dsh-tools'
+import { publicToolName, syncTools, type ToolBridgeOptions } from '@deepseek-ai/dsh-mcp-client/src/tools.ts'
+import { createTransport } from '@deepseek-ai/dsh-mcp-client/src/transport.ts'
+import type { Config } from '@deepseek-ai/dsh-mcp-client'
+
+// ---- Mock MCP Client ----
+
+interface MockTool {
+  name: string
+  description?: string
+  inputSchema: Record<string, unknown>
+}
+
+interface MockCallResult {
+  content: Array<{ type: string; text?: string; mimeType?: string }>
+  isError?: boolean
+}
+
+function createMockClient(tools: MockTool[], callResult: MockCallResult = { content: [{ type: 'text', text: 'ok' }] }) {
+  return {
+    listTools: vi.fn().mockResolvedValue({ tools, nextCursor: undefined }),
+    callTool: vi.fn().mockResolvedValue(callResult),
+    setNotificationHandler: vi.fn(),
+    connect: vi.fn().mockResolvedValue(undefined),
+    close: vi.fn().mockResolvedValue(undefined),
+  }
+}
+
+// ---- Test harness helper ----
+
+async function mountRegistry(): Promise<Context> {
+  const ctx = new Context()
+  await ctx.plugin(SystemPrompt)
+  await ctx.plugin(ToolRegistry)
+  return ctx
+}
+
+const defaultOpts: ToolBridgeOptions = {
+  serverName: 'srv',
+  toolCallTimeoutMs: 60_000,
+}
+
+// ---- Tests ----
+
+describe('publicToolName', () => {
+  it('joins clean names verbatim', () => {
+    expect(publicToolName('github', 'create_issue')).toBe('mcp__github__create_issue')
+    expect(publicToolName('everything', 'get-sum')).toBe('mcp__everything__get-sum')
+  })
+
+  it('replaces invalid characters and appends an identity hash', () => {
+    const name = publicToolName('srv', 'admin.reset')
+    expect(name).toMatch(/^mcp__srv__admin_reset_[0-9a-f]{12}$/)
+    expect(name.length).toBeLessThanOrEqual(64)
+  })
+
+  it('truncates over-long names and appends an identity hash', () => {
+    const rawName = 'a'.repeat(80)
+    const name = publicToolName('srv', rawName)
+    expect(name).toHaveLength(64)
+    expect(name).toMatch(/_[0-9a-f]{12}$/)
+    expect(name.startsWith('mcp__srv__aaa')).toBe(true)
+  })
+
+  it('is deterministic and collision-free for distinct identities', () => {
+    // Two raw names that normalize to the same base must not collapse.
+    const a = publicToolName('srv', 'admin.reset')
+    const b = publicToolName('srv', 'admin_reset')
+    expect(a).toBe(publicToolName('srv', 'admin.reset'))
+    expect(a).not.toBe(b)
+  })
+})
+
+describe('syncTools', () => {
+  let ctx: Context
+
+  beforeEach(async () => {
+    ctx = await mountRegistry()
+  })
+
+  it('registers tools under server-qualified public names', async () => {
+    const client = createMockClient([
+      { name: 'greet', description: 'Say hello', inputSchema: { type: 'object', properties: { name: { type: 'string' } } } },
+      { name: 'add', description: 'Add numbers', inputSchema: { type: 'object', properties: {} } },
+    ])
+
+    const disposers = await syncTools(client as never, ctx, defaultOpts, new Map())
+
+    expect(disposers.size).toBe(2)
+    expect(ctx.tools.get('mcp__srv__greet')).toBeDefined()
+    expect(ctx.tools.get('mcp__srv__add')).toBeDefined()
+    // Raw names are NOT registered.
+    expect(ctx.tools.get('greet')).toBeUndefined()
+    expect(ctx.tools.get('add')).toBeUndefined()
+  })
+
+  it('lets two servers publish the same raw name side by side', async () => {
+    const clientA = createMockClient([{ name: 'search', inputSchema: { type: 'object' } }])
+    const clientB = createMockClient([{ name: 'search', inputSchema: { type: 'object' } }])
+
+    await syncTools(clientA as never, ctx, { ...defaultOpts, serverName: 'github' }, new Map())
+    await syncTools(clientB as never, ctx, { ...defaultOpts, serverName: 'web' }, new Map())
+
+    expect(ctx.tools.get('mcp__github__search')).toBeDefined()
+    expect(ctx.tools.get('mcp__web__search')).toBeDefined()
+  })
+
+  it('coexists with a native tool of the same raw name', async () => {
+    ctx.tools.register({
+      name: 'search',
+      description: 'Native search',
+      parameters: { type: 'object' },
+      execute: async () => [{ type: 'text', text: 'native' }],
+    })
+    const client = createMockClient([{ name: 'search', inputSchema: { type: 'object' } }])
+
+    await syncTools(client as never, ctx, defaultOpts, new Map())
+
+    expect(ctx.tools.get('search')).toBeDefined()
+    expect(ctx.tools.get('mcp__srv__search')).toBeDefined()
+    const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'search', arguments: {} })
+    expect(result.content[0]).toEqual({ type: 'text', text: 'native' })
+  })
+
+  it('rejects a tool list where one raw name appears twice', async () => {
+    const client = createMockClient([
+      { name: 'dup', inputSchema: { type: 'object' } },
+      { name: 'dup', inputSchema: { type: 'object' } },
+    ])
+
+    await expect(syncTools(client as never, ctx, defaultOpts, new Map()))
+      .rejects.toThrow(/listed tool "dup" more than once/)
+    // Nothing registered, previous generation untouched (it was empty).
+    expect(ctx.tools.get('mcp__srv__dup')).toBeUndefined()
+  })
+
+  it('keeps the previous generation when the fetch phase fails', async () => {
+    const client = createMockClient([{ name: 'stable', inputSchema: { type: 'object' } }])
+    const first = await syncTools(client as never, ctx, defaultOpts, new Map())
+    expect(ctx.tools.get('mcp__srv__stable')).toBeDefined()
+
+    client.listTools.mockRejectedValue(new Error('network down'))
+    await expect(syncTools(client as never, ctx, defaultOpts, first)).rejects.toThrow('network down')
+
+    // The previous generation is still live.
+    expect(ctx.tools.get('mcp__srv__stable')).toBeDefined()
+  })
+
+  it('rolls back the whole generation when a foreign tool squats on the namespace', async () => {
+    // A foreign registration occupies one of this server's public names.
+    ctx.tools.register({
+      name: 'mcp__srv__taken',
+      description: 'Squatter',
+      parameters: { type: 'object' },
+      execute: async () => [{ type: 'text', text: 'squatter' }],
+    })
+    const client = createMockClient([
+      { name: 'free', inputSchema: { type: 'object' } },
+      { name: 'taken', inputSchema: { type: 'object' } },
+    ])
+
+    const disposers = await syncTools(client as never, ctx, defaultOpts, new Map())
+
+    // All-or-nothing: the non-conflicting tool is rolled back too.
+    expect(disposers.size).toBe(0)
+    expect(ctx.tools.get('mcp__srv__free')).toBeUndefined()
+    // The squatter is untouched.
+    expect(ctx.tools.get('mcp__srv__taken')).toBeDefined()
+  })
+
+  it('unregisters previous tools before re-syncing', async () => {
+    const client = createMockClient([
+      { name: 'old_tool', inputSchema: { type: 'object' } },
+    ])
+
+    const firstDisposers = await syncTools(client as never, ctx, defaultOpts, new Map())
+    expect(ctx.tools.get('mcp__srv__old_tool')).toBeDefined()
+
+    // Second sync with different tools should remove old_tool.
+    client.listTools.mockResolvedValue({ tools: [{ name: 'new_tool', inputSchema: { type: 'object' } }], nextCursor: undefined })
+    const secondDisposers = await syncTools(client as never, ctx, defaultOpts, firstDisposers)
+
+    expect(ctx.tools.get('mcp__srv__old_tool')).toBeUndefined()
+    expect(ctx.tools.get('mcp__srv__new_tool')).toBeDefined()
+    expect(secondDisposers.size).toBe(1)
+  })
+
+  it('drains paginated listTools responses', async () => {
+    const client = createMockClient([])
+    client.listTools
+      .mockResolvedValueOnce({ tools: [{ name: 'page1', inputSchema: { type: 'object' } }], nextCursor: 'cursor1' })
+      .mockResolvedValueOnce({ tools: [{ name: 'page2', inputSchema: { type: 'object' } }], nextCursor: undefined })
+
+    const disposers = await syncTools(client as never, ctx, defaultOpts, new Map())
+
+    expect(disposers.size).toBe(2)
+    expect(ctx.tools.get('mcp__srv__page1')).toBeDefined()
+    expect(ctx.tools.get('mcp__srv__page2')).toBeDefined()
+  })
+})
+
+describe('tool execution', () => {
+  let ctx: Context
+
+  beforeEach(async () => {
+    ctx = await mountRegistry()
+  })
+
+  it('calls MCP callTool with the RAW name and returns text content', async () => {
+    const client = createMockClient(
+      [{ name: 'echo', inputSchema: { type: 'object' } }],
+      { content: [{ type: 'text', text: 'hello world' }] },
+    )
+
+    await syncTools(client as never, ctx, defaultOpts, new Map())
+    const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'mcp__srv__echo', arguments: { msg: 'hi' } })
+
+    expect(result.isError).toBe(false)
+    expect(result.content).toEqual([{ type: 'text', text: 'hello world' }])
+    // The wire sees the raw MCP name, never the public name.
+    expect(client.callTool).toHaveBeenCalledWith(
+      { name: 'echo', arguments: { msg: 'hi' } },
+      undefined,
+      expect.objectContaining({ timeout: 60_000 }),
+    )
+  })
+
+  it('sends the raw name for normalized public names', async () => {
+    const client = createMockClient(
+      [{ name: 'admin.reset', inputSchema: { type: 'object' } }],
+      { content: [{ type: 'text', text: 'reset done' }] },
+    )
+
+    await syncTools(client as never, ctx, defaultOpts, new Map())
+    const publicName = publicToolName('srv', 'admin.reset')
+    const result = await ctx.tools.execute({ callId: CallId('c1'), name: publicName, arguments: {} })
+
+    expect(result.isError).toBe(false)
+    expect(client.callTool).toHaveBeenCalledWith(
+      { name: 'admin.reset', arguments: {} },
+      undefined,
+      expect.anything(),
+    )
+  })
+
+  it('joins multiple text blocks with newline', async () => {
+    const client = createMockClient(
+      [{ name: 'multi', inputSchema: { type: 'object' } }],
+      { content: [{ type: 'text', text: 'line1' }, { type: 'text', text: 'line2' }] },
+    )
+
+    await syncTools(client as never, ctx, defaultOpts, new Map())
+    const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'mcp__srv__multi', arguments: {} })
+
+    expect(result.content).toEqual([{ type: 'text', text: 'line1\nline2' }])
+  })
+
+  it('discards image content with placeholder', async () => {
+    const client = createMockClient(
+      [{ name: 'img', inputSchema: { type: 'object' } }],
+      { content: [{ type: 'text', text: 'before' }, { type: 'image', mimeType: 'image/png' }] },
+    )
+
+    await syncTools(client as never, ctx, defaultOpts, new Map())
+    const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'mcp__srv__img', arguments: {} })
+
+    expect(result.content[0]).toEqual({ type: 'text', text: 'before\n[image: image/png, content discarded]' })
+  })
+
+  it('maps isError to an error result via throw', async () => {
+    const client = createMockClient(
+      [{ name: 'fail', inputSchema: { type: 'object' } }],
+      { content: [{ type: 'text', text: 'something went wrong' }], isError: true },
+    )
+
+    await syncTools(client as never, ctx, defaultOpts, new Map())
+    const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'mcp__srv__fail', arguments: {} })
+
+    expect(result.isError).toBe(true)
+    expect(result.content[0]).toEqual({ type: 'text', text: 'Error: something went wrong' })
+  })
+
+  it('passes abort signal to callTool', async () => {
+    const controller = new AbortController()
+    const client = createMockClient(
+      [{ name: 'slow', inputSchema: { type: 'object' } }],
+      { content: [{ type: 'text', text: 'done' }] },
+    )
+
+    await syncTools(client as never, ctx, defaultOpts, new Map())
+    await ctx.tools.execute({ callId: CallId('c1'), name: 'mcp__srv__slow', arguments: {}, signal: controller.signal })
+
+    expect(client.callTool).toHaveBeenCalledWith(
+      expect.anything(),
+      undefined,
+      expect.objectContaining({ signal: controller.signal }),
+    )
+  })
+
+  it('handles legacy toolResult shape', async () => {
+    const client = createMockClient(
+      [{ name: 'legacy', inputSchema: { type: 'object' } }],
+    )
+    client.callTool.mockResolvedValue({ toolResult: { key: 'value' } })
+
+    await syncTools(client as never, ctx, defaultOpts, new Map())
+    const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'mcp__srv__legacy', arguments: {} })
+
+    expect(result.isError).toBe(false)
+    expect(result.content[0]).toEqual({ type: 'text', text: '{"key":"value"}' })
+  })
+})
+
+describe('tool execution edge cases', () => {
+  let ctx: Context
+
+  beforeEach(async () => {
+    ctx = await mountRegistry()
+  })
+
+  it('handles audio content with placeholder', async () => {
+    const client = createMockClient(
+      [{ name: 'audio_tool', inputSchema: { type: 'object' } }],
+      { content: [{ type: 'audio', mimeType: 'audio/mp3' }] },
+    )
+
+    await syncTools(client as never, ctx, defaultOpts, new Map())
+    const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'mcp__srv__audio_tool', arguments: {} })
+
+    expect(result.content[0]).toEqual({ type: 'text', text: '[audio: audio/mp3, content discarded]' })
+  })
+
+  it('handles resource content with placeholder', async () => {
+    const client = createMockClient(
+      [{ name: 'res_tool', inputSchema: { type: 'object' } }],
+      { content: [{ type: 'resource' }] },
+    )
+
+    await syncTools(client as never, ctx, defaultOpts, new Map())
+    const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'mcp__srv__res_tool', arguments: {} })
+
+    expect(result.content[0]).toEqual({ type: 'text', text: '[resource: content discarded]' })
+  })
+
+  it('handles resource_link content with placeholder', async () => {
+    const client = createMockClient(
+      [{ name: 'link_tool', inputSchema: { type: 'object' } }],
+      { content: [{ type: 'resource_link' }] },
+    )
+
+    await syncTools(client as never, ctx, defaultOpts, new Map())
+    const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'mcp__srv__link_tool', arguments: {} })
+
+    expect(result.content[0]).toEqual({ type: 'text', text: '[resource: content discarded]' })
+  })
+
+  it('handles unknown content types', async () => {
+    const client = createMockClient(
+      [{ name: 'unknown_tool', inputSchema: { type: 'object' } }],
+      { content: [{ type: 'video' }] },
+    )
+
+    await syncTools(client as never, ctx, defaultOpts, new Map())
+    const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'mcp__srv__unknown_tool', arguments: {} })
+
+    expect(result.content[0]).toEqual({ type: 'text', text: '[unsupported content type: video]' })
+  })
+
+  it('handles image with missing mimeType (buggy server)', async () => {
+    const client = createMockClient(
+      [{ name: 'img2', inputSchema: { type: 'object' } }],
+      { content: [{ type: 'image' }] },
+    )
+
+    await syncTools(client as never, ctx, defaultOpts, new Map())
+    const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'mcp__srv__img2', arguments: {} })
+
+    expect(result.content[0]).toEqual({ type: 'text', text: '[image: unknown, content discarded]' })
+  })
+
+  it('handles audio with missing mimeType (buggy server)', async () => {
+    const client = createMockClient(
+      [{ name: 'audio_no_mime', inputSchema: { type: 'object' } }],
+      { content: [{ type: 'audio' }] },
+    )
+
+    await syncTools(client as never, ctx, defaultOpts, new Map())
+    const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'mcp__srv__audio_no_mime', arguments: {} })
+
+    expect(result.content[0]).toEqual({ type: 'text', text: '[audio: unknown, content discarded]' })
+  })
+
+  it('handles text block with missing text (buggy server)', async () => {
+    const client = createMockClient(
+      [{ name: 'notext', inputSchema: { type: 'object' } }],
+      { content: [{ type: 'text' }] },
+    )
+
+    await syncTools(client as never, ctx, defaultOpts, new Map())
+    const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'mcp__srv__notext', arguments: {} })
+
+    expect(result.content[0]).toEqual({ type: 'text', text: '(notext returned no text content)' })
+  })
+
+  it('handles empty content array', async () => {
+    const client = createMockClient(
+      [{ name: 'empty_tool', inputSchema: { type: 'object' } }],
+      { content: [] },
+    )
+
+    await syncTools(client as never, ctx, defaultOpts, new Map())
+    const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'mcp__srv__empty_tool', arguments: {} })
+
+    expect(result.content[0]).toEqual({ type: 'text', text: '(empty_tool returned no text content)' })
+  })
+
+
+  it('handles legacy toolResult with undefined value', async () => {
+    const client = createMockClient(
+      [{ name: 'legacy2', inputSchema: { type: 'object' } }],
+    )
+    client.callTool.mockResolvedValue({})
+
+    await syncTools(client as never, ctx, defaultOpts, new Map())
+    const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'mcp__srv__legacy2', arguments: {} })
+
+    expect(result.content[0]).toEqual({ type: 'text', text: '(no output)' })
+  })
+
+  it('handles isError with non-text content (fallback error message)', async () => {
+    const client = createMockClient(
+      [{ name: 'err_notext', inputSchema: { type: 'object' } }],
+      { content: [{ type: 'image', mimeType: 'image/png' }], isError: true },
+    )
+
+    await syncTools(client as never, ctx, defaultOpts, new Map())
+    const result = await ctx.tools.execute({ callId: CallId('c1'), name: 'mcp__srv__err_notext', arguments: {} })
+
+    expect(result.isError).toBe(true)
+    expect(result.content[0]).toEqual({ type: 'text', text: 'Error: [image: image/png, content discarded]' })
+  })
+
+
+  it('uses tool description when provided', async () => {
+    const client = createMockClient([
+      { name: 'described', description: 'A described tool', inputSchema: { type: 'object' } },
+    ])
+
+    await syncTools(client as never, ctx, defaultOpts, new Map())
+    const tool = ctx.tools.get('mcp__srv__described')
+    expect(tool?.description).toBe('A described tool')
+  })
+
+  it('uses empty description when tool has no description', async () => {
+    const client = createMockClient([
+      { name: 'nodesc', inputSchema: { type: 'object' } },
+    ])
+
+    await syncTools(client as never, ctx, defaultOpts, new Map())
+    const tool = ctx.tools.get('mcp__srv__nodesc')
+    expect(tool?.description).toBe('')
+  })
+})
+
+describe('createTransport', () => {
+  it('creates StdioClientTransport for stdio config', () => {
+    const config: Config = {
+      transport: 'stdio',
+      serverName: 'srv',
+      command: 'node',
+      args: ['server.js'],
+      env: {},
+      cwd: '/tmp',
+      toolCallTimeoutMs: 60_000,
+    }
+    const transport = createTransport(config)
+    expect(transport).toBeDefined()
+    expect(transport).toHaveProperty('start')
+    expect(transport).toHaveProperty('close')
+  })
+
+  it('creates StreamableHTTPClientTransport for http config without headers', () => {
+    const config: Config = {
+      transport: 'streamable-http',
+      serverName: 'srv',
+      url: 'http://localhost:3000/mcp',
+      headers: {},
+      toolCallTimeoutMs: 60_000,
+    }
+    const transport = createTransport(config)
+    expect(transport).toBeDefined()
+    expect(transport).toHaveProperty('start')
+    expect(transport).toHaveProperty('close')
+  })
+
+  it('creates StreamableHTTPClientTransport for http config with headers', () => {
+    const config: Config = {
+      transport: 'streamable-http',
+      serverName: 'srv',
+      url: 'http://localhost:3000/mcp',
+      headers: { Authorization: 'Bearer token' },
+      toolCallTimeoutMs: 60_000,
+    }
+    const transport = createTransport(config)
+    expect(transport).toBeDefined()
+    expect(transport).toHaveProperty('start')
+    expect(transport).toHaveProperty('close')
+  })
+
+  it('scrubs sensitive env vars and forwards the rest', () => {
+    const original = { ...process.env }
+    try {
+      process.env.SAFE_VAR = 'kept'
+      process.env.MY_SECRET = 'hidden'
+      process.env.API_KEY = 'hidden'
+      process.env.AUTH_TOKEN = 'hidden'
+
+      const config: Config = {
+        transport: 'stdio',
+        serverName: 'srv',
+        command: 'echo',
+        args: [],
+        env: { EXTRA: 'injected' },
+        cwd: '',
+        toolCallTimeoutMs: 60_000,
+      }
+      // createTransport internally calls buildChildEnv; we verify by inspecting
+      // the constructed StdioClientTransport. Since we can't inspect private fields
+      // easily, we at least confirm it doesn't throw and returns a transport.
+      const transport = createTransport(config)
+      expect(transport).toBeDefined()
+    } finally {
+      // Restore env
+      delete process.env.SAFE_VAR
+      delete process.env.MY_SECRET
+      delete process.env.API_KEY
+      delete process.env.AUTH_TOKEN
+      for (const key of Object.keys(process.env)) {
+        if (!(key in original)) Reflect.deleteProperty(process.env, key)
+      }
+    }
+  })
+
+  it('merges explicit env on top of scrubbed ambient env', () => {
+    const config: Config = {
+      transport: 'stdio',
+      serverName: 'srv',
+      command: 'echo',
+      args: [],
+      env: { CUSTOM: 'value' },
+      cwd: '',
+      toolCallTimeoutMs: 60_000,
+    }
+    const transport = createTransport(config)
+    expect(transport).toBeDefined()
+  })
+})
+
+describe('tool execution — non-object args fallback', () => {
+  let ctx: Context
+
+  beforeEach(async () => {
+    ctx = await mountRegistry()
+  })
+
+  it('coerces null args to empty object for callTool', async () => {
+    const client = createMockClient(
+      [{ name: 'coerce', inputSchema: { type: 'object' } }],
+      { content: [{ type: 'text', text: 'ok' }] },
+    )
+
+    await syncTools(client as never, ctx, defaultOpts, new Map())
+    // Simulate model emitting `null` as tool arguments (malformed).
+    await ctx.tools.execute({ callId: CallId('c1'), name: 'mcp__srv__coerce', arguments: null })
+
+    expect(client.callTool).toHaveBeenCalledWith(
+      { name: 'coerce', arguments: {} },
+      undefined,
+      expect.anything(),
+    )
+  })
+
+  it('coerces primitive string args to empty object for callTool', async () => {
+    const client = createMockClient(
+      [{ name: 'coerce2', inputSchema: { type: 'object' } }],
+      { content: [{ type: 'text', text: 'ok' }] },
+    )
+
+    await syncTools(client as never, ctx, defaultOpts, new Map())
+    await ctx.tools.execute({ callId: CallId('c1'), name: 'mcp__srv__coerce2', arguments: 'bad' })
+
+    expect(client.callTool).toHaveBeenCalledWith(
+      { name: 'coerce2', arguments: {} },
+      undefined,
+      expect.anything(),
+    )
+  })
+})
--- a/packages/mcp/mcp-client/tsconfig.json
+++ b/packages/mcp/mcp-client/tsconfig.json
@@ -0,0 +1,15 @@
+{
+  "extends": "../../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../../../vendor/cosmokit" },
+    { "path": "../../../vendor/cordis" },
+    { "path": "../../../vendor/schemastery" },
+    { "path": "../../llm/llm" },
+    { "path": "../../core/tools" }
+  ]
+}
--- a/packages/subagent/subagent-acp/README.md
+++ b/packages/subagent/subagent-acp/README.md
@@ -33,7 +33,7 @@ ACP advertises no start-time capabilities because this process cannot enforce th
  config:
    providerName: acp
    command: node
-    args: ['--import', 'tsx', './packages/ui/acp-agent/src/bin.ts', '--config', './examples/acp-agent/cordis.yml']
+    args: ['--import', 'tsx', './packages/examples/acp-demo/src/bin.ts', '--config', './examples/acp-agent/cordis.yml']
    permission: reject
    env:
      DEEPSEEK_API_KEY: !!js process.env.DEEPSEEK_API_KEY
--- a/packages/subagent/subagent-acp/tests/subagent-acp.e2e.ts
+++ b/packages/subagent/subagent-acp/tests/subagent-acp.e2e.ts
@@ -15,7 +15,7 @@ import * as acp from '../src/index.ts'
 */

 // The real acp-agent example: its bin + cordis.yml (the live DeepSeek config).
-const binScript = fileURLToPath(new URL('../../../ui/acp-agent/src/bin.ts', import.meta.url))
+const binScript = fileURLToPath(new URL('../../../examples/acp-demo/src/bin.ts', import.meta.url))
 const exampleConfig = fileURLToPath(new URL('../../../../examples/acp-agent/cordis.yml', import.meta.url))
 const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
 const repoTsconfig = fileURLToPath(new URL('../../../../tsconfig.json', import.meta.url))
--- a/packages/support/README.md
+++ b/packages/support/README.md
@@ -10,4 +10,4 @@ Packages that exist to serve development, testing, and the examples rather than
 | `llm-replay/` | Record/replay adapter: short-circuits `llm/stream` from a recorded session JSONL (keyless snapshot tests) | (listens on `llm/stream`) |
 | `subagent-mock/` | Scripted `SubagentProvider` for deterministic seam/tool tests | (registers on `ctx.subagents`) |

-`invariants` is development support but has no environment guard: it runs wherever registered, and the default `dsh-agent-core` bundle mounts it unconditionally. `llm-replay` backs the demos and the snapshot test tier under the per-file coverage gate. `acp-snapshot` carries the snapshot tier's harness/normalizer/suite machinery, while `loader-smoke` owns the parallel stdio/Loader process boundary used by keyless example e2e suites. `subagent-mock` exercises the real `ctx.subagents` load path without a model or child agent. A package graduates OUT of `support/` into a product group only when it gains documented product consumers.
+`invariants` is development support but has no environment guard: it runs wherever registered, and the default `dsh-agent-spine-demo` bundle mounts it unconditionally. `llm-replay` backs the demos and the snapshot test tier under the per-file coverage gate. `acp-snapshot` carries the snapshot tier's harness/normalizer/suite machinery, while `loader-smoke` owns the parallel stdio/Loader process boundary used by keyless example e2e suites. `subagent-mock` exercises the real `ctx.subagents` load path without a model or child agent. A package graduates OUT of `support/` into a product group only when it gains documented product consumers.
--- a/packages/support/acp-snapshot/README.md
+++ b/packages/support/acp-snapshot/README.md
@@ -21,7 +21,7 @@ const SCENARIOS: Scenario[] = [

 defineAcpSnapshotSuite({
  agent: { // absolute paths, resolved from the suite's own location
-    binScript: fileURLToPath(new URL('../../../packages/ui/acp-agent/src/bin.ts', import.meta.url)),
+    binScript: fileURLToPath(new URL('../../../packages/examples/acp-demo/src/bin.ts', import.meta.url)),
    configPath: fileURLToPath(new URL('../cordis.yml', import.meta.url)),
    tsconfigPath: fileURLToPath(new URL('../../../tsconfig.json', import.meta.url)),
  },
--- a/packages/support/acp-snapshot/src/harness.ts
+++ b/packages/support/acp-snapshot/src/harness.ts
@@ -37,7 +37,7 @@ const tsxLoader = fileURLToPath(import.meta.resolve('tsx'))
 * them from its own `import.meta.url`.
 */
 export interface AgentUnderTest {
-  /** The agent bin entry (e.g. `packages/ui/acp-agent/src/bin.ts`), run unbuilt via tsx. */
+  /** The agent bin entry (e.g. `packages/examples/acp-demo/src/bin.ts`), run unbuilt via tsx. */
  binScript: string
  /**
   * The example's live `cordis.yml`. Under `DSH_SNAPSHOT=replay` the bin swaps
--- a/packages/support/invariants/README.md
+++ b/packages/support/invariants/README.md
@@ -2,7 +2,7 @@

 Runtime event-contract assertions intended for development diagnostics. This pure-listener plugin checks relationships among session events, agent states, scoped dispatches, and model requests; it does not own or change product behavior.

-The plugin has no environment guard: it is active wherever it is registered. The default [`dsh-agent-core`](../../core/agent-core/README.md) bundle mounts it unconditionally; a custom composition can omit it when the runtime cost is undesirable. It doubles as executable documentation of the event taxonomy — the assertions *are* the contract.
+The plugin has no environment guard: it is active wherever it is registered. The default [`dsh-agent-spine-demo`](../../examples/agent-spine-demo/README.md) bundle mounts it unconditionally; a custom composition can omit it when the runtime cost is undesirable. It doubles as executable documentation of the event taxonomy — the assertions *are* the contract.

 Session itself owns immutable log storage in every composition: it takes one lossless JSON snapshot of each accepted event, deep-freezes that record, and exposes the log through immutable array snapshots. The invariants plugin checks the cross-record and cross-seam rules that storage immutability cannot express.

--- a/packages/support/invariants/src/index.ts
+++ b/packages/support/invariants/src/index.ts
@@ -2,7 +2,7 @@
 * Runtime listeners that fail loudly when cross-event contracts are broken:
 * turn and step nesting, scoped dispatch, status transitions, and request
 * reconstruction. The plugin has no environment guard and is active wherever
- * mounted, including the default `dsh-agent-core` bundle; custom compositions
+ * mounted, including the default `dsh-agent-spine-demo` bundle; custom compositions
 * may omit it. Sessions still own event snapshots and freezing.
 * @module @deepseek-ai/dsh-invariants
 */
--- a/packages/todo/README.md
+++ b/packages/todo/README.md
@@ -6,4 +6,4 @@ The model-facing todo tool. A single **product** package — there is no interfa
 |---|---|---|
 | `tool-todo/` | Model-facing `todo_write` tool; writes the whole list to the session log (`todo/write`) | (registers on `ctx.tools`) |

-The list lives on the event-sourced session log (`SessionEventMap['todo/write']`, owned by [`dsh-session`](../core/session)); this package is the thin consumer that appends the snapshot. UIs render off `session/event`: the [stdio app's readline UI](../ui/stdio-agent) prints the list, the [ACP bridge](../ui/acp) maps it to a `plan` sessionUpdate.
+The list lives on the event-sourced session log (`SessionEventMap['todo/write']`, owned by [`dsh-session`](../core/session)); this package is the thin consumer that appends the snapshot. UIs render off `session/event`: the [stdio app's readline UI](../examples/stdio-demo) prints the list, the [ACP bridge](../ui/acp) maps it to a `plan` sessionUpdate.
--- a/packages/todo/tool-todo/README.md
+++ b/packages/todo/tool-todo/README.md
@@ -18,7 +18,7 @@ Beyond the schema's type/required/enum checks, `execute` rejects an empty or dup

 ## Rendering

-The tool writes only the session event; it does not render. UIs subscribe to `session/event` and render the `todo/write` data themselves: the [stdio app's readline UI](../../ui/stdio-agent) prints a glyphed checklist, and the [ACP bridge](../../ui/acp) maps the list to a `plan` sessionUpdate (synthesizing the `priority` ACP requires).
+The tool writes only the session event; it does not render. UIs subscribe to `session/event` and render the `todo/write` data themselves: the [stdio app's readline UI](../../examples/stdio-demo) prints a glyphed checklist, and the [ACP bridge](../../ui/acp) maps the list to a `plan` sessionUpdate (synthesizing the `priority` ACP requires).

 ## Export shape

--- a/packages/ui/README.md
+++ b/packages/ui/README.md
@@ -10,14 +10,11 @@ Integrations that expose the agent to an external editor or client. These are **
 | `user-interaction/` | Abstract human question/answer seam used by UI-backed confirmation tools | `ctx.userInteraction` |
 | `tool-ask-user/` | Model-facing `ask_user_question` tool over `ctx.userInteraction` | (registers on `ctx.tools`) |
 | `stdio/` | Terminal readline channel over `ctx.agents`, `session/event`, and `ctx.userInteraction`; agent lifecycle stays with app/developer code | (drives `ctx.agents`) |
-| `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`) |
 | `jsonrpc/` | Stdio JSON-RPC server for out-of-process SDK clients | (drives `ctx.agents`) |
-| `jsonrpc-agent/` | Bin-only SDK runtime app that boots an external `cordis.yml` | (`bin` only) |
 | `app-boot/` | Shared boot glue for the 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 `jsonrpc` plugin is the SDK-client sibling of the `acp` bridge (a JSON-RPC server over `ctx.agents` for out-of-process SDK clients rather than editors). The [`stdio`](stdio/README.md) plugin is the unstructured readline analogue of the `acp` bridge; app bundles and SDK projects compose it explicitly with the services and tools their product profile selects.

 `user-approval`, `user-interaction`, and `tool-ask-user` live here because asking a human is a UI-backed product affordance, not part of the providerless core spine. `user-approval` owns the one-shot `ctx.approval` decision mechanism and its policy tier; answerers remain with their UI channel owners. `user-interaction` remains provider-neutral (`ctx.userInteraction`), while `tool-ask-user` is its model-facing consumer and the app/bridge packages provide concrete providers.

-`stdio-agent` and `acp-agent` compose the [`agent-core`](../core/agent-core/README.md) spine with their front-door plugins and own their boot bins; a leaf `cordis.yml` supplies backends and optional tools. `jsonrpc-agent` is bin-only because its external config also chooses the serving `jsonrpc` plugin. Each lives in `ui/` as a user-facing front door whose artifact owns its stdout policy.
+The runnable app bundles that bake these bridges into boot bins — the stdio chat app, the ACP server app, and the JSON-RPC SDK-runtime bin — live in [`examples/`](../examples/README.md) (`stdio-demo`, `acp-demo`, `jsonrpc-demo`), each composed over the [`agent-spine-demo`](../examples/agent-spine-demo/README.md) bundle. `ui/` keeps the reusable bridge/channel plugins and the `app-boot` glue; each front door owns its stdout policy, and a leaf `cordis.yml` supplies backends and optional tools.
--- a/packages/ui/app-boot/README.md
+++ b/packages/ui/app-boot/README.md
@@ -1,6 +1,6 @@
 # `@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.
+Shared boot glue for the app bins ([`dsh-stdio-demo`](../../examples/stdio-demo/README.md), [`dsh-acp-demo`](../../examples/acp-demo/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 |
 |---|---|
--- a/packages/ui/app-boot/src/index.ts
+++ b/packages/ui/app-boot/src/index.ts
@@ -1,5 +1,5 @@
 /**
- * Shared boot glue for the app bins (`dsh-stdio-agent`, `dsh-acp-agent`): load the gitignored
+ * Shared boot glue for the app bins (`dsh-stdio-demo`, `dsh-acp-demo`): 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.
 * @module @deepseek-ai/dsh-app-boot
--- a/packages/ui/jsonrpc/README.md
+++ b/packages/ui/jsonrpc/README.md
@@ -1,6 +1,6 @@
 # @deepseek-ai/dsh-jsonrpc

-Stdio JSON-RPC plugin for out-of-process SDK clients such as Python `deepseek_harness`. [`HarnessSdkServer`](src/server.ts) handles `initialize` → `session/prompt` → `shutdown` plus session and subagent notifications over [`JsonRpcLineTransport`](src/transport.ts). This package owns the protocol; [`jsonrpc-agent`](../jsonrpc-agent/README.md) boots the external `cordis.yml` that chooses the surrounding runtime. See the [single-executable RFC](../../../docs/rfc/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md) for the distribution design.
+Stdio JSON-RPC plugin for out-of-process SDK clients such as Python `deepseek_harness`. [`HarnessSdkServer`](src/server.ts) handles `initialize` → `session/prompt` → `shutdown` plus session and subagent notifications over [`JsonRpcLineTransport`](src/transport.ts). This package owns the protocol; [`jsonrpc-agent`](../../examples/jsonrpc-demo/README.md) boots the external `cordis.yml` that chooses the surrounding runtime. See the [single-executable RFC](../../../docs/rfc/implemented/architecture/2026-07-10-single-file-executable-sdk-runtime-distribution.md) for the distribution design.

 ## Wiring

--- a/packages/ui/jsonrpc/package.json
+++ b/packages/ui/jsonrpc/package.json
@@ -35,7 +35,7 @@
  "devDependencies": {
    "@cordisjs/plugin-loader": "workspace:^",
    "@deepseek-ai/dsh-agent": "workspace:^",
-    "@deepseek-ai/dsh-agent-core": "workspace:^",
+    "@deepseek-ai/dsh-agent-spine-demo": "workspace:^",
    "@deepseek-ai/dsh-llm": "workspace:^",
    "@deepseek-ai/dsh-llm-deepseek": "workspace:^",
    "@deepseek-ai/dsh-session": "workspace:^",
--- a/packages/ui/jsonrpc/tests/plugin-apply.spec.ts
+++ b/packages/ui/jsonrpc/tests/plugin-apply.spec.ts
@@ -6,7 +6,7 @@ import { tmpdir } from 'node:os'
 import { PassThrough, Writable } from 'node:stream'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
-import * as agentCore from '@deepseek-ai/dsh-agent-core'
+import * as agentCore from '@deepseek-ai/dsh-agent-spine-demo'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
 import * as jsonrpc from '../src/index.ts'

--- a/packages/ui/jsonrpc/tests/server.spec.ts
+++ b/packages/ui/jsonrpc/tests/server.spec.ts
@@ -7,7 +7,7 @@ import { afterEach, describe, expect, it, vi } from 'vitest'
 import { Context } from 'cordis'
 import { AgentId, type Agent, type AgentHandle } from '@deepseek-ai/dsh-agent'
 import { SessionId } from '@deepseek-ai/dsh-session'
-import * as agentCore from '@deepseek-ai/dsh-agent-core'
+import * as agentCore from '@deepseek-ai/dsh-agent-spine-demo'
 import SessionPersistenceJsonl from '@deepseek-ai/dsh-session-persistence-jsonl'
 import * as LlmDeepSeek from '@deepseek-ai/dsh-llm-deepseek'
 import SubagentService, { type SubagentRunEndInfo } from '@deepseek-ai/dsh-subagent'