docs: rebalance prose cleanup and add trimming skill

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)