docs: rebalance prose cleanup and add trimming skill

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

@@ -1,7 +1,8 @@
 #!/usr/bin/env node
 /**
- * The `dsh-stdio-agent` bin: boot a Cordis app from a leaf `cordis.yml` that loads the {@link
- * @deepseek-ai/dsh-stdio-agent} app plugin (plus a backend LLM adapter and a bash executor).
+ * Boot a stdio app from a leaf `cordis.yml`; usage is `dsh-stdio-agent [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
  */
 

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

@@ -3,6 +3,9 @@
  * coupled front-door cluster a terminal chat needs — a console logger, the readline UI (the
  * in-package `stdio-chat` module), JSONL session persistence, and a pre-created `main` agent
  * the UI drives.
+ * 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
  */
 

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

@@ -1,6 +1,7 @@
 /**
- * The stdio app's readline UI: reads lines from stdin → `agent.send()`/ `steer()`, and renders
- * the durable transcript to stdout.
+ * The stdio app's readline UI: reads lines from stdin into `agent.send()` or
+ * `steer()`, renders the durable event stream to stdout, and exits piped input
+ * only after submitted work reaches idle.
  * @module @deepseek-ai/dsh-stdio-agent/stdio-chat
  */
 
@@ -83,16 +84,15 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt
   const agentId = AgentId(config.agent ?? 'main')
   const { input, output, exit } = runtime
 
-  // Render label lookup: the `turn/start` session event carries only the turn number, so to
-  // print the short agent id (`[main turn 1]`) we map the session's id to its agent's id.
+  // Session ids need not equal agent ids. Seed existing agents before listening
+  // so a pre-created or HMR-surviving agent still gets its short render label.
   const labelBySession = new Map<string, string>()
   for (const agent of ctx.agents.list()) labelBySession.set(agent.session.header.id, agent.id)
   ctx.on('agent/created', (agent) => { labelBySession.set(agent.session.header.id, agent.id) })
   ctx.on('agent/disposed', (agent) => { labelBySession.delete(agent.session.header.id) })
 
-  // Transcript rendering off the durable `session/event` feed — the assistant token stream,
-  // turn/step boundaries, tool activity, and todos all come from the one canonical stream (no
-  // agent/* mirrors).
+  // Render the canonical append order from session/event so reasoning state is
+  // deterministic across chunks and boundaries; there are no agent/* mirrors.
   let inReasoning = false
   ctx.on('session/event', (session, event) => {
     if (event.type === 'assistant/chunk') {
@@ -135,9 +135,9 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt
 
   ctx.effect(() => {
     const reader = createInterface({ input, output, terminal: isTTYPair(input, output) })
-    // Piped-input exit, once stdin reaches EOF: - If no line ever submitted work (empty stdin,
-    // blank-only lines), exit immediately — no turn will ever start, so there is nothing to
-    // wait for.
+    // On piped EOF, exit immediately if no work was submitted. Otherwise wait
+    // for a real running state followed by idle: sends do not synchronously mark
+    // running, and several queued lines may share one turn.
     let stdinClosed = false
     let disposed = false
     let submittedWork = false
@@ -155,7 +155,8 @@ export function createStdioChat(ctx: Context, config: Config, runtime: StdioRunt
         const agent = ctx.agents.get(agentId)
         if (agent && agent.status !== 'idle') return // a turn is still running
       }
-      // Let any final output flush, then exit.
+      // Let final output flush; track the timer so re-entry coalesces and HMR
+      // disposal can cancel it before it exits the replacement process.
       if (exitTimer !== undefined) {
         return // exit already scheduled — coalesce re-entrant calls
       }

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

@@ -7,13 +7,17 @@ import { fileURLToPath } from 'node:url'
 import { afterEach, describe, expect, it } from 'vitest'
 
 /**
- * Built-ARTIFACT smoke for the published `dsh-stdio-agent` bin.
+ * Published-entry smoke: run `lib/bin.js` under plain Node in a symlinked external consumer and
+ * require the banner plus echo round-trip. This catches built-only early-exit and config-resolution
+ * failures masked by tsx source smokes. It skips before build; `--expose-internals` enables Cordis
+ * bare-plugin loading, matching the demo command.
  */
 
 const repoRoot = fileURLToPath(new URL('../../../../', import.meta.url))
 const stdioBin = join(repoRoot, 'packages/ui/stdio-agent/lib/bin.js')
 
-// Workspace packages the stdio app's tree needs, by repo-relative path.
+// 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',
   'core/tools', 'core/agent-loop', 'llm/llm', 'bash/bash', 'bash/bash-local',
@@ -32,8 +36,9 @@ async function pkgName(absDir: string): Promise<string> {
 }
 
 /**
- * Build a temporary symlinked consumer for the stdio app. The optional disabled
- * broken entry verifies that load guards accept intentionally fiber-less entries.
+ * Build a temporary external consumer with built workspace/vendor links and a mock-backed config.
+ * The optional missing-but-disabled plugin verifies load guards accept intentionally fiber-less
+ * entries rather than treating them as import failures.
  */
 async function makeConsumer(welcome: string, disabledBrokenEntry = false): Promise<string> {
   const dir = await mkdtemp(join(tmpdir(), 'stdio-built-bin-'))
@@ -130,7 +135,8 @@ describe.skipIf(!existsSync(stdioBin))('dsh-stdio-agent BUILT bin (node lib/bin.
 
   it('boots cleanly when the config disables an (otherwise unresolvable) entry', async () => {
     // A `disabled: true` entry settles without a fiber by design; the fail-loud entry-load
-    // guard must not mistake it for a failed import.
+    // guard must not mistake it for a failed import. The nonexistent path makes that distinction
+    // observable while the successful round-trip proves boot continued.
     consumer = await makeConsumer('DISABLED-OK ready.', true)
     const { stdout, code, stderr } = await runBuiltBin(consumer, './cordis.yml', 'echo hi')
     expect(stderr).not.toContain('failed to load')
@@ -140,7 +146,8 @@ describe.skipIf(!existsSync(stdioBin))('dsh-stdio-agent BUILT bin (node lib/bin.
   }, 30_000)
 
   it('fails LOUD (non-zero exit + stderr) on a config whose directory does not exist', async () => {
-    // A consumer who typos the config path must get a clear failure, not silent success.
+    // A nonexistent directory prevents even the include plugin import. Loader leaves no fiber, and
+    // boot's settled-entry guard must turn that state into a clear non-zero failure.
     consumer = await makeConsumer('unused')
     const { code, stderr } = await runBuiltBin(consumer, '/nonexistent/dir/cordis.yml', '')
     expect(code).not.toBe(0)

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

@@ -10,9 +10,10 @@ import { TOOL_ORDER_REST } from '@deepseek-ai/dsh-system-prompt'
 import * as stdioAgent from '../src/index.ts'
 
 /**
- * Unit coverage for the @deepseek-ai/dsh-stdio-agent app plugin: mounting it composes the
- * console logger, the agent-core spine (pre-creating the `main` agent from the app config),
- * the JSONL backend, and the readline UI in one `ctx.plugin`.
+ * 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
+ * keyless echo smoke; this tier pins the export shape because an inject-less app could otherwise
+ * survive namespace collapse while silently losing its schema.
  */
 async function mount(config: stdioAgent.Config): Promise<Context> {
   const ctx = new Context()
@@ -152,7 +153,8 @@ describe('dsh-stdio-agent app', () => {
   })
 
   it('has the namespace-plugin export shape (no stray default) so the Loader keeps name/Config/apply', () => {
-    // Loader must retain the namespace so name, Config, and apply survive unwrapping.
+    // A default export would make `unwrapExports` collapse this inject-less namespace and silently
+    // drop `name`/`Config` while the app still boots. Guard the postmortem-0001 shape directly.
     expect('default' in stdioAgent).toBe(false)
     expect(typeof stdioAgent.apply).toBe('function')
 

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

@@ -181,7 +181,8 @@ describe('createStdioChat rendering', () => {
   it('seeds labels for agents already registered before the UI installs', async () => {
     // The pre-created `main` agent (and any agent surviving an HMR reload of just this fiber)
     // fired its `agent/created` before the UI's listener existed, so the live listener alone
-    // would miss it.
+    // would miss it. Seeding from `ctx.agents.list()` preserves the `[main turn N]` label instead
+    // of falling back to the raw session id.
     const ctx = new Context()
     await ctx.plugin(AgentRegistry)
     await ctx.plugin(UserInteractionService)