docs: trim generated prose

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

@@ -1,29 +1,8 @@
 #!/usr/bin/env node
 /**
- * The `dsh-acp-agent` bin: boot the ACP server from a leaf `cordis.yml` that
- * loads the {@link @deepseek-ai/dsh-acp-agent} app plugin (plus an LLM adapter
- * and a bash executor), speaking ACP JSON-RPC on stdio. The shared boot glue —
- * `.env` loading, the fail-loud Loader guards, snapshot-aware config
- * resolution, the settle-the-tree boot sequence — lives in
- * {@link @deepseek-ai/dsh-app-boot}; this bin owns only the ACP-specific
- * lifecycle:
- *
- *  - `.env` loading is SKIPPED in snapshot REPLAY so a stray key can never
- *    trigger a live model call.
- *  - `DSH_SNAPSHOT=replay` swaps the given `cordis.yml` for its sibling
- *    `cordis.snapshot.yml` (the keyless replay tree: `llm-replay` in place of
- *    `llm-deepseek`).
- *  - In a snapshot run the harness closes stdin when done, so dispose the
- *    context (flushing persistence) and exit cleanly. In a normal editor
- *    session stdin stays open for the connection's lifetime (the editor kills
- *    the process), so the EOF handler never fires.
- *
- * IMPORTANT: stdout is the ACP JSON-RPC channel. This bin writes diagnostics to
- * STDERR only (the app plugin loads no stdout logger, and the shared guards
- * write to stderr); a stray stdout write corrupts the protocol frames.
- *
- * Usage: `dsh-acp-agent [path-to-cordis.yml]` (default `./cordis.yml`).
- *
+ * The `dsh-acp-agent` bin: boot the ACP server from a leaf `cordis.yml` that loads the {@link
+ * @deepseek-ai/dsh-acp-agent} app plugin (plus an LLM adapter and a bash executor), speaking
+ * ACP JSON-RPC on stdio.
  * @module @deepseek-ai/dsh-acp-agent/bin
  */
 

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

@@ -1,32 +1,7 @@
 /**
- * The ACP server app: the default agent spine ({@link
- * @deepseek-ai/dsh-agent-core}) plus the coupled front-door cluster an ACP
- * server needs — JSONL session persistence and the {@link @deepseek-ai/dsh-acp}
- * bridge, and DELIBERATELY NOTHING that writes to stdout.
- *
- * The cluster is the OPPOSITE of {@link @deepseek-ai/dsh-stdio-agent}'s, and
- * baking it in is the whole point: an ACP server speaks JSON-RPC on stdout, so
- * a stray console logger would corrupt the protocol frames (the [stdout-purity
- * footgun]). This package contains NO console-logger entry, NO `hmr` (the editor
- * owns the subprocess), and pre-creates NO agents (ACP `session/new` creates
- * them on demand) — so the default front door has no logger entry to get wrong.
- * (A leaf `cordis.yml` could still add a sibling `@cordisjs/plugin-logger-console`,
- * which this app does not prevent — so the rule "never add a stdout logger to an
- * ACP leaf" still stands; the app just gives the leaf nothing to misconfigure.)
- *
- * The leaf supplies the swappable backends: the LLM adapter (`llm-deepseek` for
- * the real model, `llm-replay` for keyless snapshot replay), the bash executor
- * (`bash-local`), and any optional product tools it wants to expose. This app's
- * {@link Config} (model, system prompt, persistence root) routes each value to
- * where it is wired — model/prompt onto the bridge's per-session agent
- * template, the root onto the JSONL backend.
- *
- * Plugin export shape: named `name`/`Config`/`apply`, NO default export — the
- * cordis Loader's `unwrapExports` does `exports.default ?? exports`, so a stray
- * default would collapse the module to the bare `apply` and drop the `Config`
- * namespace (see docs/postmortem/0001 — the exact bug that shipped here once).
- * The keyless ACP snapshot/Loader-path tests guard this end-to-end.
- *
+ * The ACP server app: the default agent spine ({@link @deepseek-ai/dsh-agent-core}) plus the
+ * coupled front-door cluster an ACP server needs — JSONL session persistence and the {@link
+ * @deepseek-ai/dsh-acp} bridge, and deliberately NOTHING that writes to stdout.
  * @module @deepseek-ai/dsh-acp-agent
  */
 

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

@@ -139,14 +139,7 @@ describe('dsh-acp-agent composition', () => {
   })
 
   it('has the namespace-plugin export shape (no stray default) so the Loader keeps name/Config/apply', () => {
-    // Postmortem 0001 guard: a stray `export default apply` makes the Loader's
-    // `unwrapExports` (`exports.default ?? exports`) collapse the module to the
-    // bare `apply` function, DROPPING the named `name`/`Config`. This package has
-    // no `inject` export, so that collapse would NOT crash at load (the keyless
-    // bin smoke would still answer `initialize`) — it would silently lose its
-    // config schema. So guard the shape directly here: assert no `default`
-    // export, and that the real `unwrapExports` leaves `name`/`Config`/`apply`
-    // intact. Adding `export default` to src/index.ts fails this test.
+    // Loader must retain the namespace so name, Config, and apply survive unwrapping.
     expect('default' in acpAgent).toBe(false)
     expect(typeof acpAgent.apply).toBe('function')
 

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

@@ -18,20 +18,9 @@ import { Readable, Writable } from 'node:stream'
 import { afterEach, describe, expect, it } from 'vitest'
 
 /**
- * BUILT-ARTIFACT smoke for the published `dsh-acp-agent` bin. `load-path.e2e.ts`
- * boots `src/bin.ts` under tsx — but the package's `bin` field points at
- * `lib/bin.js`, run under plain `node` by a real consumer. This runs the REAL
- * `lib/bin.js` under `node` (NOT tsx) and asserts it answers an `initialize`
- * JSON-RPC frame, so a regression in the published entry (a settle race that
- * exits before the bridge attaches, a stdout logger leaking onto the protocol)
- * fails here.
- *
- * It build-gates: SKIPS if `lib/bin.js` is absent (suite run without
- * `pnpm run build`); CI runs it after the build step. Setup mirrors a real
- * install (a temp dir whose `node_modules` symlinks the built packages) and runs
- * `node --expose-internals` (the cordis Loader resolves bare plugin specifiers
- * via its internal module loader, active only under that flag). KEYLESS:
- * `initialize` never reaches the model; a dummy key lets `llm-deepseek` boot.
+ * Built-ARTIFACT smoke for the published `dsh-acp-agent` bin. `load-path.e2e.ts` boots
+ * `src/bin.ts` under tsx — but the package's `bin` field points at `lib/bin.js`, run under
+ * plain `node` by a real consumer.
  */
 
 const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
@@ -48,12 +37,7 @@ const vendorPackages = [
   'cordis', 'loader', 'include', 'timer', 'hmr', 'logger-console',
   'schemastery', 'cosmokit',
 ]
-// Third-party deps the ACP bridge needs at runtime. They are declared by
-// `dsh-acp` (NOT by `acp-agent`), so they live under `packages/ui/acp/node_modules`
-// and are NOT necessarily hoisted where THIS test file can resolve them — pnpm's
-// strict layout only exposes a package's deps under that package. Resolve each
-// from the `ui/acp` package directory (the one that declares it) so the lookup
-// works regardless of hoisting, then symlink it into the consumer for plain node.
+// Third-party deps the ACP bridge needs at runtime.
 const npmDeps = ['@agentclientprotocol/sdk', 'zod']
 const acpPkgDir = join(repoRoot, 'packages/ui/acp')
 
@@ -161,18 +145,14 @@ describe.skipIf(!existsSync(acpBin))('dsh-acp-agent BUILT bin (node lib/bin.js,
   }, 30_000)
 
   it('fails LOUD (non-zero exit + stderr) on a config whose directory does not exist', async () => {
-    // A typo'd config path must fail clearly, not exit 0. The include plugin
-    // itself cannot be imported from a non-existent dir; the Loader logs that and
-    // leaves the entry with no fiber, which boot()'s entry-load check throws on.
+    // A typo'd config path must fail clearly, not exit 0.
     const { code, stderr } = await runBinExpectingExit('/nonexistent/dir/cordis.yml')
     expect(code).not.toBe(0)
     expect(stderr).toContain('failed to load')
   }, 30_000)
 
   it('fails LOUD (non-zero exit + stderr) on a missing config file in a real directory', async () => {
-    // The directory exists (the include imports), but the file does not — the
-    // include's init throws "config file not found", which surfaces as an
-    // unhandled rejection the fail-loud guard turns into a non-zero exit.
+    // Existing directory plus missing config exercises the include plugin's fail-loud path.
     consumer = await makeConsumer()
     const { code, stderr } = await runBinExpectingExit('./does-not-exist.yml', consumer)
     expect(code).not.toBe(0)

packages/ui/acp-agent/tests/load-path.e2e.ts

@@ -17,22 +17,9 @@ import {
 } from '@agentclientprotocol/sdk'
 
 /**
- * REAL-load-path smoke for @deepseek-ai/dsh-acp-agent: boot the app through its
- * own `bin` (the demo:acp entry) as a subprocess, driving the cordis Loader and
- * `unwrapExports` over a minimal `cordis.yml` that loads THIS package. This is
- * the guard a hand-built `ctx.plugin({...})` mount structurally cannot be — that
- * bypasses `unwrapExports`, the exact path that once dropped the bridge's
- * `inject` and shipped (docs/postmortem/0001). It exercises the headline ACP
- * operations end-to-end: `initialize` → `session/new` → `session/load`.
- *
- * KEYLESS: `session/new` and `session/load` reach the agent FACTORY but never
- * the model (no prompt is sent), so no DEEPSEEK_API_KEY is needed. A dummy key
- * lets `llm-deepseek`'s `apply()` (key-PRESENT check only) boot the tree.
- *
- * The config is written into a temp dir whose cwd IS the session workspace, so
- * the bash workdir validation passes. We point tsx at the repo-root tsconfig
- * (TSX_TSCONFIG_PATH) because the child's cwd is outside the repo and the
- * unbuilt `paths` map is found by searching UP from cwd.
+ * real-load-path smoke for @deepseek-ai/dsh-acp-agent: boot the app through its own `bin` (the
+ * demo:acp entry) as a subprocess, driving the cordis Loader and `unwrapExports` over a
+ * minimal `cordis.yml` that loads THIS package.
  */
 
 const binScript = fileURLToPath(new URL('../src/bin.ts', import.meta.url))
@@ -131,13 +118,8 @@ describe('dsh-acp-agent real-load-path smoke (bin + Loader, keyless)', () => {
     const { sessionId } = await client.newSession({ cwd, mcpServers: [] })
     expect(sessionId).toBeTruthy()
 
-    // session/load reaches the resume FACTORY + persistence without the model:
-    // load an UNKNOWN id (loading the live `sessionId` would correctly reject as
-    // "already loaded"). The bridge consults `sessionPersistence.list()` then
-    // `agents.resume()`, both of which run from the JSON-RPC read loop OUTSIDE
-    // the bridge's inject scope — the exact path postmortem 0001 crashed. A
-    // healthy tree rejects with a not-found error; a broken export shape would
-    // instead throw "cannot get property … without inject" before reaching it.
+    // session/load reaches the resume FACTORY + persistence without the model: load an UNKNOWN
+    // id (loading the live `sessionId` would correctly reject as "already loaded").
     const unknownId = '00000000-0000-4000-8000-000000000000'
     await client.loadSession({ sessionId: unknownId, cwd, mcpServers: [] }).then(
       () => { throw new Error('expected session/load of an unknown id to reject') },