diff --git a/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.i18n.yaml b/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.i18n.yaml
index a85d782857..5892d118ec 100644
--- a/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md
-2026-08-09-concrete-prose-names-actors-and-recorded-facts.md: b7df5403ea11ff8ba32be0f9bede5a32d5bcd6ee
-2026-08-09-concrete-prose-names-actors-and-recorded-facts.zh.md: 8a45d452bfd98c1fe87a9a42bd4930273d034ca8
+2026-08-09-concrete-prose-names-actors-and-recorded-facts.md: 887a3666501a97e0930fe7eb4282603f537c17e8
+2026-08-09-concrete-prose-names-actors-and-recorded-facts.zh.md: 0202be5c22c75ff4feec225cdff12b772d64d1cf
diff --git a/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md b/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md
index b7df5403ea..887a366650 100644
--- a/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md
+++ b/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md
@@ -16,6 +16,8 @@ Maintained prose names the exact actor, action, source, event, field, file, or p
 
 The rule applies to Markdown, READMEs, active Agent Notes, JSDoc and comments, prompts, diagnostics, and user-visible strings. An audit judges each sentence separately; it does not replace a term across the repository with one preferred synonym. The edited sentence preserves actor, action, conditions, order, modality, exceptions, ownership, failure behavior, and consequences.
 
+Comments retain only facts that nearby code cannot express. Documentation stays at its owning level and omits private control flow and rare implementation cases unless they change supported behavior, safe use, compatibility, data integrity, security, or another maintained contract. The [simplification workflow](../../../skills/dsh-find-simplifications/SKILL.md) applies this rule while surveying code and prose together.
+
 Exact code identifiers, public APIs, durable fields, protocol members, type names, headings with external references, and filenames stay unchanged unless a coordinated contract rename is independently required. Surrounding prose explains their fields or behavior directly. Generated documents and catalogs update from their owning source.
 
 Before using `contract`, `boundary`, or `shape`, writers check whether the sentence means a more specific rule, operation, data structure, field set, validation point, timing point, API, type, or failure condition. `Contract` remains correct for preconditions, postconditions, invariants, compatibility promises, and other obligations that callers, callees, implementers, providers, producers, or consumers rely on. `Boundary` remains correct for a literal security, trust, wire, process, serialization, transaction, or lifecycle division. `Shape` remains correct when the structural form itself is the subject and no narrower term such as fields, schema, type, union variant, file layout, or export form states the fact. Code and API names containing these words remain unchanged unless a separate coordinated rename is required.
diff --git a/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.zh.md b/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.zh.md
index 8a45d452bf..0202be5c22 100644
--- a/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.zh.md
+++ b/.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.zh.md
@@ -16,6 +16,8 @@ Status: implemented
 
 该规则适用于 Markdown、README、活跃 Agent Note、JSDoc 与注释、提示词、诊断信息和用户可见字符串。审查会分别判断每个句子，不会在整个仓库中用一个偏好的近义词统一替换某个术语。编辑后的句子保留执行者、动作、条件、顺序、情态、例外、归属、失败行为和后果。
 
+注释只保留附近代码无法表达的事实。文档停留在内容归属的层级；除非私有控制流或罕见实现情形会改变受支持行为、安全使用、兼容性、数据完整性、安全保障或另一项持续维护的约定，否则文档不描述它们。[简化工作流](../../../skills/dsh-find-simplifications/SKILL.md)在同时巡查代码与行文时应用此规则。
+
 除非另一项独立需求明确要求协调重命名约定，否则确切的代码标识符、公开 API、持久字段、协议成员、类型名、带有外部引用的标题和文件名均保持不变。它们周围的行文直接说明其字段或行为。生成的文档和目录在维护它们的源文件修改后更新。
 
 使用 `contract`、`boundary` 或 `shape` 之前，写作者要确认句子是否实际指更具体的规则、操作、数据结构、字段集合、校验点、时间点、API、类型或失败条件。调用方、被调用方、实现方、提供方、生产方或消费方依赖的前置条件、后置条件、不变量、兼容性承诺及其他义务仍可准确称为 `contract`。真实的安全、信任、wire、进程、序列化、事务或生命周期分界仍可准确称为 `boundary`。当结构形式本身就是主题，且字段、schema、类型、联合变体、文件布局或导出形式等更窄的词无法说明事实时，仍可使用 `shape`。除非另一项独立需求要求协调重命名，否则包含这些词的代码和 API 名称保持不变。
diff --git a/.agents/skills/dsh-find-simplifications/SKILL.md b/.agents/skills/dsh-find-simplifications/SKILL.md
index 2a10999c27..ef7f387c4e 100644
--- a/.agents/skills/dsh-find-simplifications/SKILL.md
+++ b/.agents/skills/dsh-find-simplifications/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: dsh-find-simplifications
-description: 'Use when working in the deepseek-harness repo to find non-obvious simplification candidates, write proposed Agent Notes or inline TODO/FIXME/XXX notes, audit or coalesce superseded Agent Notes, or fold worthwhile simplification ideas from another PR; especially for dead, duplicated, speculative, over-built, added-then-removed, or hand-rolled-where-a-dependency-exists surfaces.'
+description: 'Use when working in the deepseek-harness repo to find non-obvious simplification candidates, remove redundant comments or implementation-heavy documentation, write proposed Agent Notes or inline TODO/FIXME/XXX notes, audit or coalesce superseded Agent Notes, or fold worthwhile simplification ideas from another PR; especially for dead, duplicated, speculative, over-built, added-then-removed, or hand-rolled-where-a-dependency-exists surfaces.'
 ---
 
 # Finding DeepSeek Harness Simplifications
@@ -44,6 +44,13 @@ If subagents are unavailable, simulate the same breadth yourself. Do not let the
 
 Start with the largest production-code deltas. A broad simplification audit that stops after obvious unused symbols can miss the files where duplicated lifecycle or defensive machinery carries most of the cost.
 
+## Simplify Prose With The Code
+
+Treat comments and documentation as maintained surface area. Apply [dsh-prose-standard](../dsh-prose-standard/SKILL.md) when a survey includes prose.
+
+- Delete comments that restate code or explain behavior owned elsewhere; keep required local contracts.
+- Keep docs at their owning level; omit implementation details and rare cases unless they change a maintained contract.
+
 ## Audit Trust And Lifecycle Boundaries
 
 For every defensive copy, freeze, validator, and callback capture, name where the value came from and who owns it next. Same-process typed service/plugin calls ordinarily borrow readonly values; parsers, config loaders, queues, model/tool JSON, durable files, workers, processes, and wire decoders own or validate their data. Tests built around hostile getters, fake typed objects, callback replacement, or mutation after a same-process handoff are evidence of a potentially speculative contract, not automatic justification for keeping it.
diff --git a/AGENTS.md b/AGENTS.md
index a66d6cdc54..0a026bdb83 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -117,7 +117,7 @@ Real-API tests and demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`,
 - **Source plane vs artifact plane, never mixed.** Static gates and tests resolve workspace imports through tsconfig `paths` to `src` and pass on a clean tree; gates consuming built `lib/` declare that dependency ([layout](docs/development.md#typescript-project-layout)).
 - **Keep compiler faces explicit.** Each package uses one aggregate except `api/remotes`; repo-wide programs seed a face config, never the root solution ([layout](docs/development.md#typescript-project-layout)).
 - **An empty `catch` names what it swallows** and why nothing else can reach it; keep the `try` to one statement.
-- Do not comment on facts obvious from code.
+- **Keep comments local.** Do not restate code, explain distant behavior unless locally required, or expand unrelated comments ([rationale](.agents/notes/implemented/process/2026-08-09-concrete-prose-names-actors-and-recorded-facts.md)).
 - **Prefer symmetry for parallel values**; unexplained asymmetry usually signals a missed extraction.
 - **Tests describe behavior, not correctness.** Change obsolete behavior with its tests; explain why in the PR.
 - **Non-trivial changes MUST include an Agent Note in the same PR;** only mechanical/local edits are exempt ([scope](.agents/notes/README.md#when-to-write-one)). Archived notes are frozen: never edit or treat them as current authority ([archive policy](.agents/notes/README.md#archiving-and-deletion)).
diff --git a/apps/cli/src/bin.ts b/apps/cli/src/bin.ts
index 9aa44f8b22..321849f2d9 100644
--- a/apps/cli/src/bin.ts
+++ b/apps/cli/src/bin.ts
@@ -1,8 +1,6 @@
 #!/usr/bin/env node
 /**
- * dsh — command-line entry. Dynamic imports per mode keep unrelated modes out
- * of each dispatch path; the adapter prints and exits for
- * `--help`/`--version`/a parse error, so only a valid mode reaches the switch.
+ * Command-line entry for dsh.
  * @module @deepseek-ai/dsh/bin
  */
 
@@ -16,7 +14,6 @@ import { parseDshArgs } from './args.ts'
 // Both the source tree (apps/cli/src) and the bundled bin (apps/cli/lib) sit
 // one directory under apps/cli, so the checked-in manifest resolves with the
 // same relative hop from either artifact.
-/** This app's version, read from its checked-in package.json. */
 function readVersion(): string {
   const manifest = JSON.parse(
     readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8'),
diff --git a/apps/web/src/main.ts b/apps/web/src/main.ts
index 7359ce5ade..2ff361f3db 100644
--- a/apps/web/src/main.ts
+++ b/apps/web/src/main.ts
@@ -1,8 +1,4 @@
-/**
- * Web application entry: thin bootstrap over the shell library. Everything —
- * module-table seeding, the boot page, and the UI-renderer handoff — lives
- * in @deepseek-ai/dsh-client-web; this file only finds the mount point.
- */
+/** Browser entry for the Web client. */
 import { AppWebEntry } from '@deepseek-ai/dsh-client-web'
 
 const el = document.getElementById('root')
diff --git a/apps/web/src/node-module-stub.ts b/apps/web/src/node-module-stub.ts
index 0a9b04ea5f..15e2c1c8da 100644
--- a/apps/web/src/node-module-stub.ts
+++ b/apps/web/src/node-module-stub.ts
@@ -3,10 +3,10 @@
  * configured loader path and fails loud if that assumption changes.
  */
 
-/** Throwing stand-in for node:module's createRequire (never reached in the browser boot). */
+/** Fail if browser boot reaches Node's module loader. */
 export const createRequire = (): never => {
   throw new Error('node:module is not available in the browser')
 }
 
-/** Erased type peer for the vendored loader's type-only LoadHookContext import. */
+/** Type-only peer for the vendored loader. */
 export type LoadHookContext = never
diff --git a/apps/web/tests/approval-composer.e2e.ts b/apps/web/tests/approval-composer.e2e.ts
index e57367ee46..9739c13b07 100644
--- a/apps/web/tests/approval-composer.e2e.ts
+++ b/apps/web/tests/approval-composer.e2e.ts
@@ -1,16 +1,5 @@
-// Web e2e scenario: the composer-takeover approval panel under a long
-// command. The shipped composition confines bash through the sandbox policy
-// and routes its escalation through the approval seam, so a read-only session
-// asked to write a file produces a REAL pending approval — the panel renders
-// in the browser, the test measures its geometry, answers through it, and the
-// escalated command then runs. Replay is deterministic: the denial, the
-// escalation retry and its command text arrive from replayed chunks, and the
-// answer click is the test's own gesture (the same sanctioned reaction to
-// model content as the question composer: the turn cannot complete without it).
-//
-// Geometry is the point of the scenario. The command is unbounded model text,
-// and an uncapped card grows with it until the refuse/allow buttons leave the
-// viewport — an approval the user could see and not answer.
+// Browser geometry for a pending approval whose model-supplied command would
+// push the actions outside the viewport without a capped text region.
 import { readFile } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
 import { join } from 'node:path'
@@ -29,17 +18,12 @@ import { connectFreshWorkspace, newEnglishPage, saveFailureShot } from './suppor
 
 const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/approval-composer', import.meta.url))
 const FIXTURE = join(SNAPSHOT_DIR, 'session.jsonl')
-// The scenario's one golden: the waiting panel. Everything the answered state
-// proves is asserted directly — see the world-state block at the end.
+// The golden covers the stable waiting panel; direct assertions cover its answer.
 const UI_EXPECTED = join(SNAPSHOT_DIR, 'ui.expected.md')
 const MODE = webSnapshotMode()
 
-// Irreducible payload: the command has to be long enough to pass the card's
-// height cap, which is the only command length that reproduces an action row pushed off
-// screen. Unrelated tokens, not a repeated word — a repeated word is what the
-// model compressed into `printf 'alpha %.0s' {1..400}` while recording, and a
-// short command proves nothing here. The formula keeps the source small; the
-// model receives the expanded literal it has to put in the command.
+// Unrelated tokens keep the recorded model from compressing the payload into a
+// short shell loop that would not overflow the card.
 const TOKENS = Array.from({ length: 220 }, (_, index) => `tok${((index + 1) * 7919 % 99991).toString(36)}`).join(' ')
 const PROMPT = `Write a file named notes.txt in the workspace containing exactly this text on one line: ${TOKENS}. Use one bash command with the literal text inline. Then reply with the single word DONE and stop.`
 
@@ -77,19 +61,12 @@ describe('web e2e: approval takeover keeps its actions reachable', () => {
     const input = page.locator('textarea').first()
     await input.waitFor({ timeout: 10_000 })
 
-    // The composer's own text cap, measured on the live draft scrollport before
-    // the takeover replaces it — the box that carries the cap, while the
-    // textarea inside it is as tall as the whole draft. The panel's scroll
-    // region must stop at the same height (the designer's requirement: one cap
-    // for the composer seat), and measuring it here keeps the assertion free of
-    // the px value itself.
+    // Derive the expected cap from the live composer instead of duplicating its pixel value.
     await input.fill(CAP_PROBE)
     const composerCap = await input.evaluate(el => el.closest('[data-input-scroll]')?.clientHeight ?? 0)
     expect(composerCap).toBeGreaterThan(0)
     await input.fill('')
 
-    // Read-only: the mode whose denial the model escalates from. Switched
-    // through the shipped access-mode chip, not a test-only override.
     await page.locator('[aria-label^="Access mode"]').click()
     await page.getByRole('menuitem', { name: 'Read Only' }).click()
     await expect.poll(
@@ -101,22 +78,15 @@ describe('web e2e: approval takeover keeps its actions reachable', () => {
     await input.fill(PROMPT)
     await input.press('Enter')
 
-    // The panel takes over the input area while the tool blocks. Its presence
-    // is a STABLE waiting state (it stays until answered), so waitFor is
-    // race-free.
     const panel = page.locator('[data-approval-key]')
     await panel.waitFor({ timeout: MODE === 'record' ? 180_000 : 60_000 })
     const scroll = panel.locator('[data-approval-scroll]')
     await expect.poll(() => scroll.getByText(/tok/).count(), { timeout: 15_000 }).toBeGreaterThan(0)
 
     if (MODE !== 'record') {
-      // This golden owns the stable waiting surface; the answered golden below
-      // owns the resulting transcript.
       const snapshot = await captureStableAria(page, '[data-approval-key]', scaffold.workspaceCwd)
       await compareOrRefreshGolden(UI_EXPECTED, snapshot, MODE)
 
-      // The uncapped-card hazard the header names, measured at the lane
-      // baseline and at a short viewport, on the live panel.
       const original = page.viewportSize() ?? { width: 1680, height: 1000 }
       for (const height of [1000, 700]) {
         await page.setViewportSize({ width: 900, height })
@@ -140,11 +110,8 @@ describe('web e2e: approval takeover keeps its actions reachable', () => {
         })
         expect(geometry.buttons).toBe(2)
         expect(geometry.scrolls).toBe(true)
-        // One cap for the seat: the panel's text region stops where the
-        // composer draft does (sub-pixel tolerance for the shared padding).
+        // The panel and composer share one cap; allow sub-pixel layout variance.
         expect(Math.abs(geometry.capped - composerCap)).toBeLessThan(1)
-        // Both buttons stay inside the card AND inside the viewport — the
-        // answerable state the cap exists to guarantee.
         expect(geometry.actionsTop).toBeGreaterThan(0)
         expect(geometry.actionsBottom).toBeLessThanOrEqual(geometry.viewport)
         expect(geometry.actionsBottom).toBeLessThanOrEqual(geometry.cardBottom)
@@ -159,12 +126,8 @@ describe('web e2e: approval takeover keeps its actions reachable', () => {
       await recordFixture(scaffold, sessionId, FIXTURE)
       return
     }
-    // World state: the granted escalation is what let the command run, and the
-    // panel leaves with the regular composer restored. Asserted on the world
-    // and the DOM rather than through a transcript golden — the denied first
-    // attempt renders the OS's own refusal ("Operation not permitted" on
-    // macOS, "Read-only file system" on Linux), so the answered transcript is
-    // not a platform-neutral golden surface.
+    // The denied attempt contains platform-specific OS text, so direct state
+    // and DOM assertions cover the answered outcome.
     expect(JSON.stringify(sessionEvents.filter(e => e.type === 'approval/decided').at(-1)))
       .toContain('allowed-once')
     const written = await readFile(join(scaffold.workspaceCwd, 'workspace', 'notes.txt'), 'utf8')
diff --git a/apps/web/tests/background-job-list.e2e.ts b/apps/web/tests/background-job-list.e2e.ts
index 0e0a98de93..b0fdc62ddb 100644
--- a/apps/web/tests/background-job-list.e2e.ts
+++ b/apps/web/tests/background-job-list.e2e.ts
@@ -1,8 +1,5 @@
-// Web e2e scenario: the session-header background-job list over the real
-// host. No model call is involved — a genuine `run_in_background` bash call
-// registers with `ctx.jobs`, and the assertion chain is the whole delivery
-// path: registry change feed → api-proxy `session/jobs` frame → the client's
-// `jobsBySession` mirror → the header action.
+// Session-header background jobs driven by a real `ctx.jobs` entry. No model
+// call is involved.
 import { readFile } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
 import { join } from 'node:path'
@@ -30,7 +27,7 @@ const SEED_ID = 'background-job-list-web-e2e'
 const COMMAND = 'sleep 45'
 
 /**
- * Wait for the Host to publish the live Agent that opening a session resumes.
+ * Wait for opening a session to publish its live Agent.
  * @param scaffold - the booted web scaffold.
  * @param sessionId - the opened session's identity.
  * @returns the registered Agent instance.
@@ -82,9 +79,7 @@ describe.skipIf(MODE === 'record')('web e2e: background job list', () => {
 
   it('shows a running background job in the session header without a refresh', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-background-job-running'))
-    // Point assertion, not a poll: `expect.poll` retries until a predicate
-    // holds, so polling for zero passes at t=0 and proves nothing. The
-    // "renders nothing without a task" branch is owned by the component suite.
+    // Polling for zero would pass at t=0 before delivery and prove nothing.
     const trigger = page.getByRole('button', { name: '1 background job running' })
     expect(await trigger.count()).toBe(0)
 
@@ -116,8 +111,6 @@ describe.skipIf(MODE === 'record')('web e2e: background job list', () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-background-job-settled'))
     expect(scaffold.ctx.jobs.kill(jobId, agent, 'web e2e cancellation')).toBe('requested')
 
-    // The trigger drops its live count once the task leaves running/stopping,
-    // which is also the proof that settlement reached the browser unprompted.
     const idle = page.getByRole('button', { name: '1 background job' })
     await idle.waitFor({ timeout: 20_000 })
 
diff --git a/apps/web/tests/code-mode-round.e2e.ts b/apps/web/tests/code-mode-round.e2e.ts
index 051700dc35..342f9328e0 100644
--- a/apps/web/tests/code-mode-round.e2e.ts
+++ b/apps/web/tests/code-mode-round.e2e.ts
@@ -1,11 +1,4 @@
-// Web e2e scenario: a Code Mode round trip. The scaffold boots the SAME
-// shipped tree with the tools row patched to mode: code (the run_code-only
-// wire), a real chromium sends a prompt engineered to elicit one run_code
-// program with several sub-calls, and the UI must render the code-variant
-// parent row with its always-visible nested sub-rows — each sub-row the same
-// component a native call renders through — plus details-panel resolution for
-// a clicked sub-row. Drive steps wait only on generic completion
-// (whenTurnSettled); assertion steps run in replay/refresh only.
+// Code Mode browser round trip with nested sub-calls and details selection.
 // Record: DSH_SNAPSHOT=record rewrites session.jsonl, then a keyless
 // DSH_SNAPSHOT=refresh regenerates ui.expected.md.
 import { readFile } from 'node:fs/promises'
@@ -24,9 +17,7 @@ const FIXTURE = fileURLToPath(new URL('./snapshots/code-mode-round/session.jsonl
 const UI_EXPECTED = fileURLToPath(new URL('./snapshots/code-mode-round/ui.expected.md', import.meta.url))
 const MODE = webSnapshotMode()
 
-// The scenario's one drive prompt: elicits one program with a bash sub-call
-// and a failing read the program tolerates — the sub-row set the assertions
-// need. Never asserted against model prose.
+// Elicits the successful and failed sub-rows this scenario asserts.
 const PROMPT = 'Using ONE run_code program: run bash `echo CODE_ROUND_OK`, then read the file missing.txt '
   + 'catching its error in the program. Return an object with both outcomes. Then reply DONE and stop.'
 
@@ -48,7 +39,6 @@ describe('web e2e: Code Mode round renders nested sub-calls', () => {
     tripwire = watchConsole(page)
     await page.goto(scaffold.baseUrl, { waitUntil: 'load' })
     await page.waitForSelector('[class*="frame"]', { timeout: 30_000 })
-    // Fresh world: connect a Workspace so the composer scenarios start live.
     await connectFreshWorkspace(page, scaffold.workspaceCwd)
   }, 120_000)
 
@@ -60,7 +50,6 @@ describe('web e2e: Code Mode round renders nested sub-calls', () => {
   it('drives the recorded prompt to a settled turn (all modes)', async () => {
     onTestFailed(() => saveFailureShot(page, 'web-e2e-code-mode-drive'))
     if (MODE !== 'record') {
-      // Drift guard: the committed fixture must carry exactly the drive prompt.
       expect(fixtureUserPrompts(await readFile(FIXTURE, 'utf8'))).toEqual([PROMPT])
     }
     const input = page.locator('textarea').first()
@@ -75,11 +64,9 @@ describe('web e2e: Code Mode round renders nested sub-calls', () => {
   }, 200_000)
 
   it.skipIf(MODE === 'record')('the durable log carries run_code with full-content sub-dispatches', () => {
-    // Wire discipline: code mode collapsed the call surface to run_code.
     const calls = sessionEvents.filter(event => event.type === 'tool/call')
     expect(calls.length).toBeGreaterThanOrEqual(1)
     expect(new Set(calls.map(call => (call.data as { name: string }).name))).toEqual(new Set(['run_code']))
-    // Sub-dispatches logged with the complete tool/result vocabulary.
     const dispatches = sessionEvents.filter(event => (event.type as string) === 'tool/code-dispatch')
     expect(dispatches.length).toBeGreaterThanOrEqual(2)
     for (const dispatch of dispatches) {
@@ -107,14 +94,9 @@ describe('web e2e: Code Mode round renders nested sub-calls', () => {
     // description as its summary (the presentCall contract).
     const codeRow = page.locator('[data-variant="code"]').first()
     await codeRow.waitFor({ timeout: 10_000 })
-    // Nested rows are visible WITHOUT any expand interaction, inside the
-    // sub-call nest, each rendered by the same components as native rows:
-    // the bash sub-call landed in the bash sample registration.
     const nest = page.locator('[data-subcalls]').first()
     await nest.waitFor({ timeout: 10_000 })
     expect(await nest.locator('[data-sample="bash"]').count()).toBeGreaterThanOrEqual(1)
-    // The failing read sub-call wears the same error state a native failed
-    // row wears (the recorded program tolerates a read of missing.txt).
     expect(await nest.locator('[data-state="error"]').count()).toBeGreaterThanOrEqual(1)
   }, 60_000)
 
@@ -124,7 +106,6 @@ describe('web e2e: Code Mode round renders nested sub-calls', () => {
     const frame = page.locator('[style*="grid-template-columns"]').first()
     expect(await frame.getAttribute('data-details-collapsed')).toBe('true')
     await nest.locator('[data-sample="bash"]').first().click()
-    // Tool rows do not drive layout geometry; the Session's default panel stays closed.
     await expect.poll(() => frame.getAttribute('data-details-collapsed'), { timeout: 5_000 }).toBe('true')
   })
 
diff --git a/apps/web/tests/composer-draft-scroll.e2e.ts b/apps/web/tests/composer-draft-scroll.e2e.ts
index ae48dcddca..b8fa9a6121 100644
--- a/apps/web/tests/composer-draft-scroll.e2e.ts
+++ b/apps/web/tests/composer-draft-scroll.e2e.ts
@@ -1,35 +1,6 @@
-// Web e2e scenario: a composer draft longer than the 14-line cap scrolls its
-// GLYPHS AND ITS CARET AS ONE.
-//
-// The composer paints its text in two stacked layers (see
-// packages/client/ui-conversation/src/client/skeleton/InputBar.module.css): the
-// `<textarea>` carries the value, the selection and the caret but renders its
-// own glyphs `color: transparent`, and every visible character is painted by the
-// `[data-input-backdrop]` div underneath it, which also carries the claim-token
-// highlight, the chips and the ghost hint.
-//
-// Two layers can only stay together by moving together. They do: both sit
-// inside `[data-input-scroll]`, the composer's single scrolling box, and are as
-// tall as the whole draft — so one offset, applied by the browser, moves the
-// caret and the words in the same frame. Scrolling the textarea and assigning
-// its offset to the backdrop looks equivalent and is not: a wheel gesture is
-// composited off the main thread, so the assignment lands frames late and the
-// caret visibly flies ahead of the text it belongs to.
-//
-// That failure is what the same-task measurement below pins. Every metric here
-// is read through the caret's own coordinate frame — where the textarea puts
-// line n — against where the backdrop paints line n, because that difference is
-// the defect a user sees, and it is the one number a mirror between two boxes
-// cannot hold at zero.
-//
-// Only a real engine can show any of this. Scrolling is layout: jsdom reports
-// `scrollHeight === clientHeight` for every element and never scrolls one, so
-// the unit spec in packages/client/ui-conversation/tests/input-bar.client.spec.tsx can
-// only assert that one scrollport contains both layers.
-//
-// Zero model calls: a fresh workspace's blank session already carries a live
-// composer, and the scenario only types into it. A stray stream would fail loud
-// with NO_ADAPTER.
+// Browser geometry for the composer's caret and visible text layers. A
+// same-task gap probe detects deferred scroll synchronization that DOM-only
+// tests cannot observe.
 import { fileURLToPath } from 'node:url'
 import { join } from 'node:path'
 import type { Browser, Page } from 'playwright'
@@ -42,13 +13,7 @@ import {
 import { connectFreshWorkspace, newEnglishPage, saveFailureShot } from './support.ts'
 
 const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/composer-draft-scroll', import.meta.url))
-/**
- * Committed golden of the composer's two-layer scroll geometry. The change
- * alters no accessible name, so the aria goldens the other scenarios commit are
- * byte-identical with and without it; this records the relations instead, which
- * makes a shift in the cap or in the layer coupling a reviewable diff rather
- * than an assertion someone has to reconstruct.
- */
+/** Scroll geometry is absent from ARIA snapshots, so this scenario records it directly. */
 const GEOMETRY_EXPECTED = join(SNAPSHOT_DIR, 'geometry.expected.md')
 const MODE = webSnapshotMode()
 
@@ -75,20 +40,11 @@ const DRAFT_TRAILING_NEWLINE = `${DRAFT}\n`
 
 /** The composer's text layers as the browser lays them out. */
 interface ComposerMetrics {
-  /** True when the draft is taller than the capped box — the situation under test. */
   overflows: boolean
-  /** Visible height of the scrollport's content box: the cap in pixels. */
   clientHeight: number
-  /** Whole lines that fit in the visible box, at the composer's own line-height. */
   visibleLines: number
-  /** The composer's one scroll offset, which the caret and the glyphs both follow. */
   scrollTop: number
-  /** Furthest that offset can go. */
   scrollMax: number
-  /**
-   * Scrollable overflow the textarea holds on its own — 0, or a second offset
-   * exists that nothing keeps equal to this one.
-   */
   inputScrollable: number
   /**
    * Distance between where the caret sits for a draft line and where the
@@ -98,25 +54,14 @@ interface ComposerMetrics {
    */
   caretGlyphGap: number
   /**
-   * How much that gap moves when the offset changes inside a single task: 0
-   * here, because one box carries both layers. Assigning one box's offset to
-   * another cannot be 0 — a scroll event is dispatched after the task that
-   * moved the box, so between the two there is a frame with the caret at the
-   * new offset and the glyphs at the old one.
+   * How much the caret-to-glyph gap moves when the offset changes before a
+   * scroll listener can run.
    */
   gapShiftOnScroll: number
-  /**
-   * Top of the LAST draft line relative to the visible box's top, in pixels: at
-   * most `clientHeight` when that line is on screen.
-   */
   lastLineOffset: number
-  /** Top of the FIRST draft line relative to the visible box's top: negative once it has scrolled out. */
   firstLineOffset: number
-  /** Content width the textarea wraps at. */
   inputWrapWidth: number
-  /** Content width the backdrop wraps at — equal, or the layers break lines in different places. */
   backdropWrapWidth: number
-  /** Content width the hidden auto-grow mirror wraps at — it decides the box's height. */
   mirrorWrapWidth: number
 }
 
@@ -187,14 +132,8 @@ function measureComposer(page: Page): Promise<ComposerMetrics> {
 }
 
 /**
- * Render the golden body.
- *
- * Absolute glyph coordinates are deliberately absent: they depend on font
- * metrics and would make the fixture fail on a machine that measures text
- * differently — a golden that needs re-recording per platform documents the
- * platform, not the behavior. What is recorded is the cap, the caret-to-glyph
- * relation, and which lines are on screen, each a comparison that survives any
- * layout keeping the coupling.
+ * Render platform-neutral comparisons instead of font-dependent glyph
+ * coordinates.
  * @param top - metrics with the draft scrolled to its start.
  * @param bottom - metrics with the draft scrolled to its end.
  * @param trailingNewline - metrics with the trailing-newline draft scrolled to its end.
@@ -328,9 +267,7 @@ describe('web e2e: composer draft scrolling', () => {
     const input = page.locator('textarea:enabled').first()
     await input.hover()
     const resting = (await measureComposer(page)).caretGlyphGap
-    // One delta past the whole draft: the box clamps at its own end, and the
-    // wheel-chaining handler leaves it native because the box is not yet at its
-    // edge when the gesture starts (the chaining itself is owned by the unit spec).
+    // One delta past the whole draft: the box clamps at its own end.
     await page.mouse.wheel(0, 2000)
     await expect.poll(async () => (await measureComposer(page)).scrollTop, { timeout: 10_000 })
       .toBeGreaterThan(0)
@@ -453,9 +390,7 @@ describe('web e2e: composer draft scrolling', () => {
       const data = new DataTransfer()
       data.setData('text/plain', text)
       el.dispatchEvent(new ClipboardEvent('paste', { clipboardData: data, bubbles: true, cancelable: true }))
-      // The ordinary case, without a trailing newline, so the collapsed branch
-      // of the reveal keeps a real engine under it; the case above owns the
-      // after-newline branch.
+      // Keep a final glyph so the collapsed caret position has a client rect.
     }, `\n${DRAFT}`)
     await expect.poll(async () => (await measureComposer(page)).overflows, { timeout: 10_000 }).toBe(true)
     await expect.poll(async () => (await measureComposer(page)).scrollTop, { timeout: 10_000 }).toBeGreaterThan(0)
@@ -465,8 +400,6 @@ describe('web e2e: composer draft scrolling', () => {
   }, 60_000)
 
   it('commits exactly the fixtures it reads', async () => {
-    // Zero model calls, so the scenario records no session fixture: the geometry
-    // golden is the whole inventory.
     await assertFixtureInventory(SNAPSHOT_DIR, ['geometry.expected.md'])
   })
 
diff --git a/apps/web/tests/composer-tab-geometry.e2e.ts b/apps/web/tests/composer-tab-geometry.e2e.ts
index 0f7b01c7ff..0399e665f8 100644
--- a/apps/web/tests/composer-tab-geometry.e2e.ts
+++ b/apps/web/tests/composer-tab-geometry.e2e.ts
@@ -1,47 +1,6 @@
-// Web e2e scenario: the input card holds one horizontal position across the
-// Chat and Trajectory tabs.
-//
-// The composer seat is the same node in both tabs, but it measures itself
-// against a different edge in each (see
-// packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css).
-// In Chat it is a sticky CHILD of the column's scroller, so it rides that
-// scroller's content box — the box a space-consuming scrollbar shortens. A view
-// that opts into a composer overlay (`data-conversation-composer-overlay`, which
-// Trajectory declares and which moves the column's own scrolling into the view)
-// gets an absolutely positioned seat instead, laid out against the padding box,
-// which the scrollbar never reduces.
-//
-// The column handles the two edges without reserving the gutter on both: Chat
-// keeps `scrollbar-gutter: stable` so its seat's content box never jumps as the
-// transcript starts to scroll; the overlay branch does NOT reserve (the view
-// owns its own scrollers, so a reserved gutter would only narrow the view's
-// content by the bar's width), and the overlay seat instead gives back the
-// bar's width (`right: var(--dsh-scrollbar-width)`) so both seats measure the
-// same width and the card does not move.
-//
-// Only a real engine can show this. The seat's geometry is layout: jsdom gives
-// every element a zero-sized box and reports no scrollbar at all, so a unit spec
-// can assert the declarations exist but not that the two states land in the same
-// place. What is asserted here is the user-visible fact — the card does not move
-// — measured as the distance between the two tabs' card rectangles.
-//
-// The browser is launched WITHOUT Playwright's default `--hide-scrollbars`,
-// which is load-bearing rather than incidental. Under that argument a scroll
-// container's bar consumes no layout width at all, so the two tabs agree with
-// and without the compensation and every comparison below holds vacuously —
-// measured: the uncompensated cascade leaves both tabs' bands at 0 there,
-// against 8 and 0 with the argument dropped. Dropping it is also the faithful
-// configuration: ui-theme's scrollbar.css gives `::-webkit-scrollbar` a width,
-// and a bar that occupies layout space is what the product actually draws.
-//
-// The scenario runs that uncompensated cascade in the page — the overlay seat's
-// `right` compensation dropped to 0 — and measures the same two tabs through
-// it, which is what keeps the equal rectangles above from being explained by a
-// tab switch that never reached the layout. It is the reported symptom as a
-// number: the card moves 4px, half the 8px band, on each edge.
-//
-// Zero model calls: a seeded cold session renders from its log, and switching
-// tabs asks the host for nothing. A stray stream would fail loud with NO_ADAPTER.
+// Browser geometry for the input card across Chat and Trajectory. The browser
+// must expose layout-consuming scrollbars, and an uncompensated control keeps
+// equal rectangles from passing vacuously.
 import { fileURLToPath } from 'node:url'
 import { join } from 'node:path'
 import type { Browser, Page } from 'playwright'
@@ -55,17 +14,7 @@ import {
 import { newEnglishPage, saveFailureShot } from './support.ts'
 
 const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/composer-tab-geometry', import.meta.url))
-/**
- * Committed golden of where the input card sits in each tab, at a wide viewport
- * (card at its width cap) and a narrow one (card shrinking with the column).
- *
- * Absolute coordinates are deliberately absent: they depend on the sidebar's
- * laid-out width and on font metrics, so committing them would produce a fixture
- * that has to be re-recorded per platform. What is recorded is the distance
- * between the two tabs' rectangles, which is zero when the compensation holds and
- * the bar's width when it does not — including under the control, so the golden
- * carries the shift the uncompensated cascade produces rather than only its absence.
- */
+/** Records platform-neutral distances between the two tabs' card rectangles. */
 const GEOMETRY_EXPECTED = join(SNAPSHOT_DIR, 'geometry.expected.md')
 const MODE = webSnapshotMode()
 
@@ -127,21 +76,13 @@ const CONTROL_CSS = `
 
 /** The column scroller and the input card as the browser lays them out, in one tab. */
 interface TabMetrics {
-  /** Resolved `scrollbar-gutter` on the column's scroller. */
   gutter: string
-  /** Resolved `overflow-x`: `hidden` in both states, so neither grows a horizontal bar. */
   overflowX: string
-  /** Resolved `overflow-y`: `auto` in both states, which is the form WebKit honours the gutter on. */
   overflowY: string
-  /** Border-box width minus client width: the space the scrollbar takes out of the content area. */
   band: number
-  /** True when the column's scroller actually scrolls — only Chat does. */
   scrolls: boolean
-  /** Left edge of the input card in viewport coordinates. */
   cardLeft: number
-  /** Right edge of the input card. */
   cardRight: number
-  /** Width of the input card, capped at the composer card max width. */
   cardWidth: number
 }
 
@@ -149,11 +90,8 @@ interface TabMetrics {
 interface TabComparison {
   chat: TabMetrics
   trajectory: TabMetrics
-  /** Distance between the two tabs' card left edges: 0 when the card holds its position. */
   leftShift: number
-  /** Distance between the two tabs' card right edges. */
   rightShift: number
-  /** Difference between the two tabs' card widths. */
   widthShift: number
 }
 
@@ -306,8 +244,7 @@ describe('web e2e: input card position across view tabs', () => {
   beforeAll(async () => {
     scaffold = await launchWebScaffold({})
     await seedSession(scaffold, FIXTURE.log, SEED_ID)
-    // Scrollbars must take layout space here or the scenario proves nothing;
-    // see the file header for the measurement behind dropping this argument.
+    // Scrollbars must take layout space here or the comparison is vacuous.
     browser = await chromium.launch({ ignoreDefaultArgs: ['--hide-scrollbars'] })
     page = await newEnglishPage(browser, WIDE_VIEWPORT.height)
     tripwire = watchConsole(page)
diff --git a/apps/web/tests/sidebar-scrollbar.e2e.ts b/apps/web/tests/sidebar-scrollbar.e2e.ts
index 16e98a356e..3500e09188 100644
--- a/apps/web/tests/sidebar-scrollbar.e2e.ts
+++ b/apps/web/tests/sidebar-scrollbar.e2e.ts
@@ -1,67 +1,8 @@
-// Web e2e scenario: the sidebar session list's scrollbar as the browser
-// actually lays it out — the observable half of the themed scrollbars
-// (packages/client/ui-theme/src/styles/scrollbar.css plus the
-// `scrollbar-gutter: stable` reservation on WorkspaceBrowser's `.list`). The
-// ui-theme/ui-workspace unit specs read the CSS text; only a real engine
-// reports the reserved gutter width and the substituted `scrollbar-color`, so
-// those two facts live here.
-//
-// Zero model calls: the list only has to overflow, so the scenario seeds many
-// cold sessions from another spec's committed fixture (seeded-history's
-// seed.jsonl, reused read-only — this spec needs row count, not new recorded
-// content) and never launches a replay row. A stray stream would fail loud
-// with NO_ADAPTER.
-//
-// Headless-chromium caveats, load-bearing for what is asserted below.
-//
-// Headless chromium defaults to an OVERLAY scrollbar: one drawn on top of the
-// content, consuming no layout width unless something reserves space. That is
-// the mode in which the reported symptom exists at all, so this environment
-// reproduces it rather than merely approximating it — without either
-// declaration the list's band is 0 and the bar covers 7px of the relative
-// time. (Under a classic space-consuming bar, `clientWidth` already excludes
-// the bar and nothing can be covered; a headed run under xvfb behaves that way
-// and cannot show the symptom.)
-//
-// The consequence for assertions: comparing the time element's right edge
-// against the list's CLIENT-area right edge holds in both states and proves
-// nothing, because with an overlay bar the client edge is the border edge. The
-// two signals that do separate the states are the reserved band width and
-// `timeCoveredBy`, which measures the overlap against the bar's own width.
-//
-// Both the `scrollbar-gutter: stable` reservation and the sheet's
-// `::-webkit-scrollbar` width are needed for that band, and neither suffices:
-// measured on the running app, deleting either one takes the band from 8 to 0
-// while the other stays in force. The gutter states that space be reserved; the
-// pseudo-element width is what makes chromium treat the bar as occupying layout
-// space in the first place.
-//
-// That conjunction is why `band` and `timeCoveredBy` are both asserted and
-// neither replaces the other. Removing only the gutter leaves `timeCoveredBy` at
-// 0, because the bar is then 8px wide and the row's right padding is also 8px,
-// so it abuts the timestamp without covering it; `band` catches that case.
-// Removing both is what produces the reported overlap, and `timeCoveredBy`
-// measures it at 7.
-//
-// The thumb is a pointer affordance (ui-sidebar rebinds the indirection pair
-// to `transparent` while the pointer is outside the column), so every
-// measurement below states which pointer position it was taken at: the
-// scenario parks the pointer over the sidebar before asserting a colour, and
-// the quiet state and its linger get their own test.
-//
-// Chromium also takes the `::-webkit-scrollbar*` path, not the standard
-// properties: scrollbar.css gates `scrollbar-width`/`scrollbar-color` behind
-// `@supports not selector(::-webkit-scrollbar)`, which is false here. The
-// resolved standard properties therefore read `auto`, and that reading is
-// asserted — a concrete value would mean the gate leaked and silenced the
-// pseudo-element rules. What the theme test measures instead is the pair the
-// pseudo-element rules read: the indirection variables as they resolve ON the
-// list, plus the `::-webkit-scrollbar-thumb:hover` declaration as it stands in
-// the cascade. The hover thumb colour is not observable any other way —
-// chromium folds the `:hover` rule into `getComputedStyle(el,
-// '::-webkit-scrollbar-thumb')`, so that query reports the hover colour at
-// rest and cannot pin either state (measured by deleting the hover rule live:
-// the same query flipped from the hover colour to the resting one).
+// Browser geometry for the sidebar scrollbar reservation and theme. Headless
+// Chromium uses overlay scrollbars, so the reserved band and `timeCoveredBy`
+// together distinguish reserved space from a bar painted over content. Its
+// computed pseudo-element style also folds in `:hover`, so the test reads that
+// declaration from the cascade.
 import { readFile } from 'node:fs/promises'
 import { fileURLToPath } from 'node:url'
 import { join } from 'node:path'
@@ -76,14 +17,7 @@ import { newEnglishPage, saveFailureShot } from './support.ts'
 
 const SEED = fileURLToPath(new URL('./snapshots/seeded-history/seed.jsonl', import.meta.url))
 const SNAPSHOT_DIR = fileURLToPath(new URL('./snapshots/sidebar-scrollbar', import.meta.url))
-/**
- * Committed golden of the resolved scrollbar style and geometry, in both
- * palettes. The aria goldens the other scenarios commit cannot carry this
- * change: it alters no DOM and no accessible name, so their normalized trees are
- * byte-identical with and without it. This one records the values instead, which
- * makes an unintended shift in thumb colour, band width, or rendering path a
- * reviewable diff rather than an assertion someone has to think about.
- */
+/** Geometry and resolved style are absent from ARIA snapshots, so this scenario records them directly. */
 const GEOMETRY_EXPECTED = join(SNAPSHOT_DIR, 'geometry.expected.md')
 const MODE = webSnapshotMode()
 /** Enough rows that the list overflows the 800px-tall viewport's sidebar; the scenario asserts the overflow rather than trusting it. */
@@ -91,42 +25,24 @@ const SEED_COUNT = 24
 
 /** Geometry and resolved scrollbar style of one scroll container, measured in the page. */
 interface ListMetrics {
-  /** Resolved `scrollbar-gutter`. */
   gutter: string
-  /** Resolved `::-webkit-scrollbar` width: the pseudo-element path's own sizing. */
   width: string
-  /** Resolved `::-webkit-scrollbar-track` background. */
   track: string
-  /** Resolved `scrollbar-width`, expected `auto` because the gate excludes chromium. */
   standardWidth: string
-  /** Resolved `scrollbar-color`, expected `auto` for the same reason. */
   standardColor: string
-  /** `::-webkit-scrollbar-thumb:hover` background declarations found in the cascade, in sheet order. */
   hoverRules: string[]
-  /** `--dsh-scrollbar-thumb` resolved on the list, serialized as a colour. */
   token: string
-  /** `--dsh-scrollbar-thumb-hover` resolved on the list, serialized the same way. */
   hoverToken: string
-  /** True when the list actually scrolls. */
   overflows: boolean
-  /** Border-box width minus client width: the space the scrollbar takes out of the content area. */
   band: number
-  /** Distance from the scrollbar's right edge to the sidebar edge. */
   scrollbarEdgeOffset: number
-  /** Distance from the first row background's right edge to the sidebar edge. */
   rowEdgeInset: number
-  /** Client-area right edge in viewport coordinates (`clientWidth` excludes the scrollbar band). */
   clientRight: number
-  /** Border-box right edge in viewport coordinates. */
   borderRight: number
-  /** Right edge of the first row's relative-time element, the content the unreserved bar covered. */
   timeRight: number
   /**
-   * Pixels of the relative time the scrollbar paints over: how far its right
-   * edge reaches into the band the bar occupies, `[borderRight - barWidth,
-   * borderRight]`. This is the reported symptom as a number, and it is the one
-   * geometric signal that separates the two states in this environment — see
-   * the file header on why `clientWidth` comparisons cannot.
+   * Pixels of relative time under the scrollbar, measured against the bar's
+   * width because an overlay scrollbar does not move the client edge.
    */
   timeCoveredBy: number
 }
@@ -145,13 +61,8 @@ function measureList(page: Page): Promise<ListMetrics> {
     if (time === null) throw new Error('no row relative-time element in the sidebar list')
     const row = list.querySelector<HTMLElement>('[role="treeitem"]')
     if (row === null) throw new Error('no row in the sidebar list')
-    // Each indirection variable is resolved through its own throwaway probe
-    // appended to the list: `var()` substitution then happens where the list
-    // sits in the cascade, which is the claim, and `color` normalizes whatever
-    // notation the palette sheet chose into one comparable serialization. A
-    // REUSED probe would report only the last value read — `getComputedStyle`
-    // returns a live declaration, so reassigning `style.color` retroactively
-    // changes every earlier read.
+    // Use one probe per variable because computed style declarations are live;
+    // the color property also normalizes palette syntax.
     const resolve = (name: string): string => {
       const probe = document.createElement('span')
       probe.style.color = `var(${name})`
@@ -160,11 +71,8 @@ function measureList(page: Page): Promise<ListMetrics> {
       probe.remove()
       return value
     }
-    // The hover colour is read out of the cascade rather than computed:
-    // chromium reports the `:hover` background for the resting pseudo-element
-    // too (see the file header), so no computed query separates the states.
-    // Cross-origin sheets throw on `cssRules`; none is expected, and skipping
-    // them cannot mask the rule under test, which ships in the app's own CSS.
+    // Computed pseudo style folds in hover even at rest, so inspect the cascade.
+    // Cross-origin sheets may throw and cannot contain the app-owned rule.
     const hoverRules = [...document.styleSheets]
       .flatMap((sheet) => {
         try {
@@ -233,9 +141,7 @@ function measureRowInset(page: Page): Promise<Pick<ListMetrics, 'overflows' | 'r
 
 /** One palette's readings, taken at both pointer positions. */
 interface PaletteMetrics {
-  /** Everything measured with the pointer over the list, which is when a thumb exists. */
   hovered: ListMetrics
-  /** `--dsh-scrollbar-thumb` with the pointer parked outside the column. */
   quietThumb: string
 }
 
@@ -260,17 +166,8 @@ async function measurePalette(page: Page): Promise<PaletteMetrics> {
 }
 
 /**
- * Render the golden body: the resolved scrollbar style of the list in each
- * palette, plus the geometric relations the scrollbar-gutter/thin-scrollbar
- * declarations establish.
- *
- * Absolute coordinates are deliberately absent. `timeRight`, `clientRight`, and
- * `borderRight` depend on the sidebar's laid-out width and on font metrics, so
- * committing them would make the golden fail on a machine whose fonts measure
- * differently — a fixture that has to be re-recorded per platform documents the
- * platform, not the behavior. What is recorded instead is the band, the overlap,
- * and the two orderings, each of which is a difference or a comparison and so
- * survives any layout that keeps the reservation.
+ * Render platform-neutral differences and comparisons instead of absolute
+ * coordinates that depend on sidebar width and font metrics.
  * @param light - metrics measured under the light palette.
  * @param dark - metrics measured under the dark palette.
  * @returns the golden body, without a trailing newline.
@@ -416,27 +313,12 @@ describe('web e2e: sidebar session list scrollbar (reserved gutter / themed thum
     await expect.poll(async () => (await measureList(page)).overflows, { timeout: 10_000 }).toBe(true)
     const metrics = await measureList(page)
     expect(metrics.gutter).toBe('stable')
-    // The control. `band > 0` is the whole observable effect of the
-    // reservation: the scrollbar is taken out of the content area instead of
-    // drawn over it. Removing the declaration makes it exactly 0. The value
-    // itself is not pinned — it tracks `scrollbar-width` and the platform.
+    // Pin presence, not width, because the width is platform-dependent.
     expect(metrics.band).toBeGreaterThan(0)
     expect(metrics.scrollbarEdgeOffset).toBe(2)
     expect(metrics.rowEdgeInset).toBe(12)
-    // The reported symptom, stated directly: no part of the row's relative time
-    // lies under the bar. Without either declaration it measures 7 — the `h`
-    // of `1h` is the covered part. Unlike the client-edge comparison below it
-    // does not go vacuous under an overlay scrollbar, because it measures
-    // against the bar's own width rather than against a content edge the
-    // overlay bar does not move. It is not a replacement for the band
-    // assertion above; see the file header for which regression each one
-    // catches.
+    // Measure against the bar because overlay scrollbars do not move the client edge.
     expect(metrics.timeCoveredBy).toBe(0)
-    // Corollaries of the reservation, kept because they pin where the band sits
-    // rather than only that it exists: the time ends inside the content area,
-    // and the content area ends before the border box. Each holds in both
-    // states on its own (see the file header) and is meaningful only alongside
-    // the two assertions above.
     expect(metrics.timeRight).toBeLessThanOrEqual(metrics.clientRight)
     expect(metrics.clientRight).toBeLessThan(metrics.borderRight)
     expect(tripwire.pageErrors).toEqual([])
diff --git a/apps/web/tests/startup-rpc-budget.e2e.ts b/apps/web/tests/startup-rpc-budget.e2e.ts
index 135ff15e23..b9e06fcb3b 100644
--- a/apps/web/tests/startup-rpc-budget.e2e.ts
+++ b/apps/web/tests/startup-rpc-budget.e2e.ts
@@ -1,22 +1,12 @@
-// Cold-boot RPC budget. The describe mirror (packages/client/ui-settings) is
-// the one `settings.describe` reader in the browser, so startup describe
-// traffic stays bounded no matter how many client plugins own a preference.
-// A regression here means a consumer bypassed the mirror — grep for
-// `settings.describe(` outside ui-settings' client sources.
-//
-// Zero model calls: the lane only boots chrome, so no replay fixture mounts.
+// Cold boot may issue at most two settings.describe calls regardless of client
+// plugin count. No model call or replay fixture is involved.
 import type { Browser, Page } from 'playwright'
 import { chromium } from 'playwright'
 import { afterAll, beforeAll, describe, expect, it } from 'vitest'
 import { launchWebScaffold, watchConsole, type WebScaffold } from './scaffold.ts'
 import { newEnglishPage } from './support.ts'
 
-/**
- * Both reads are the mirror's: once eagerly at bind time over HTTP, and once
- * on the first-connection reset — that second read closes the window where a
- * document commit lands between the eager read and the SSE subscription and
- * its invalidation is lost. Every settings consumer derives from these two.
- */
+/** One eager read plus one first-connection reset closes the pre-subscription commit window. */
 const DESCRIBE_BUDGET = 2
 
 let scaffold: WebScaffold
diff --git a/docs/config-catalog.i18n.yaml b/docs/config-catalog.i18n.yaml
index 4cdc47a0b1..5fa1696881 100644
--- a/docs/config-catalog.i18n.yaml
+++ b/docs/config-catalog.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/config-catalog.md
-config-catalog.md: a41538ffc2fc18939e015e8c08676868f588d897
-config-catalog.zh.md: 9481cb2b4db13d7d91c11e323e8d1118184f5bfe
+config-catalog.md: 9c679db07b9922d49e5ddb5f64c6726c7443e4ff
+config-catalog.zh.md: b9b9b4ae8243f71fb8c60aec314709d1da325dbb
diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index a41538ffc2..9c679db07b 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -692,7 +692,7 @@ export type Config = LocalConfig
 
 Depends on: [`LocalConfig`](#deepseek-aidsh-fs-local)
 
-Source: [`packages/fs/fs-sandbox/src/index.ts:49`](../packages/fs/fs-sandbox/src/index.ts)
+Source: [`packages/fs/fs-sandbox/src/index.ts:45`](../packages/fs/fs-sandbox/src/index.ts)
 
 <a id="deepseek-aidsh-goal"></a>
 
@@ -3110,7 +3110,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/web/web-fetch-http/src/index.ts:34`](../packages/web/web-fetch-http/src/index.ts)
+Source: [`packages/web/web-fetch-http/src/index.ts:32`](../packages/web/web-fetch-http/src/index.ts)
 
 <a id="deepseek-aidsh-web-search-deepseek"></a>
 
@@ -3162,7 +3162,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/web/web-search-exa/src/index.ts:38`](../packages/web/web-search-exa/src/index.ts)
+Source: [`packages/web/web-search-exa/src/index.ts:35`](../packages/web/web-search-exa/src/index.ts)
 
 <a id="deepseek-aidsh-web-search-perplexity"></a>
 
@@ -3186,7 +3186,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/web/web-search-perplexity/src/index.ts:32`](../packages/web/web-search-perplexity/src/index.ts)
+Source: [`packages/web/web-search-perplexity/src/index.ts:30`](../packages/web/web-search-perplexity/src/index.ts)
 
 <a id="deepseek-aidsh-workflow-worker-thread"></a>
 
diff --git a/docs/config-catalog.zh.md b/docs/config-catalog.zh.md
index 9481cb2b4d..b9b9b4ae82 100644
--- a/docs/config-catalog.zh.md
+++ b/docs/config-catalog.zh.md
@@ -694,7 +694,7 @@ export type Config = LocalConfig
 
 依赖：[`LocalConfig`](#deepseek-aidsh-fs-local)
 
-来源：[`packages/fs/fs-sandbox/src/index.ts:49`](../packages/fs/fs-sandbox/src/index.ts)
+来源：[`packages/fs/fs-sandbox/src/index.ts:45`](../packages/fs/fs-sandbox/src/index.ts)
 
 <a id="deepseek-aidsh-goal"></a>
 
@@ -3112,7 +3112,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/web/web-fetch-http/src/index.ts:34`](../packages/web/web-fetch-http/src/index.ts)
+来源：[`packages/web/web-fetch-http/src/index.ts:32`](../packages/web/web-fetch-http/src/index.ts)
 
 <a id="deepseek-aidsh-web-search-deepseek"></a>
 
@@ -3164,7 +3164,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/web/web-search-exa/src/index.ts:38`](../packages/web/web-search-exa/src/index.ts)
+来源：[`packages/web/web-search-exa/src/index.ts:35`](../packages/web/web-search-exa/src/index.ts)
 
 <a id="deepseek-aidsh-web-search-perplexity"></a>
 
@@ -3188,7 +3188,7 @@ export interface Config {
 }
 ```
 
-来源：[`packages/web/web-search-perplexity/src/index.ts:32`](../packages/web/web-search-perplexity/src/index.ts)
+来源：[`packages/web/web-search-perplexity/src/index.ts:30`](../packages/web/web-search-perplexity/src/index.ts)
 
 <a id="deepseek-aidsh-workflow-worker-thread"></a>
 
diff --git a/docs/event-producer-consumer.i18n.yaml b/docs/event-producer-consumer.i18n.yaml
index 4f4df86e41..0255a185ba 100644
--- a/docs/event-producer-consumer.i18n.yaml
+++ b/docs/event-producer-consumer.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/event-producer-consumer.md
-event-producer-consumer.md: 52a8003beb55c178f2ae7513f2b21d3a6c686b2b
-event-producer-consumer.zh.md: c66e07657ec3be4bd4ce1c461782a04f1b1edf8f
+event-producer-consumer.md: 43b6c2b13ce2c09b2e3c938e30651e5dcbca36b3
+event-producer-consumer.zh.md: 7813f488a494cfed0ede01443d5bad31bd4774f1
diff --git a/docs/event-producer-consumer.md b/docs/event-producer-consumer.md
index 52a8003beb..43b6c2b13c 100644
--- a/docs/event-producer-consumer.md
+++ b/docs/event-producer-consumer.md
@@ -47,10 +47,10 @@ This matrix shows which packages dispatch each harness-owned event and which pac
 | `settings/document-updated` | `emit` | [`packages/settings/settings/src/types.ts:48`](../packages/settings/settings/src/types.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `apiproxy` |
 | `settings/updated` | `emit` | [`packages/settings/settings/src/types.ts:35`](../packages/settings/settings/src/types.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) |
 | `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:297`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
-| `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:166`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), `server`, [`subagent`](../packages/subagent/subagent) |
-| `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:140`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
-| `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:146`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
-| `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:157`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`subagent`](../packages/subagent/subagent) |
+| `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:164`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), `server`, [`subagent`](../packages/subagent/subagent) |
+| `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:138`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
+| `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:144`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
+| `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:155`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`subagent`](../packages/subagent/subagent) |
 | `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:31`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`system-prompt`](../packages/core/system-prompt) |
 | `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:37`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
 | `tools/change` | `emit` | [`packages/core/tools/src/index.ts:207`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
diff --git a/docs/event-producer-consumer.zh.md b/docs/event-producer-consumer.zh.md
index c66e07657e..7813f488a4 100644
--- a/docs/event-producer-consumer.zh.md
+++ b/docs/event-producer-consumer.zh.md
@@ -49,10 +49,10 @@
 | `settings/document-updated` | `emit` | [`packages/settings/settings/src/types.ts:48`](../packages/settings/settings/src/types.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | `apiproxy` |
 | `settings/updated` | `emit` | [`packages/settings/settings/src/types.ts:35`](../packages/settings/settings/src/types.ts) | [`settings`](../packages/settings/settings) (`events.dispatch`) | [`settings`](../packages/settings/settings) |
 | `skills/change` | `emit` | [`packages/skill/skill/src/index.ts:297`](../packages/skill/skill/src/index.ts) | [`skill`](../packages/skill/skill) (`events.dispatch`) | - |
-| `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:166`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), `server`, [`subagent`](../packages/subagent/subagent) |
-| `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:140`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
-| `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:146`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
-| `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:157`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`subagent`](../packages/subagent/subagent) |
+| `subagent/end` | `emit` | [`packages/subagent/subagent/src/index.ts:164`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), `server`, [`subagent`](../packages/subagent/subagent) |
+| `subagent/provider-added` | `emit` | [`packages/subagent/subagent/src/index.ts:138`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`emit`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
+| `subagent/provider-removed` | `emit` | [`packages/subagent/subagent/src/index.ts:144`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`subagent`](../packages/subagent/subagent), [`tool-subagent`](../packages/subagent/tool-subagent) |
+| `subagent/start` | `emit` | [`packages/subagent/subagent/src/index.ts:155`](../packages/subagent/subagent/src/index.ts) | [`subagent`](../packages/subagent/subagent) (`events.dispatch`) | [`hooks-claude-code`](../packages/hooks/hooks-claude-code), [`subagent`](../packages/subagent/subagent) |
 | `system-prompt/assemble` | `waterfall` | [`packages/core/system-prompt/src/index.ts:31`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`waterfall`) | [`agent`](../packages/core/agent), [`agent-presets`](../packages/preset/agent-presets), [`system-prompt`](../packages/core/system-prompt) |
 | `system-prompt/change` | `emit` | [`packages/core/system-prompt/src/index.ts:37`](../packages/core/system-prompt/src/index.ts) | [`system-prompt`](../packages/core/system-prompt) (`emit`) | - |
 | `tools/change` | `emit` | [`packages/core/tools/src/index.ts:207`](../packages/core/tools/src/index.ts) | [`tools`](../packages/core/tools) (`emit`) | - |
diff --git a/docs/subsystems/session-telemetry.i18n.yaml b/docs/subsystems/session-telemetry.i18n.yaml
index 8624d3c10d..9e8a3fa318 100644
--- a/docs/subsystems/session-telemetry.i18n.yaml
+++ b/docs/subsystems/session-telemetry.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write docs/subsystems/session-telemetry.md
-session-telemetry.md: 1158171c30228389317f708a35114bf4495a4e34
-session-telemetry.zh.md: f6c2d1dccf5ef5e6dad8e6e11ea843310a53f2d1
+session-telemetry.md: 718fe5dabfd1c059a6a02077407480e96bdd271a
+session-telemetry.zh.md: d4081664a121877e36a2cba123e9c5840108b529
diff --git a/docs/subsystems/session-telemetry.md b/docs/subsystems/session-telemetry.md
index 1158171c30..718fe5dabf 100644
--- a/docs/subsystems/session-telemetry.md
+++ b/docs/subsystems/session-telemetry.md
@@ -64,9 +64,8 @@ The seam's acknowledgement contract (owned by the [Service Definition README's s
 /**
  * Deployment-selected session-sharing policy disclosed by a mounted
  * {@link SessionTelemetryBackend} backend to human-facing acknowledgement surfaces (the
- * `/feedback` command's confirmation text). The seam owns the vocabulary so
- * any backend can disclose a policy without depending on the OTel package;
- * the values mirror the OTel backend's serialized `SessionTelemetryMode` choices.
+ * `/feedback` command's confirmation text). The Service Definition owns the
+ * vocabulary so consumers and backends do not depend on a specific provider.
  */
 type SessionTelemetrySharingStatus = 'full' | 'feedback-only' | 'disabled'
 ```
diff --git a/docs/subsystems/session-telemetry.zh.md b/docs/subsystems/session-telemetry.zh.md
index f6c2d1dccf..d4081664a1 100644
--- a/docs/subsystems/session-telemetry.zh.md
+++ b/docs/subsystems/session-telemetry.zh.md
@@ -64,9 +64,8 @@ interface SessionTelemetryRecord {
 /**
  * Deployment-selected session-sharing policy disclosed by a mounted
  * {@link SessionTelemetryBackend} backend to human-facing acknowledgement surfaces (the
- * `/feedback` command's confirmation text). The seam owns the vocabulary so
- * any backend can disclose a policy without depending on the OTel package;
- * the values mirror the OTel backend's serialized `SessionTelemetryMode` choices.
+ * `/feedback` command's confirmation text). The Service Definition owns the
+ * vocabulary so consumers and backends do not depend on a specific provider.
  */
 type SessionTelemetrySharingStatus = 'full' | 'feedback-only' | 'disabled'
 ```
diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index cfcae2eb1f..dc3c596864 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -1,9 +1,5 @@
-// FixtureApi: standalone UI development without a server. Real contract shape: unary takes
-// RpcRequest<P> and returns RpcResponse<T> (echoing the rpcId); streams yield RpcRequest<frame>
-// (the fixture IS the fake server, so it mints frame rpcIds); root respond takes ClientResponse
-// and returns RpcReceipt. fx-alpha carries a hand-built history script (74 turns, pageable);
-// prompt triggers a chunked streaming replay; cancel stops the replay; resident pending
-// approval/question requests exercise replay and composer takeover with stable rpcIds.
+// Standalone browser fixture. It models server-owned frame rpcIds and echoes
+// unary request rpcIds through the production carrier types.
 
 import {
   createAssistantMessage,
@@ -177,13 +173,6 @@ const SEARCH_MATCHES_FIXTURE: { path: string; matches: { lineNumber: number; lin
   },
 ]
 
-/**
- * The model-facing grep render text for the sample — what a UI without a search
- * card shows, attached as the view's `content`. Mirrors the real grep
- * presenter's shape (see formatGrepOutput in dsh-tool-fs-search): a
- * `Found X of Y matches` header, the matches grouped under file headers with
- * `Line N:` rows, then a spill-recovery footer.
- */
 const SEARCH_MATCHES_TEXT = [
   'Found 9 of 42 matches',
   '',
@@ -193,10 +182,6 @@ const SEARCH_MATCHES_TEXT = [
   '(Full grep result stored at: fixture://spill/grep-66. Read it to see every match.)',
 ].join('\n')
 
-/**
- * Structured glob result for the search sample (turn 68): a flat path list,
- * truncated with a larger `total` so the path card shows its capped indicator.
- */
 const SEARCH_PATHS_FIXTURE = [
   'packages/client/ui-primitives/src/SearchBlock.tsx',
   'packages/client/ui-primitives/src/SearchBlock.module.css',
@@ -205,25 +190,12 @@ const SEARCH_PATHS_FIXTURE = [
   'packages/client/ui-tool/tests/search-card.client.spec.tsx',
 ]
 
-/**
- * The model-facing glob render text — the newline-joined path list plus a
- * spill-recovery footer, mirroring the real glob presenter's shape (see
- * formatGlobOutput in dsh-tool-fs-search).
- */
 const SEARCH_PATHS_TEXT = [
   ...SEARCH_PATHS_FIXTURE,
   '',
   '(Showing 5 of 23 paths. Full sorted result stored at: fixture://spill/glob-67. Read it to see every path.)',
 ].join('\n')
 
-/**
- * Read-card sample for the read turn: a WINDOW past an offset, so the line
- * numbers start above 1 (the card's gutter keeps the file's own numbering) and
- * `totalLines` exceeds the window (the card shows a "showing N of M" note). The
- * fixture is client-side and cannot import the read tool, so the structured
- * window is authored inline exactly as the tool would project it through
- * `presentationMeta`. `lang` is a `ts` hint so the shiki path highlights it.
- */
 const READ_SAMPLE_FIRST_LINE = 41
 const READ_SAMPLE_SOURCE = [
   'export interface ReadBlockProps {',
@@ -373,8 +345,7 @@ function buildAlphaLog(): SessionEvent[] {
     events.push({ seq, time: (time += 800), ...authored })
     return seq
   }
-  // This resident history represents completed model requests, so retain the
-  // route capacity that accompanied them just as the live prompt path does.
+  // Completed fixture requests retain the route capacity recorded with them.
   push({
     type: 'request/context',
     data: { provider: 'deepseek-official', model: 'deepseek-v4-flash', contextWindow: 128_000 },
@@ -2021,7 +1992,7 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
   /** At most one in-flight replay per session; cancel clears it. */
   const replays = new Map<SessionId, { timer: ReturnType<typeof setTimeout>; finish(aborted: boolean): void }>()
 
-  /** history transit delay (timing hooks below); the page snapshot is taken at request time, like a real host. */
+  /** History transit delay; the page snapshot is taken at request time. */
   let historyDelayMs = 0
   /** One-shot history failure (timing hook: a pre-disconnect history request already doomed when reconnect lands). */
   let failNextHistory = false
@@ -2032,10 +2003,7 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
   /** The single opt-in browser stress producer; normal fixture journeys never start it. */
   let activeReasoningChunkStorm: ReasoningChunkStormState | null = null
 
-  // Timing-acceptance hooks (browser test backdoor): the in-memory fixture is
-  // ideally timed. These let
-  // browser acceptance runs create slow-history, lost-frame, and reconnect
-  // windows a real host produces naturally.
+  // Browser-only timing hooks for slow history, lost frames, and reconnects.
   const timingHooks = {
     setHistoryDelay(ms: number): void {
       historyDelayMs = ms
@@ -2357,7 +2325,7 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
         modelSelections.set(created.sessionId, { provider: 'deepseek-official', model: 'deepseek-v4-flash' })
         attachedSessions += 1
         const emitSession = (): void => {
-          // Mirrors the host: the frame fires at creation, so blank is constantly true.
+          // The creation frame precedes later workspace-attachment work.
           emitHost({ type: 'host/session-added', sessionId: created.sessionId, blank: true, cwd })
         }
         if (workspace !== undefined && options.failWorkspaceAttach) {
@@ -2447,7 +2415,7 @@ function createFixtureWorld(options: FixtureOptions): FixtureWorld {
       },
       history: async (request) => {
         const log = logs.get(request.payload.sessionId) ?? []
-        // Snapshot at request time, deliver after the transit delay (mirrors a real host under latency).
+        // Snapshot at request time, then deliver after the transit delay.
         const page = pageOf(log, request.payload.beforeSeq, request.payload.maxMessages ?? 50)
         // Tail page carries the projections block (host parallel: one consistent
         // cut over the registered units; asOfSeq = window tail seq, -1 on an
diff --git a/packages/client/connection/tests/fixture.client.spec.ts b/packages/client/connection/tests/fixture.client.spec.ts
index ed5089d345..0842eb8ed3 100644
--- a/packages/client/connection/tests/fixture.client.spec.ts
+++ b/packages/client/connection/tests/fixture.client.spec.ts
@@ -1,9 +1,3 @@
-/**
- * Fixture impl semantics: the demo data source must honor the same contract
- * shapes as the real host (paging boundaries, rpcId echo, replay lifecycle,
- * baseline replay, timing hooks) — this is the vitest-side drift detector for
- * the hand-written fixture/host parallel implementations.
- */
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import type { SessionId, WorkspaceId } from '../src/client/api.ts'
 import { RpcId } from '../src/client/api.ts'
diff --git a/packages/client/locale/tests/language-row.client.spec.tsx b/packages/client/locale/tests/language-row.client.spec.tsx
index 6f30c197e7..d1a0379912 100644
--- a/packages/client/locale/tests/language-row.client.spec.tsx
+++ b/packages/client/locale/tests/language-row.client.spec.tsx
@@ -1,6 +1,4 @@
 // @vitest-environment jsdom
-/** LanguageRow behavior: selector pill shows the active locale, the menu
- * opens/closes, and selection drives setLocale. */
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { createSnapshotStore, type SessionListState, type WorkspaceListState } from '@deepseek-ai/dsh-client-runtime/client'
@@ -13,7 +11,6 @@ afterEach(cleanup)
 
 const OPTIONS = [{ id: 'zh', label: '中文' }, { id: 'en', label: 'English' }]
 
-/** Empty global standard-kit hooks (the row reads neither). */
 function emptySessions() {
   const store = createSnapshotStore<SessionListState>(
     { ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined })
diff --git a/packages/client/modules/tests/loader.client.spec.ts b/packages/client/modules/tests/loader.client.spec.ts
index 4c9b1cd1fa..747067ba37 100644
--- a/packages/client/modules/tests/loader.client.spec.ts
+++ b/packages/client/modules/tests/loader.client.spec.ts
@@ -1,12 +1,4 @@
 // @vitest-environment jsdom
-/**
- * ClientModuleSystem behavior: lazy CJS arrival (bundle execution only
- * registers the factory), materialization on first import/require with
- * memoization and recursive self-sequencing, the resolution branch order,
- * shared in-flight arrival, invalidate-refetch (HMR), style claiming, the
- * default transport hook, and the loud failure modes (duplicate
- * registration, cycles, table misses, double boot).
- */
 import { Context } from '@deepseek-ai/cordis'
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import {
diff --git a/packages/client/runtime/src/client/index.ts b/packages/client/runtime/src/client/index.ts
index 90a2b2f5f3..d5d6333e14 100644
--- a/packages/client/runtime/src/client/index.ts
+++ b/packages/client/runtime/src/client/index.ts
@@ -39,8 +39,6 @@ export type { RootOwnerProps } from './slots.ts'
 export { SessionCreateError, SessionRuntime, scopeOf, workspaceTitleOf } from './sessions/service.ts'
 export { indexSubagentDescendants } from './sessions/subagent-lineage.ts'
 export type { SubagentDescendantSummary } from './sessions/subagent-lineage.ts'
-// The provide channel is shared with the client test runtime (one
-// materialization/projection implementation; no test-side mirror to drift).
 export { SessionProvideChannel } from './sessions/provide.ts'
 export type { SessionProvideChannelHost } from './sessions/provide.ts'
 export { createScope } from './agents/scope.ts'
diff --git a/packages/client/runtime/src/client/sessions/conversation.ts b/packages/client/runtime/src/client/sessions/conversation.ts
index 90cad73e1d..4cfa857a1f 100644
--- a/packages/client/runtime/src/client/sessions/conversation.ts
+++ b/packages/client/runtime/src/client/sessions/conversation.ts
@@ -1,9 +1,6 @@
-// ConversationSnapshot / ConversationNode: the only data shape the logic layer feeds the UI.
-// Publication contract: every change swaps the top-level object; unchanged
-// substructures keep their references (the React.memo premise). Chat node and
-// Location stores are stable live readers, so old snapshots are not time-point
-// views. callId/approvalId stay plain string here (narrow to real brands when
-// convenient).
+// Each publication replaces the top-level snapshot while preserving unchanged
+// substructure references. Stable node and location stores make old snapshots
+// live readers rather than time-point views.
 
 import type { CommandId } from '@deepseek-ai/dsh-commands/brand'
 import type { MessageId } from '@deepseek-ai/dsh-llm/brand'
diff --git a/packages/client/runtime/src/client/sessions/notifier.ts b/packages/client/runtime/src/client/sessions/notifier.ts
index 58b82d29b9..cc15beebd7 100644
--- a/packages/client/runtime/src/client/sessions/notifier.ts
+++ b/packages/client/runtime/src/client/sessions/notifier.ts
@@ -1,16 +1,8 @@
-// Notifier: subscription + batched notification primitive shared by Session and
-// SessionManager. Semantics: N markDirty calls collapse into one microtask flush, while
-// N markFrameDirty calls collapse into one animation-frame flush;
-// the flush rebuilds the snapshot cache BEFORE notifying (useSyncExternalStore requires a stable
-// getSnapshot reference). With no listeners the rebuild is skipped and only the dirty bit is set
-// (keeps frame storms cheap); the next getSnapshot rebuilds lazily.
-//
-// Freshness and notification are SEPARATE bits: a pull (ensureFresh) between
-// markDirty and the scheduled flush rebuilds the snapshot but must not
-// swallow the notification — push subscribers (object-layer watchers) would
-// otherwise starve whenever any reader pulls first.
-
-/** Subscription + batched notification primitive (shared by Session and SessionManager). */
+/**
+ * Batches structural updates in microtasks and stream updates by animation
+ * frame. Reads may rebuild a dirty snapshot without consuming the pending
+ * subscriber notification.
+ */
 export class Notifier {
   private listeners = new Set<() => void>()
   private dirty = false
@@ -33,7 +25,7 @@ export class Notifier {
     }
   }
 
-  /** State-change entry: mark dirty and schedule the batched flush. */
+  /** Mark the snapshot dirty and notify in a microtask. */
   markDirty(): void {
     this.dirty = true
     this.notifyPending = true
@@ -41,7 +33,7 @@ export class Notifier {
     this.schedule('microtask')
   }
 
-  /** Stream-change entry: mark dirty and publish the cumulative state at most once per frame. */
+  /** Mark the snapshot dirty and publish cumulative state at most once per frame. */
   markFrameDirty(): void {
     this.dirty = true
     this.notifyPending = true
diff --git a/packages/client/runtime/src/client/sessions/partial.ts b/packages/client/runtime/src/client/sessions/partial.ts
index 599ea61c3d..478b5b2791 100644
--- a/packages/client/runtime/src/client/sessions/partial.ts
+++ b/packages/client/runtime/src/client/sessions/partial.ts
@@ -1,7 +1,3 @@
-// PartialAccumulator: assistant/chunk accumulator.
-// Folds the six StreamChunk variants into AssistantBlock[] keyed by block index;
-// block-level immutability (a delta only swaps that block's reference).
-
 import type { StreamChunk } from '@deepseek-ai/dsh-llm/types'
 import type { AssistantBlock, PartialAssistant } from './conversation.ts'
 import { toAssistantBlock } from './conversation.ts'
diff --git a/packages/client/runtime/src/client/slots.ts b/packages/client/runtime/src/client/slots.ts
index 1ff51b9c58..9cd76b8f8e 100644
--- a/packages/client/runtime/src/client/slots.ts
+++ b/packages/client/runtime/src/client/slots.ts
@@ -369,7 +369,6 @@ export class SlotRegistry extends Service {
     // there before this layer commits anything.
     const dispose = (this._core as unknown as ErasedCore).register(erased, component)
     if (store !== undefined) {
-      // Register succeeded, so the target's spec is on the ledger.
       const scope = (this._core.specDynamic(options.name) as SlotSpec<SlotEntryDef>).scope
       this._acquire(store, scope)
     }
diff --git a/packages/client/ui-agent-preset/src/client/AgentPresetSection.tsx b/packages/client/ui-agent-preset/src/client/AgentPresetSection.tsx
index cac8452f00..ed7f9c24b8 100644
--- a/packages/client/ui-agent-preset/src/client/AgentPresetSection.tsx
+++ b/packages/client/ui-agent-preset/src/client/AgentPresetSection.tsx
@@ -221,7 +221,6 @@ export function AgentPresetSection(props: AgentPresetSectionProps): ReactNode {
           props.close()
         }}
       >
-        {/* Same glyph as the Models page's add affordances. */}
         <IconPlusOutline16 size={14} />
         {t('creatorDraft')}
       </button>
diff --git a/packages/client/ui-agent-preset/tests/settings-store.client.spec.ts b/packages/client/ui-agent-preset/tests/settings-store.client.spec.ts
index 36b6f2a188..3bb310a97e 100644
--- a/packages/client/ui-agent-preset/tests/settings-store.client.spec.ts
+++ b/packages/client/ui-agent-preset/tests/settings-store.client.spec.ts
@@ -54,7 +54,7 @@ function fakeApi(
         if (options.failWrite !== undefined) {
           return Promise.resolve({ rpcId: 'r', result: { ok: false as const, error: { code: 'internal', message: options.failWrite, details: {} } } })
         }
-        // A committed write moves the roster's default, exactly as the host does.
+        // A committed write moves the roster's default.
         for (const preset of presets) {
           preset.isDefault = preset.id === (payload.patch as { default?: string }).default
         }
diff --git a/packages/client/ui-attachment/src/AttachmentRail.module.css b/packages/client/ui-attachment/src/AttachmentRail.module.css
index ac8968f777..f2624bdf7d 100644
--- a/packages/client/ui-attachment/src/AttachmentRail.module.css
+++ b/packages/client/ui-attachment/src/AttachmentRail.module.css
@@ -1,7 +1,3 @@
-/* Thumbnail geometry mirrors DeepSeek Chat's composer rail: 64px cards with a
-   16px radius, remove control fully inside the card, arrows overlaid at the
-   edges instead of a scrollbar. */
-
 .root {
   position: relative;
   min-width: 0;
diff --git a/packages/client/ui-attachment/src/DropOverlay.module.css b/packages/client/ui-attachment/src/DropOverlay.module.css
index cacf9a7f5a..84e7e250bc 100644
--- a/packages/client/ui-attachment/src/DropOverlay.module.css
+++ b/packages/client/ui-attachment/src/DropOverlay.module.css
@@ -1,7 +1,5 @@
-/* Full-viewport drop invitation (DeepSeek Chat DragMask). pointer-events:
-   none — the layer is decoration; drag events must keep hitting the page so
-   the owner's enter/leave count stays balanced. The frosted sheet color is
-   the theme's drop-mask alias (dark override lives with the theme owner). */
+/* Drag events must keep reaching the page so the owner's enter/leave count
+   stays balanced. */
 .mask {
   position: fixed;
   inset: 0;
diff --git a/packages/client/ui-attachment/tests/attachment-rail.client.spec.tsx b/packages/client/ui-attachment/tests/attachment-rail.client.spec.tsx
index 6d6ee7bcd6..cc08a78d1c 100644
--- a/packages/client/ui-attachment/tests/attachment-rail.client.spec.tsx
+++ b/packages/client/ui-attachment/tests/attachment-rail.client.spec.tsx
@@ -1,7 +1,4 @@
 // @vitest-environment jsdom
-// AttachmentRail behavior in the jsdom lane: item rendering and callbacks,
-// arrow paging over stubbed scroll geometry (jsdom lays nothing out), the
-// exclusive vertical-wheel pan, and the new-item end reveal.
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render } from '@testing-library/react'
diff --git a/packages/client/ui-commands/tests/popup.client.spec.ts b/packages/client/ui-commands/tests/popup.client.spec.ts
index ef1c464c66..ad559c0e45 100644
--- a/packages/client/ui-commands/tests/popup.client.spec.ts
+++ b/packages/client/ui-commands/tests/popup.client.spec.ts
@@ -1,11 +1,3 @@
-/**
- * PopupSelectController behavior: one options load per
- * open with local search filtering, filtered highlight movement,
- * single-flight select with open-time context, consume-on-success (CAS miss
- * benign), failure-keeps-open retry semantics for both options and onSelect,
- * and binding-identity revocation of late settlements after
- * dismiss/reopen/dispose.
- */
 import { describe, expect, it, vi } from 'vitest'
 import type { SelectOption } from '../src/client/contract.ts'
 import type { PopupSpec, TokenSegment } from '../src/client/popup.ts'
diff --git a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.module.css b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.module.css
index c9e8d19d77..fc82c77cb9 100644
--- a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.module.css
+++ b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.module.css
@@ -1,8 +1,3 @@
-/* Assistant flow body: full-width narration (figma 16/28), block gap 16.
-   IconActions sit below the body with an explicit 16px top margin (figma
-   43:32997) — separate from the body's internal gap so the footer spacing
-   stays fixed when the body is a single block. */
-
 .root {
   display: flex;
   flex-direction: column;
diff --git a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
index c758827317..d47c8e12d0 100644
--- a/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
+++ b/packages/client/ui-conversation/src/client/chat/AssistantMarkdown.tsx
@@ -1,14 +1,3 @@
-// AssistantMarkdown: renders assistant blocks in order — markdown text body,
-// reasoning as the figma Think summary row (expand = indented gray text),
-// other-block JSON fallback. Tool-call heads are NOT rendered here: the chat
-// view groups them into tool rows through its keyed toolview slot (figma
-// step-summary flow). Shared by finalized nodes and the streaming partial;
-// the turn-level loading dots live in the chat view's tail, not here.
-// Finalized content (text) nodes append IconActions once their turn ends
-// (`time` is omitted for mid-turn narration and while the turn still runs);
-// their branch action is enabled only when the node is also the completed
-// turn's transcript tail. Think / tool-head-only nodes stay chrome-free.
-
 import { Fragment, memo, useMemo } from 'react'
 import type { ReactNode } from 'react'
 import type { AssistantBlock } from '@deepseek-ai/dsh-client-runtime/client'
diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.module.css b/packages/client/ui-conversation/src/client/chat/ChatView.module.css
index 73fa688f95..1ed70239f9 100644
--- a/packages/client/ui-conversation/src/client/chat/ChatView.module.css
+++ b/packages/client/ui-conversation/src/client/chat/ChatView.module.css
@@ -1,8 +1,3 @@
-/* Chat flow: one 16px rhythm everywhere through the column gap. Input
-   padding cap rides the skeleton. Under
-   `[data-conversation-scroll]` the column host owns overflow and this view
-   is ordinary flow (see ConversationRoot active-phase rules). */
-
 .root {
   position: relative;
   display: flex;
diff --git a/packages/client/ui-conversation/src/client/chat/ChatView.tsx b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
index 80f9bc2d73..8964a32482 100644
--- a/packages/client/ui-conversation/src/client/chat/ChatView.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ChatView.tsx
@@ -1,17 +1,5 @@
-// ChatView: the default conversation view — one stable keyed parent list over
-// final business Nodes, plus paging, pending steering and bottom-follow.
-// Each row dispatches through 'conversation.chat.node'; ui-tool owns the
-// tool-call renderer and its recursive root/subcall composition. A Host
-// open-path refusal from the injected opener is an in-page dialog here.
-//
-// Scroll: when nested under `[data-conversation-scroll]` (active conversation
-// column), that host is the scrollport and this view is flow content; when
-// mounted alone (unit tests), `.scroll` owns overflow. Bottom-follow and
-// prepend anchoring always target the resolved scrollport.
-//
-// Render economics: order changes only when rows enter, leave or move. Each
-// ChatNodeSeat subscribes to one Node key, so Assistant deltas and Tool
-// lifecycle updates replace only their own row without remounting it.
+// An enclosing `[data-conversation-scroll]` owns scrolling when present;
+// otherwise this view owns it. Each row subscribes to one stable node key.
 
 import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from 'react'
 import type { ConversationTimelineSnapshot } from '@deepseek-ai/dsh-client-runtime/client'
diff --git a/packages/client/ui-conversation/src/client/chat/CompactionCommandCard.tsx b/packages/client/ui-conversation/src/client/chat/CompactionCommandCard.tsx
index c2f0191d85..a4fd43723b 100644
--- a/packages/client/ui-conversation/src/client/chat/CompactionCommandCard.tsx
+++ b/packages/client/ui-conversation/src/client/chat/CompactionCommandCard.tsx
@@ -1,7 +1,5 @@
-// CompactionCommandCard: the `/compact` command's running row and its
-// successful checkpoint disclosure. Outcomes without a checkpoint keep the
-// generic command card so no-history, cancellation, and failures retain their
-// complete handler-authored text.
+// Only a structured checkpoint uses the compaction marker; all other outcomes
+// retain the command's complete settlement text.
 
 import type { ChatViewSlotProps, CommandRowOwnerProps } from '../contract/slots.ts'
 import { CompactionItem } from './CompactionItem.tsx'
diff --git a/packages/client/ui-conversation/src/client/chat/CompactionItem.tsx b/packages/client/ui-conversation/src/client/chat/CompactionItem.tsx
index b42918a603..bcab4a360a 100644
--- a/packages/client/ui-conversation/src/client/chat/CompactionItem.tsx
+++ b/packages/client/ui-conversation/src/client/chat/CompactionItem.tsx
@@ -1,10 +1,5 @@
-// CompactionItem: the one row a landed compaction contributes to the flow.
-// The conversation it shadowed on the model surface stays above it, so this
-// marker reports where the model stopped seeing that history — it never
-// replaces it. The framed checkpoint payload is written for the model and is
-// not rendered; the disclosure shows the summary from the checkpoint's own
-// cited `compaction/summary` event, and a window cut that left that event outside makes the row
-// non-expandable rather than empty.
+// A compaction marker does not replace shadowed transcript rows. It is
+// expandable only when the current window includes its cited summary.
 
 import { memo, useState } from 'react'
 import type { CompactionSummaryNode } from '@deepseek-ai/dsh-client-runtime/client'
@@ -28,7 +23,7 @@ interface CompactionItemProps {
 }
 
 /**
- * The collapsed-by-default compaction marker.
+ * Renders the model-history compaction marker.
  * @param props - the marker node off the snapshot cache.
  * @returns the marker row, with the summary disclosure when one is available.
  */
diff --git a/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
index 676e433fa5..f12992a043 100644
--- a/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
+++ b/packages/client/ui-conversation/src/client/chat/GenericCommandCard.tsx
@@ -1,9 +1,3 @@
-// GenericCommandCard: the default command row — a stripped-down
-// GenericToolCard rendering the command name and its settlement text.
-// Supplied by the chat view as the keyed commandview slot's render-site
-// fallback (an unregistered command name lands here); registrants may compose
-// it as a base, feeding the same owner payload through.
-
 import { useState, type ReactNode } from 'react'
 import type { ChatViewSlotProps, CommandRowOwnerProps } from '../contract/slots.ts'
 import { DisclosureRow, IconApiOutline14, StateDot } from '@deepseek-ai/dsh-client-ui-primitives'
@@ -35,10 +29,8 @@ export function GenericCommandCard({ node, t, runningSummary }: GenericCommandCa
   const summary = node.outcome === null
     ? runningSummary ?? t('command.running')
     : text ?? (node.outcome.kind === 'error' ? t('command.failed') : t('command.done'))
-  // Title is the bare command name: the row already reads `name · outcome`,
-  // and the dispatched line's own `/` and arguments only restate what the
-  // settlement text says (`permission · preset workspace-write`). A
-  // cross-window node whose run page fell out of the window has no name.
+  // The summary already carries the settlement text, so the title is the bare
+  // command name.
   const title = node.name ?? t('command.title')
   const state = stateOf(node.outcome)
   const body = text !== undefined && text.includes('\n') ? text : null
diff --git a/packages/client/ui-conversation/src/client/chat/MessageItem.tsx b/packages/client/ui-conversation/src/client/chat/MessageItem.tsx
index 8a882a70c5..0f2f2dcbe3 100644
--- a/packages/client/ui-conversation/src/client/chat/MessageItem.tsx
+++ b/packages/client/ui-conversation/src/client/chat/MessageItem.tsx
@@ -1,8 +1,3 @@
-// MessageItem: simple chat nodes — user and consumed-steering bubbles
-// (right-aligned, with clock + copy IconActions; branch lives only under
-// assistant answers), pending steering (copy only), context injection,
-// compaction marker, retry disclosure, and unknown-surface JSON rows.
-
 import { memo, useEffect, useMemo, useState } from 'react'
 import type { ReactNode } from 'react'
 import type {
diff --git a/packages/client/ui-conversation/src/client/queue/QueueDock.tsx b/packages/client/ui-conversation/src/client/queue/QueueDock.tsx
index 19cc9c62c8..a78ba74689 100644
--- a/packages/client/ui-conversation/src/client/queue/QueueDock.tsx
+++ b/packages/client/ui-conversation/src/client/queue/QueueDock.tsx
@@ -1,8 +1,3 @@
-// Queue dock entry: renders the authoritative transient inbox snapshot and
-// addresses per-row mutations through the session-scoped conversation face.
-//
-// The 'conversation.input.dock' SlotMap declaration lives in
-// ../contract/slots.ts beside the other input-region slots.
 import type { Context } from '@deepseek-ai/cordis'
 import { useEffect, useId, useMemo, useState } from 'react'
 import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
@@ -212,17 +207,10 @@ export function QueueDock({ useSession, updateQueue, notify, t }: QueueDockProps
   )
 }
 
-/**
- * The dock entry as a plain registrant plugin. The conversation service is
- * the action contract; the slot declaration has an independent lifecycle boundary.
- */
+/** Registers queue actions backed by the session-scoped conversation service. */
 export const queueDockEntry = {
   name: 'conversation-queue-dock',
   inject: ['slots', 'conversation', 'sessions'],
-  /**
-   * Register the queue strip as the terminal input-dock entry (order 20).
-   * @param ctx - registrant context (disposal rides ctx.effect inside slots.register).
-   */
   apply(ctx: Context): void {
     ctx.slots.inject('conversation.input.dock', () => ctx.slots.register({
       name: 'conversation.input.dock',
diff --git a/packages/client/ui-conversation/src/client/skeleton/ApprovalPanel.module.css b/packages/client/ui-conversation/src/client/skeleton/ApprovalPanel.module.css
index 87cdc07a0c..3c6cc58187 100644
--- a/packages/client/ui-conversation/src/client/skeleton/ApprovalPanel.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/ApprovalPanel.module.css
@@ -1,9 +1,3 @@
-/* Composer-takeover approval panel (draft approval.png): the same floating
-   capsule footprint as the InputBar card, with an amber header band, the
-   justification headline, a muted command line, and right-aligned actions.
-   Warn semantics ride the alias state tokens; no hardcoded colors. */
-
-/* Mirrors InputBar .root so the takeover is a content swap, not a layout jump. */
 .root {
   display: flex;
   flex-direction: column;
diff --git a/packages/client/ui-conversation/src/client/skeleton/ApprovalPanel.tsx b/packages/client/ui-conversation/src/client/skeleton/ApprovalPanel.tsx
index e700b112b4..32f7e64b92 100644
--- a/packages/client/ui-conversation/src/client/skeleton/ApprovalPanel.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/ApprovalPanel.tsx
@@ -1,17 +1,3 @@
-// ApprovalPanel: the composer-takeover approval prompt (designer draft
-// approval.png), registered as a selector-routed entry of the
-// conversation-declared composer chain. While an approval question is
-// pending, this panel occupies the composer slot in place of the InputBar:
-// an amber "Waiting for approval" strip on the card top, the model's
-// justification as the headline, the paired command in muted code text, and
-// a right-aligned refuse/allow action row. Justification and command are
-// unbounded model text, so they scroll inside the card at the shared composer
-// cap (`data-approval-scroll`) and the action row stays outside it — the
-// buttons must be reachable no matter how long the command is.
-// One-shot: the buttons disable
-// after a click and the panel leaves (the InputBar returns) on the broadcast
-// resolved frame.
-
 import { useMemo, useState } from 'react'
 import { Button } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { RunningToolCall } from '@deepseek-ai/dsh-client-runtime/client'
@@ -26,15 +12,12 @@ export function commandOf(call: RunningToolCall | undefined): string | undefined
     const args = JSON.parse(call.argsRaw) as Record<string, unknown>
     return typeof args.command === 'string' ? args.command : undefined
   } catch {
-    // Unparseable model args: the panel still renders, just without the command line.
     return undefined
   }
 }
 
 /**
- * Composer takeover boundary: mints the domain face on the carrier's stable
- * identity and remounts the flow per request key, so the one-shot answered
- * latch never leaks to the next pending approval.
+ * Render one pending approval and remount local answer state per request.
  * @param props - the selector-matched pending approval carrier plus the framework standard kit.
  * @returns The approval prompt for this request.
  */
@@ -54,9 +37,8 @@ function ApprovalFlow({ pending, command, t }: {
   command?: string
   t: ApprovalComposerProps['t']
 }) {
-  // Local one-shot latch: the panel leaves only when the resolved frame
-  // lands; until then the buttons must not re-fire. An answer failure
-  // (rejected receipt / transport) re-arms them for retry.
+  // Keep actions disabled until the resolved frame arrives; failed answers
+  // re-enable them for retry.
   const [answered, setAnswered] = useState(false)
   const answer = (outcome: 'allowed-once' | 'rejected'): void => {
     setAnswered(true)
diff --git a/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css
index 265a0bd802..588f93d057 100644
--- a/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css
@@ -1,8 +1,3 @@
-/* Conversation column skeleton: header (breadcrumb row only for subagents not fork + tabs) over the view
-   area, composer InputBar at the bottom. Column width/squeeze is layout's;
-   this fills its cell. Figma: Header 39:27730 (83px two-row), tabs 13px with
-   a 2px active bar. */
-
 .root {
   display: flex;
   flex-direction: column;
diff --git a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
index 8d11e3c5ea..33a6194a53 100644
--- a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
@@ -1,11 +1,3 @@
-// DetailsPanel: close button + the selected call's args and
-// result — args as JSON, the result raw except for a terminal-card call, whose
-// Output section is the command's terminal card. Reads the
-// selection from the shared chat
-// store (conversation writes, this panel reads — the cross-registration
-// share the store seat exists for) and derives the call material from the
-// session snapshot — no data of its own.
-
 import { Fragment } from 'react'
 import { CodeBlock } from '@deepseek-ai/dsh-client-ui-primitives'
 import { shallowEqual } from '@deepseek-ai/dsh-client-runtime/client'
@@ -14,28 +6,19 @@ import type { DetailsSlotProps } from '../contract/slots.ts'
 import { findToolCall } from '../chat/tool-node-reader.ts'
 import css from './DetailsPanel.module.css'
 
-/** Full props composed by reference from the contract (automatic shares & injected share). */
 export type DetailsPanelProps = DetailsSlotProps
 
-/**
- * Selected call material: the call's display name and args plus the frozen
- * block slice it came from. `block` is a snapshot-cached reference, so the
- * wrapper stays shallow-equal across unrelated snapshot frames; the settled /
- * running split is read off it with the `'kind' in block` discrimination
- * instead of duplicated as flags.
- */
+/** The snapshot-owned block reference must remain stable across unrelated frames. */
 interface CallMaterial {
   name: string
   argsRaw: string | null
   block: ToolCallBlock
 }
 
-/** Material of a settled result node (native call or run_code sub-dispatch). */
 function settledMaterial(node: ToolResultNode, callId: string): CallMaterial {
   return { name: node.call?.name ?? callId, argsRaw: node.call?.argsRaw ?? null, block: node }
 }
 
-/** Material of an in-flight call (native call or run_code sub-dispatch). */
 function runningMaterial(call: RunningToolCall): CallMaterial {
   return { name: call.name, argsRaw: call.argsRaw, block: call }
 }
@@ -50,7 +33,6 @@ function pretty(raw: string): string {
   try {
     return JSON.stringify(JSON.parse(raw), null, 2)
   } catch {
-    // Not JSON (streaming fragment or plain text): show verbatim.
     return raw
   }
 }
diff --git a/packages/client/ui-conversation/src/client/skeleton/EmptyHero.tsx b/packages/client/ui-conversation/src/client/skeleton/EmptyHero.tsx
index 9db09e3141..c10cec74f9 100644
--- a/packages/client/ui-conversation/src/client/skeleton/EmptyHero.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/EmptyHero.tsx
@@ -1,8 +1,5 @@
-// Hero chrome for the blank-draft phase of ConversationRoot: fish headline,
-// glow backdrop, and the workspace row. Pure presentation — the resident
-// composer is NOT rendered here (it keeps its own stable tree position in
-// ConversationRoot so the textarea survives the hero → composer flip); CSS
-// positions it over this shell's glow area during the hero phase.
+// The composer remains in ConversationRoot so switching out of the blank-draft
+// phase does not remount its textarea.
 
 import { useId } from 'react'
 import type { ReactNode, RefObject } from 'react'
@@ -119,7 +116,6 @@ export function HeroShell({ t, renderSlot, children }: HeroShellProps) {
     <div className={css.root}>
       <div className={css.stack}>
         <div className={css.headline}>
-          {/* figma 34:10412: fish 34×25 leading the headline, gap 10. */}
           <span className={css.fishHitbox}>
             {renderSlot('conversation.hero.brand.mark', { size: 34, className: css.fish }, {
               fallback: <FishLogo size={34} className={css.fish} />,
@@ -129,10 +125,7 @@ export function HeroShell({ t, renderSlot, children }: HeroShellProps) {
           <span className={css.previewBadge}>{t('hero.preview')}</span>
         </div>
         <div className={css.body}>
-          {/* The resident composer (ConversationRoot's root-owned scrollport;
-              the workspace row rides the stack above the card) is CSS-centered
-              in that scroll body during hero — see
-              ConversationRoot.module.css [data-phase='hero']. */}
+          {/* The composer remains mounted outside this component. */}
         </div>
       </div>
       {children}
diff --git a/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css b/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
index e5b85df3e9..d9911597f7 100644
--- a/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/InputBar.module.css
@@ -1,13 +1,4 @@
 
-/* Floating capsule input (figma Input_Bottom 75:8208): card floats above the
-   viewport bottom inside the centered message column; textarea on top, action
-   row below, primary action controls bottom-right. Input width rides the
-   column (--dsh-composer-card-max-width = chat content + 32px, 16px per side,
-   is a cap, not a fixed size — layout rule: the box shrinks with the center
-   column keeping its clearance). Hero variant = the same card centered in the
-   empty state; the transition between the two is a position move of one
-   component. */
-
 .root {
   display: flex;
   flex-direction: column;
diff --git a/packages/client/ui-conversation/src/client/skeleton/PermissionSelect.tsx b/packages/client/ui-conversation/src/client/skeleton/PermissionSelect.tsx
index 5230f59835..1f72d993d6 100644
--- a/packages/client/ui-conversation/src/client/skeleton/PermissionSelect.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/PermissionSelect.tsx
@@ -147,7 +147,6 @@ export function PermissionSelect({ value, locked, command, t }: PermissionSelect
               <span className={css.triggerIcon} aria-hidden>{permissionGlyph(currentValue)}</span>
             )}
             <span className={css.triggerLabel}>{current === undefined ? displayName(currentValue) : optionLabel(current)}</span>
-            {/* Same glyph + open rotation as the sibling ModelSelect trigger. */}
             <span className={clsx(css.chevron, open && css.chevronOpen)} aria-hidden>
               <IconChevronDownOutline14 />
             </span>
diff --git a/packages/client/ui-conversation/src/client/skeleton/TodoPanel.module.css b/packages/client/ui-conversation/src/client/skeleton/TodoPanel.module.css
index e67037db7d..f39b10dae4 100644
--- a/packages/client/ui-conversation/src/client/skeleton/TodoPanel.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/TodoPanel.module.css
@@ -1,8 +1,3 @@
-/* Todo strip in the composer context stack (Figma 1236:32276): tip surface,
-   status icons + secondary item labels. Its visible card aligns with the
-   GoalBar and the Queue panel inside their shared dock column: 12px radius,
-   36px collapsed row, 12px side padding, 14px tertiary leading glyph. */
-
 .root {
   box-sizing: border-box;
   flex: none;
diff --git a/packages/client/ui-conversation/src/client/skeleton/TodoPanel.tsx b/packages/client/ui-conversation/src/client/skeleton/TodoPanel.tsx
index ad627e7cad..64d2fc0480 100644
--- a/packages/client/ui-conversation/src/client/skeleton/TodoPanel.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/TodoPanel.tsx
@@ -1,10 +1,3 @@
-// TodoPanel: plan strip above the composer (the web counterpart of the TUI
-// plan panel). Renders the standing todo/write whole-list snapshot (cleared on
-// the next turn/start) — no data of its own, hidden while the list is empty.
-// Mounted through the 'conversation.input.dock' slot (QueueDock posture): the
-// dock adapter does the selecting, so the panel takes the plain list and stays
-// framework-free. Visual: figma 772:51905 / 772:52972 / 772:53419.
-
 import { useId, useState } from 'react'
 import type { Context } from '@deepseek-ai/cordis'
 import type { PropsLocale, PropsRuntime } from '@deepseek-ai/dsh-client-ui-slots'
@@ -127,26 +120,19 @@ export function TodoPanel({ todos, t }: TodoPanelProps) {
   )
 }
 
-/** Full props of a dock entry: InputZone owner share + session standard kit + global seat + the locale seat. */
+/** Props for the projected todo dock. */
 export type TodoDockProps = PropsRuntime<'conversation.input.dock'> & PropsLocale<'conversation'>
 
-/** Dock adapter: reads the host-computed 'todos' projection (whole list; absent or null renders nothing). */
+/** Renders the current todo projection, or nothing when it is absent. */
 export function TodoDock({ useProjection, t }: TodoDockProps) {
   const todos = useProjection('todos')
   return <TodoPanel todos={todos ?? []} t={t} />
 }
 
-/**
- * The plan strip as a plain registrant plugin (QueueDock posture), following
- * the input-dock declaration across independent activation and reload.
- */
+/** Registers the projected todo dock. */
 export const todoDockEntry = {
   name: 'conversation-todo-dock',
   inject: ['slots'],
-  /**
-   * Register the plan strip before the goal and queue entries (order 0).
-   * @param ctx - registrant context (disposal rides ctx.effect inside slots.register).
-   */
   apply(ctx: Context): void {
     ctx.slots.inject('conversation.input.dock', () =>
       ctx.slots.register({ name: 'conversation.input.dock', id: 'todo', order: 0, locale: NS }, TodoDock))
diff --git a/packages/client/ui-conversation/tests/apply-inject.client.spec.tsx b/packages/client/ui-conversation/tests/apply-inject.client.spec.tsx
index 1f61399fda..90b4d804cf 100644
--- a/packages/client/ui-conversation/tests/apply-inject.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/apply-inject.client.spec.tsx
@@ -1,18 +1,4 @@
 // @vitest-environment jsdom
-// apply inject factories exercised end to end against the terminal thin
-// API: the strict session API (views triple, draft mirror), the
-// provide-channel input face (machine-sink submit choreography incl.
-// transactional clear + failure retention), the resident API (selectWorkspace
-// draft carrying), the composer-bar stop face, openDetails = select action +
-// layout orchestration, and the closeDetails details API. Complements
-// chat-apply.spec.tsx (registration) and selection-survival.spec.tsx (store
-// axis). History opening is NOT an inject concern — the runtime sessions
-// service opens on watch (sessions-service.spec.ts owns that behavior).
-//
-// The inject APIs are read off the ledger entries deliberately (typed at
-// this spec's own contract): these cases pin factory choreography the UI
-// guards would mask. Rendering-path acceptance lives in
-// chat-toolview-slot.spec.tsx.
 
 import { describe, expect, it, vi } from 'vitest'
 import { SlotTestRuntime, usePinnedBrowserLanguages, stubSettingsScope } from '@deepseek-ai/dsh-client-test-runtime'
diff --git a/packages/client/ui-conversation/tests/chat-apply.client.spec.tsx b/packages/client/ui-conversation/tests/chat-apply.client.spec.tsx
index 5dc6b3d78a..c4c18f2623 100644
--- a/packages/client/ui-conversation/tests/chat-apply.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-apply.client.spec.tsx
@@ -1,9 +1,4 @@
 // @vitest-environment jsdom
-// apply wiring: the conversation service provided, the chat view registered
-// as the first 'conversation.view' ring entry declaring the whole-Tool seat,
-// the slot registrations land against a root entry's children declarations
-// (the AppFrame role), and the shared store handle rides all strict session
-// entries. Tool composition belongs to ui-tool and its machinery spec.
 
 import { describe, expect, it, vi } from 'vitest'
 import { SlotTestRuntime, usePinnedBrowserLanguages, stubSettingsScope } from '@deepseek-ai/dsh-client-test-runtime'
diff --git a/packages/client/ui-conversation/tests/chat-branch-tails.client.spec.tsx b/packages/client/ui-conversation/tests/chat-branch-tails.client.spec.tsx
index ce8c10016d..7edb6a2215 100644
--- a/packages/client/ui-conversation/tests/chat-branch-tails.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-branch-tails.client.spec.tsx
@@ -1,9 +1,4 @@
 // @vitest-environment jsdom
-// Remaining chat branch tails: MessageItem context/unknown arms,
-// user IconActions, StatsLine no-cache join,
-// AssistantMarkdown single-line reasoning. (Tool-row dispatch tails live
-// with the keyed-slot machinery specs since the tool ring dissolved into
-// renderSlot.)
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
@@ -40,7 +35,6 @@ afterEach(() => {
   vi.unstubAllGlobals()
 })
 
-// Mirrors the real lookup chain (conversation namespace, then common).
 const t: ChatNodeViewProps['t'] = makeTranslate(zh, commonZh)
 const renderMessageImages: AssistantMarkdownProps['renderMessageImages'] = () => null
 const RETRY_ID = 'retry-fixture' as Extract<ConversationNode, { kind: 'model-retry' }>['retryId']
diff --git a/packages/client/ui-conversation/tests/chat-stats.client.spec.tsx b/packages/client/ui-conversation/tests/chat-stats.client.spec.tsx
index be55ee0579..5592c24730 100644
--- a/packages/client/ui-conversation/tests/chat-stats.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-stats.client.spec.tsx
@@ -1,6 +1,4 @@
 // @vitest-environment jsdom
-// StatsLine (composer.dock entry): totals derivation + the RFC hard
-// acceptance — zero renders during streaming.
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render } from '@testing-library/react'
@@ -16,7 +14,6 @@ import { StatsLine, contextOccupancy, deriveStats, formatDuration, formatTokens,
 import { en, zh } from '../src/client/locales.ts'
 import { chatSnapshotFixture } from './chat-snapshot-fixture.client.ts'
 
-// Mirrors the real lookup chain (conversation namespace, then common).
 const t: StatsLineProps['t'] = makeTranslate(zh, commonZh)
 const tEn: StatsLineProps['t'] = makeTranslate(en, commonEn)
 
diff --git a/packages/client/ui-conversation/tests/chat-view.client.spec.tsx b/packages/client/ui-conversation/tests/chat-view.client.spec.tsx
index b81dff8e6e..b2072fb220 100644
--- a/packages/client/ui-conversation/tests/chat-view.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-view.client.spec.tsx
@@ -1,7 +1,4 @@
 // @vitest-environment jsdom
-// ChatView behavior: flow derivation, streaming isolation (Profiler counts),
-// Tool seat ownership and selection handoff — driven through a scripted
-// ObservableSnapshot fake, no wire or Tool presentation plugin.
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render, screen, waitFor, within } from '@testing-library/react'
@@ -162,8 +159,7 @@ function makeHarness(init?: Partial<ConversationSnapshot>) {
     read: () => savedScroll,
   }
   const forkAt = vi.fn()
-  // Selection rides the REAL chat store (same construction path as
-  // production; the view reads it through the PropsStore useStore share).
+  // Rows and the harness must observe the same chat-store instance.
   const chat = createChatStore().create()
   const t = makeTranslate(zh, commonZh)
   const toolOwners: Array<{
@@ -289,7 +285,6 @@ function makeHarness(init?: Partial<ConversationSnapshot>) {
     forkAt,
     // Absent-service default; mention tests override with a real resolver.
     fileMentions: () => undefined,
-    // Mirrors the real lookup chain (conversation namespace, then common).
     t,
   }
   const setSelection = (next: SelectionTarget | null): void => { chat.actions.select(next) }
@@ -343,7 +338,6 @@ describe('Chat node rendering', () => {
       ],
       turnEnds: new Map([[1, 4]]),
     })
-    // Stub provider mirroring the real service: only produced files resolve.
     h.props.fileMentions = owner => ({
       resolve: (value) => {
         if (value !== 'report.html') return undefined
diff --git a/packages/client/ui-conversation/tests/context-meter.client.spec.tsx b/packages/client/ui-conversation/tests/context-meter.client.spec.tsx
index f4bd33bb8e..83499cd6d3 100644
--- a/packages/client/ui-conversation/tests/context-meter.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/context-meter.client.spec.tsx
@@ -1,6 +1,4 @@
 // @vitest-environment jsdom
-// ContextMeter (composer trailing control): occupancy ring gating, the
-// click-open breakdown panel, and its close gestures.
 
 import { afterEach, describe, expect, it } from 'vitest'
 import { cleanup, fireEvent, render } from '@testing-library/react'
@@ -12,7 +10,6 @@ import { en, zh } from '../src/client/locales.ts'
 
 afterEach(cleanup)
 
-// Mirrors the real lookup chain (conversation namespace, then common).
 const t = makeTranslate(zh, commonZh) as ContextMeterProps['t']
 const tEn = makeTranslate(en, commonEn) as ContextMeterProps['t']
 
@@ -21,7 +18,6 @@ const BREAKDOWN = { systemTokens: 120, toolsTokens: 21_500, messageTokens: 477_0
 const segmentClass = css.segment
 if (segmentClass === undefined) throw new Error('segment class missing from ContextMeter.module.css')
 
-/** Stub the projection seat: a key-addressed table of whole values. */
 function projections(values: Record<string, unknown>): ContextMeterProps['useProjection'] {
   return (key: string) => values[key]
 }
diff --git a/packages/client/ui-conversation/tests/coverage-tails.client.spec.tsx b/packages/client/ui-conversation/tests/coverage-tails.client.spec.tsx
index c6e3563e3e..604f2fc095 100644
--- a/packages/client/ui-conversation/tests/coverage-tails.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/coverage-tails.client.spec.tsx
@@ -1,6 +1,4 @@
 // @vitest-environment jsdom
-// Branch tails the acceptance specs do not reach: the node-half apply
-// without a settings service and AssistantMarkdown reasoning/unknown block arms.
 
 import { afterEach, describe, expect, it } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
@@ -11,7 +9,6 @@ import { apply as nodeApply } from '../src/index.ts'
 import { AssistantMarkdown, type AssistantMarkdownProps } from '../src/client/chat/AssistantMarkdown.tsx'
 import { zh } from '../src/client/locales.ts'
 
-// Mirrors the real lookup chain (conversation namespace, then common).
 const t: AssistantMarkdownProps['t'] = makeTranslate(zh, commonZh)
 const renderMessageImages: AssistantMarkdownProps['renderMessageImages'] = () => null
 
diff --git a/packages/client/ui-conversation/tests/gate-branch-tails.client.spec.tsx b/packages/client/ui-conversation/tests/gate-branch-tails.client.spec.tsx
index debca260e7..6b7cc0280b 100644
--- a/packages/client/ui-conversation/tests/gate-branch-tails.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/gate-branch-tails.client.spec.tsx
@@ -19,7 +19,6 @@ import { DetailsPanel } from '../src/client/skeleton/DetailsPanel.tsx'
 import { zh } from '../src/client/locales.ts'
 import { chatSnapshotFixture } from './chat-snapshot-fixture.client.ts'
 
-// Mirrors the real lookup chain (conversation namespace, then common).
 const t: AssistantMarkdownProps['t'] = makeTranslate(zh, commonZh)
 const renderMessageImages: AssistantMarkdownProps['renderMessageImages'] = () => null
 
diff --git a/packages/client/ui-conversation/tests/image-labels.client.spec.tsx b/packages/client/ui-conversation/tests/image-labels.client.spec.tsx
index 1fc4af3987..7f4a986286 100644
--- a/packages/client/ui-conversation/tests/image-labels.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/image-labels.client.spec.tsx
@@ -1,5 +1,4 @@
 // @vitest-environment jsdom
-// Conversation-owned attachment errors and the message-image slot handoff.
 
 import { afterEach, describe, expect, it } from 'vitest'
 import { cleanup, render } from '@testing-library/react'
diff --git a/packages/client/ui-conversation/tests/input-bar.client.spec.tsx b/packages/client/ui-conversation/tests/input-bar.client.spec.tsx
index 4f32b68211..c81531afe6 100644
--- a/packages/client/ui-conversation/tests/input-bar.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-bar.client.spec.tsx
@@ -1,8 +1,4 @@
 // @vitest-environment jsdom
-// InputBar behavior over the machine wiring: Enter-send semantics (IME guard,
-// Shift newline, busy Enter policy, Ctrl/Meta steering, repeat suppression), running
-// semantics (input stays free; continuable children keep Send beside Stop), the machine pending lock,
-// decoration backdrop, error banners, status strips, and the focus-keeping mousedown.
 
 import { afterEach, describe, expect, it, onTestFinished, vi } from 'vitest'
 import { act, cleanup, fireEvent, render } from '@testing-library/react'
@@ -187,7 +183,6 @@ function bench(over?: BenchOptions) {
     useMenuLauncher: bindSnapshotSelector(menuLauncher),
     stop,
     command: over?.command ?? (() => Promise.resolve(true)),
-    // Mirrors the real lookup chain (conversation namespace, then common).
     t: over?.t ?? makeTranslate(zh, commonZh),
     renderSlot,
     variant: over?.variant ?? 'composer',
diff --git a/packages/client/ui-conversation/tests/input-matrix.client.spec.tsx b/packages/client/ui-conversation/tests/input-matrix.client.spec.tsx
index 71f96b8d4e..05d2e6b528 100644
--- a/packages/client/ui-conversation/tests/input-matrix.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-matrix.client.spec.tsx
@@ -67,7 +67,6 @@ function mountBar(shell: SessionInputShell, over?: { running?: boolean; disabled
     renderSlot: (() => null) as InputBarProps['renderSlot'],
     stop: vi.fn(),
     command: () => Promise.resolve(true),
-    // Mirrors the real lookup chain (conversation namespace, then common).
     t: makeTranslate(zh, commonZh),
     variant: 'composer',
   }
diff --git a/packages/client/ui-conversation/tests/input-scenarios.client.spec.tsx b/packages/client/ui-conversation/tests/input-scenarios.client.spec.tsx
index 6231519bc2..33d2209176 100644
--- a/packages/client/ui-conversation/tests/input-scenarios.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/input-scenarios.client.spec.tsx
@@ -176,7 +176,6 @@ async function scopedBench(register?: (inputTriggers: InputTriggerService) => vo
     renderSlot: (() => null) as InputBarProps['renderSlot'],
     stop: vi.fn(),
     command: () => Promise.resolve(true),
-    // Mirrors the real lookup chain (conversation namespace, then common).
     t: makeTranslate(zh, commonZh),
     variant: 'composer',
   }
diff --git a/packages/client/ui-conversation/tests/queue-dock.client.spec.tsx b/packages/client/ui-conversation/tests/queue-dock.client.spec.tsx
index 4367a74dad..861e8db7d6 100644
--- a/packages/client/ui-conversation/tests/queue-dock.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/queue-dock.client.spec.tsx
@@ -63,10 +63,8 @@ function liveSession(initial: ConversationSnapshot) {
   }
 }
 
-/** InputZone owner stub (the dock reads useSession only; the zone fields satisfy the owner share). */
 const INPUT_STATE: InputState = { draft: '', imageIds: [], draftRev: 0, phase: 'plain', occurrences: [], queue: [] }
 
-// Standard locale seat stub mirroring the real ns → common → key chain.
 const t: QueueDockProps['t'] = makeTranslate(zh, commonZh)
 
 function kitFor(snapshot: ConversationSnapshot, injected: Partial<QueueDockInjected> = {}) {
diff --git a/packages/client/ui-conversation/tests/skeleton.client.spec.tsx b/packages/client/ui-conversation/tests/skeleton.client.spec.tsx
index 76450d1805..ea80451b1d 100644
--- a/packages/client/ui-conversation/tests/skeleton.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/skeleton.client.spec.tsx
@@ -1,7 +1,4 @@
 // @vitest-environment jsdom
-// ConversationRoot skeleton behavior: the ONE resident composer across the
-// hero (blank session) and active phases — same textarea DOM node, machine-
-// owned draft, and the hero workspace picker (switching = retargetWorkspace).
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import type { ReactNode } from 'react'
 import { act, cleanup, fireEvent, render } from '@testing-library/react'
@@ -31,7 +28,6 @@ import type {
 } from '../src/client/contract/slots.ts'
 import type { ViewTab } from '../src/client/contract/views.ts'
 
-/** Machine-backed wiring over a sink spy. */
 function fakeWiring() {
   const sink = vi.fn(() => Promise.resolve({ kind: 'success' as const }))
   const shell = new SessionInputShell({ actx: {} as ClientContext, defaultSink: sink, commandImages: { serialize: () => Promise.resolve([]), release: () => {}, unsupportedNotice: (token: string) => `${token.trim()} images-unsupported` } })
@@ -54,7 +50,6 @@ beforeEach(() => {
   vi.stubGlobal('ResizeObserver', ResizeObserverStub)
 })
 
-// Mirrors the real lookup chain (conversation namespace, then common).
 const t: ConversationRootProps['t'] = makeTranslate(zh, commonZh)
 
 const sid = (id: string) => id as SessionId
diff --git a/packages/client/ui-conversation/tests/todo-panel.client.spec.tsx b/packages/client/ui-conversation/tests/todo-panel.client.spec.tsx
index b836b568e6..b2a2bb5dca 100644
--- a/packages/client/ui-conversation/tests/todo-panel.client.spec.tsx
+++ b/packages/client/ui-conversation/tests/todo-panel.client.spec.tsx
@@ -15,7 +15,6 @@ import type { TodoDockProps } from '../src/client/skeleton/TodoPanel.tsx'
 import { TodoDock, TodoPanel, todoDockEntry } from '../src/client/skeleton/TodoPanel.tsx'
 import { NS, zh } from '../src/client/locales.ts'
 
-// Mirrors the real lookup chain (conversation namespace, then common).
 const t: TodoDockProps['t'] = makeTranslate(zh, commonZh)
 
 afterEach(cleanup)
diff --git a/packages/client/ui-deliverables/src/client/ProducedFiles.tsx b/packages/client/ui-deliverables/src/client/ProducedFiles.tsx
index a14e2bea86..e882920378 100644
--- a/packages/client/ui-deliverables/src/client/ProducedFiles.tsx
+++ b/packages/client/ui-deliverables/src/client/ProducedFiles.tsx
@@ -1,9 +1,3 @@
-// ProducedFiles: the produced-file row a finished turn ends with. The paths
-// come pre-matched by the turn-tail chain from the mutation tools'
-// follow-along locations, never from the closing prose. Clicking one goes
-// through the same openFile the tool rows use — the Host's own opener, on the
-// Host machine.
-
 import { useLayoutEffect, useRef, useState } from 'react'
 import type { HostDescriptionSource } from '@deepseek-ai/dsh-client-connection/client'
 import type { InjectFace, PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
diff --git a/packages/client/ui-directory-picker-browse/src/client/DirectoryBrowser.module.css b/packages/client/ui-directory-picker-browse/src/client/DirectoryBrowser.module.css
index b5fbb611a4..75f59b7cb9 100644
--- a/packages/client/ui-directory-picker-browse/src/client/DirectoryBrowser.module.css
+++ b/packages/client/ui-directory-picker-browse/src/client/DirectoryBrowser.module.css
@@ -1,9 +1,3 @@
-/* Directory-browser dialog (figma 813-23126 family). The shared Modal renders
- * headless here — mask, card, Escape only — and this module owns the figma
- * frame: 680×500 card (viewport-clamped; upsized from the figma 600×420),
- * header (title + crumbs, l3 separator),
- * the one-or-two-column Miller content, and the bordered footer. */
-
 /* Doubled class beats Modal's own .dialog regardless of stylesheet order. */
 /* Short viewports clamp the card: header/footer are flex-none and the
  * columns scroll, so shrinking the height keeps Open/Cancel reachable
diff --git a/packages/client/ui-directory-picker-browse/src/client/DirectoryBrowser.tsx b/packages/client/ui-directory-picker-browse/src/client/DirectoryBrowser.tsx
index 222bcbe079..8e322d6c76 100644
--- a/packages/client/ui-directory-picker-browse/src/client/DirectoryBrowser.tsx
+++ b/packages/client/ui-directory-picker-browse/src/client/DirectoryBrowser.tsx
@@ -279,7 +279,6 @@ export function DirectoryBrowser({ open, listDirectory, createDirectory, onOpen,
   const [pathDraft, setPathDraft] = useState<string | null>(null)
   // Show-hidden toggle state (pure client-side filter, reset on each open).
   const [showHidden, setShowHidden] = useState(false)
-  // Create-folder state: null = closed; a string = the nested dialog's draft.
   const [folderDraft, setFolderDraft] = useState<string | null>(null)
   const [creatingFolder, setCreatingFolder] = useState(false)
   const [createError, setCreateError] = useState<string | null>(null)
diff --git a/packages/client/ui-directory-picker-browse/tests/directory-browser.client.spec.tsx b/packages/client/ui-directory-picker-browse/tests/directory-browser.client.spec.tsx
index 6329887add..584f791290 100644
--- a/packages/client/ui-directory-picker-browse/tests/directory-browser.client.spec.tsx
+++ b/packages/client/ui-directory-picker-browse/tests/directory-browser.client.spec.tsx
@@ -1329,7 +1329,6 @@ describe('DirectoryBrowser', () => {
     fireEvent.compositionEnd(pathInput)
     fireEvent.keyDown(pathInput, { key: 'Enter' })
     await waitFor(() => { expect(b.listDirectory).toHaveBeenLastCalledWith(DOCS, expect.any(AbortSignal)) })
-    // Create dialog: same guard.
     fireEvent.click(screen.getByRole('button', { name: 'browser.newFolder' }))
     const nameInput = screen.getByLabelText('browser.folderName')
     fireEvent.change(nameInput, { target: { value: '新建' } })
diff --git a/packages/client/ui-goal/tests/goalbar.client.spec.tsx b/packages/client/ui-goal/tests/goalbar.client.spec.tsx
index a45387f048..064b34ea9f 100644
--- a/packages/client/ui-goal/tests/goalbar.client.spec.tsx
+++ b/packages/client/ui-goal/tests/goalbar.client.spec.tsx
@@ -1,7 +1,4 @@
 // @vitest-environment jsdom
-// GoalBar behavior: the docked strip above the composer — phase labels,
-// inline edit form, and resume/clear icon actions — driven purely through
-// props, no wire. Loading, absent, and complete goals render nothing.
 
 import { act, cleanup, fireEvent, render, screen, waitFor } from '@testing-library/react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
@@ -12,7 +9,6 @@ import { GoalBar } from '../src/client/GoalBar.tsx'
 import type { GoalActionResult, GoalBarActions } from '../src/client/slots.ts'
 import { zh } from '../src/client/locales.ts'
 
-// The framework-injected t seat, stubbed over the zh dictionaries (the default locale).
 const t: Parameters<typeof GoalBar>[0]['t'] = makeTranslate(zh, commonZh)
 
 afterEach(cleanup)
diff --git a/packages/client/ui-input-trigger/src/client/MenuView.module.css b/packages/client/ui-input-trigger/src/client/MenuView.module.css
index 49ff264929..3648430816 100644
--- a/packages/client/ui-input-trigger/src/client/MenuView.module.css
+++ b/packages/client/ui-input-trigger/src/client/MenuView.module.css
@@ -1,9 +1,3 @@
-/* Trigger candidate menu (figma SLASH 39:26572 MenuDropdown): menu surface,
- * r12, hairline border, shadow-lv3, 4px inset padding; anchored to the
- * composer top edge, left-aligned with the input text. Cells follow
- * .Menu_cell (min-h 40, r10, pad 10/8, gap 8, 14/22 primary label) with a
- * trailing dimmed description. */
-
 .menu {
   position: absolute;
   bottom: calc(100% + 4px);
diff --git a/packages/client/ui-input-trigger/tests/core-menu.client.spec.ts b/packages/client/ui-input-trigger/tests/core-menu.client.spec.ts
index 9ec2d30e91..a849a7c69d 100644
--- a/packages/client/ui-input-trigger/tests/core-menu.client.spec.ts
+++ b/packages/client/ui-input-trigger/tests/core-menu.client.spec.ts
@@ -1,5 +1,3 @@
-// menuReduce generation gating, auto-close, silent group removal, cyclic
-// highlight movement, stale/no-op reference identity; exactMatch lookup.
 import { describe, expect, it } from 'vitest'
 import type { MenuState, TriggerHit } from '../src/core/contract.ts'
 import { exactMatch, MENU_CLOSED, menuReduce, seedGroups } from '../src/core/menu.ts'
@@ -12,7 +10,6 @@ const hit = (query = ''): TriggerHit => ({
   span: { start: 0, end: 1 + query.length, draftRev: 1 },
 })
 
-/** Seed sources onto the closed state and open a first generation. */
 function open(sources: readonly string[], h: TriggerHit = hit()): MenuState {
   return menuReduce(seedGroups(MENU_CLOSED, sources.map(name => ({ name }))), { type: 'hit', hit: h })
 }
diff --git a/packages/client/ui-layout/tests/apply.client.spec.ts b/packages/client/ui-layout/tests/apply.client.spec.ts
index 95f8cad439..f8f4dd3c72 100644
--- a/packages/client/ui-layout/tests/apply.client.spec.ts
+++ b/packages/client/ui-layout/tests/apply.client.spec.ts
@@ -1,10 +1,4 @@
 // @vitest-environment jsdom
-// Client apply wiring under the terminal register form: ctx.layout provided,
-// ONE register() call declares the three child slots + seats the store factory
-// + wires the panel actions through the inject hook; teardown cascades
-// (service unprovided + declarations gone + registration cleared). Node half
-// and the invariant companion ride along — one line exposes the aggregate
-// coverage gate still requires exercised.
 
 import { Context } from '@deepseek-ai/cordis'
 import { stubSettingsScope } from '@deepseek-ai/dsh-client-test-runtime'
diff --git a/packages/client/ui-layout/tests/service.client.spec.ts b/packages/client/ui-layout/tests/service.client.spec.ts
index e1267b4f49..ea4118927c 100644
--- a/packages/client/ui-layout/tests/service.client.spec.ts
+++ b/packages/client/ui-layout/tests/service.client.spec.ts
@@ -1,9 +1,3 @@
-/**
- * LayoutController behavior: the cross-plugin panel-action face. Geometry
- * lives in the entry store (layout-store.spec.ts) — here we assert the
- * delegation contract: attachPanels wiring, the three actions forwarding, the
- * unwired fail-loud, and re-attach overwriting a stale action set.
- */
 import { describe, expect, it, vi } from 'vitest'
 import { LayoutController } from '@deepseek-ai/dsh-client-ui-layout/src/client/service.ts'
 import type { PanelActions } from '@deepseek-ai/dsh-client-ui-layout/src/client/service.ts'
diff --git a/packages/client/ui-layout/tests/theme-presenter.client.spec.ts b/packages/client/ui-layout/tests/theme-presenter.client.spec.ts
index 36a4975fc9..79f6b974d0 100644
--- a/packages/client/ui-layout/tests/theme-presenter.client.spec.ts
+++ b/packages/client/ui-layout/tests/theme-presenter.client.spec.ts
@@ -1,8 +1,4 @@
 // @vitest-environment jsdom
-// ThemePresenter behavior account: root color-scheme and the palette attribute
-// follow active.colorScheme only, token variables replace the previous apply's
-// set, theme-color metadata follows the rendered body background, and dispose
-// retracts everything the presenter wrote.
 
 import { afterEach, beforeEach, describe, expect, it } from 'vitest'
 import type { ThemeSnapshot } from '@deepseek-ai/dsh-client-ui-theme/client'
diff --git a/packages/client/ui-message-feedback/src/client/MessageFeedbackActions.module.css b/packages/client/ui-message-feedback/src/client/MessageFeedbackActions.module.css
index 45055ad559..ddc25290bf 100644
--- a/packages/client/ui-message-feedback/src/client/MessageFeedbackActions.module.css
+++ b/packages/client/ui-message-feedback/src/client/MessageFeedbackActions.module.css
@@ -1,10 +1,3 @@
-/* Per-message feedback controls. The rating buttons mirror the shared message
-   IconActions chrome so the strip reads as one row. The note editor is a
-   popover portaled to document.body and fixed from the note trigger's rect,
-   so it neither competes with the row for inline width nor gets cropped by the
-   conversation column's overflow clip. Surface recipe follows the Menu card:
-   r12, inverted hairline border, shadow-lv3. */
-
 .action {
   display: inline-flex;
   align-items: center;
diff --git a/packages/client/ui-permission-presets/src/client/index.ts b/packages/client/ui-permission-presets/src/client/index.ts
index 8df17b5b32..5248dc31d9 100644
--- a/packages/client/ui-permission-presets/src/client/index.ts
+++ b/packages/client/ui-permission-presets/src/client/index.ts
@@ -111,8 +111,7 @@ export function apply(ctx: ClientContext): void {
   ctx.effect(() => ctx.locale.register('settings.permission', { zh, en }), 'ui-permission: settings row dictionaries')
 
   const connection = ctx.get('connection') as ConnectionHandle
-  // The row follows the shared describe mirror, whose owning plugin already
-  // refreshes it on document commits and reconnects.
+  // The shared SettingsScope mirror updates after document commits and reconnects.
   const controller = new PermissionPresetSettingsController(
     ctx.settingsScope.describe(), connection.api, ctx.settingsSchema)
   const load = (): Promise<void> => controller.load()
diff --git a/packages/client/ui-primitives/src/BrandWordmark.tsx b/packages/client/ui-primitives/src/BrandWordmark.tsx
index ed86980646..a9df992179 100644
--- a/packages/client/ui-primitives/src/BrandWordmark.tsx
+++ b/packages/client/ui-primitives/src/BrandWordmark.tsx
@@ -1,8 +1,3 @@
-// DeepSeek Harness brand wordmark (figma 356:14644, exact extract): whale +
-// "deepseek-official" letterforms + HARNESS badge plate in one svg. Native 182x24.
-// Ink rides currentColor; the badge text is knocked out in the inverted
-// label color so the plate stays legible in both themes.
-
 import type { IconProps } from './icons/props.ts'
 
 /** Display options for the official brand wordmark. */
diff --git a/packages/client/ui-primitives/src/ConnectionBanner.tsx b/packages/client/ui-primitives/src/ConnectionBanner.tsx
index 9954c8d782..5418e37159 100644
--- a/packages/client/ui-primitives/src/ConnectionBanner.tsx
+++ b/packages/client/ui-primitives/src/ConnectionBanner.tsx
@@ -1,8 +1,3 @@
-// ConnectionBanner: top strip surfacing connection loss. The atom is pure:
-// the owner subscribes to connection state and passes `reconnecting` down.
-// A null/connecting state upstream should stay quiet too — only an actual
-// outage (reconnect backoff in progress) shows the strip.
-
 import css from './ConnectionBanner.module.css'
 
 /**
diff --git a/packages/client/ui-primitives/src/DiffBlock.module.css b/packages/client/ui-primitives/src/DiffBlock.module.css
index c5b79006a3..4f64417d0c 100644
--- a/packages/client/ui-primitives/src/DiffBlock.module.css
+++ b/packages/client/ui-primitives/src/DiffBlock.module.css
@@ -1,9 +1,3 @@
-/* Geometry mirrors CodeBlock/TerminalBlock (12px radius, code-block surface +
-   banner row, markdown code-block font) so a diff card reads as one family with
-   a fenced block and a terminal card. The deliberate divergence, shared with
-   TerminalBlock: the body keeps `white-space: pre` and scrolls horizontally,
-   because folding a source line destroys the indentation a diff is read by. */
-
 .block {
   --dsl-diff-radius: 12px;
   --dsl-diff-line-height: 22px;
diff --git a/packages/client/ui-primitives/src/DiffBlock.tsx b/packages/client/ui-primitives/src/DiffBlock.tsx
index 41af796ab3..b1284243e6 100644
--- a/packages/client/ui-primitives/src/DiffBlock.tsx
+++ b/packages/client/ui-primitives/src/DiffBlock.tsx
@@ -1,29 +1,14 @@
-// DiffBlock: the inline-diff surface for a file mutation (write/edit) — a copy
-// control over one or more per-file hunks, each a bold path header followed by
-// the removed block (`-`, error color) and the added block (`+`, success
-// color), with a dim `└ +A -R · N file(s)` footer. Unlike the TUI's exact
-// changed-row comparison, this block renders the old and new sides in full.
-// Both front ends share the line-terminator rule and distinct-path file count.
-// Output never soft-wraps — an aligned source line keeps its indentation and
-// scrolls horizontally instead of folding. Colors resolve through --dsw-*
-// tokens; geometry mirrors CodeBlock.
-
 import { useCallback, useMemo, useState } from 'react'
 import clsx from 'clsx'
 import { writeClipboard } from './clipboard.ts'
 import css from './DiffBlock.module.css'
 
-/**
- * Output lines shown before the height cap collapses the middle. Matches
- * {@link DEFAULT_TERMINAL_MAX_LINES} so a diff card and a terminal card cut a
- * long body at the same place.
- */
+/** Output lines shown before the height cap collapses the middle. */
 export const DEFAULT_DIFF_MAX_LINES = 16
 
 /**
- * One file's change, in the shape {@link DiffBlock} draws. Structurally the
- * render-intent contract's `FileDiff`, redeclared here so this primitive stays
- * free of the tool contract (the terminal card's decoupling, applied to diffs).
+ * One file change in the form {@link DiffBlock} renders. It is declared here
+ * so this primitive stays independent of the tool contract.
  */
 export interface DiffHunk {
   /** The changed file's path, drawn verbatim as the hunk's header (the tool's model-facing path). */
diff --git a/packages/client/ui-primitives/src/FishLogo.tsx b/packages/client/ui-primitives/src/FishLogo.tsx
index 9b882a850c..130060c660 100644
--- a/packages/client/ui-primitives/src/FishLogo.tsx
+++ b/packages/client/ui-primitives/src/FishLogo.tsx
@@ -1,8 +1,3 @@
-// DeepSeek fish logo (figma I39:24057;88:8943 fillGeometry, exact extract;
-// the full-canvas rectangle path from the raw dump is a background plate and
-// is intentionally dropped). Native 23.16x17.04, rendered 24x18 by default;
-// hero usage scales to 34x25. Color rides currentColor (wordmark ink).
-
 import type { IconProps } from './icons/props.ts'
 
 /**
diff --git a/packages/client/ui-primitives/src/HoverCard.tsx b/packages/client/ui-primitives/src/HoverCard.tsx
index ea14afad1f..56dbe46fce 100644
--- a/packages/client/ui-primitives/src/HoverCard.tsx
+++ b/packages/client/ui-primitives/src/HoverCard.tsx
@@ -1,13 +1,3 @@
-// HoverCard: delayed hover-preview card portaled to document.body.
-// Same portal mechanics as Menu: the wrapper span supplies the anchor rect,
-// the card is fixed-positioned at its right edge and repositions on
-// scroll/resize while open. The card is reachable: it takes pointer events,
-// and leaving the anchor only arms a grace-delayed close, so the pointer can
-// cross the 8px gap and settle on the card to read a clipped path or title.
-// The portaled card is a React child of the wrapper, so React's enter/leave
-// traversal already treats it as inside — one pair of wrapper handlers covers
-// anchor and card alike.
-
 import { useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react'
 import type { ReactNode } from 'react'
 import { createPortal } from 'react-dom'
diff --git a/packages/client/ui-primitives/src/Menu.tsx b/packages/client/ui-primitives/src/Menu.tsx
index 46c30b8afb..0360ddf9af 100644
--- a/packages/client/ui-primitives/src/Menu.tsx
+++ b/packages/client/ui-primitives/src/Menu.tsx
@@ -1,13 +1,3 @@
-// Menu: minimal controlled dropdown (group-by pickers, project selectors).
-// Default: pure CSS positioning relative to the anchor wrapper — no popper.
-// Opt-in `portal` renders the list into document.body, fixed-positioned from
-// the anchor rect, for anchors inside overflow-clipping containers (sidebar).
-// The owner controls `open`; outside-click closing uses one document listener
-// active only while open. Submenus open on hover/focus inside the same root.
-// Entries also cover non-interactive `label` headings and `danger` rows.
-// Lists keep 12px clearance to the viewport's top/bottom edges and scroll
-// internally past that; submenu-bearing menus are exempt (see .scrollable).
-
 import { useEffect, useLayoutEffect, useRef, useState } from 'react'
 import type { CSSProperties, ReactNode } from 'react'
 import { createPortal } from 'react-dom'
diff --git a/packages/client/ui-primitives/src/Modal.tsx b/packages/client/ui-primitives/src/Modal.tsx
index 778fb82387..4686efa63a 100644
--- a/packages/client/ui-primitives/src/Modal.tsx
+++ b/packages/client/ui-primitives/src/Modal.tsx
@@ -1,8 +1,3 @@
-// Modal: controlled full-viewport dialog (create-workspace and similar).
-// The overlay portals to this document's body so ancestor stacking contexts
-// cannot leave sticky page controls above the mask. This is still an in-page
-// WebUI dialog; it never creates or targets another browser/native window.
-
 import { useEffect } from 'react'
 import type { ReactNode } from 'react'
 import { createPortal } from 'react-dom'
@@ -11,20 +6,17 @@ import { IconCloseOutline16 } from './icons/index.tsx'
 import css from './Modal.module.css'
 
 /**
- * Render a centered modal over a blurred page mask.
+ * Render a centered, body-portaled modal over a blurred page mask.
  * @param props.open - whether the dialog is showing.
  * @param props.onClose - Escape or mask click.
  * @param props.title - dialog heading (aria-label in every mode).
- * @param props.closeLabel - accessible close-button label.
+ * @param props.closeLabel - localized accessible close-button label.
  * @param props.description - optional supporting sentence under the title.
  * @param props.children - body (inputs, etc.).
  * @param props.footer - action row (Cancel / Create).
  * @param props.contentClassName - optional class for a scrollable content region.
  * @param props.headless - render children directly in the card (no default
- * header/close/body chrome) for dialogs whose figma frame owns its own
- * header structure; mask, card, Escape, and aria-label remain.
- * @param props.closeLabel - close-button aria label; the owner passes
- * localized copy (this package is cordis-free, so copy arrives via props).
+ * header/close/body chrome); mask, card, Escape, and aria-label remain.
  * @returns null when closed; otherwise the overlay tree.
  */
 export function Modal({
diff --git a/packages/client/ui-primitives/src/OnboardingSurface.tsx b/packages/client/ui-primitives/src/OnboardingSurface.tsx
index 1bbb6cbc46..bc43dcd7f0 100644
--- a/packages/client/ui-primitives/src/OnboardingSurface.tsx
+++ b/packages/client/ui-primitives/src/OnboardingSurface.tsx
@@ -1,19 +1,11 @@
-// OnboardingSurface: the full-viewport first-run takeover an onboarding step
-// wraps its visible content in. The overlay portals to this document's body
-// (the Modal precedent: ancestor stacking contexts cannot leave sticky page
-// controls above the mask), and the surface holds `#root` inert for exactly
-// its own lifetime — a step that renders null paints nothing and blocks
-// nothing, so "should onboarding show right now" stays a plain render
-// decision inside the step component.
-
 import { useEffect } from 'react'
 import type { ReactNode } from 'react'
 import { createPortal } from 'react-dom'
 import css from './OnboardingSurface.module.css'
 
 /**
- * Render the onboarding takeover chrome (mask + opaque stage) around one
- * step's content and keep the application root inert while mounted.
+ * Render a body-portaled onboarding stage and keep the application root inert
+ * while mounted.
  * @param props.children - the step's page content, centered on the stage.
  * @returns the body-portaled overlay tree.
  */
diff --git a/packages/client/ui-primitives/src/ReadBlock.module.css b/packages/client/ui-primitives/src/ReadBlock.module.css
index a18afe6152..2c4cf0370d 100644
--- a/packages/client/ui-primitives/src/ReadBlock.module.css
+++ b/packages/client/ui-primitives/src/ReadBlock.module.css
@@ -1,9 +1,3 @@
-/* Geometry mirrors CodeBlock (12px radius, code-block surface + banner row,
-   markdown code-block font) so a read card and a fenced code block read as one
-   family. Content keeps `white-space: pre` and scrolls horizontally rather than
-   folding, because a source line's indentation is part of what a reader is
-   reading. */
-
 .block {
   --dsl-read-radius: 12px;
   --dsl-read-line-height: 22px;
diff --git a/packages/client/ui-primitives/src/ReadBlock.tsx b/packages/client/ui-primitives/src/ReadBlock.tsx
index a6a83d3668..9aba555e10 100644
--- a/packages/client/ui-primitives/src/ReadBlock.tsx
+++ b/packages/client/ui-primitives/src/ReadBlock.tsx
@@ -1,14 +1,3 @@
-// ReadBlock: the file surface for a read tool result — a banner (label +
-// language + a "showing N of M" note when the read is a window + a copy
-// control) over line-numbered, syntax-highlighted source. Each row carries the
-// file's OWN line number in a gutter, so a windowed read past an offset keeps
-// its file numbering rather than re-counting from 1. Highlighting reuses the
-// CodeBlock shiki path (highlight.ts) at the per-line granularity a gutter
-// needs; an unknown or absent language renders plain monospace. Long content is
-// height-capped with the same head/tail arithmetic TerminalBlock uses, so the
-// two cards collapse a long body at the same place. Colors resolve through
-// --shiki-*/--dsw-* tokens.
-
 import { useCallback, useMemo, useState, useSyncExternalStore } from 'react'
 import clsx from 'clsx'
 import { writeClipboard } from './clipboard.ts'
@@ -50,13 +39,6 @@ export interface ReadBlockProps {
   className?: string | undefined
 }
 
-/**
- * Render one line's highlighted runs. The css-variables theme colors every run,
- * so each run is a styled span; a line with no highlighting at all takes the
- * bare-text path in the caller instead (an unknown or absent language).
- * @param spans - the line's styled runs.
- * @returns the line's children.
- */
 function renderSpans(spans: readonly HighlightSpan[]) {
   return spans.map((span, index) => <span key={index} style={span.style}>{span.text}</span>)
 }
@@ -75,26 +57,19 @@ export function ReadBlock({
   maxLines = DEFAULT_READ_MAX_LINES,
   className,
 }: ReadBlockProps) {
-  // The raw text the copy control writes and the highlighter tokenizes: the
-  // window's lines joined by newlines, without the file numbers or any chrome.
-  // Highlighting the whole window in one call (not line by line) keeps grammar
-  // context across lines — a multi-line string or comment stays one construct.
+  // Whole-window highlighting preserves multiline grammar context; copy uses
+  // the same text without gutter or banner chrome.
   const raw = useMemo(() => lines.map(line => line.text).join('\n'), [lines])
   // Re-render when a lazy grammar finishes loading, so a read card that showed
   // plain text while its language's grammar imported picks up highlighting. The
   // snapshot value is opaque; only its change across renders drives the memo.
   const loaded = useSyncExternalStore(subscribeGrammarLoaded, grammarLoadCount, grammarLoadCount)
-  // Per-line highlighted runs aligned 1:1 with `lines`; undefined for an
-  // unknown/absent (or not-yet-loaded) language, when every line renders as
-  // bare text.
   const highlighted = useMemo(() => highlightLines(raw, lang), [raw, lang, loaded])
   const [expanded, setExpanded] = useState(false)
   const [copied, setCopied] = useState(false)
 
   const onCopy = useCallback(() => {
     if (copied) return
-    // The window's raw text, never the rendered tree: the gutter numbers and the
-    // banner are chrome the file does not contain.
     void writeClipboard(raw).then((ok) => {
       if (!ok) return
       setCopied(true)
@@ -106,19 +81,12 @@ export function ReadBlock({
 
   const hidden = lines.length - maxLines
   const capped = hidden > 0 && !expanded
-  // Same split arithmetic as TerminalBlock's height cap, so a long read and a
-  // long command output slice their head and tail at the same place.
   const headLines = Math.ceil(maxLines / 2)
   const tailLines = maxLines - headLines
   // A read is a window when its returned lines are fewer than the file's total;
   // the note states that so a reader is not misled that the file ends here.
   const windowed = lines.length < totalLines
 
-  /**
-   * Render a slice of the line array as gutter-numbered rows.
-   * @param slice - the lines to draw, each with its aligned run array.
-   * @returns the row elements.
-   */
   const rows = (slice: readonly (readonly [ReadBlockLine, readonly HighlightSpan[] | undefined])[]) =>
     slice.map(([line, spans]) => (
       <div key={line.number} className={css.line}>
@@ -127,8 +95,6 @@ export function ReadBlock({
       </div>
     ))
 
-  // Pair each line with its aligned run array up front, so head/tail slicing
-  // keeps the two in step without re-indexing.
   const paired = lines.map((line, index): readonly [ReadBlockLine, readonly HighlightSpan[] | undefined] =>
     [line, highlighted?.[index]])
 
@@ -141,10 +107,7 @@ export function ReadBlock({
             <span className={css.count}>{`显示 ${lines.length} / ${totalLines} 行`}</span>
           )}
           <span className={css.lang}>{lang ?? ''}</span>
-          {/* Hide copy on an empty window, matching TerminalBlock's empty-output
-              guard: a successful read of an empty file returns lines: [] with
-              card:'read', so this branch is reachable, and copying then would
-              wipe the clipboard with an empty string. */}
+          {/* Empty files omit Copy to avoid replacing the clipboard with an empty string. */}
           {lines.length > 0 && (
             <button type="button" className={css.copyButton} onClick={onCopy}>
               {copied ? '复制成功' : '复制'}
diff --git a/packages/client/ui-primitives/src/SearchBlock.module.css b/packages/client/ui-primitives/src/SearchBlock.module.css
index 5eef6e4216..467e23b709 100644
--- a/packages/client/ui-primitives/src/SearchBlock.module.css
+++ b/packages/client/ui-primitives/src/SearchBlock.module.css
@@ -1,9 +1,3 @@
-/* Geometry mirrors CodeBlock and TerminalBlock (12px radius, code-block
-   surface + banner row, markdown code-block font) so a search card reads as one
-   family with them. The deliberate divergence they share: the result rows keep
-   `white-space: pre` and scroll horizontally, because folding a long match line
-   or path destroys the alignment a reader scans by. */
-
 .block {
   --dsl-search-radius: 12px;
   --dsl-search-line-height: 22px;
@@ -15,8 +9,6 @@
   border-radius: var(--dsl-search-radius);
 }
 
-/* The banner: result summary on the left, the copy control holding its
-   intrinsic width on the right. */
 .header {
   display: flex;
   align-items: center;
diff --git a/packages/client/ui-primitives/src/SearchBlock.tsx b/packages/client/ui-primitives/src/SearchBlock.tsx
index 463a3bfa26..63989455e3 100644
--- a/packages/client/ui-primitives/src/SearchBlock.tsx
+++ b/packages/client/ui-primitives/src/SearchBlock.tsx
@@ -1,13 +1,3 @@
-// SearchBlock: the search surface for a completed content or path search — a
-// banner (result summary that folds the pre-cap total in when the tool capped
-// the result, plus a copy control), then either grep matches grouped by file
-// (each file a bold
-// path header with its `lineNumber: line` rows, the group collapsible) or a
-// flat glob path list. Both shapes flatten to one list of rows the height cap
-// slices head/tail over, and neither soft-wraps: a long match line or path
-// scrolls horizontally instead of folding. Geometry mirrors CodeBlock and
-// TerminalBlock so a search card reads as one family with them.
-
 import { useCallback, useState, type ReactNode } from 'react'
 import clsx from 'clsx'
 import { headTailCap } from './head-tail-cap.ts'
diff --git a/packages/client/ui-primitives/src/StateDot.tsx b/packages/client/ui-primitives/src/StateDot.tsx
index e83851edfc..d2b9254e30 100644
--- a/packages/client/ui-primitives/src/StateDot.tsx
+++ b/packages/client/ui-primitives/src/StateDot.tsx
@@ -1,8 +1,3 @@
-// StateDot: session state indicator (figma nodes 14:3303/3305/3312, 122:9182).
-// done/warning/error: 10x10 halo (same color, 10% opacity) around a 6x6 solid
-// core. ongoing: a pixel-art chase — the 8 outer cells of a 3x3 matrix light
-// up clockwise with a stepped trail. Colors resolve through --dsw-* tokens only.
-
 import clsx from 'clsx'
 import css from './StateDot.module.css'
 
diff --git a/packages/client/ui-primitives/src/TerminalBlock.module.css b/packages/client/ui-primitives/src/TerminalBlock.module.css
index 0d3ff07d3b..7a74327c74 100644
--- a/packages/client/ui-primitives/src/TerminalBlock.module.css
+++ b/packages/client/ui-primitives/src/TerminalBlock.module.css
@@ -1,9 +1,3 @@
-/* Geometry mirrors CodeBlock (12px radius, code-block surface + banner rows,
-   markdown code-block font) so a terminal card and a fenced code block read as
-   one family. The one deliberate divergence: output keeps `white-space: pre`
-   and scrolls horizontally, because folding a column-aligned command's output
-   destroys its alignment. */
-
 .block {
   --dsl-terminal-radius: 12px;
   --dsl-terminal-line-height: 22px;
diff --git a/packages/client/ui-primitives/src/TerminalBlock.tsx b/packages/client/ui-primitives/src/TerminalBlock.tsx
index e28c3fd657..f23c78c139 100644
--- a/packages/client/ui-primitives/src/TerminalBlock.tsx
+++ b/packages/client/ui-primitives/src/TerminalBlock.tsx
@@ -1,10 +1,3 @@
-// TerminalBlock: the terminal surface for a shell command and its output —
-// prompt line (run-state dot + shortened cwd + command), ANSI-colored output,
-// settled exit status, and a copy control for the raw output. Output never soft-wraps:
-// column-aligned output (ls, tables, box drawing) keeps its alignment and
-// scrolls horizontally instead of folding. Colors resolve through --dsw-*
-// tokens; ANSI parsing lives in ansi.ts.
-
 import { useCallback, useMemo, useState } from 'react'
 import clsx from 'clsx'
 import { parseAnsiLines, type AnsiLine } from './ansi.ts'
@@ -14,11 +7,7 @@ import { Pill } from './Pill.tsx'
 import { StateDot, type StateDotState } from './StateDot.tsx'
 import css from './TerminalBlock.module.css'
 
-/**
- * Output lines shown before the height cap collapses the middle. Matches the
- * TUI transcript's default tool-output budget so both front ends cut a long
- * command's output at the same place.
- */
+/** Output lines shown before the height cap collapses the middle. */
 export const DEFAULT_TERMINAL_MAX_LINES = 16
 
 /**
diff --git a/packages/client/ui-primitives/src/Toast.module.css b/packages/client/ui-primitives/src/Toast.module.css
index 458cce9221..ab0482b37f 100644
--- a/packages/client/ui-primitives/src/Toast.module.css
+++ b/packages/client/ui-primitives/src/Toast.module.css
@@ -1,8 +1,5 @@
-/* Transient top-center banner (DeepSeek Chat toast look): contrast fill,
-   inverted label, slide-in, then hold-and-fade. The fade delay/duration MUST
-   agree with HOLD_MS/FADE_MS in Toast.tsx: the component unmounts at their
-   sum, so a mismatched sheet either cuts the fade or leaves an invisible
-   banner blocking nothing. */
+/* Keep the fade delay and duration synchronized with HOLD_MS and FADE_MS in
+   Toast.tsx so the toast unmounts after the fade. */
 
 .toast {
   position: fixed;
@@ -11,9 +8,7 @@
   /* Above the 1000 the image lightbox backdrop uses: a failure reported while
      a preview is open must stay readable. */
   z-index: 1100;
-  /* Purely an announcement: it must never intercept clicks — in particular
-     after the CSS fade finished while a throttled background-tab timer has
-     not yet unmounted the still-hit-testable fixed element. */
+  /* Announcements never intercept clicks. */
   pointer-events: none;
   display: flex;
   align-items: center;
diff --git a/packages/client/ui-primitives/src/Tooltip.module.css b/packages/client/ui-primitives/src/Tooltip.module.css
index c5f92c8482..031c45f02f 100644
--- a/packages/client/ui-primitives/src/Tooltip.module.css
+++ b/packages/client/ui-primitives/src/Tooltip.module.css
@@ -1,10 +1,3 @@
-/* Visual spec mirrors deepsuite @deepseek/ui Tooltip.css (size m, no arrow),
-   except padding tightened 6/12 -> 3/7, type 14/22 -> 13/20, radius
-   10 -> 8, a tooltip-bg plate,
-   one text color across both themes (the plate stays dark in light and dark
-   mode). Behavior (fixed positioning off the anchor rect) is local — the
-   upstream Floating stack is intentionally not vendored. */
-
 .bubble {
   position: fixed;
   z-index: 100;
diff --git a/packages/client/ui-primitives/src/Tooltip.tsx b/packages/client/ui-primitives/src/Tooltip.tsx
index fd6bd406e5..a1893a1d39 100644
--- a/packages/client/ui-primitives/src/Tooltip.tsx
+++ b/packages/client/ui-primitives/src/Tooltip.tsx
@@ -1,12 +1,5 @@
-// Hover/focus label bubble (figma tooltip pill: dark plate, white text).
-// TODO: interaction is a placeholder (horizontal overflow clamps and a
-// vertical collision flips the bubble to the other side, but there is no
-// arrow) — visuals and behavior get a proper pass later.
-// The anchor is the child element itself (cloneElement, no wrapper node), so
-// attaching a tooltip never changes the anchor's layout context. The bubble is
-// position:fixed and coordinates come from the anchor's rect at show time, so
-// it escapes ancestor overflow clipping (the sidebar rail clips its column)
-// without a portal.
+// Cloning the anchor preserves its layout context. Fixed positioning lets the
+// bubble escape ancestor overflow clipping without a portal.
 
 import { cloneElement, useCallback, useEffect, useLayoutEffect, useRef, useState } from 'react'
 import type { FocusEventHandler, MouseEventHandler, MutableRefObject, ReactElement, Ref } from 'react'
diff --git a/packages/client/ui-primitives/src/WebBlock.module.css b/packages/client/ui-primitives/src/WebBlock.module.css
index 9f1a57be1d..3f04723e60 100644
--- a/packages/client/ui-primitives/src/WebBlock.module.css
+++ b/packages/client/ui-primitives/src/WebBlock.module.css
@@ -1,9 +1,3 @@
-/* Geometry mirrors CodeBlock/TerminalBlock (12px radius, code-block surface,
-   16px vertical margin) so a web card, a terminal card, and a fenced code block
-   read as one family. A source list is prose, not aligned output, so each row
-   wraps horizontally rather than scrolling sideways like a terminal card; the
-   list as a whole scrolls vertically within a capped height (see .sources). */
-
 .block {
   --dsl-web-radius: 12px;
 
diff --git a/packages/client/ui-primitives/src/WebBlock.tsx b/packages/client/ui-primitives/src/WebBlock.tsx
index f13220f56c..5341d86cfe 100644
--- a/packages/client/ui-primitives/src/WebBlock.tsx
+++ b/packages/client/ui-primitives/src/WebBlock.tsx
@@ -1,24 +1,3 @@
-// WebBlock: the surface for a completed web retrieval. One component draws both
-// kinds of the `web` render intent, discriminated by `kind`: a `search` shows an
-// optional provider answer above a citation list of sources (each a safe
-// external link labelled by its title, or its hostname when the provider gave
-// none, with the snippet and publication date below it), and a `fetch` shows a
-// compact retrieval summary (the linked final URL and its HTTP status). Both
-// mark a capped retrieval. Every link is a same-origin-safe external anchor:
-// only http(s) URLs become anchors (target/rel set) — the http(s) subset of the
-// allowlist MarkdownText applies to untrusted assistant-authored links (it also
-// permits mailto, excluded here); an unparseable or non-http URL renders as
-// plain text. Geometry, radius, and fonts mirror CodeBlock/TerminalBlock so a
-// web card reads as one family with them; the whole source list renders inside a
-// fixed-height scroll container (its `.sources` max-height), so a long list
-// scrolls in place rather than growing the card — and that container's
-// `padding-left` must stay wide enough for the widest `<li>` marker, since a
-// scroll container clips inline-start overflow irrecoverably. The card draws every source the
-// view carries: the tool already cut the list to its source cap, and `truncated`
-// reports that cut. A content-only transform downstream of the tool — spill-policy
-// replacing an oversized result's text while leaving its presentationMeta whole —
-// can still narrow what the model reads below this list.
-
 import clsx from 'clsx'
 import { MarkdownText } from './markdown/MarkdownText.tsx'
 import css from './WebBlock.module.css'
diff --git a/packages/client/ui-primitives/src/ansi.ts b/packages/client/ui-primitives/src/ansi.ts
index 9eeba29e12..534d2ab42f 100644
--- a/packages/client/ui-primitives/src/ansi.ts
+++ b/packages/client/ui-primitives/src/ansi.ts
@@ -1,9 +1,5 @@
-// ANSI model behind TerminalBlock: anser splits the SGR runs, this module
-// resolves each run's colors and decorations into a plain style record and
-// folds the runs into per-line span arrays so a height cap can slice whole
-// lines. Sequences anser does not turn into color (OSC, cursor movement,
-// other C0 controls) are removed before parsing so they never reach the DOM
-// as literal characters.
+// Strip control sequences that anser does not consume before resolving SGR
+// runs, so they cannot reach the DOM as literal characters.
 
 import Anser from 'anser'
 import type { CSSProperties } from 'react'
diff --git a/packages/client/ui-primitives/src/head-tail-cap.ts b/packages/client/ui-primitives/src/head-tail-cap.ts
index f0852052a4..195a1c98be 100644
--- a/packages/client/ui-primitives/src/head-tail-cap.ts
+++ b/packages/client/ui-primitives/src/head-tail-cap.ts
@@ -1,8 +1,3 @@
-// Head/tail height-cap arithmetic shared by the block primitives (TerminalBlock,
-// SearchBlock), so long results use consistent head and tail slices. The split is
-// `ceil(maxLines / 2)` head rows and the remainder as tail rows; a result within
-// the cap shows every row and hides none.
-
 /** The head/tail split metrics for a capped list. */
 export interface HeadTailCap {
   /** Rows beyond the cap (list length − maxLines); ≤ 0 means nothing is hidden. */
diff --git a/packages/client/ui-primitives/src/markdown/CodeBlock.tsx b/packages/client/ui-primitives/src/markdown/CodeBlock.tsx
index 7f2fb1caf7..d79f2b47f9 100644
--- a/packages/client/ui-primitives/src/markdown/CodeBlock.tsx
+++ b/packages/client/ui-primitives/src/markdown/CodeBlock.tsx
@@ -1,9 +1,3 @@
-// CodeBlock: one code surface for every consumer — markdown fences, the
-// run_code program body, and the details panel's raw args/output — with
-// shiki highlighting for the registered grammars and an identical-geometry
-// plain fallback for everything else. Chrome (language banner + copy) matches
-// deepsuite `@deepseek/md` code blocks; token colors stay on `--shiki-*`.
-
 import { useCallback, useMemo, useRef, useState, useSyncExternalStore } from 'react'
 import clsx from 'clsx'
 import { writeClipboard } from '../clipboard.ts'
diff --git a/packages/client/ui-primitives/src/pointer-grace.ts b/packages/client/ui-primitives/src/pointer-grace.ts
index 1619cfe66e..4b91a84b0a 100644
--- a/packages/client/ui-primitives/src/pointer-grace.ts
+++ b/packages/client/ui-primitives/src/pointer-grace.ts
@@ -1,9 +1,3 @@
-// Shared close timing for pointer-dismissed popups (HoverCard, hover-closing
-// Menu). Both float free of their anchor, so the pointer has to cross ground
-// that belongs to neither on its way in; closing on the first pointerleave
-// makes the popup unreachable. The grace turns that transit into a cancelable
-// pending close.
-
 import { useCallback, useEffect, useRef } from 'react'
 
 /**
diff --git a/packages/client/ui-primitives/src/use-copy-feedback.ts b/packages/client/ui-primitives/src/use-copy-feedback.ts
index 1340a00625..73c8581206 100644
--- a/packages/client/ui-primitives/src/use-copy-feedback.ts
+++ b/packages/client/ui-primitives/src/use-copy-feedback.ts
@@ -1,9 +1,3 @@
-// The copy-to-clipboard-with-feedback hook shared by the block primitives
-// (TerminalBlock, SearchBlock): write the given text, and on success flip a
-// transient `copied` flag that the caller renders as a "复制成功" label for one
-// second. A refused write leaves the flag untouched, so the control never claims
-// a copy the host declined.
-
 import { useCallback, useState } from 'react'
 import { writeClipboard } from './clipboard.ts'
 
diff --git a/packages/client/ui-primitives/tests/ansi.client.spec.ts b/packages/client/ui-primitives/tests/ansi.client.spec.ts
index dbd520d626..6f1f924d38 100644
--- a/packages/client/ui-primitives/tests/ansi.client.spec.ts
+++ b/packages/client/ui-primitives/tests/ansi.client.spec.ts
@@ -1,9 +1,3 @@
-// parseAnsiLines, the ANSI model behind TerminalBlock: anser's SGR runs
-// resolved into inline styles and folded into per-line span arrays, with every
-// escape and control character that carries no color removed first. The DOM
-// side of the same model (which runs get a span wrapper) is in
-// terminal-block.spec.tsx.
-
 import { describe, expect, it } from 'vitest'
 import { parseAnsiLines } from '../src/ansi.ts'
 
@@ -12,12 +6,10 @@ const BS = '\u0008'
 /** A combining acute accent: zero-width, so it takes no terminal column. */
 const ACCENT = '\u0301'
 
-/** Paint `text` with the SGR `codes`, then reset. */
 function sgr(codes: string, text: string): string {
   return `${ESC}[${codes}m${text}${ESC}[0m`
 }
 
-/** The single span of a single-line, single-run parse. */
 function onlySpan(text: string) {
   const lines = parseAnsiLines(text)
   expect(lines).toHaveLength(1)
diff --git a/packages/client/ui-primitives/tests/code-block.client.spec.tsx b/packages/client/ui-primitives/tests/code-block.client.spec.tsx
index 9179ec9797..f1599c9bc5 100644
--- a/packages/client/ui-primitives/tests/code-block.client.spec.tsx
+++ b/packages/client/ui-primitives/tests/code-block.client.spec.tsx
@@ -1,9 +1,4 @@
 // @vitest-environment jsdom
-// CodeBlock + the shiki singleton: registered grammars highlight into token
-// spans colored by --shiki-* custom properties; unknown/absent languages take
-// the identical-geometry plain arm; aliases resolve; the trailing newline is
-// display-trimmed. MarkdownText's fence route is pinned in markdown.spec.tsx
-// alongside the rest of the markdown family.
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
diff --git a/packages/client/ui-primitives/tests/diff-block.client.spec.tsx b/packages/client/ui-primitives/tests/diff-block.client.spec.tsx
index 575cfd06bd..21d2ec5744 100644
--- a/packages/client/ui-primitives/tests/diff-block.client.spec.tsx
+++ b/packages/client/ui-primitives/tests/diff-block.client.spec.tsx
@@ -1,11 +1,4 @@
 // @vitest-environment jsdom
-// DiffBlock: the per-file hunk rows (path header, removed block, added block),
-// the same-file second-hunk gap separator, the `+A -R · N file(s)` footer and
-// its singular/plural, the head/tail height cap and its expand control, the
-// empty-diffs null render, and the copy control writing the prefixed diff text
-// on both the accepted and the refused clipboard paths. writeClipboard's own
-// return contract is pinned in terminal-block.spec.tsx (the shared return contract), so
-// only its DOM consequence is asserted here.
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
@@ -17,17 +10,14 @@ beforeEach(() => {
   vi.useRealTimers()
 })
 
-/** The rendered body rows, one string per visible line (CSS-module class prefix). */
 function bodyRows(container: HTMLElement): string[] {
   return [...container.querySelectorAll('[class*="_line_"]')].map(row => row.textContent ?? '')
 }
 
-/** Only the changed rows (add/del), excluding the path header and gap chrome. */
 function changeRows(container: HTMLElement): string[] {
   return [...container.querySelectorAll('[class*="_del_"], [class*="_add_"]')].map(row => row.textContent ?? '')
 }
 
-/** `count` numbered added lines as one hunk's newText. */
 function added(count: number): string {
   return Array.from({ length: count }, (_v, i) => `line ${i + 1}`).join('\n')
 }
diff --git a/packages/client/ui-primitives/tests/markdown-dom-parity.client.spec.tsx b/packages/client/ui-primitives/tests/markdown-dom-parity.client.spec.tsx
index 093b84a133..c14e2eacc2 100644
--- a/packages/client/ui-primitives/tests/markdown-dom-parity.client.spec.tsx
+++ b/packages/client/ui-primitives/tests/markdown-dom-parity.client.spec.tsx
@@ -1,20 +1,6 @@
 // @vitest-environment jsdom
-// DOM-parity contract for MarkdownText: every corpus document's rendered DOM
-// is pinned as a file snapshot. The fixtures were recorded from the
-// react-markdown implementation this renderer replaced; the custom mdast
-// renderer must reproduce them byte-for-byte (after whitespace
-// normalization), so a fixture diff means a user-visible markdown style
-// change and must be reviewed as such — never re-record to silence a
-// refactor.
-//
-// The fixture source is reproducible: the replaced pipeline last lived at commit
-// 9e8101b800 (origin/master before the renderer swap merged). Checking out
-// that ref in a worktree, copying this spec, and running it records all
-// fixtures from react-markdown byte-identical to the ones committed here:
-//   git worktree add /tmp/parity origin/master --detach && cd /tmp/parity
-//   pnpm install && cp <this spec> packages/client/ui-primitives/tests/
-//   npx vitest run packages/client/ui-primitives/tests/markdown-dom-parity.spec.tsx
-//   diff -r <recorded fixtures> <this branch's fixtures>   # byte-identical
+// The fixture corpus is a DOM compatibility baseline; review diffs as
+// user-visible Markdown changes rather than regenerating them for refactors.
 import { cleanup, render } from '@testing-library/react'
 import { afterEach, describe, expect, it } from 'vitest'
 import { MarkdownText } from '@deepseek-ai/dsh-client-ui-primitives'
@@ -62,7 +48,6 @@ function serializeChildren(element: Element, indent: string, inPre: boolean): st
   return out
 }
 
-/** Render one markdown source through MarkdownText and serialize the DOM. */
 function renderCase(text: string, streaming: boolean): string {
   const { container, unmount } = render(<MarkdownText text={text} streaming={streaming} />)
   const out = [...container.childNodes].map(child => serialize(child, '', false)).join('')
diff --git a/packages/client/ui-primitives/tests/read-block.client.spec.tsx b/packages/client/ui-primitives/tests/read-block.client.spec.tsx
index fab9450932..8982fb64aa 100644
--- a/packages/client/ui-primitives/tests/read-block.client.spec.tsx
+++ b/packages/client/ui-primitives/tests/read-block.client.spec.tsx
@@ -1,11 +1,4 @@
 // @vitest-environment jsdom
-// ReadBlock + the highlightLines token path: the banner (label, language, the
-// "showing N of M" note only when the read is a window, copy control), the
-// gutter-numbered rows keeping the file's own line numbers, the shiki per-line
-// highlighting resolved to css-variables token spans with an identical-geometry
-// plain fallback for an unknown/absent language, the head/tail height cap and
-// its expand control, and the copy control writing the raw window text on both
-// the accepted and refused clipboard paths.
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
@@ -18,17 +11,14 @@ beforeEach(() => {
   vi.useRealTimers()
 })
 
-/** `count` lines starting at `first`, each with distinct text. */
 function lines(count: number, first = 1): ReadBlockLine[] {
   return Array.from({ length: count }, (_value, index) => ({ number: first + index, text: `line ${first + index}` }))
 }
 
-/** The rendered rows as `<gutter><content>` strings (CSS-module class prefix). */
 function rowTexts(container: HTMLElement): string[] {
   return [...container.querySelectorAll('[class^="_line_"]')].map(row => row.textContent ?? '')
 }
 
-/** The gutter numbers of the rendered rows, in order. */
 function gutters(container: HTMLElement): string[] {
   return [...container.querySelectorAll('[class^="_gutter_"]')].map(cell => cell.textContent ?? '')
 }
diff --git a/packages/client/ui-primitives/tests/search-block.client.spec.tsx b/packages/client/ui-primitives/tests/search-block.client.spec.tsx
index 29cf87fb91..1f925a45d3 100644
--- a/packages/client/ui-primitives/tests/search-block.client.spec.tsx
+++ b/packages/client/ui-primitives/tests/search-block.client.spec.tsx
@@ -1,9 +1,4 @@
 // @vitest-environment jsdom
-// SearchBlock: both kinds (grouped grep matches and a flat glob path list), the
-// folded truncation summary, the empty arm, per-file collapse/expand, the
-// head/tail height cap and its expand control, the tail slice restoring its
-// owning file header, and the copy control writing the whole structured
-// result on both the accepted and refused clipboard paths.
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
@@ -16,17 +11,14 @@ beforeEach(() => {
   vi.useRealTimers()
 })
 
-/** The rendered result rows, one string per visible row (CSS-module class prefix). */
 function lines(container: HTMLElement): string[] {
   return [...container.querySelectorAll('[class^="_line_"]')].map(row => row.textContent ?? '')
 }
 
-/** The file-group header rows, one string per header (path + count concatenated). */
 function fileHeaders(container: HTMLElement): string[] {
   return [...container.querySelectorAll('[class^="_fileHeader_"]')].map(row => row.textContent ?? '')
 }
 
-/** `count` numbered match lines under one file, without a terminating newline. */
 function group(path: string, count: number, from = 1): SearchFileGroup {
   return {
     path,
diff --git a/packages/client/ui-primitives/tests/terminal-block.client.spec.tsx b/packages/client/ui-primitives/tests/terminal-block.client.spec.tsx
index 23a38e8e09..15ae044881 100644
--- a/packages/client/ui-primitives/tests/terminal-block.client.spec.tsx
+++ b/packages/client/ui-primitives/tests/terminal-block.client.spec.tsx
@@ -1,11 +1,4 @@
 // @vitest-environment jsdom
-// TerminalBlock: the prompt label's cwd shortening, the running/empty/settled
-// arms, the prompt line's run-state dot, the exit-status pill, the head/tail height cap and its expand control,
-// and the copy control writing the raw output on both the accepted and the
-// refused clipboard paths. writeClipboard's own return contract is pinned here
-// too, since it is the return contract both copy controls in this package share; the
-// resolution of ANSI runs into styles is pinned in ansi.spec.ts, so only its
-// DOM consequence (which runs get a span wrapper) is asserted here.
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
@@ -20,12 +13,10 @@ beforeEach(() => {
   vi.useRealTimers()
 })
 
-/** The rendered output rows, one string per visible line (CSS-module class prefix). */
 function outputLines(container: HTMLElement): string[] {
   return [...container.querySelectorAll('[class^="_line_"]')].map(row => row.textContent ?? '')
 }
 
-/** The prompt line's run-state dot: its StateDot state plus the hidden text label beside it. */
 function runStateOf(container: HTMLElement): { state: string | null; label: string | undefined } {
   const dot = container.querySelector('[class*="_runState_"][data-state]')
   return {
@@ -34,12 +25,10 @@ function runStateOf(container: HTMLElement): { state: string | null; label: stri
   }
 }
 
-/** The prompt rows as `<label><command>`, one per command line (the visual gap is CSS). */
 function promptRows(container: HTMLElement): string[] {
   return [...container.querySelectorAll('[class^="_promptLine_"]')].map(row => (row.textContent ?? '').trim())
 }
 
-/** `count` numbered output lines, without the terminating newline. */
 function body(count: number): string {
   return Array.from({ length: count }, (_value, index) => `line ${index + 1}`).join('\n')
 }
diff --git a/packages/client/ui-primitives/tests/web-block.client.spec.tsx b/packages/client/ui-primitives/tests/web-block.client.spec.tsx
index 69ff1bf609..c595a7ef06 100644
--- a/packages/client/ui-primitives/tests/web-block.client.spec.tsx
+++ b/packages/client/ui-primitives/tests/web-block.client.spec.tsx
@@ -1,10 +1,4 @@
 // @vitest-environment jsdom
-// WebBlock: both kinds of the web card. The search card's answer, its citation
-// list with the title-or-hostname label fallback and optional snippet/date, the
-// full source list under one <ol>, and the truncated indicator; the fetch
-// card's linked URL, status, and truncation. Safe-link
-// attributes on both kinds: an http(s) URL becomes an external anchor
-// (target/rel), any other URL renders as plain text with no href.
 
 import { afterEach, describe, expect, it } from 'vitest'
 import { cleanup, render } from '@testing-library/react'
@@ -13,7 +7,6 @@ import type { WebSourceView } from '../src/index.ts'
 
 afterEach(cleanup)
 
-/** `count` sources with sequential hostnames, so each row reads distinctly. */
 function sources(count: number): WebSourceView[] {
   return Array.from({ length: count }, (_value, index) => ({
     url: `https://site-${index}.example.com/page`,
diff --git a/packages/client/ui-renderer/tests/session-provider.client.spec.tsx b/packages/client/ui-renderer/tests/session-provider.client.spec.tsx
index 9b334624f9..e726577725 100644
--- a/packages/client/ui-renderer/tests/session-provider.client.spec.tsx
+++ b/packages/client/ui-renderer/tests/session-provider.client.spec.tsx
@@ -1,11 +1,4 @@
 // @vitest-environment jsdom
-/**
- * SessionProvider behavior account (render-prop form, framework-wired):
- * empty/body branching off the host's current-session source, key={sessionId}
- * remount semantics, and cell delivery observed through a session slot's
- * standard kit — never through the internal context objects (BindingContext
- * does not leave the package).
- */
 import { useEffect, useRef } from 'react'
 import { describe, expect, it, vi } from 'vitest'
 import { act, render } from '@testing-library/react'
diff --git a/packages/client/ui-settings-general/src/client/SettingsRoot.module.css b/packages/client/ui-settings-general/src/client/SettingsRoot.module.css
index 03e0f6372c..d9c94a1781 100644
--- a/packages/client/ui-settings-general/src/client/SettingsRoot.module.css
+++ b/packages/client/ui-settings-general/src/client/SettingsRoot.module.css
@@ -1,10 +1,3 @@
-/* Settings shell (figma 501:29904 mask context / 501:29947 panel): sidebar
-   foot trigger row + centered 1080x700 modal panel. The trigger uses the
-   sidebar foot's 42px row / 36px rail circle rhythm; the
-   panel is a two-column layout — 188px nav rail + content column with a
-   54px header and the 24px-padded options area. */
-
-/* Trigger row: the 42px foot-row box shared with the Cordis footer action. */
 .trigger {
   flex: none;
   display: flex;
diff --git a/packages/client/ui-settings-general/src/client/index.ts b/packages/client/ui-settings-general/src/client/index.ts
index dd62e8a138..574bc8e2c3 100644
--- a/packages/client/ui-settings-general/src/client/index.ts
+++ b/packages/client/ui-settings-general/src/client/index.ts
@@ -68,8 +68,7 @@ export function apply(ctx: ClientContext): void {
   // locale/change re-registration wiring.
   const t = ctx.locale.bind(NS)
   const connection = ctx.get('connection') as ConnectionHandle
-  // The action follows the shared describe mirror, whose owning plugin
-  // already refreshes it on document commits and reconnects.
+  // The shared SettingsScope mirror updates after document commits and reconnects.
   const documentController = connection.isLoopback
     ? new SettingsDocumentStore(connection.api, ctx.settingsScope.describe())
     : undefined
diff --git a/packages/client/ui-settings-models/src/client/CustomProviderCard.tsx b/packages/client/ui-settings-models/src/client/CustomProviderCard.tsx
index 617c4450d5..f84118a2c6 100644
--- a/packages/client/ui-settings-models/src/client/CustomProviderCard.tsx
+++ b/packages/client/ui-settings-models/src/client/CustomProviderCard.tsx
@@ -75,8 +75,7 @@ export interface CustomProviderCardProps {
  */
 export function CustomProviderCard(props: CustomProviderCardProps): ReactNode {
   const { taken, protocols, api, t } = props
-  // Captured at mount, like the editor's: the write must be judged against the
-  // section this card was drafted over, not whatever it grew into meanwhile.
+  // The write is checked against the revision on which this draft was opened.
   const [openedAt] = useState(() => props.revision)
   const [route, setRoute] = useState('')
   const [displayName, setDisplayName] = useState('')
diff --git a/packages/client/ui-settings-models/src/client/ModelListEditor.tsx b/packages/client/ui-settings-models/src/client/ModelListEditor.tsx
index a4b80f52a0..20276412bb 100644
--- a/packages/client/ui-settings-models/src/client/ModelListEditor.tsx
+++ b/packages/client/ui-settings-models/src/client/ModelListEditor.tsx
@@ -25,10 +25,8 @@ import type { en } from './locales.ts'
 import styles from './ModelsSection.module.css'
 
 /**
- * One configured model row. Structurally open, exactly like the DeepSeek
- * catalog editor's rows: a profile field this card does not edit — one a future
- * schema adds, or one hand-written in `settings.yaml` — has to survive being
- * edited here rather than being dropped by a rebuild.
+ * One configured model row. Fields this card does not edit must survive an
+ * edit rather than being dropped by a rebuild.
  */
 export type ModelDraft = DeepSeekModelDraft
 
diff --git a/packages/client/ui-settings-models/src/client/ModelsSection.module.css b/packages/client/ui-settings-models/src/client/ModelsSection.module.css
index 6b8c2047a4..3719535a3a 100644
--- a/packages/client/ui-settings-models/src/client/ModelsSection.module.css
+++ b/packages/client/ui-settings-models/src/client/ModelsSection.module.css
@@ -1,9 +1,4 @@
-/* Models settings section, in the settings-panel design language: 14/22 body,
- * 12/18 caption, capsule controls (h36 r18; h28 r14 where a row is dense),
- * 32px fields, and `border-l2` hairlines — the vocabulary GeneralSection and
- * the Button/Input primitives already use.
- *
- * Every color resolves through a `--dsw-alias-*` token. Bare `--border` /
+/* Every color resolves through a `--dsw-alias-*` token. Bare `--border` /
  * `--surface` / `--text-*` names, which nothing in this app defines, would
  * render the light-mode literals written as their fallbacks and stay light
  * under the dark theme. */
diff --git a/packages/client/ui-settings-models/src/client/ModelsSection.tsx b/packages/client/ui-settings-models/src/client/ModelsSection.tsx
index de377a893c..7f178564d6 100644
--- a/packages/client/ui-settings-models/src/client/ModelsSection.tsx
+++ b/packages/client/ui-settings-models/src/client/ModelsSection.tsx
@@ -151,9 +151,7 @@ function targetOf(row: ProviderRow): EditorTarget {
     settingsNs: row.entry.settingsNs,
     settingsPath: row.entry.settingsPath,
     ...credentialRef === undefined ? {} : { credentialRef },
-    // Absent is not "shipped": an adapter that answers nothing leaves the
-    // route-level fields only a declared route owns off the card, exactly as
-    // it leaves the custom tag off the row.
+    // Only declared routes may expose route-owned fields.
     ...row.entry.declared === true ? { declared: true } : {},
   }
 }
@@ -478,7 +476,6 @@ function Loaded({ injected }: { injected: ModelsSectionFace }): ReactNode {
                     setEditing(targetOf(first))
                   }}
                 >
-                  {/* Same glyph as the composer's attach button. */}
                   <IconPlusOutline16 size={14} />
                   {t('add')}
                 </button>
diff --git a/packages/client/ui-settings-plugins/src/client/index.ts b/packages/client/ui-settings-plugins/src/client/index.ts
index daf7a280dc..b7f31d6cce 100644
--- a/packages/client/ui-settings-plugins/src/client/index.ts
+++ b/packages/client/ui-settings-plugins/src/client/index.ts
@@ -72,9 +72,7 @@ export function apply(ctx: ClientContext): void {
     'ui-settings-plugins: credential invalidations',
   )
 
-  // Which namespaces the Host serves comes from the shared describe mirror,
-  // whose owning plugin already refreshes it on document commits and
-  // reconnects — the tab only derives.
+  // The shared SettingsScope mirror updates after document commits and reconnects.
   const configurable = new ConfigurablePluginsTabController(
     ctx.settingsScope.describe(), () => ctx.slots.entries('settings.plugin.item'))
   ctx.effect(() => () => { configurable.dispose() }, 'ui-settings-plugins: tab directory')
diff --git a/packages/client/ui-settings-plugins/tests/fields.client.spec.tsx b/packages/client/ui-settings-plugins/tests/fields.client.spec.tsx
index f9370106e0..d9a8d29ac2 100644
--- a/packages/client/ui-settings-plugins/tests/fields.client.spec.tsx
+++ b/packages/client/ui-settings-plugins/tests/fields.client.spec.tsx
@@ -1,8 +1,4 @@
 // @vitest-environment jsdom
-/**
- * Field-control behavior: what a control renders for a staged draft, how an
- * overridden field offers its reset, and that a control never writes on its own.
- */
 
 import { cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
diff --git a/packages/client/ui-settings-plugins/tests/section.client.spec.tsx b/packages/client/ui-settings-plugins/tests/section.client.spec.tsx
index 348319e01f..9e9bced1cb 100644
--- a/packages/client/ui-settings-plugins/tests/section.client.spec.tsx
+++ b/packages/client/ui-settings-plugins/tests/section.client.spec.tsx
@@ -1,9 +1,4 @@
 // @vitest-environment jsdom
-/**
- * What the section and its cards show: the empty line when no plugin
- * contributed one, a card that renders nothing while its namespace is
- * unavailable, and the save footer that decides when staged edits are written.
- */
 
 import { cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
@@ -30,7 +25,6 @@ afterEach(cleanup)
 
 const t = (key: keyof typeof en) => en[key]
 
-/** A settled form: nothing staged, everything served. */
 const settled: CardShell = {
   available: true,
   writable: true,
@@ -40,7 +34,6 @@ const settled: CardShell = {
   failed: false,
 }
 
-/** One control's state, defaulting to an inherited value. */
 function field(text: string, rest: Partial<CardFieldState> = {}): CardFieldState {
   return { text, overridden: false, invalid: false, ...rest }
 }
@@ -60,11 +53,6 @@ function renderSection(rows: readonly PluginsSettingsTabEntry[]) {
   render(<PluginsSettingsSection {...props} />)
 }
 
-/**
- * Render the tab over the namespaces it was told to dispatch, with `cards`
- * standing in for the slot ledger: a key it names renders that text, and one
- * it does not renders nothing, exactly as an unclaimed key does.
- */
 function renderConfigurable(namespaces: string[], cards: Record<string, string> = {}, loaded = true) {
   const store = createSnapshotStore<ConfigurablePluginsTabState>({ loaded, namespaces })
   const props = {
diff --git a/packages/client/ui-settings/tests/plugin.client.spec.ts b/packages/client/ui-settings/tests/plugin.client.spec.ts
index 136e061e0f..2dbd28630f 100644
--- a/packages/client/ui-settings/tests/plugin.client.spec.ts
+++ b/packages/client/ui-settings/tests/plugin.client.spec.ts
@@ -1,9 +1,3 @@
-/**
- * The settings domain base plugin's own mounting behavior: it stands up
- * `ctx.settingsScope` over one shared describe mirror, keeps that mirror
- * fresh on settings-document and connection-reset invalidations, and retires
- * both the service and the subscriptions with its fiber.
- */
 import { Context } from '@deepseek-ai/cordis'
 import { describe, expect, it, vi } from 'vitest'
 import { TestRemote } from '@deepseek-ai/dsh-client-test-runtime'
@@ -11,7 +5,6 @@ import { apply, inject } from '../src/client/index.ts'
 import { SettingsSchemaService } from '../src/client/schema.ts'
 import { SettingsScopeBinder } from '../src/client/settings-scope.ts'
 
-/** Boot the browser half over a fake loopback connection and test remote. */
 function bench() {
   const describeCall = vi.fn().mockResolvedValue({
     rpcId: 'plugin-bench' as never,
diff --git a/packages/client/ui-skill/src/client/SkillRow.tsx b/packages/client/ui-skill/src/client/SkillRow.tsx
index a26c41ada5..c6f9286154 100644
--- a/packages/client/ui-skill/src/client/SkillRow.tsx
+++ b/packages/client/ui-skill/src/client/SkillRow.tsx
@@ -1,7 +1,3 @@
-// Skill toolview registrant: a domain-owned row over the keyed toolview hole.
-// The compact accent row keeps loaded instructions scannable in the transcript;
-// the exact durable tool output remains available in a bounded disclosure card.
-
 import { useState, type KeyboardEvent, type ReactNode } from 'react'
 import {
   IconChevronDownOutline14, IconInspectOutline12, IconSkillOutline16, StateDot,
@@ -13,7 +9,6 @@ import css from './SkillRow.module.css'
 /** Skill row lifecycle derived solely from the durable call slice. */
 type SkillRowState = 'running' | 'ok' | 'error' | 'stopped'
 
-/** Full row props: the toolview runtime share plus this package's locale seat. */
 type SkillRowProps = ToolCallViewProps & PropsLocale<'skill'>
 
 /** Compact, replay-stable view model for the dedicated row. */
diff --git a/packages/client/ui-skill/tests/skill-row.client.spec.tsx b/packages/client/ui-skill/tests/skill-row.client.spec.tsx
index 431055101c..8fbbaef7c0 100644
--- a/packages/client/ui-skill/tests/skill-row.client.spec.tsx
+++ b/packages/client/ui-skill/tests/skill-row.client.spec.tsx
@@ -1,6 +1,4 @@
 // @vitest-environment jsdom
-// Dedicated skill tool row: replay-stable naming, lifecycle states, disclosure,
-// keyboard operation, exact output, and the trajectory Inspect handoff.
 
 import { cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { afterEach, describe, expect, it, vi } from 'vitest'
diff --git a/packages/client/ui-slots/tests/core.client.spec.ts b/packages/client/ui-slots/tests/core.client.spec.ts
index ad12700ca5..69e283ba66 100644
--- a/packages/client/ui-slots/tests/core.client.spec.ts
+++ b/packages/client/ui-slots/tests/core.client.spec.ts
@@ -1,6 +1,3 @@
-// SlotCore terminal-design behavior: the single register composition API —
-// a-priori 'root', children declaration/authorization, load-time validation,
-// one-axis lifecycle cascade, store scope pinning, subscription API.
 import { describe, expect, it, vi } from 'vitest'
 import type { SlotComponent, StoreHandle } from '@deepseek-ai/dsh-client-ui-slots'
 import { SlotCore } from '@deepseek-ai/dsh-client-ui-slots'
@@ -23,7 +20,6 @@ declare module '@deepseek-ai/dsh-client-ui-slots' {
 // RendersCheck would demand a renderSlot consumer).
 const Comp: SlotComponent<object> = () => null
 
-/** A minimal structurally-valid store handle (identity is what the ledger tracks). */
 function fakeHandle(): StoreHandle<{ n: number }, Record<string, (d: { n: number }) => void>> {
   return {
     spec: { init: () => ({ n: 0 }), actions: {} },
@@ -31,7 +27,6 @@ function fakeHandle(): StoreHandle<{ n: number }, Record<string, (d: { n: number
   }
 }
 
-/** Register a root-frame entry declaring the four test child slots. */
 function mountFrame(core: SlotCore) {
   return core.register({
     name: 'root',
diff --git a/packages/client/ui-theme/tests/appearance-row.client.spec.tsx b/packages/client/ui-theme/tests/appearance-row.client.spec.tsx
index e1658d50ea..d8764a46c6 100644
--- a/packages/client/ui-theme/tests/appearance-row.client.spec.tsx
+++ b/packages/client/ui-theme/tests/appearance-row.client.spec.tsx
@@ -1,6 +1,4 @@
 // @vitest-environment jsdom
-/** AppearanceRow behavior: three cubes, selection follows the persisted
- * preference, clicks drive setTheme. */
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
 import { createSnapshotStore, type SessionListState, type WorkspaceListState } from '@deepseek-ai/dsh-client-runtime/client'
@@ -19,7 +17,6 @@ const COPY: Record<string, string> = {
   'appearance.system': 'System',
 }
 
-/** Empty global standard-kit hooks (the row reads neither). */
 function emptySessions() {
   const store = createSnapshotStore<SessionListState>(
     { ids: [], byId: {}, current: undefined, phase: 'ready', subagentsByParent: {}, jobsBySession: {}, currentAddress: undefined })
diff --git a/packages/client/ui-tool/src/client/tool/components/ToolRow.tsx b/packages/client/ui-tool/src/client/tool/components/ToolRow.tsx
index bd4add4234..c868666c68 100644
--- a/packages/client/ui-tool/src/client/tool/components/ToolRow.tsx
+++ b/packages/client/ui-tool/src/client/tool/components/ToolRow.tsx
@@ -1,22 +1,3 @@
-// ToolRow: the single-line tool summary row (figma component set 122:9479) —
-// 16px leading slot (state dot / tool icon, chevron on hover or expanded) + title +
-// separator dot + FILL-truncated summary, drawn through the shared
-// DisclosureRow chrome with the whole row as the expand toggle (click /
-// Enter / Space, icon→chevron hover preview). The collapsed row is always
-// one line; every row with body, output, or a card material (terminal, diff,
-// read, search, web) is expandable; the summary stays inline while open.
-// The expanded body — an IN/OUT gutter-labeled card (figma 1249:35657) for
-// text input/output, the run_code program through CodeBlock, or a card
-// primitive (TerminalBlock, DiffBlock, ReadBlock, SearchBlock, WebBlock) for a
-// call that declared that render intent — lives in a max-height scroll
-// container so a long payload scrolls internally instead of taking over the
-// message flow. Every card kind starts collapsed, so a run of tool calls stays
-// scannable; the details panel is the single-call full-height reading surface.
-// Expand state is component-local view state. File-tool summaries are path
-// links that open through the host (stopPropagation keeps the two gestures
-// independent); an error row's collapsed summary is the failure's first line in
-// the error color.
-
 import { useState, type KeyboardEvent, type MouseEvent, type ReactNode } from 'react'
 import clsx from 'clsx'
 import {
@@ -32,12 +13,10 @@ import type { ToolRowState, ToolRowVariant } from '../models/tool-call-model.ts'
 import css from './ToolRow.module.css'
 
 export interface ToolRowProps {
-  /** The render site's conversation locale seat (terminal/code body copy). */
   t: TranslateNS<'conversation'>
   variant: ToolRowVariant
   /** Wire tool name for tool-owned styling layered over the generic variant. */
   toolName?: string | undefined
-  /** Leading 16px tool icon, shown while collapsed and not running/failed. */
   icon: ReactNode
   title: string
   summary: string
@@ -55,36 +34,11 @@ export interface ToolRowProps {
   output?: string | null | undefined
   /** Error first line shown as the collapsed summary on an error row; null/absent = keep `summary`. */
   errorSummary?: string | null | undefined
-  /**
-   * Terminal-card material for a call whose render intent is a terminal card
-   * (derived by `terminalCardModel`); it replaces the text sections when
-   * present. A call carries at most one card kind, so the card props below are
-   * mutually exclusive.
-   */
+  /** Terminal card; card fields are mutually exclusive and replace text sections. */
   terminal?: TerminalCardModel | null | undefined
-  /**
-   * Diff-card material for a call whose render intent is a diff card (derived by
-   * `diffCardModel`); it replaces the text body when present, the same way
-   * `terminal` does.
-   */
   diff?: DiffCardModel | null | undefined
-  /**
-   * Read-card material for a call whose render intent is a read card (derived by
-   * `readCardModel`); it replaces the text body with the file's line-numbered,
-   * syntax-highlighted window when present.
-   */
   read?: ReadCardModel | null | undefined
-  /**
-   * Search-card material for a call whose render intent is a search card
-   * (derived by `searchCardModel`); it replaces the text body with grouped
-   * matches or a path list when present.
-   */
   search?: SearchCardModel | null | undefined
-  /**
-   * Web-card material for a call whose render intent is a web card (derived by
-   * `webCardModel`); it replaces the text body with the retrieval's citation
-   * list or fetched-source card when present.
-   */
   web?: WebBlockProps | null | undefined
   state: ToolRowState
   /**
@@ -101,9 +55,6 @@ export interface ToolRowProps {
   inspect?: (() => void) | undefined
 }
 
-/** Leading-slot state substitution: the tool icon yields to the terminal state
- *  semantic (error = red, interrupted = amber halo). Running keeps the icon —
- *  the row sweep (CSS on data-state) carries the in-flight signal. */
 function leadingFor(state: ToolRowState, icon: ReactNode): ReactNode {
   switch (state) {
     case 'error': return <StateDot state="error" />
@@ -153,23 +104,14 @@ export function ToolRow({
   const searchBody = search ?? null
   const webBody = web ?? null
   const outputText = output ?? null
-  // A card replaces the text body; a call carries at most one card kind, so the
-  // card props are mutually exclusive. Any of them, or a text body/output,
-  // makes the row expandable.
   const card = terminalBody ?? diffBody ?? readBody ?? searchBody ?? webBody
   const expandable = body !== null || outputText !== null || card !== null
   const open = expanded && expandable
-  // The run-state label AT needs: the StateDot and the running sweep are both
-  // aria-hidden / colour-only, so a stopped or running row is otherwise silent.
   const status = stateStatus(state, t)
-  // An error row's collapsed summary IS the failure: the first error line in
-  // the error color outranks both the args summary and a terminal description.
+  // A failure must replace, not supplement, the normal summary.
   const failureLine = state === 'error' ? errorSummary ?? null : null
   const summaryText = failureLine ?? summary
-  // The failure line replaces the summary wholesale, so a suffix derived from
-  // the call args has nothing left to sit beside.
   const suffix = failureLine === null ? summarySuffix ?? null : null
-  // The failure line is error prose, not the path: no open-file affordance.
   const fileLink = filePath !== undefined && onOpenFile !== undefined && failureLine === null
   const toggleExpand = () => {
     setExpanded(v => !v)
@@ -188,9 +130,6 @@ export function ToolRow({
   // The code variant's program renders through CodeBlock (shiki), so only its
   // output joins the IN/OUT card; every other variant's input does too.
   const cardBody = variant === 'code' ? null : body
-  // The state substitution rides the idle icon slot, so an expandable error
-  // row keeps DisclosureRow's icon→chevron hover preview (its default) instead
-  // of losing it with the icon.
   return (
     <div className={css.root} data-variant={variant} data-tool={toolName} data-state={state}>
       {status !== null && <span className={css.visuallyHidden}>{status}</span>}
@@ -231,8 +170,6 @@ export function ToolRow({
           </>
         )}
       >
-        {/* The wrapper (sibling of the header row, so clicks inside never
-            toggle it) carries the expanded body and the Inspect pill below. */}
         <div className={css.bodyWrap}>
           {terminalBody !== null
             ? (
diff --git a/packages/client/ui-tool/src/client/tool/toolviews/GenericToolCard.tsx b/packages/client/ui-tool/src/client/tool/toolviews/GenericToolCard.tsx
index 99fb68b9af..d3aa3ad7e1 100644
--- a/packages/client/ui-tool/src/client/tool/toolviews/GenericToolCard.tsx
+++ b/packages/client/ui-tool/src/client/tool/toolviews/GenericToolCard.tsx
@@ -1,9 +1,3 @@
-// GenericToolCard: the default tool row — classifies the tool into a visual
-// variant and renders the summary row. Supplied by the Tool call tree as the
-// keyed atomic-view slot's render-site fallback (an
-// unregistered tool name lands here); registrants may also compose it as a
-// base, feeding the same owner payload through.
-
 import type { ReactNode } from 'react'
 import {
   IconApiOutline14, IconBrowseOutline16, IconCodeOutline16, IconEditOutline16, IconSearchOutline16, IconSparkle16,
@@ -53,9 +47,6 @@ export function GenericToolCard({ toolName, block, cwd, home, openFile, inspect,
       toolName={toolName}
       icon={VARIANT_ICONS[model.variant]}
       title={model.title}
-      // A terminal presenter's description is the contract's above-card text, so
-      // it outranks the args-derived summary here exactly as it does in BashRow;
-      // a search result view's replacement title outranks it the same way.
       summary={terminal?.description ?? search?.title ?? model.summary}
       // Single-file tools never expose an args body — the path link is the only
       // args interaction. A card is not an args body: a read/write/edit row is
diff --git a/packages/client/ui-tool/src/client/tool/toolviews/ask-question-row.tsx b/packages/client/ui-tool/src/client/tool/toolviews/ask-question-row.tsx
index 8876775703..feb3904953 100644
--- a/packages/client/ui-tool/src/client/tool/toolviews/ask-question-row.tsx
+++ b/packages/client/ui-tool/src/client/tool/toolviews/ask-question-row.tsx
@@ -1,11 +1,3 @@
-// ask_user_question toolview: question-flavored summary row replacing the
-// generic "Tool call" card, registered into the keyed
-// 'tool.call.toolview' hole like todo-row. The row composes ToolRow
-// (chrome, running sweep, whole-row expand) and swaps in the interaction
-// outcome — `waiting` while pending, answered-count once settled, `cancelled`
-// when the user dismissed the whole set — because the questions themselves
-// render in the composer takeover.
-
 import { IconQuestionOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { Context } from '@deepseek-ai/cordis'
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
@@ -39,11 +31,9 @@ function answeredSummary(text: string, t: AskQuestionRowProps['t']): string | nu
   return t('ask.answered', { answered, total: answers.length })
 }
 
-/** Full row props: the toolview runtime share plus the standard locale seat. */
 type AskQuestionRowProps = ToolCallViewProps & PropsLocale<'conversation'>
 
-/** One-line question-interaction row (the whole row toggles the call's
- *  Input/Output sections, ToolRow's unified expand). */
+/** Summarizes a pending, answered, cancelled, or interrupted question set. */
 export function AskQuestionRow({ toolName, block, inspect, t }: AskQuestionRowProps) {
   const model = toolRowModel(toolName, block)
   // Composer verdicts settle the call as specific UserQuestionErrors
@@ -82,17 +72,10 @@ export function AskQuestionRow({ toolName, block, inspect, t }: AskQuestionRowPr
   )
 }
 
-/**
- * The ask-question row as a plain registrant plugin following the chat
- * toolview declaration across independent activation and reload lifetimes.
- */
+/** Registers the ask-user-question conversation row. */
 export const askQuestionToolview = {
   name: 'ask-question-toolview',
   inject: ['slots'],
-  /**
-   * Register the ask-question row into the Tool-owned keyed view slot.
-   * @param ctx - registrant context (disposal rides ctx.effect inside slots.register).
-   */
   apply(ctx: Context): void {
     ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({
       name: 'tool.call.toolview', key: 'ask_user_question', locale: NS,
diff --git a/packages/client/ui-tool/src/client/tool/toolviews/bash-sample.tsx b/packages/client/ui-tool/src/client/tool/toolviews/bash-sample.tsx
index dc9a02a901..f476e0b075 100644
--- a/packages/client/ui-tool/src/client/tool/toolviews/bash-sample.tsx
+++ b/packages/client/ui-tool/src/client/tool/toolviews/bash-sample.tsx
@@ -1,18 +1,3 @@
-// Bash toolview registrant: third-party posture over the keyed toolview hole
-// (ctx.slots.register + ToolRowProps only — never imports the chat domain).
-// Product chrome matches ToolRow / Think (figma: Bash · {description}).
-//
-// A bash call normally declares the terminal render intent, so this row renders
-// the command's own output through TerminalBlock. Execution failures that
-// settle without terminal material use the bounded generic IN/OUT fallback —
-// both are expand-gated exactly like
-// ToolRow's unified interaction: collapsed by default, the whole summary row
-// is the toggle (click / Enter / Space, icon→chevron hover preview; the
-// summary stays inline while open),
-// and the expanded card max-height-scrolls inside its own surface with the
-// full output (maxLines Infinity — no middle collapse). An error row's
-// collapsed summary is the failure's first line in the error color.
-
 import { useState, type KeyboardEvent } from 'react'
 import type { Context } from '@deepseek-ai/cordis'
 import clsx from 'clsx'
@@ -26,7 +11,6 @@ import { toolRowModel, type ToolRowState } from '../models/tool-call-model.ts'
 import { CONVERSATION_NS as NS } from '../../locale.ts'
 import css from './bash-sample.module.css'
 
-/** Bash row props: the toolview runtime share plus the standard locale seat. */
 type BashRowProps = ToolCallViewProps & PropsLocale<'conversation'>
 
 function leadingFor(state: ToolRowState) {
@@ -48,11 +32,7 @@ function stateStatus(state: ToolRowState, t: BashRowProps['t']): string | null {
   }
 }
 
-/**
- * Bash row: icon + Bash · {description} in the shared ToolRow chrome, the
- * whole row toggling the command's terminal or generic error card (ToolRow's unified
- * expand interaction, replicated locally per the registrant posture).
- */
+/** Renders expandable Bash output with an accessible lifecycle label. */
 export function BashRow({ toolName, block, sessionId, useSessions, inspect, t }: BashRowProps) {
   const model = toolRowModel(toolName, block)
   // Session workspace root: the terminal view's cwd resolves against it (an
@@ -111,15 +91,11 @@ export function BashRow({ toolName, block, sessionId, useSessions, inspect, t }:
         {status !== null && <span className={css.visuallyHidden}>{status}</span>}
         <span className={css.title}>{model.title}</span>
         <span className={css.sep} aria-hidden />
-        {/* The terminal presenter's description is the contractual
-            above-card summary; a failure's first line outranks both. */}
         <span className={clsx(css.summary, failureLine !== null && css.errorSummary)}>
           {failureLine ?? terminal?.description ?? model.summary}
         </span>
       </div>
       {open && (
-        /* Same hover-Inspect posture as ToolRow's expanded body, replicated
-           locally per the registrant posture. */
         <div className={css.bodyWrap}>
           {terminal !== null
             ? (
@@ -163,17 +139,10 @@ export function BashRow({ toolName, block, sessionId, useSessions, inspect, t }:
   )
 }
 
-/**
- * The sample as a plain registrant plugin. Slot injection follows the chat
- * toolview declaration across independent activation and reload lifetimes.
- */
+/** Registers the standalone Bash conversation-row sample. */
 export const bashToolviewSample = {
   name: 'bash-toolview-sample',
   inject: ['slots'],
-  /**
-   * Register the bash row into the Tool-owned keyed view slot.
-   * @param ctx - registrant context (disposal rides ctx.effect inside slots.register).
-   */
   apply(ctx: Context): void {
     ctx.slots.inject('tool.call.toolview', () =>
       ctx.slots.register({ name: 'tool.call.toolview', key: 'bash', locale: NS }, BashRow))
diff --git a/packages/client/ui-tool/src/client/tool/toolviews/file-mutation-row.tsx b/packages/client/ui-tool/src/client/tool/toolviews/file-mutation-row.tsx
index ad99ed7999..ecd16b52c7 100644
--- a/packages/client/ui-tool/src/client/tool/toolviews/file-mutation-row.tsx
+++ b/packages/client/ui-tool/src/client/tool/toolviews/file-mutation-row.tsx
@@ -1,13 +1,3 @@
-// File-mutation toolview registrant: the keyed toolview hole for the `edit`
-// and `write` tools. The row composes the shared ToolRow (chrome, running
-// sweep, whole-row expand) and feeds it the applied diff as ToolRow's `diff`
-// card material, so the change renders through DiffBlock in the collapsed-by-
-// default expanded body — the same unified interaction every other card row
-// has. The summary stays a path link (the file-tool interaction) that opens
-// through the host; an errored mutation (write/edit return no diff on
-// `result.isError`) keeps the model-facing error text on ToolRow's Output
-// section, its first line in the collapsed summary.
-
 import type { Context } from '@deepseek-ai/cordis'
 import { IconEditOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
@@ -17,17 +7,10 @@ import { toolRowModel } from '../models/tool-call-model.ts'
 import { ToolRow } from '../components/ToolRow.tsx'
 import { CONVERSATION_NS as NS } from '../../locale.ts'
 
-/** Full row props: the toolview runtime share plus the standard locale seat. */
 type FileMutationRowProps = ToolCallViewProps & PropsLocale<'conversation'>
 
 /**
- * File-mutation row: icon + {Edit,Write} · {path} in the shared ToolRow chrome,
- * with the applied diff as the row's collapsed-by-default card body. The
- * summary is a path link (a file tool's interaction); the host's `openFile`
- * resolves it against the session cwd, so this passes the tool's own path
- * verbatim. An errored mutation has no diff card, so ToolRow surfaces the
- * model-facing error text through its Output section and its first line in the
- * collapsed summary instead.
+ * Lets users expand an applied file diff and open the reported path.
  */
 export function FileMutationRow({ toolName, block, cwd, home, openFile, inspect, t }: FileMutationRowProps) {
   const model = toolRowModel(toolName, block, cwd, home)
@@ -52,18 +35,10 @@ export function FileMutationRow({ toolName, block, cwd, home, openFile, inspect,
   )
 }
 
-/**
- * The file-mutation rows as a plain registrant plugin following the chat
- * toolview declaration across independent activation and reload lifetimes.
- */
+/** Registers the edit and write conversation rows. */
 export const fileMutationToolview = {
   name: 'file-mutation-toolview',
   inject: ['slots'],
-  /**
-   * Register the file-mutation row into the Tool-owned keyed view slot
-   * under both mutation tool names.
-   * @param ctx - registrant context (disposal rides ctx.effect inside slots.register).
-   */
   apply(ctx: Context): void {
     ctx.slots.inject('tool.call.toolview', function* () {
       yield ctx.slots.register({ name: 'tool.call.toolview', key: 'edit', locale: NS }, FileMutationRow)
diff --git a/packages/client/ui-tool/src/client/tool/toolviews/read-row.tsx b/packages/client/ui-tool/src/client/tool/toolviews/read-row.tsx
index 7f798a5e96..375950c823 100644
--- a/packages/client/ui-tool/src/client/tool/toolviews/read-row.tsx
+++ b/packages/client/ui-tool/src/client/tool/toolviews/read-row.tsx
@@ -1,12 +1,3 @@
-// Read toolview registrant: the keyed toolview hole for the read tool. The row
-// composes the shared ToolRow (chrome, running sweep, whole-row expand) and
-// feeds it the file's line-numbered, syntax-highlighted content as ToolRow's
-// `read` card material, so it renders through ReadBlock in the collapsed-by-
-// default expanded body — the same unified interaction every other card row
-// has. The summary path is an openable host link. A running read (no result
-// yet) and a non-read result render the summary row alone: the read intent is
-// result-side only, so there is no running-state read card to draw.
-
 import type { Context } from '@deepseek-ai/cordis'
 import { IconBrowseOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
@@ -16,13 +7,10 @@ import { toolRowModel } from '../models/tool-call-model.ts'
 import { ToolRow } from '../components/ToolRow.tsx'
 import { CONVERSATION_NS as NS } from '../../locale.ts'
 
-/** Full row props: the toolview runtime share plus the standard locale seat. */
 type ReadRowProps = ToolCallViewProps & PropsLocale<'conversation'>
 
 /**
- * Read row: icon + Read · {path} in the shared ToolRow chrome, with the file's
- * read card as the row's collapsed-by-default card body. The summary path is an
- * openable host link when the row names a single file.
+ * Lets users expand a completed read result and open its reported path.
  */
 export function ReadRow({ toolName, block, cwd, home, openFile, inspect, t }: ReadRowProps) {
   const model = toolRowModel(toolName, block, cwd, home)
@@ -47,17 +35,10 @@ export function ReadRow({ toolName, block, cwd, home, openFile, inspect, t }: Re
   )
 }
 
-/**
- * The read row as a plain registrant plugin following the atomic Tool-view
- * declaration across independent activation and reload lifetimes.
- */
+/** Registers the read tool's conversation row. */
 export const readToolview = {
   name: 'read-toolview',
   inject: ['slots'],
-  /**
-   * Register the read row into the Tool-owned keyed view slot.
-   * @param ctx - registrant context (disposal rides ctx.effect inside slots.register).
-   */
   apply(ctx: Context): void {
     ctx.slots.inject('tool.call.toolview', () =>
       ctx.slots.register({ name: 'tool.call.toolview', key: 'read', locale: NS }, ReadRow))
diff --git a/packages/client/ui-tool/src/client/tool/toolviews/search-row.tsx b/packages/client/ui-tool/src/client/tool/toolviews/search-row.tsx
index e49189d6d4..80f59b886f 100644
--- a/packages/client/ui-tool/src/client/tool/toolviews/search-row.tsx
+++ b/packages/client/ui-tool/src/client/tool/toolviews/search-row.tsx
@@ -1,16 +1,3 @@
-// Search toolview registrant: the keyed toolview hole for the `grep` and `glob`
-// tools. One SearchRow component registered under both, since both declare the
-// same `card: 'search'` render intent and render as one visual object; the
-// derived model's `kind` decides the card shape (grouped matches or a path
-// list). The row composes the shared ToolRow (chrome, running sweep, whole-row
-// expand) and feeds it the completed search as ToolRow's `search` card
-// material, so it renders through SearchBlock in the collapsed-by-default
-// expanded body — with a capped search's recovery footer below the card. A
-// search declares its render intent result-time only, so a running row is the
-// summary line alone; a settled call with no search card (an errored search, a
-// nested run_code sub-dispatch, a legacy generic result) surfaces its
-// model-facing text through ToolRow's Output section instead.
-
 import type { Context } from '@deepseek-ai/cordis'
 import { IconSearchOutline16 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
@@ -20,7 +7,6 @@ import { toolRowModel } from '../models/tool-call-model.ts'
 import { ToolRow } from '../components/ToolRow.tsx'
 import { CONVERSATION_NS as NS } from '../../locale.ts'
 
-/** Full row props: the toolview runtime share plus the standard locale seat. */
 type SearchRowProps = ToolCallViewProps & PropsLocale<'conversation'>
 
 const SEARCH_TITLES: Record<string, string> = {
@@ -28,14 +14,7 @@ const SEARCH_TITLES: Record<string, string> = {
   glob: 'Glob',
 }
 
-/**
- * Search row: icon + Grep/Glob · {summary} in the shared ToolRow chrome, with the
- * completed search's card as the row's collapsed-by-default card body (a capped
- * search's recovery footer rides below it, inside ToolRow). Registered under
- * both `grep` and `glob`; the derived model's `kind` decides the card shape. A
- * settled call with no search card surfaces its model-facing text through
- * ToolRow's Output section, since the keyed SearchRow owns this render slot.
- */
+/** Lets users expand grep or glob results and recover capped searches. */
 export function SearchRow({ toolName, block, inspect, t }: SearchRowProps) {
   const model = toolRowModel(toolName, block)
   const search = searchCardModel(block)
@@ -46,16 +25,10 @@ export function SearchRow({ toolName, block, inspect, t }: SearchRowProps) {
       toolName={toolName}
       icon={<IconSearchOutline16 size={14} />}
       title={SEARCH_TITLES[toolName] ?? model.title}
-      // The result view's replacement title outranks the args-derived summary,
-      // matching the terminal card's description precedence.
       summary={search?.title ?? model.summary}
       body={null}
-      // A settled call with no search card (errored search, nested run_code
-      // sub-dispatch, legacy generic result) has its text nowhere else to go;
-      // ToolRow's Output section carries it, and errorSummary its first line.
-      // When a card is present ToolRow renders it instead of the output, so
-      // model.output passes unconditionally and the four card rows stay
-      // symmetric.
+      // ToolRow ignores output when a structured card is present; otherwise it
+      // preserves the generic fallback for errors and legacy results.
       output={model.output}
       errorSummary={model.errorSummary}
       search={search}
@@ -65,19 +38,10 @@ export function SearchRow({ toolName, block, inspect, t }: SearchRowProps) {
   )
 }
 
-/**
- * The search view follows the atomic Tool-view declaration across activation
- * and reload. One component registers under both keys because `grep` and
- * `glob` are the same visual object discriminated by the result view's `kind`.
- */
+/** Registers the grep and glob conversation rows. */
 export const searchToolview = {
   name: 'search-toolview',
   inject: ['slots'],
-  /**
-   * Register the search row into the Tool-owned keyed view slot under both
-   * the `grep` and `glob` tool names.
-   * @param ctx - registrant context (disposal rides ctx.effect inside slots.register).
-   */
   apply(ctx: Context): void {
     ctx.slots.inject('tool.call.toolview', function* () {
       yield ctx.slots.register({ name: 'tool.call.toolview', key: 'grep', locale: NS }, SearchRow)
diff --git a/packages/client/ui-tool/src/client/tool/toolviews/todo-row.tsx b/packages/client/ui-tool/src/client/tool/toolviews/todo-row.tsx
index 143a43ee29..ef4deee981 100644
--- a/packages/client/ui-tool/src/client/tool/toolviews/todo-row.tsx
+++ b/packages/client/ui-tool/src/client/tool/toolviews/todo-row.tsx
@@ -1,12 +1,3 @@
-// todo_write toolview: plan-flavored summary row replacing the generic
-// "Tool call" card, registered into the keyed 'tool.call.toolview'
-// hole like the bash sample (a product registration, not a sample). The row
-// composes ToolRow (chrome, running sweep, whole-row expand) and swaps in a
-// summary of the written list (counts + active items) from the call args, with
-// the parallel-active count riding ToolRow's non-shrinking summary suffix so a
-// narrow row never clips it; the durable list itself renders in the TodoPanel
-// above the composer, so the row stays one line until expanded.
-
 import { IconChecklistOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { Context } from '@deepseek-ai/cordis'
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
@@ -16,7 +7,6 @@ import { ToolRow } from '../components/ToolRow.tsx'
 import { CONVERSATION_NS as NS } from '../../locale.ts'
 import { planSummary, type PlanItemLike } from './plan-summary.ts'
 
-/** Todo row props: the toolview runtime share plus the standard locale seat. */
 type TodoRowProps = ToolCallViewProps & PropsLocale<'conversation'>
 
 function isItem(value: unknown): value is PlanItemLike {
@@ -54,10 +44,7 @@ function summarize(argsRaw: string, t: TodoRowProps['t']): RowSummary | null {
   }
 }
 
-/** One-line plan update row (the whole row toggles the call's Input/Output
- *  sections, ToolRow's unified expand). Non-ok execution states keep the
- *  shared row's dot semantics — a cancelled call wrote no todo/write, so it
- *  must not read as a completed update. */
+/** Summarizes a plan update without presenting a cancelled call as completed. */
 export function TodoRow({ toolName, block, inspect, t }: TodoRowProps) {
   const model = toolRowModel(toolName, block)
   const argsRaw = ('kind' in block ? block.call?.argsRaw : block.argsRaw) ?? ''
@@ -80,17 +67,10 @@ export function TodoRow({ toolName, block, inspect, t }: TodoRowProps) {
   )
 }
 
-/**
- * The todo row as a plain registrant plugin following the atomic Tool-view
- * declaration across independent activation and reload lifetimes.
- */
+/** Registers the todo conversation row. */
 export const todoToolview = {
   name: 'todo-toolview',
   inject: ['slots'],
-  /**
-   * Register the todo row into the Tool-owned keyed view slot.
-   * @param ctx - registrant context (disposal rides ctx.effect inside slots.register).
-   */
   apply(ctx: Context): void {
     ctx.slots.inject('tool.call.toolview', () =>
       ctx.slots.register({ name: 'tool.call.toolview', key: 'todo_write', locale: NS }, TodoRow))
diff --git a/packages/client/ui-tool/src/client/tool/toolviews/web-row.tsx b/packages/client/ui-tool/src/client/tool/toolviews/web-row.tsx
index 3dab222e95..4be87b10d5 100644
--- a/packages/client/ui-tool/src/client/tool/toolviews/web-row.tsx
+++ b/packages/client/ui-tool/src/client/tool/toolviews/web-row.tsx
@@ -1,14 +1,3 @@
-// Web toolview registrant: the keyed toolview hole for the `web_search` and
-// `web_fetch` tools. Registered under BOTH, since both declare the one `web`
-// render intent and render through the one WebBlock family; the row
-// discriminates on the toolName only to pick its icon and title. The row
-// composes the shared ToolRow (chrome, running sweep, whole-row expand) and
-// feeds it the completed retrieval as ToolRow's `web` card material, so it
-// renders through WebBlock in the collapsed-by-default expanded body — the same
-// unified interaction every other card row has. Until the call settles there is
-// no web card (the tools keep a generic pending view), so a running row is the
-// summary line alone.
-
 import type { Context } from '@deepseek-ai/cordis'
 import { IconBrowseOutline16, IconGlobeOutline14 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { PropsLocale } from '@deepseek-ai/dsh-client-ui-slots'
@@ -18,24 +7,17 @@ import { toolRowModel } from '../models/tool-call-model.ts'
 import { ToolRow } from '../components/ToolRow.tsx'
 import { CONVERSATION_NS as NS } from '../../locale.ts'
 
-/** Full row props: the toolview runtime share plus the standard locale seat. */
 type WebRowProps = ToolCallViewProps & PropsLocale<'conversation'>
 
-/** web_fetch reads one URL; web_search queries. Titles are figma literals. */
 const WEB_TITLES: Record<string, string> = {
   web_search: 'Search',
   web_fetch: 'Fetch',
 }
 
-/**
- * Web row: icon + Search/Fetch · {summary} in the shared ToolRow chrome, with
- * the completed retrieval's web card as the row's collapsed-by-default card
- * body. The row discriminates on `toolName` only to pick its icon and title.
- */
+/** Lets users expand a completed web search or fetch result. */
 export function WebRow({ toolName, block, inspect, t }: WebRowProps) {
   const model = toolRowModel(toolName, block)
   const web = webCardModel(block)
-  // Web search uses a globe; local grep/glob keep the magnifier family.
   const icon = toolName === 'web_fetch' ? <IconBrowseOutline16 size={14} /> : <IconGlobeOutline14 size={14} />
   return (
     <ToolRow
@@ -55,17 +37,10 @@ export function WebRow({ toolName, block, inspect, t }: WebRowProps) {
   )
 }
 
-/**
- * The web rows follow the atomic Tool-view declaration across activation and
- * reload. One WebRow component registers under both web tool names.
- */
+/** Registers the web search and fetch conversation rows. */
 export const webToolview = {
   name: 'web-toolview',
   inject: ['slots'],
-  /**
-   * Register the web row under both web tool names' keyed toolview holes.
-   * @param ctx - registrant context (disposal rides ctx.effect inside slots.register).
-   */
   apply(ctx: Context): void {
     ctx.slots.inject('tool.call.toolview', function* () {
       yield ctx.slots.register({ name: 'tool.call.toolview', key: 'web_search', locale: NS }, WebRow)
diff --git a/packages/client/ui-tool/tests/ask-question-row.client.spec.tsx b/packages/client/ui-tool/tests/ask-question-row.client.spec.tsx
index 7b950e954d..7bc7c46447 100644
--- a/packages/client/ui-tool/tests/ask-question-row.client.spec.tsx
+++ b/packages/client/ui-tool/tests/ask-question-row.client.spec.tsx
@@ -30,7 +30,6 @@ const resultNode = (argsRaw: string, resultText: string | null, over?: Partial<T
 const runningCall = (argsRaw: string) =>
   ({ callId: 'c1', name: 'ask_user_question', argsRaw, turn: 1, step: 1, time: 1_000, callView: null, subCalls: [] })
 
-// Standard locale seat stub mirroring the real ns → common → key chain.
 const t = makeTranslate(zh, commonZh)
 
 function rowProps(block: unknown): Parameters<typeof AskQuestionRow>[0] {
diff --git a/packages/client/ui-tool/tests/chat-code-subcalls.client.spec.tsx b/packages/client/ui-tool/tests/chat-code-subcalls.client.spec.tsx
index d73c09013c..687720fbef 100644
--- a/packages/client/ui-tool/tests/chat-code-subcalls.client.spec.tsx
+++ b/packages/client/ui-tool/tests/chat-code-subcalls.client.spec.tsx
@@ -1,12 +1,4 @@
 // @vitest-environment jsdom
-// Code Mode sub-call acceptance on the REAL machinery stack (same bench as
-// chat-toolview-slot.spec): a run_code result renders the 'code' variant row
-// (description summary, program body), its logged sub-dispatches render as
-// always-visible nested rows through the SAME keyed toolview hole — the bash
-// sub-call lands in the bash sample plugin's registration exactly like a
-// top-level bash row, unregistered sub-tools fall back to GenericToolCard —
-// and a file sub-row click opens the host path. Running parents
-// (runningCalls) nest their so-far dispatches the same way.
 
 import { Context } from '@deepseek-ai/cordis'
 import { stubSettingsScope } from '@deepseek-ai/dsh-client-test-runtime'
@@ -206,10 +198,6 @@ describe('run_code sub-calls through the real chat machinery', () => {
     expect(view.getByText('Code')).toBeTruthy()
     expect(view.getByText('List the notes directory')).toBeTruthy()
 
-    // Nested rows are ALWAYS visible (no parent expand needed): the bash
-    // sub-call landed in the bash sample plugin's keyed registration — Bash ·
-    // description chrome, same as a top-level bash row — and the unregistered
-    // sub-tool fell back to GenericToolCard at the same render site.
     const nest = view.container.querySelector('[data-subcalls]')
     expect(nest).not.toBeNull()
     expect(nest!.querySelector('[data-sample="bash"]')).not.toBeNull()
diff --git a/packages/client/ui-tool/tests/coverage-tails.client.spec.tsx b/packages/client/ui-tool/tests/coverage-tails.client.spec.tsx
index 4650e94599..61b4fc576b 100644
--- a/packages/client/ui-tool/tests/coverage-tails.client.spec.tsx
+++ b/packages/client/ui-tool/tests/coverage-tails.client.spec.tsx
@@ -1,5 +1,4 @@
 // @vitest-environment jsdom
-// Tool presentation branch tails not reached by the main acceptance specs.
 
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, render } from '@testing-library/react'
@@ -15,7 +14,6 @@ import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.t
 
 type BashRowProps = Parameters<typeof BashRow>[0]
 
-// Mirrors the real lookup chain (conversation namespace, then common).
 const t: GenericToolCardProps['t'] = makeTranslate(zh, commonZh)
 
 afterEach(cleanup)
diff --git a/packages/client/ui-tool/tests/diff-card.client.spec.tsx b/packages/client/ui-tool/tests/diff-card.client.spec.tsx
index 6ca46e0243..e4cf03c044 100644
--- a/packages/client/ui-tool/tests/diff-card.client.spec.tsx
+++ b/packages/client/ui-tool/tests/diff-card.client.spec.tsx
@@ -1,8 +1,4 @@
 // @vitest-environment jsdom
-// The diff render intent on the web side: the pure diffCardModel derivation
-// over callView/resultView, and both conversation render sites that consume it
-// — the chat tool row's expanded body (GenericToolCard / FileMutationRow) and
-// the details panel's Output section.
 
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render } from '@testing-library/react'
@@ -27,7 +23,6 @@ import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.t
 
 afterEach(cleanup)
 
-/** FileMutationRow's full prop shape (ToolRow runtime share + conversation locale seat). */
 type FileMutationRowProps = Parameters<typeof FileMutationRow>[0]
 
 const SID = 's1' as SessionId
diff --git a/packages/client/ui-tool/tests/read-card.client.spec.tsx b/packages/client/ui-tool/tests/read-card.client.spec.tsx
index 8ae0b21cfc..400b8eecdd 100644
--- a/packages/client/ui-tool/tests/read-card.client.spec.tsx
+++ b/packages/client/ui-tool/tests/read-card.client.spec.tsx
@@ -1,10 +1,4 @@
 // @vitest-environment jsdom
-// The read render intent on the web side: the pure readCardModel derivation
-// over the settled result view, and both conversation render sites that consume
-// it — the chat tool row (the keyed ReadRow and the GenericToolCard fallback,
-// each composing ToolRow with the read card as its collapsed-by-default expanded
-// body) and the details panel's Output section (resident, full height). Also
-// pins the keyed 'read' toolview registration.
 
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render } from '@testing-library/react'
diff --git a/packages/client/ui-tool/tests/search-card.client.spec.tsx b/packages/client/ui-tool/tests/search-card.client.spec.tsx
index 24c6d331d2..b2064e4b3f 100644
--- a/packages/client/ui-tool/tests/search-card.client.spec.tsx
+++ b/packages/client/ui-tool/tests/search-card.client.spec.tsx
@@ -1,10 +1,4 @@
 // @vitest-environment jsdom
-// The search render intent on the web side: the pure searchCardModel derivation
-// over resultView, and the conversation render sites that consume it — the chat
-// tool row (GenericToolCard's fallback body and SearchRow, both composing the
-// shared ToolRow with the search card collapsed by default) and the details
-// panel's Output section (resident, full height). The keyed registration under
-// both grep and glob is pinned here too.
 
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render } from '@testing-library/react'
@@ -27,12 +21,10 @@ import { DetailsPanel } from '@deepseek-ai/dsh-client-ui-conversation/src/client
 import { SearchRow, searchToolview } from '../src/client/tool/toolviews/search-row.tsx'
 import { renderToolDetails, SessionProviderStub, toolChatSnapshot } from './tool-details-render.client.tsx'
 
-/** SearchRow now composes ToolRow, so its props include the locale `t` seat. */
 type SearchRowProps = Parameters<typeof SearchRow>[0]
 
 afterEach(cleanup)
 
-/** Conversation-locale translate stub for the render sites' `t` seat. */
 const t: GenericToolCardProps['t'] = makeTranslate(zh, commonZh)
 
 /** The rendered search card's kind attribute, so a render site cannot silently drop it. */
diff --git a/packages/client/ui-tool/tests/terminal-card.client.spec.tsx b/packages/client/ui-tool/tests/terminal-card.client.spec.tsx
index 261e3a4066..4a2e87e7a7 100644
--- a/packages/client/ui-tool/tests/terminal-card.client.spec.tsx
+++ b/packages/client/ui-tool/tests/terminal-card.client.spec.tsx
@@ -1,8 +1,4 @@
 // @vitest-environment jsdom
-// The terminal render intent on the web side: the pure terminalCardModel
-// derivation over callView/resultView, and both conversation render sites that
-// consume it — the chat tool row's expanded body (GenericToolCard / BashRow)
-// and the details panel's Output section.
 
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render } from '@testing-library/react'
@@ -27,7 +23,6 @@ import { zh } from '@deepseek-ai/dsh-client-ui-conversation/src/client/locales.t
 
 type BashRowProps = Parameters<typeof BashRow>[0]
 
-// Mirrors the real lookup chain (conversation namespace, then common).
 const t: GenericToolCardProps['t'] = makeTranslate(zh, commonZh)
 
 afterEach(cleanup)
diff --git a/packages/client/ui-tool/tests/tool-row.client.spec.tsx b/packages/client/ui-tool/tests/tool-row.client.spec.tsx
index 2d1b289b9d..9661b8d3c6 100644
--- a/packages/client/ui-tool/tests/tool-row.client.spec.tsx
+++ b/packages/client/ui-tool/tests/tool-row.client.spec.tsx
@@ -14,7 +14,6 @@ afterEach(() => {
   cleanup()
 })
 
-// Mirrors the real lookup chain (conversation namespace, then common).
 const t: GenericToolCardProps['t'] = makeTranslate(zh, commonZh)
 
 const running = (over?: Partial<RunningToolCall>): RunningToolCall => ({
diff --git a/packages/client/ui-tool/tests/toolview-slot.client.spec.tsx b/packages/client/ui-tool/tests/toolview-slot.client.spec.tsx
index bdfba88345..c14575b236 100644
--- a/packages/client/ui-tool/tests/toolview-slot.client.spec.tsx
+++ b/packages/client/ui-tool/tests/toolview-slot.client.spec.tsx
@@ -1,13 +1,4 @@
 // @vitest-environment jsdom
-// The Tool presentation package's acceptance chain on the REAL machinery stack:
-// SlotTestRuntime (cordis Context + SlotRegistry ledger + the ui-renderer
-// renderer) + ui-conversation and ui-tool apply — no outlet twins. Proves the
-// keyed 'tool.call.toolview' hole end to end: registered rows dispatch by
-// entryKey (the bash sample lands through its plugin), unregistered tools
-// fall back to GenericToolCard at the render site, live registration/unload
-// flips rows in place, duplicate keys fail loud, the inject channel feeds
-// (sessionId) => I into row components, and a registrant can activate before
-// the declaration then land through slots.inject when the chat entry appears.
 
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
 import { cleanup } from '@testing-library/react'
diff --git a/packages/client/ui-tool/tests/web-card.client.spec.tsx b/packages/client/ui-tool/tests/web-card.client.spec.tsx
index ffcab58353..f9712c091e 100644
--- a/packages/client/ui-tool/tests/web-card.client.spec.tsx
+++ b/packages/client/ui-tool/tests/web-card.client.spec.tsx
@@ -1,12 +1,4 @@
 // @vitest-environment jsdom
-// The web render intent on the web side: the pure webCardModel derivation over
-// resultView, and the conversation render sites that consume it — the keyed
-// WebRow (registered under both web_search and web_fetch), the GenericToolCard
-// render-site fallback, and the details panel's Output section. Mirrors
-// terminal-card.spec.tsx: model derivation + null arms, both kinds, the chat
-// row's collapsed-by-default ToolRow card, the panel arm, and the keyed
-// registration. WebRow now composes the shared ToolRow, so its web card is
-// collapsed by default and appears only once the whole row is expanded.
 
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render } from '@testing-library/react'
@@ -35,7 +27,6 @@ afterEach(cleanup)
 
 const SID = 's1' as SessionId
 
-/** Locale seat for the card render sites (GenericToolCard, DetailsPanel), as the sibling suites build it. */
 const t = makeTranslate(zh, commonZh)
 
 const SEARCH_ARGS = '{"query":"deepseek harness"}'
@@ -187,8 +178,6 @@ describe('chat row web body', () => {
   })
 
   it('the GenericToolCard fallback also expands to a web card for a web-declaring tool', () => {
-    // A web-declaring tool without its own keyed row lands on the fallback; its
-    // card routes through the same collapsed-by-default ToolRow.
     const view = render(<GenericToolCard {...ownerProps(settledSearch({
       call: { name: 'fx-web', argsRaw: SEARCH_ARGS },
     }), 'fx-web')} t={t} />)
diff --git a/packages/client/ui-user-questions/src/client/PlanReviewPanel.module.css b/packages/client/ui-user-questions/src/client/PlanReviewPanel.module.css
index a9b5310d40..6c97273755 100644
--- a/packages/client/ui-user-questions/src/client/PlanReviewPanel.module.css
+++ b/packages/client/ui-user-questions/src/client/PlanReviewPanel.module.css
@@ -1,11 +1,3 @@
-/* Plan-review takeover: the waiting-approval card language (amber strip on a
-   floating capsule, right-aligned actions) applied to a reviewed plan. Kept as
-   its own module rather than shared with ui-conversation's ApprovalPanel: the
-   two takeovers agree on tokens and geometry, not on content — this one's body
-   is scrollable markdown, that one's is a headline plus a command line. Warn
-   semantics ride the alias state tokens; no hardcoded colors. */
-
-/* Mirrors the question card's frame so the takeover is a content swap. */
 .frame {
   display: flex;
   justify-content: center;
diff --git a/packages/client/ui-user-questions/src/client/PlanReviewPanel.tsx b/packages/client/ui-user-questions/src/client/PlanReviewPanel.tsx
index 9f7bf6e18a..bd683959d4 100644
--- a/packages/client/ui-user-questions/src/client/PlanReviewPanel.tsx
+++ b/packages/client/ui-user-questions/src/client/PlanReviewPanel.tsx
@@ -1,18 +1,3 @@
-// PlanReviewPanel: the composer takeover for a question carrying the
-// `plan-review` presentation intent. A plan under review is one decision over
-// one body of markdown, so it takes the waiting-approval card shape — tinted
-// strip, content, right-aligned action row — instead of the generic question
-// flow's pager, numbered options, skip and custom-answer affordances, which
-// read as a quiz the user is being graded on.
-//
-// The three actions are the whole decision surface: approve and decline answer
-// the question with the option labels the asker offered (localised copy on the
-// buttons, the asker's descriptions as their tooltips), while "discuss"
-// dismisses the request so the composer returns and the user can simply say
-// what they want. Dismissal is the generic flow's own cancel verb, promoted to
-// a labelled button because in a two-outcome decision it is the third real
-// answer, not an escape hatch.
-
 import { useState } from 'react'
 import { Button, IconEditOutline16, MarkdownText } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { PendingQuestion, PlanReview, QuestionComposerProps } from './contract/slots.ts'
@@ -40,10 +25,8 @@ function tooltip(description: string | undefined): { title?: string } {
  * @returns The plan-review takeover for this request.
  */
 export function PlanReviewPanel({ pending, review, t }: PlanReviewPanelProps) {
-  // One-shot latch shaped like the approval takeover's: the panel leaves only
-  // when the host's resolved frame lands, so until then a second click must
-  // not re-fire. A failed send (rejected receipt / transport) re-arms it and
-  // shows why, since nothing else would tell the user the click was lost.
+  // The panel waits for the host's resolved frame before leaving, so repeated
+  // clicks must not resubmit. A failed send re-enables it and shows the error.
   const [busy, setBusy] = useState(false)
   const [error, setError] = useState<string | null>(null)
   const settle = (send: () => Promise<void>): void => {
diff --git a/packages/client/ui-user-questions/tests/plan-review-panel.client.spec.tsx b/packages/client/ui-user-questions/tests/plan-review-panel.client.spec.tsx
index 2abbe85844..4479a50fed 100644
--- a/packages/client/ui-user-questions/tests/plan-review-panel.client.spec.tsx
+++ b/packages/client/ui-user-questions/tests/plan-review-panel.client.spec.tsx
@@ -1,8 +1,4 @@
 // @vitest-environment jsdom
-// The plan-review takeover, driven through the composer entry that routes to
-// it: a request carrying the intent must reach the decision card and answer
-// with the asker's own option labels, and a request that does not (or cannot)
-// must keep the generic question flow.
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { cleanup, fireEvent, render, screen } from '@testing-library/react'
 import type {
@@ -22,7 +18,6 @@ afterEach(cleanup)
 
 const SID = 's1' as SessionId
 
-/** Seat stub over a dictionary pair mirroring the real lookup chain: package dictionary, then common vocabulary, then the key. */
 const seatOver = (dict: Record<string, string>, common: Record<string, string>): QuestionComposerProps['t'] =>
   (key => dict[key] ?? common[key] ?? key)
 
@@ -209,7 +204,7 @@ describe('PlanReviewPanel', () => {
   it('reports a non-Error transport failure as its stringified value', async () => {
     // A non-Error rejection is the case under test: a carrier can reject with
     // anything, and the panel must still show the user something.
-    // oxlint-disable-next-line typescript/prefer-promise-reject-errors
+    // oxlint-disable-next-line typescript/prefer-promise-reject-errors -- exercises non-Error rejections
     const { carrier } = wait({ questions: questions() }, vi.fn(() => Promise.reject('socket gone')))
     render(<QuestionComposer matched={carrier} interactions={[carrier]} {...kit} />)
 
diff --git a/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx b/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx
index 7c16c6e61b..6d999d9743 100644
--- a/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx
+++ b/packages/client/ui-user-questions/tests/user-questions-composer.client.spec.tsx
@@ -18,7 +18,6 @@ afterEach(cleanup)
 
 const SID = 's1' as SessionId
 
-/** Seat stub over a dictionary pair mirroring the real lookup chain: package dictionary, then common vocabulary, then the key. */
 const seatOver = (dict: Record<string, string>, common: Record<string, string>): QuestionComposerProps['t'] =>
   (key => dict[key] ?? common[key] ?? key)
 
diff --git a/packages/client/ui-workspace/src/client/WorkspaceBrowser.module.css b/packages/client/ui-workspace/src/client/WorkspaceBrowser.module.css
index 4d19163322..dd9ee488bf 100644
--- a/packages/client/ui-workspace/src/client/WorkspaceBrowser.module.css
+++ b/packages/client/ui-workspace/src/client/WorkspaceBrowser.module.css
@@ -1,8 +1,3 @@
-/* Workspace browsing region (fills the sidebar shell's hole): section
-   header, search capsule, and the scrolling session list. Wide/rail
-   variants ride the shell's fold state through the `wide` owner prop —
-   rail state renders only the two 36x36 icon controls. */
-
 .root {
   --dsh-session-list-edge-inset: var(--dsh-sidebar-inline-padding);
   --dsh-session-list-scrollbar-width: 8px;
diff --git a/packages/client/ui-workspace/src/client/rows/Rows.module.css b/packages/client/ui-workspace/src/client/rows/Rows.module.css
index 5dc899af45..02a99ee5a0 100644
--- a/packages/client/ui-workspace/src/client/rows/Rows.module.css
+++ b/packages/client/ui-workspace/src/client/rows/Rows.module.css
@@ -1,8 +1,3 @@
-/* Tree rows: project 34px, session 32px, radius 8, indent step 22px
-   (16px slot + 6px gap). Hover swaps
-   are pure CSS: project folder -> chevron + action buttons; session time ->
-   ellipsis button. */
-
 .projectRow,
 .sessionRow {
   display: flex;
diff --git a/packages/client/ui-workspace/tests/rows.client.spec.tsx b/packages/client/ui-workspace/tests/rows.client.spec.tsx
index f86e275c5e..b7f7844721 100644
--- a/packages/client/ui-workspace/tests/rows.client.spec.tsx
+++ b/packages/client/ui-workspace/tests/rows.client.spec.tsx
@@ -11,7 +11,6 @@ import { zh } from '../src/client/locales.ts'
 
 afterEach(cleanup)
 
-// Standard locale seat stub mirroring the real ns → common → key chain (zh default).
 const t = makeTranslate(zh, commonZh) as never
 
 const sid = (id: string) => id as SessionId
diff --git a/packages/code-runtime/code-runtime-worker-thread/README.i18n.yaml b/packages/code-runtime/code-runtime-worker-thread/README.i18n.yaml
index a76182b8f9..31ef4f9dbf 100644
--- a/packages/code-runtime/code-runtime-worker-thread/README.i18n.yaml
+++ b/packages/code-runtime/code-runtime-worker-thread/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/code-runtime/code-runtime-worker-thread/README.md
-README.md: 5507faee57a5d6cd53a1429fa426d2b876046b87
-README.zh.md: c34e0094e66a0f01f9f5a2ccc099ba4e3275e508
+README.md: 778d52e1175457a100962b15f61379372a2e8ad0
+README.zh.md: 92c767cf353aa10cdfce2dfc5eff0ac7a5783dfb
diff --git a/packages/code-runtime/code-runtime-worker-thread/README.md b/packages/code-runtime/code-runtime-worker-thread/README.md
index 5507faee57..778d52e117 100644
--- a/packages/code-runtime/code-runtime-worker-thread/README.md
+++ b/packages/code-runtime/code-runtime-worker-thread/README.md
@@ -25,7 +25,7 @@ Every field is validated and defaulted; `maxOutputBytes` is a safe integer of at
 - **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 validates every binding resolution and completion as lossless JSON. Forged `log`/`done` messages cannot bypass the outer cap: the host repeats validation and accounts every admitted log plus the completion or diagnostic. Worker-side namespaces are null-prototype with `defineProperty`, so `__proto__`-shaped binding names are ordinary keys.
 - **Binding rejection classes are request data** — an optional namespace descriptor names the constructor global and the own property that receives the failed member name. The worker materializes and injects that real class, so `instanceof` works without hardcoding `tools` or `ToolCallError`; declarations with invalid or colliding globals fail before a worker spawns. Failures use module-captured error and property-definition intrinsics plus null-prototype descriptors, so later model mutations cannot turn a rejected binding into a worker crash.
 - **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'`). `maxWallMs` is range-checked at load against `MAX_TIMER_DELAY_MS`: `setTimeout` clamps a longer delay to 1 ms, so a positivity check alone would accept a ceiling that expires on the first tick. `computeMs` needs no such bound, being compared against measured utilization rather than fed to a timer.
-- **Intermediate binding values are complete JSON** — binding arguments and resolutions undergo iterative lossless-JSON validation. Before program execution, the worker captures its own realm's plain-container prototype identities plus the native function-source check used only for foreign realms, so constructor-slot mutation and user-authored impostors cannot change container classification. It also captures every structural and metering intrinsic used by this JSON boundary, creates property descriptors without a prototype, and bypasses mutable collection prototypes for private traversal state; model mutations of globals, prototype methods, or descriptor-shaped `Object.prototype` fields therefore cannot alter validation, wire transport, or byte accounting. Values flatten into a bounded-depth pre-order wire value for structured clone and rebuild iteratively on the other side. They have no byte, JavaScript call-stack, or nested structured-clone depth cap. They never enter the outer-output ledger or model context; provider/executor acquisition bounds and process/worker memory remain the limits.
+- **Intermediate binding values are complete JSON** — binding arguments and resolutions undergo lossless-JSON validation and transfer without a byte cap. The worker captures the validation primitives before executing untrusted code, so mutations to globals or prototypes cannot weaken validation or byte accounting. Intermediate values never enter the outer-output ledger or model context; provider/executor acquisition bounds and process/worker memory remain the limits.
 - **Logs stream eagerly into one outer ledger** — console/stdout/stderr text crosses the port in emission order, so a timed-out or killed program still shows what it printed. The worker charges exact JSON-string bytes and preflights completion values and exception diagnostics against the remaining combined budget before posting them; a thrown million-byte stack therefore becomes the fixed `output-limit` diagnostic at the worker boundary. Native writes that bypass the patched stream slots arrive on pipes independent of the completion port, so the host repeats the ledger for those bytes and hostile forged traffic; settlement continues bounded pipe capture until worker termination completes before materializing the result. `maxOutputBytes` accounts the JSON serialization of the outer `logs` array plus the completion value or failure-message payload; fixed `CodeRunResult` field names, braces, the bounded error-kind tag, and later presentation whitespace are outside that variable-payload ledger. At or below the cap the exact value returns; a lossy completion is `invalid-output`, and a combined overflow is `output-limit` rather than a substituted inspected string. The failure retains the fitting captured prefix and later follows the normal outer `run_code` spill policy.
 - **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.
diff --git a/packages/code-runtime/code-runtime-worker-thread/README.zh.md b/packages/code-runtime/code-runtime-worker-thread/README.zh.md
index c34e0094e6..92c767cf35 100644
--- a/packages/code-runtime/code-runtime-worker-thread/README.zh.md
+++ b/packages/code-runtime/code-runtime-worker-thread/README.zh.md
@@ -25,7 +25,7 @@
 - **端口把对端视为不可信**：模型代码能够访问 `parentPort` 并伪造通信，因此任何代码读取入站消息前，系统都会验证其形状并重新构建（`null`、原始值、无效类型和格式错误的载荷会被静默丢弃；伪造的额外字段绝不会被带入）；宿主对每个调用 id 最多响应一次，只将绑定名称解析为自有属性（伪造的 `constructor` 无法沿原型链访问），丢弃结算后的回复，并验证每个绑定 resolve 值与完成值是否为无损 JSON。伪造的 `log`／`done` 消息无法绕过外层上限：宿主会再次验证，并统计每条获准日志以及完成值或诊断。worker 侧命名空间使用 null-prototype 和 `defineProperty`，因此形似 `__proto__` 的绑定名称只是普通键。
 - **绑定调用被拒绝时使用的异常类属于请求数据**：可选命名空间描述符会指定构造器全局变量，以及用于接收调用失败的成员名称的自有属性。worker 会创建并注入该真实类，使 `instanceof` 生效，同时无需硬编码 `tools` 或 `ToolCallError`；全局变量无效或冲突的声明会在启动 worker 前失败。失败路径使用模块捕获的错误 intrinsic 与属性定义 intrinsic，以及 null-prototype 描述符，因此模型之后的修改无法把被拒绝的绑定变成 worker 崩溃。
 - **两个独立预算，因为对端不可信**：`computeMs` 统计 worker 实际测得的忙碌时间（轮询 `worker.performance.eventLoopUtilization()`）；热循环无法借助待完成的诱饵 dispatch 隐藏，程序等待慢工具时则不累计。`maxWallMs` 为忙碌时间无法观测的情况兜底（例如等待永远不会 resolve 的 promise）。二者最终都会调用 `worker.terminate()`，连同步热循环也能终止；堆溢出会表现为 worker 的 OOM 退出（`kind: 'worker-exit'`）。`maxWallMs` 在加载时会对照 `MAX_TIMER_DELAY_MS` 做范围校验：`setTimeout` 会把更长的延迟限制为 1 ms，仅有正数校验会放行一个在第一个 tick 就到期的上限。`computeMs` 不需要这道上界，因为它对照的是实测占用率，而不是喂给定时器。
-- **中间绑定值是完整 JSON**：绑定参数与 resolve 值会接受迭代式无损 JSON 验证。程序执行前，worker 会捕获自己 realm 中的普通容器原型身份，以及只用于外部 realm 的原生函数源码检查，因此构造器槽修改和用户编写的仿冒对象都无法改变容器分类。它还会捕获该 JSON 边界使用的每一个结构与计量 intrinsic，以无原型对象创建属性描述符，并绕过可变集合原型管理私有遍历状态；因此，模型对全局对象、原型方法或 `Object.prototype` 上形似描述符字段的修改，都无法改变验证、wire 传输或字节计量。值会展平为自身嵌套深度有界的前序 wire 值，供 structured clone 使用，并在另一侧迭代式重建。它们没有字节、JavaScript 调用栈或嵌套 structured-clone 深度上限，绝不会进入外层输出账本或模型上下文；上限仍来自提供方／执行器获取限制与进程／worker 内存。
+- **中间绑定值是完整 JSON**：绑定参数与 resolve 值会接受无损 JSON 校验，并在没有字节上限的情况下传输。worker 会在执行不可信代码前捕获校验原语，因此对全局对象或原型的修改无法削弱校验或字节计量。中间值绝不会进入外层输出账本或模型上下文；上限仍来自提供方／执行器获取限制与进程／worker 内存。
 - **日志主动流入一个外层账本**：console／stdout／stderr 文本按产生顺序经端口传输，因此超时或被终止的程序仍会显示已经打印的内容。worker 会精确统计 JSON 字符串的字节数，并在发送完成值和异常诊断前，根据组合预算的剩余量预检；因此，抛出的百万字节 stack 会在 worker 边界变成固定的 `output-limit` 诊断。绕过补丁 stream 槽的原生写入会到达独立于完成端口的 pipe，因此宿主会针对这些字节和不可信伪造通信再次执行账本统计；在物化结果前，结算过程会持续进行有界 pipe 捕获，直到 worker 完成终止。`maxOutputBytes` 统计外层 `logs` 数组加完成值或失败消息载荷的 JSON 序列化；固定的 `CodeRunResult` 字段名、花括号、有界错误 kind 标签，以及后续呈现空白不计入这份可变载荷账本。未超过上限时会返回精确值；有损完成值属于 `invalid-output`，组合溢出属于 `output-limit`，不会用 inspected string 代替。失败会保留能容纳的已捕获前缀，之后按普通外层 `run_code` 落盘策略处理。
 - **空环境**：worker 使用 `env: {}` 和 `execArgv: []`，既不会获得环境变量中的凭据（比 spawn 命令的清理环境规则更严格），也不会继承 loader 标志。
 - **dispose（资源释放）时等待完全停稳**：清理会使进行中的运行以 `abort` 失败，并会等待每个 worker 退出后再完成。
diff --git a/packages/core/session/README.i18n.yaml b/packages/core/session/README.i18n.yaml
index 52af3b1e3f..15704ada90 100644
--- a/packages/core/session/README.i18n.yaml
+++ b/packages/core/session/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/session/README.md
-README.md: c62668167f4e0dfda822c7b82add3b4d8eb3d635
-README.zh.md: 0b8eb6e1bc106509a86ed51ae2f37f2ad471c7a1
+README.md: 9f0b4023e897f66ec1bcbc22e908ab2bf1c0d2cc
+README.zh.md: dcee2380802c6b7e416366a9388256f9b1d02091
diff --git a/packages/core/session/README.md b/packages/core/session/README.md
index c62668167f..9f0b4023e8 100644
--- a/packages/core/session/README.md
+++ b/packages/core/session/README.md
@@ -46,7 +46,7 @@ Plain class (not a Cordis Service). Create live sessions through `ctx.sessions.c
 
 ### Lossless JSON utilities
 
-Durable values need one accepted representation, not a check followed by a second read. `isJsonValue(value)` is the boolean predicate; `snapshotJsonValue(value)` iteratively validates and copies a plain value in one pass, returning `undefined` for invalid input and propagating a throwing getter. The snapshot helper accepts finite JSON numbers except `-0` (JSON rewrites it to `0`), dense ordinary arrays, and plain or null-prototype objects; it rejects cycles, unsupported scalars, and exotic prototypes before normalization without imposing a call-stack depth limit.
+Durable values use one lossless-JSON representation. `isJsonValue(value)` checks that representation; `snapshotJsonValue(value)` validates and detaches it in one pass and returns `undefined` for invalid input. The source JSDoc owns the exact accepted value set.
 
 Session-event import separates ownership from message validation. `snapshotSessionEvent(event)` clones a borrowed event before validating and freezing its identified message. `adoptSessionEvent(event)` performs the same message work in place and returns the original event; callers may use it only when they transfer an exclusively owned object graph with no mutable child shared with another event.
 
diff --git a/packages/core/session/README.zh.md b/packages/core/session/README.zh.md
index 0b8eb6e1bc..dcee238080 100644
--- a/packages/core/session/README.zh.md
+++ b/packages/core/session/README.zh.md
@@ -46,7 +46,7 @@
 
 ### 无损 JSON 工具
 
-持久值需要一种已接受的表示，不能先检查再二次读取。`isJsonValue(value)` 是布尔判断函数；`snapshotJsonValue(value)` 在一趟迭代中校验并复制普通值，无效输入返回 `undefined`，getter 抛出的异常则向外传播。快照辅助函数接受除 `-0` 外的有限 JSON 数值（JSON 会将其改写为 `0`）、稠密普通数组、普通对象或 null 原型对象；它会在规范化前拒绝循环引用、不支持的标量和特殊原型，同时不施加调用栈深度限制。
+持久值使用一种无损 JSON 表示。`isJsonValue(value)` 检查该表示；`snapshotJsonValue(value)` 在一趟处理中校验并分离该表示，无效输入返回 `undefined`。源码 JSDoc 负责记录确切的可接受值集合。
 
 会话事件导入将所有权与消息校验分开处理。`snapshotSessionEvent(event)` 会先克隆借用的事件，再校验并冻结其中带标识的消息。`adoptSessionEvent(event)` 原地执行相同的消息处理并返回原事件；调用方只有在移交独占的对象图，且该对象图没有与其他事件共享可变子对象时，才可以使用此函数。
 
diff --git a/packages/core/tools/README.i18n.yaml b/packages/core/tools/README.i18n.yaml
index 2ebd45d479..dfeb0e2eb3 100644
--- a/packages/core/tools/README.i18n.yaml
+++ b/packages/core/tools/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/core/tools/README.md
-README.md: dd20b1b8fdc4ff57ff9850683d6070fdb219e25a
-README.zh.md: 129bd8d0e3464985a0434f5456bf1c6f06ddc921
+README.md: 4f67dee611e6f28547ab276bd0884e787aeae0d9
+README.zh.md: 0137f295f2810930212dcb3f45e90af73bcf449c
diff --git a/packages/core/tools/README.md b/packages/core/tools/README.md
index dd20b1b8fd..4f67dee611 100644
--- a/packages/core/tools/README.md
+++ b/packages/core/tools/README.md
@@ -120,7 +120,7 @@ Under `code` or `both`, the registry exposes the reserved `run_code` transport a
 Under `code` — not `both` — the transport is also the only entry the model may use: a model-direct call naming any other visible tool resolves to `UNKNOWN_TOOL` at execution creation, before `tools/pre-execute`, approval `ask`, and guards, so nothing observes or approves a call that can only fail. The denial names the route back (`only \`run_code\` is callable directly — call \`<name>\` from inside a \`run_code\` program instead`), because the same prompt declares that tool and a bare `unknown tool` reads as a broken deployment. SDK sub-dispatches carry the outer execution's `parent` token and are exempt, so programs keep every binding the SDK declared. See the [executor-collapse note](../../../.agents/notes/implemented/bug-fix/2026-08-07-code-mode-executor-collapse.md), the [Code Mode foundation](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md), [typed-return contract](../../../.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md), and [code-runtime seam](../../code-runtime/README.md). Try `pnpm run demo:code-mode`.
 
 - **The SDK section** (`tools:sdk`, order 150): a lazy prompt section regenerating the language-appropriate SDK text at each assembly. In the TypeScript flavor it emits `JsonValue`, exact `ToolArgsMap` / `ToolOutputMap`, `ToolName`, the `ToolCallError` declaration, and a mapped `tools` namespace for the calling scope's visible end capabilities (exotic names via quoted keys), plus fixed usage instructions; the Python flavor (`ctx.codeRuntime.language === 'python'`) emits the equivalent named `TypedDict`s and a `tools` object with matching usage instructions. Deterministic — lexicographic tool order, byte-identical text for an unchanged tool set (prefix-cache-friendly). Both codegens are exported and never throw during prompt assembly: `jsonSchemaToTs` handles every unified schema construct and degrades unsupported raw constructs to `unknown`; `jsonSchemaToPy` does the same, degrading to `Any` (and a whole object to `dict[str, Any]` when a field name is not a legal `TypedDict` attribute, or whenever it is called outside the SDK render, which supplies the naming context a `TypedDict` declaration needs).
-- **The dispatch bridge** (`run_code`'s execute): every binding call is snapshotted as lossless JSON before dispatch (`undefined`, `BigInt`, cycles, sparse arrays, `-0`, and exotic objects reject that one call), scheduled through a per-run pool that reuses the native concurrency contract — calls start strictly in submission order, consecutive `isConcurrencySafe` calls overlap up to the validated `maxParallelSubCalls` config (default 10; `1` restores serial dispatch), and an exclusive-classified call drains the pool, runs alone, and bars later calls — given the outer execution's opaque token as `parent`, and run through the complete pre-execute → guards → execute → post-execute → result pipeline. A success returns the final canonical value after policy; a failure reaches the worker as one message and becomes `ToolCallError(toolName, message)`. Each started sub-call logs a `tool/code-dispatch-start` event (deterministic id `<parent>:code:<n>`, numbered by submission) at pipeline entry and settles with one `tool/code-dispatch` event carrying the complete model-facing `content`/`isError` outcome (the `tool/result` vocabulary, so UIs render sub-calls through the native path — the pair's `time` fields carry per-sub-call timing); a queued call abandoned by run settlement logs neither. `deriveMessages()` surfaces neither event nor persists the canonical value. Token correlation lets commit-style observers defer an inner success until the final `run_code` result without exposing the live outer execution; ordinary tool side effects are not rolled back. Every sub-call `additionalContexts` entry and every successful final content sequence containing an image is deferred through the outer `ToolRunContext` in dispatch order; the loop appends those contexts only after the parent `run_code` result, preserving adjacency and source attribution even when the program later fails.
+- **The dispatch bridge** (`run_code`'s execute): every binding call is snapshotted as lossless JSON before dispatch, scheduled through a per-run pool that reuses the native concurrency contract — calls start strictly in submission order, consecutive `isConcurrencySafe` calls overlap up to the validated `maxParallelSubCalls` config (default 10; `1` restores serial dispatch), and an exclusive-classified call drains the pool, runs alone, and bars later calls — given the outer execution's opaque token as `parent`, and run through the complete pre-execute → guards → execute → post-execute → result pipeline. A success returns the final canonical value after policy; a failure reaches the worker as one message and becomes `ToolCallError(toolName, message)`. Each started sub-call logs a `tool/code-dispatch-start` event (deterministic id `<parent>:code:<n>`, numbered by submission) at pipeline entry and settles with one `tool/code-dispatch` event carrying the complete model-facing `content`/`isError` outcome (the `tool/result` vocabulary, so UIs render sub-calls through the native path — the pair's `time` fields carry per-sub-call timing); a queued call abandoned by run settlement logs neither. `deriveMessages()` surfaces neither event nor persists the canonical value. Token correlation lets commit-style observers defer an inner success until the final `run_code` result without exposing the live outer execution; ordinary tool side effects are not rolled back. Every sub-call `additionalContexts` entry and every successful final content sequence containing an image is deferred through the outer `ToolRunContext` in dispatch order; the loop appends those contexts only after the parent `run_code` result, preserving adjacency and source attribution even when the program later fails.
 - **Settlement discipline**: the bridge owns a run-scoped abort that follows the outer signal in and fires when the run settles for any reason, so a budget expiry aborts an in-flight sub-tool instead of orphaning it; the bridge then drains its queue BEFORE returning, so every `tool/code-dispatch` lands inside the open turn. A failed run throws `CodeRunFailedError` (`code: 'CODE_RUN_FAILED'`, message = the failure kind + captured logs), which the pipeline converts to a structured `isError` the model self-corrects from.
 - **Result size**: intermediate binding values cross the worker process whole and have no per-binding byte cap. `run_code` returns canonical `{ logs: string[], result?: JsonValue }`; strings render raw, every other present JSON root renders through a stack-safe pretty JSON traversal whose total indentation is capped at ten characters (deeper subtrees stay compact), `null` remains explicit, and absent `result` means the program returned `undefined`. The worker's configurable `maxOutputBytes` (default 64 MiB) applies only to the combined serialized outer log-array, completion-value, or failure-message payloads; fixed result-envelope syntax and presentation whitespace are outside that limit. Invalid and over-limit completions fail explicitly, and only this outer result is eligible for ordinary spill.
 
diff --git a/packages/core/tools/README.zh.md b/packages/core/tools/README.zh.md
index 129bd8d0e3..0137f295f2 100644
--- a/packages/core/tools/README.zh.md
+++ b/packages/core/tools/README.zh.md
@@ -122,7 +122,7 @@ ctx.tools.register(defineTool({
 在 `code`（而非 `both`）下，该传输同时也是模型唯一可用的入口：模型直呼其他任何可见工具名，都会在创建执行时、早于 `tools/pre-execute`、审批 `ask` 和 guards 解析为 `UNKNOWN_TOOL`，因此没有任何一方会观察或批准一个注定失败的调用。拒绝信息会给出正确路径（`only \`run_code\` is callable directly — call \`<name>\` from inside a \`run_code\` program instead`），因为同一份提示词刚刚声明过那个工具，只说 `unknown tool` 会被读成部署损坏。SDK 子分发携带外层执行的 `parent` token，不受此限制，因此程序保留 SDK 声明的全部绑定。参见[执行器塌缩 note](../../../.agents/notes/implemented/bug-fix/2026-08-07-code-mode-executor-collapse.md)、[Code Mode 基础](../../../.agents/notes/implemented/feature/2026-06-15-code-mode.md)、[类型化返回约定](../../../.agents/notes/implemented/feature/2026-07-20-code-mode-typed-tool-returns.md)和[代码运行时 seam](../../code-runtime/README.md)。可以运行 `pnpm run demo:code-mode` 试用。
 
 - **SDK 段**（`tools:sdk`，顺序 150）：一个在组装时求值的提示词段，每次组装都会重新生成与所加载运行时语言相符的 SDK 文本。TypeScript 形态会生成 `JsonValue`、精确的 `ToolArgsMap` / `ToolOutputMap`、`ToolName`、`ToolCallError` 声明，以及映射调用作用域最终可见工具的 `tools` 命名空间（特殊名称使用带引号的键），并附带固定的使用说明；Python 形态（`ctx.codeRuntime.language === 'python'`）发出等价的具名 `TypedDict` 与一个带相同用法说明的 `tools` 对象。其输出具有确定性：工具按字典序排列；工具集合不变时，文本逐字节相同（有利于前缀 cache）。两个代码生成器都已导出，且绝不会在提示词组装期间抛出：`jsonSchemaToTs` 处理统一 schema 的每种构造并将不受支持的原始构造降级为 `unknown`；`jsonSchemaToPy` 同理，降级为 `Any`（当某字段名不是合法的 `TypedDict` 属性时，或在 SDK 渲染之外被调用时——`TypedDict` 声明所需的命名上下文由该渲染提供——整个对象降级为 `dict[str, Any]`）。
-- **分发桥接层**（`run_code` 的 execute）：每个绑定调用都会在分发前快照为无损 JSON（`undefined`、`BigInt`、循环、稀疏数组、`-0` 和特殊对象会使该次调用被拒绝），经由每次运行独有、复用原生并发约定的池调度——调用严格按提交顺序启动，连续的 `isConcurrencySafe` 调用最多可重叠经校验的 `maxParallelSubCalls` 配置个（默认 10；设为 `1` 即恢复串行分发），被分类为独占的调用先排空池、单独运行并阻挡其后的调用——以外层执行的不透明 token 作为 `parent`，并经过完整的 pre-execute → guards → execute → post-execute → result 流水线。成功会返回策略处理后的最终规范值；失败以一条消息到达 worker，并成为 `ToolCallError(toolName, message)`。每个已启动的子调用在进入流水线时记录一条 `tool/code-dispatch-start` 事件（确定性 id `<parent>:code:<n>`，按提交顺序编号），并以一条携带完整模型可见 `content`/`isError` 结果的 `tool/code-dispatch` 事件完结（采用 `tool/result` 词汇，因此 UI 会沿原生路径呈现子调用——这对事件的 `time` 字段承载每个子调用的计时）；因 run 结算而被放弃的排队调用两者都不记录。`deriveMessages()` 既不公开这两个事件，也不持久化规范值。token 关联使按提交语义工作的观察器可以延后提交内部调用的成功结果，直到最终 `run_code` 结果确定，而无需暴露进行中的外层执行；普通工具副作用不会回滚。每个子调用的 `additionalContexts` 条目以及每份成功且含图片的最终内容序列都会按分发顺序通过外层 `ToolRunContext` 延迟；循环只在父级 `run_code` 结果之后追加这些上下文，从而保持相邻关系和来源归属，即使程序后来失败也不例外。
+- **分发桥接层**（`run_code` 的 execute）：每个绑定调用都会在分发前快照为无损 JSON，经由每次运行独有、复用原生并发约定的池调度——调用严格按提交顺序启动，连续的 `isConcurrencySafe` 调用最多可重叠经校验的 `maxParallelSubCalls` 配置个（默认 10；设为 `1` 即恢复串行分发），被分类为独占的调用先排空池、单独运行并阻挡其后的调用——以外层执行的不透明 token 作为 `parent`，并经过完整的 pre-execute → guards → execute → post-execute → result 流水线。成功会返回策略处理后的最终规范值；失败以一条消息到达 worker，并成为 `ToolCallError(toolName, message)`。每个已启动的子调用在进入流水线时记录一条 `tool/code-dispatch-start` 事件（确定性 id `<parent>:code:<n>`，按提交顺序编号），并以一条携带完整模型可见 `content`/`isError` 结果的 `tool/code-dispatch` 事件完结（采用 `tool/result` 词汇，因此 UI 会沿原生路径呈现子调用——这对事件的 `time` 字段承载每个子调用的计时）；因 run 结算而被放弃的排队调用两者都不记录。`deriveMessages()` 既不公开这两个事件，也不持久化规范值。token 关联使按提交语义工作的观察器可以延后提交内部调用的成功结果，直到最终 `run_code` 结果确定，而无需暴露进行中的外层执行；普通工具副作用不会回滚。每个子调用的 `additionalContexts` 条目以及每份成功且含图片的最终内容序列都会按分发顺序通过外层 `ToolRunContext` 延迟；循环只在父级 `run_code` 结果之后追加这些上下文，从而保持相邻关系和来源归属，即使程序后来失败也不例外。
 - **结算纪律**：桥接层拥有一个运行作用域的中止机制；该中止会跟随传入的外层信号，并在运行因任何原因结算时触发，因此预算耗尽会中止正在运行的子工具，而不会将其遗留。桥接层随后会在返回之前排空队列，使每个 `tool/code-dispatch` 都落在仍打开的轮次内。失败的运行会抛出 `CodeRunFailedError`（`code: 'CODE_RUN_FAILED'`，message = 失败类型 + 已捕获日志），流水线会将其转换为模型可据以自我修正的结构化 `isError`。
 - **结果大小**：中间绑定值会完整传入 worker 进程，且没有逐绑定字节上限。`run_code` 返回规范的 `{ logs: string[], result?: JsonValue }`；字符串原样呈现，其他所有存在的 JSON 根都通过栈安全的美化 JSON 遍历呈现，总缩进最多为 10 个字符（更深的子树保持紧凑），`null` 保持显式，而缺少 `result` 表示程序返回 `undefined`。worker 可配置的 `maxOutputBytes`（默认 64 MiB）只应用于组合序列化后的外层日志数组、完成值或失败消息载荷；固定的结果封装语法和呈现空白不计入该上限。无效和超限的完成会明确失败，只有这个外层结果可以按常规 spill 机制处理。
 
diff --git a/packages/core/tools/src/index.ts b/packages/core/tools/src/index.ts
index 377015feb3..e8558ee64d 100644
--- a/packages/core/tools/src/index.ts
+++ b/packages/core/tools/src/index.ts
@@ -969,7 +969,7 @@ export class ToolRuntime extends Service {
         yield ctx.systemPrompt.section(this.sdkSection())
       }
     }.bind(this), 'tools.presentAs()')
-    // oxlint-disable-next-line typescript/no-misused-promises -- synchronous composite teardown; direct return preserves disposer identity
+    // oxlint-disable-next-line typescript/no-misused-promises -- synchronous composite teardown
     return dispose
   }
 
@@ -1005,8 +1005,7 @@ export class ToolRuntime extends Service {
    * Read at use time (assembly / run_code execution), NOT via static
    * `inject`: an inject entry would hold `ctx.tools` — and every tool plugin
    * behind it — hostage to a code runtime existing even under `mode:
-   * 'native'` (the loop's optional-backend idiom, same as
-   * `sessionPersistence`).
+   * 'native'`.
    *
    * Assembly and `run_code` execution read separately, so the language is not
    * bound to a request. Harmless while one published backend exists — both
diff --git a/packages/credentials/credentials-local/tests/local.spec.ts b/packages/credentials/credentials-local/tests/local.spec.ts
index 230015fe9d..5e1a8147cb 100644
--- a/packages/credentials/credentials-local/tests/local.spec.ts
+++ b/packages/credentials/credentials-local/tests/local.spec.ts
@@ -8,7 +8,6 @@ import { createLaunchEnvironmentSnapshot, DSH_LAUNCH_ENVIRONMENT_KEY } from '@de
 import type { CredentialRef } from '@deepseek-ai/dsh-credentials'
 import { LocalCredentialProvider, resolveSpec } from '../src/index.ts'
 
-/** Credential documents are seeded owner-only, exactly as the provider creates them. */
 function writeCredentials(file: string, text: string): Promise<void> {
   return writeFile(file, text, { mode: 0o600 })
 }
diff --git a/packages/credentials/credentials-local/tests/review-fixes.spec.ts b/packages/credentials/credentials-local/tests/review-fixes.spec.ts
index e385d0d3aa..42fced481c 100644
--- a/packages/credentials/credentials-local/tests/review-fixes.spec.ts
+++ b/packages/credentials/credentials-local/tests/review-fixes.spec.ts
@@ -1,7 +1,3 @@
-// Third-review behaviors: read-modify-write under the writer lock (external
-// edits survive an API write), the contained credentials/reference-updated fan-out (a
-// broken observer never fails a committed write), and the YAML document
-// editor's isolation between entries.
 import { afterEach, describe, expect, it, vi } from 'vitest'
 import { Context } from '@deepseek-ai/cordis'
 import { mkdtemp, readFile, rm, stat, writeFile } from 'node:fs/promises'
@@ -10,7 +6,6 @@ import { join } from 'node:path'
 import { credentialKey, credentialRef } from '@deepseek-ai/dsh-credentials'
 import { LocalCredentialProvider } from '../src/index.ts'
 
-/** Credential documents are seeded owner-only, exactly as the provider creates them. */
 function writeCredentials(file: string, text: string): Promise<void> {
   return writeFile(file, text, { mode: 0o600 })
 }
diff --git a/packages/credentials/credentials-local/tests/watcher.spec.ts b/packages/credentials/credentials-local/tests/watcher.spec.ts
index b51a188e5d..314d425d1f 100644
--- a/packages/credentials/credentials-local/tests/watcher.spec.ts
+++ b/packages/credentials/credentials-local/tests/watcher.spec.ts
@@ -25,7 +25,6 @@ vi.mock('node:fs/promises', async (importOriginal) => {
   }
 })
 
-/** Credential documents are seeded owner-only, exactly as the provider creates them. */
 function writeCredentials(file: string, text: string): Promise<void> {
   return writeFile(file, text, { mode: 0o600 })
 }
diff --git a/packages/fs/fs-sandbox/src/index.ts b/packages/fs/fs-sandbox/src/index.ts
index 17205a8eaf..60dd6b3bad 100644
--- a/packages/fs/fs-sandbox/src/index.ts
+++ b/packages/fs/fs-sandbox/src/index.ts
@@ -10,22 +10,18 @@
  * The fence is a policy check in TRUSTED code over a MODEL-CONTROLLED path,
  * NOT a kernel boundary — the operations are the seam's own (open, rename),
  * and only the target path is untrusted, so canonicalize-then-contain is the
- * complete answer to this surface. Kernel-grade isolation of untrusted CODE
- * stays `ctx.shell`'s job (`@deepseek-ai/dsh-bash-sandbox`). This mirrors the
- * `code-runtime` stance: containment, not a security boundary. The residual
+ * complete answer to this surface. This is containment, not a security
+ * boundary; kernel-grade isolation of untrusted CODE stays `ctx.shell`'s job
+ * (`@deepseek-ai/dsh-bash-sandbox`). The residual
  * TOCTOU (an ancestor symlink swapped between the containment re-check and the
  * syscall) is narrowed by re-canonicalizing immediately before delegating and
  * is accepted for this threat model.
  *
  * Per-call policy: `read-only` denies every mutation; `workspace-write` allows
  * a mutation only when the target canonicalizes under the policy's workspace
- * root or a platform temp area (the SAME writable-root set Seatbelt grants,
- * derived from the one `writableRoots` function so bash and fs cannot drift);
+ * root or a platform temp area from the shared `writableRoots` policy;
  * `danger-full-access` delegates unfenced. A denial throws the structured
- * `FS_SANDBOX_DENIED` — no text inference is needed (unlike bash's kernel
- * stderr), because an in-process fence knows exactly what it refused. The
- * escalation retry lives in the tool layer (`@deepseek-ai/dsh-tool-fs`),
- * exactly as bash's does.
+ * `FS_SANDBOX_DENIED`.
  *
  * @module @deepseek-ai/dsh-fs-sandbox
  */
diff --git a/packages/fs/tool-fs/src/edit.ts b/packages/fs/tool-fs/src/edit.ts
index 63bf43faef..b9fc89d4ed 100644
--- a/packages/fs/tool-fs/src/edit.ts
+++ b/packages/fs/tool-fs/src/edit.ts
@@ -137,7 +137,6 @@ export function applyEditTool(ctx: Context, sandbox: FsSandboxController): void
         // model-facing remedy; anything else passes through.
         throw remediateFsError(sandbox.mapError(error, sandboxPolicy))
       }
-      // Record the present observation (a no-op when no policy plugin listens).
       ctx.emit('fs/observed', target, { kind: 'present', version: outcome.version }, exec)
       return {
         path: target.displayPath,
diff --git a/packages/fs/tool-fs/src/session-cwd.ts b/packages/fs/tool-fs/src/session-cwd.ts
index fd4a134acf..11a6cf27e6 100644
--- a/packages/fs/tool-fs/src/session-cwd.ts
+++ b/packages/fs/tool-fs/src/session-cwd.ts
@@ -1,8 +1,7 @@
 /**
  * Derive the working directory a filesystem tool resolves relative paths against: the calling
  * agent's per-session workspace (`exec.agent.session.header.cwd`), so each session's
- * `read`/`write`/`edit` act on ITS workspace, not the server's launch dir — mirroring how
- * `dsh-tool-bash` defaults a bash `workdir` to the session cwd.
+ * `read`/`write`/`edit` act on its workspace, not the server's launch directory.
  * Non-agent calls return `undefined`, leaving the fallback in the provider rather than reading
  * `process.cwd()` at the tool boundary.
  * @module @deepseek-ai/dsh-tool-fs/session-cwd
diff --git a/packages/fs/tool-fs/src/write.ts b/packages/fs/tool-fs/src/write.ts
index bf85a33336..c7a7e555d2 100644
--- a/packages/fs/tool-fs/src/write.ts
+++ b/packages/fs/tool-fs/src/write.ts
@@ -118,7 +118,6 @@ export function applyWriteTool(ctx: Context, sandbox: FsSandboxController): void
         // model-facing remedy; anything else passes through.
         throw remediateFsError(sandbox.mapError(error, sandboxPolicy))
       }
-      // Record the present observation (a no-op when no policy plugin listens).
       ctx.emit('fs/observed', target, { kind: 'present', version: outcome.version }, exec)
       return {
         path: target.displayPath,
diff --git a/packages/llm/llm-pi-ai/tests/catalog.spec.ts b/packages/llm/llm-pi-ai/tests/catalog.spec.ts
index 99886cdbaf..f71a00fcc1 100644
--- a/packages/llm/llm-pi-ai/tests/catalog.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/catalog.spec.ts
@@ -1119,7 +1119,6 @@ describe('configurable-provider directory', () => {
   it('keeps the previous directory when a route collides with another adapter family', async () => {
     const dir = await home()
     const ctx = await bootWithSettings(dir, {})
-    // Another adapter family owns this route id, exactly as llm-deepseek does.
     ctx.llm.registerConfigurableProviders([
       { provider: 'deepseek-official', displayName: 'DeepSeek', settingsNs: 'llm-deepseek', settingsPath: [] },
     ])
diff --git a/packages/llm/llm-pi-ai/tests/dynamic-config.spec.ts b/packages/llm/llm-pi-ai/tests/dynamic-config.spec.ts
index 3decff3749..2289d56574 100644
--- a/packages/llm/llm-pi-ai/tests/dynamic-config.spec.ts
+++ b/packages/llm/llm-pi-ai/tests/dynamic-config.spec.ts
@@ -37,7 +37,6 @@ async function home(): Promise<string> {
   return dir
 }
 
-/** Real dynamic composition mirroring the deepseek twin's harness. */
 async function boot(
   dir: string,
   config: LlmPiAi.Config,
diff --git a/packages/lsp/lsp-stdio/tests/fixture-server.ts b/packages/lsp/lsp-stdio/tests/fixture-server.ts
index 428abe0268..e6b3800916 100644
--- a/packages/lsp/lsp-stdio/tests/fixture-server.ts
+++ b/packages/lsp/lsp-stdio/tests/fixture-server.ts
@@ -200,7 +200,6 @@ function send(message: Record<string, unknown>): void {
   process.stdout.write(Buffer.concat([Buffer.from(`Content-Length: ${body.length}\r\n\r\n`, 'ascii'), body]))
 }
 
-// Keep the event loop alive.
 process.stdin.resume()
 if (pauseStdinAfterInitialized) {
   setInterval(() => {}, 1000)
diff --git a/packages/lsp/tool-lsp/src/session-cwd.ts b/packages/lsp/tool-lsp/src/session-cwd.ts
index 7fc41785de..00453843e2 100644
--- a/packages/lsp/tool-lsp/src/session-cwd.ts
+++ b/packages/lsp/tool-lsp/src/session-cwd.ts
@@ -1,9 +1,7 @@
 /**
- * Derive the workspace root an `lsp` call resolves against: the calling agent's per-session
- * workspace (`exec.agent.session.header.cwd`), mirroring how the filesystem tools resolve paths.
- * Unlike those tools, LSP has NO provider fallback — a missing cwd fails the call as
- * `LSP_WORKSPACE_REQUIRED`, because the local provider must canonicalize a real workspace before it
- * can start a server.
+ * Derive the workspace root an `lsp` call resolves against from the calling
+ * agent's session. A missing cwd fails as `LSP_WORKSPACE_REQUIRED` because the
+ * local provider must canonicalize a real workspace before starting a server.
  * @module @deepseek-ai/dsh-tool-lsp/session-cwd
  */
 
diff --git a/packages/plan/plan-mode/tests/plan-mode.spec.ts b/packages/plan/plan-mode/tests/plan-mode.spec.ts
index 8285147953..eea2beddb0 100644
--- a/packages/plan/plan-mode/tests/plan-mode.spec.ts
+++ b/packages/plan/plan-mode/tests/plan-mode.spec.ts
@@ -60,7 +60,6 @@ async function agentWithSession(
   return agent
 }
 
-/** Assemble exactly as the loop does: the agent is both subject and scope. */
 function assembleFor(ctx: Context, agent: Agent) {
   return ctx.systemPrompt.assemble({ agent, scope: agent })
 }
diff --git a/packages/preset/agent-presets/tests/mount.spec.ts b/packages/preset/agent-presets/tests/mount.spec.ts
index 824308e009..49e16e6ab3 100644
--- a/packages/preset/agent-presets/tests/mount.spec.ts
+++ b/packages/preset/agent-presets/tests/mount.spec.ts
@@ -53,7 +53,6 @@ async function harness(roster: Config = { default: 'standard', roots: ROOTS, inc
   return ctx
 }
 
-/** Create one agent composed from `presetId`, exactly as a factory `setup` would. */
 async function agentOn(ctx: Context, id: string, presetId?: string): Promise<Agent> {
   const handle = await ctx.agents.create({
     sessionId: SessionId(id),
diff --git a/packages/sandbox/sandbox-windows-acl/README.i18n.yaml b/packages/sandbox/sandbox-windows-acl/README.i18n.yaml
index 99d9b9ca61..978f8f40e5 100644
--- a/packages/sandbox/sandbox-windows-acl/README.i18n.yaml
+++ b/packages/sandbox/sandbox-windows-acl/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/sandbox/sandbox-windows-acl/README.md
-README.md: 2cf79c8eede0943630f79bea717c9e072226fa7f
-README.zh.md: 0e2ed516c84268c9b44a7a3987cbb90bcc2d7696
+README.md: 055f2e92a42acfc707207306d31b51ea765cb3df
+README.zh.md: 0163c1235ec42c4967a0071258d8dcc68b278370
diff --git a/packages/sandbox/sandbox-windows-acl/README.md b/packages/sandbox/sandbox-windows-acl/README.md
index 2cf79c8eed..055f2e92a4 100644
--- a/packages/sandbox/sandbox-windows-acl/README.md
+++ b/packages/sandbox/sandbox-windows-acl/README.md
@@ -93,7 +93,6 @@ None directly; the denial surface belongs to the tool layer.
 - **One write allowlist per workspace** — the write SID is the unit of the allowlist and IS the workspace identity; reusing one sandbox instance across two workspaces widens both grants to both roots (the same SID would then name two roots). Create one instance per workspace root — the seam does exactly this, keyed by the workspace path.
 - **Cleanup is best-effort by design** — `dispose()` attempts every temp revocation and aggregates failures into an `AggregateError`; a cleanup failure can leave the random directory and its temp-SID-only ACE behind. Once the process exits no future token carries that SID, so the residue is inert until OS temp hygiene or manual directory removal reclaims it.
 - **Standing workspace ACEs are invisible residue.** Renaming a workspace derives a new SID; the old ACEs on the old path stay (inert, write-SID-only). A future cleanup command may reap them; nothing re-propagates because of them.
-- **NULL-DACL directories are not identity-preserving under grant+revoke.** A directory with a NULL DACL (rare — Windows-created directories carry real DACLs) means "everyone full control"; `grantWrite` builds the new ACL from that null, and the revoke round-trip leaves an EMPTY (deny-all) DACL rather than the original NULL DACL. The POC shares the behavior; real workspace and temp directories carry real DACLs, so this stays a documented edge rather than a guarded path.
 - **Piped stdio capture is impossible for confined grandchildren (the named-pipe default SD template).** libuv's pipe stdio uses NAMED pipes; `CreateNamedPipeW` without security attributes installs the Win32 layer's user-mode default SD template (built by KernelBase — owner/SYSTEM/Admins full, Everyone/ANONYMOUS read-only, the fixed template [MS documents](https://learn.microsoft.com/en-us/windows/win32/ipc/named-pipe-security-and-access-rights)) — NOT the token default DACL, which is what the kernel applies to a raw SD-null create — so the client-end open requests write access no restricting SID is granted: `spawn(..., { stdio: 'pipe' })` inside a confined process fails with EPERM, the POC-documented "no output redirection" boundary of WRITE_RESTRICTED tokens. Inherited (`inherit`/fd) and ignored (`ignore`) stdio spawns work, and anonymous pipes (CreatePipe — a token-default-DACL consumer, e.g. PowerShell pipelines) work because the restricted token's default DACL carries a full-access restricting-SID ACE (set at init). A confined process therefore cannot capture a grandchild's output through a pipe; tools that must capture output cannot run confined.
 - **Grant materialization is an eager full-tree propagation.** `SetNamedSecurityInfoW` on a directory with inheritable ACEs walks every descendant immediately (NOT lazily per access — measured at tens of seconds on large workspace trees). The per-workspace identity pays it once per workspace per machine (lazily at the first confined execution ever, skipped entirely on every later provision when the exact ACE stands). Private temp directories start empty, so their distinct grant is cheap. If a workspace is huge, the first confined write on this host is correspondingly slow.
 - **Read-side confinement and network policy are out of scope** — `WRITE_RESTRICTED` intersects write accesses only; pair this backend with a read-side policy for stronger confinement.
diff --git a/packages/sandbox/sandbox-windows-acl/README.zh.md b/packages/sandbox/sandbox-windows-acl/README.zh.md
index 0e2ed516c8..0163c1235e 100644
--- a/packages/sandbox/sandbox-windows-acl/README.zh.md
+++ b/packages/sandbox/sandbox-windows-acl/README.zh.md
@@ -95,7 +95,6 @@ g++ -std=c++20 -municode -O2 -o abi-probe.exe verify/abi-probe.cpp -ladvapi32 &&
 - **每个工作区一个写入白名单** —— 写入 SID 是白名单的基本单位，且**就是**工作区身份；同一沙盒实例跨两个工作区复用时，两个根目录会互相扩大授权面（同一个 SID 将命名两个根）。请按工作区根目录各建一个实例——seam 正是这样做的，以工作区路径为键。
 - **清理按设计尽力而为** —— `dispose()` 会尝试全部临时撤销并把失败聚合为 `AggregateError`；清理失败可能留下随机目录及其仅含临时 SID 的 ACE。进程退出后，不会再有令牌携带该 SID，因此残留保持失效，直到 OS 临时目录卫生或手动移除目录将其回收。
 - **常驻工作区 ACE 是不可见残留。** 工作区改名会派生新的 SID；旧路径上的旧 ACE 留在原地（失效、仅含写入 SID）。未来的清理命令可以回收它们；它们不会引起任何重新传播。
-- **NULL-DACL 目录在 grant+revoke 往返下不保持身份。** 带 NULL DACL 的目录（罕见——Windows 创建的目录都带真实 DACL）意味着「所有人完全控制」；`grantWrite` 从该 null 构建新 ACL，撤销往返后留下的是 EMPTY（全部拒绝）DACL 而非原始 NULL DACL。POC 行为相同；真实工作区与临时目录都带真实 DACL，因此这仍是记录在案的边界情形而非守护路径。
 - **受限孙进程的管道 stdio 捕获不可用（named pipe 的默认 SD 模板）。** libuv 的管道 stdio 用的是 NAMED pipe；不带安全属性调用 `CreateNamedPipeW` 时，其默认安全描述符不是内核的模板，而是 Win32 层在用户态安装的默认 SD 模板（由 KernelBase 构建——owner/SYSTEM/Admins 全权，Everyone/ANONYMOUS 只读，即 [MS 文档](https://learn.microsoft.com/en-us/windows/win32/ipc/named-pipe-security-and-access-rights)记载的固定模板）——**不是**令牌默认 DACL（后者才是内核在原始 SD-null 创建时应用的）——因此 client 端打开所请求的写访问没有任何 restricting SID 被授予：受限进程内 `spawn(..., { stdio: 'pipe' })` 以 EPERM 失败，这是 POC 记载的 WRITE_RESTRICTED「无法重定向输出」边界。继承（`inherit`/fd）与忽略（`ignore`）stdio 的 spawn 可用；匿名管道（CreatePipe——令牌默认 DACL 的消费者，例如 PowerShell 的管道）因受限令牌默认 DACL 携带 restricting SID 全权 ACE（init 时写入）而可用。受限进程因此无法用管道捕获孙进程输出；必须捕获输出的工具无法在受限下运行。
 - **授权物化是急切的全树传播。** 在带可继承 ACE 的目录上调用 `SetNamedSecurityInfoW` 会立即遍历每个后代（**不是**按访问惰性进行——大型工作区树上实测数十秒）。按工作区身份每台机器每个工作区只付一次（在首次受限执行时惰性进行，之后每次供给在精确 ACE 常驻时完全跳过）。私有临时目录创建时为空，因此其独立授权开销很小。如果工作区巨大，该主机上的第一次受限写入相应变慢。
 - **读侧隔离与网络策略不在范围内** —— `WRITE_RESTRICTED` 只交叉检查写访问；将此后端与读侧策略配对以获得更强隔离。
diff --git a/packages/sdk/client/src/api.ts b/packages/sdk/client/src/api.ts
index d615caece5..d5334f90a4 100644
--- a/packages/sdk/client/src/api.ts
+++ b/packages/sdk/client/src/api.ts
@@ -2,7 +2,6 @@
  * High-level run API over {@link HarnessClient}: `DeepSeekHarness` owns one
  * runtime subprocess across many sessions; `HarnessSession.run` sends a
  * prompt and settles when the whole agent next becomes idle.
- * Mirrors the Python SDK's `DeepSeekHarness`/`Session` pair.
  *
  * @module @deepseek-ai/dsh-sdk-client/api
  */
diff --git a/packages/sdk/client/src/client.ts b/packages/sdk/client/src/client.ts
index 1937f4a1dc..e41419819c 100644
--- a/packages/sdk/client/src/client.ts
+++ b/packages/sdk/client/src/client.ts
@@ -144,7 +144,7 @@ class NotificationSubscriptionImpl implements NotificationSubscription {
    * Deliver one notification to a waiter or the queue when the filter
    * matches. A throwing filter fails only THIS subscription (detached, the
    * throw becomes its terminal error) — it never disturbs sibling
-   * subscriptions or the transport's read loop, mirroring the Python client.
+   * subscriptions or the transport's read loop.
    * @param notification - the wire notification to deliver.
    */
   push(notification: HarnessNotification): void {
@@ -353,8 +353,8 @@ export class HarnessClient {
 
   /**
    * Subscribe to one session and the descendants discovered from
-   * `subagent.started` lineage edges (the runtime notifies for every session
-   * in its context; scoping is client-side, mirroring the Python SDK).
+   * `subagent.started` lineage edges. The runtime notifies for every session
+   * in its context, so this client applies the scope.
    * @param sessionId - the root session id.
    * @returns the filtered subscription handle.
    */
diff --git a/packages/sdk/server/src/server.ts b/packages/sdk/server/src/server.ts
index 195caa908d..ccc3b6192d 100644
--- a/packages/sdk/server/src/server.ts
+++ b/packages/sdk/server/src/server.ts
@@ -133,7 +133,7 @@ export class HarnessSdkJsonRpcServer {
     const rec = await this.getOrCreateSession(params.sessionId)
     // An agent-loop-only reload disposes the loop's agents while this record
     // survives; a retained agent accepts followup() silently, so validate the
-    // record against the live registry before delivery (as the ACP bridge does).
+    // record against the live registry before delivery.
     if (this.ctx.agents.get(rec.handle.agent.id) !== rec.handle.agent) {
       throw new Error(`session agent was disposed outside the server: ${params.sessionId}`)
     }
diff --git a/packages/session-query/tool-session-query/README.i18n.yaml b/packages/session-query/tool-session-query/README.i18n.yaml
index 33ba5b3460..9434605a7a 100644
--- a/packages/session-query/tool-session-query/README.i18n.yaml
+++ b/packages/session-query/tool-session-query/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/session-query/tool-session-query/README.md
-README.md: d973daf1124c4be05f7335b18661d431d45be39f
-README.zh.md: 71c1c74addf8cb2b29773933a36f3368b1c81bf5
+README.md: baa650dae9a0267024bdd0f6917d78d55d95f605
+README.zh.md: 16aab0be1407453a4eab42e42850c2740f8a561d
diff --git a/packages/session-query/tool-session-query/README.md b/packages/session-query/tool-session-query/README.md
index d973daf112..baa650dae9 100644
--- a/packages/session-query/tool-session-query/README.md
+++ b/packages/session-query/tool-session-query/README.md
@@ -11,11 +11,11 @@ Workspace-authorized model tools over `ctx.sessionQuery`. The opt-in package dep
 | `maxSearchResults` | `100` | Maximum authorized non-self hits collected across internal provider pages |
 | `searchTimeoutMs` | `30000` | Cooperative deadline attached to both full-text search tools |
 
-The caller comes exclusively from `ToolExecution.exec.agent`. Cross-session access requires exact equality between the target and caller session `cwd` values; a caller without `cwd` can inspect only itself. Search never exposes provider cursors, offsets, page sizes, or a model-controlled limit. Because one search consumes generation-bound provider cursors internally, both search tools execute exclusively with sibling tool calls; the three exact trace/read tools opt into parallel execution. Every exact executor passes its unchanged execution signal through authorization and the service trace/read, so cancellation waits for cooperative persistence cleanup and retains the signal's exact reason. Timestamps at the tool boundary require an explicit `Z` or numeric offset and become inclusive epoch-millisecond filters.
+The tools derive caller authority from `ToolExecution.exec.agent`. Cross-session access requires exact equality between the target and caller session `cwd` values; a caller without `cwd` can inspect only itself. Search never exposes paging controls or a model-controlled result limit. Cancellation retains the caller's reason, and timestamp filters require an explicit `Z` or numeric offset and include both endpoints.
 
 `session_search` always omits the caller session. Requested parent ids are deduplicated and checked against caller-workspace authority before FTS; only authorized ids reach the provider, while missing and cross-workspace guesses behave identically and the root marker remains independently ORed. A current-session `session_event_search` stops immediately before the step that invoked it, so the active assistant output and logged tool call cannot match themselves. Direct targets are authorized before trace, event, or title reads. Lineage output replaces unauthorized ancestor and descendant boundaries with markers that contain no hidden session id.
 
-Every trusted `ctx.sessionQuery` call crosses one model-boundary sanitizer. Caller cancellation is checked first and preserved exactly. Available corpus and provider diagnostics, including safely inspectable nested causes, are logged internally on a best-effort basis; unprintable failures use a fixed log placeholder. Diagnostic formatting and error classification are independently guarded, so an unprintable cause cannot escape or prevent a safely classified outer error, while unsafe classification or logging falls back to the fixed `SESSION_QUERY_TOOL_FAILED` code and message. Local argument-validation and authorization errors retain their precise tool-owned messages.
+Provider failures log available diagnostics but return the fixed `SESSION_QUERY_TOOL_FAILED` code and message to the model. Local argument-validation and authorization errors retain their precise tool-owned messages.
 
 The package deliberately performs no byte or character truncation and does not import a spill backend. Deployments that need bounded inline output mount `@deepseek-ai/dsh-spill-policy`, which can replace the rendered text after execution while retaining the complete result.
 
diff --git a/packages/session-query/tool-session-query/README.zh.md b/packages/session-query/tool-session-query/README.zh.md
index 71c1c74add..16aab0be14 100644
--- a/packages/session-query/tool-session-query/README.zh.md
+++ b/packages/session-query/tool-session-query/README.zh.md
@@ -11,11 +11,11 @@
 | `maxSearchResults` | `100` | 在内部提供方分页中收集的最大已授权非自身命中数 |
 | `searchTimeoutMs` | `30000` | 附加到两个全文搜索工具的协作式截止时间 |
 
-调用方只能来自 `ToolExecution.exec.agent`。跨会话访问要求目标和调用方会话的 `cwd` 值严格相等；没有 `cwd` 的调用方只能检查自己。搜索绝不公开提供方游标、偏移、分页大小或模型可控上限。由于一次搜索会在内部消费与世代绑定的提供方游标，两个搜索工具都与同级工具调用排他执行；三个精确跟踪/读取工具选择并行执行。每个精确执行器都将未更改的执行信号传递给授权和服务跟踪/读取，因此取消会等待协作式持久化清理，并保留信号的精确原因。工具边界上的时间戳要求显式 `Z` 或数字偏移，并转换为包含端点的 epoch 毫秒过滤器。
+工具根据 `ToolExecution.exec.agent` 派生调用方权限。跨会话访问要求目标和调用方会话的 `cwd` 值严格相等；没有 `cwd` 的调用方只能检查自己。搜索绝不公开分页控制项或模型可控的结果上限。取消会保留调用方原因，时间戳过滤器要求显式 `Z` 或数字偏移，并包含两个端点。
 
 `session_search` 始终省略调用方会话。请求的父 id 会被去重，并在 FTS 前根据调用方工作区权限检查；只有已授权 id 会到达提供方，而缺失猜测和跨工作区猜测的行为完全相同，root 标记仍独立使用 OR。当前会话中的 `session_event_search` 会在调用它的步骤之前立即停止，因此当前 assistant 输出和已记录工具调用无法匹配自身。直接目标在跟踪、事件或标题读取前完成授权。血缘输出会用不含隐藏会话 id 的标记替换未授权祖先和后代边界。
 
-每个可信 `ctx.sessionQuery` 调用都会经过一个模型边界净化器。首先检查调用方取消，并精确保留。可获取的语料库诊断信息和提供方诊断信息（包括可安全检查的嵌套原因）会尽力记录到内部日志；不可打印的失败使用固定日志占位符。诊断格式化和错误分类各自独立受保护，因此不可打印的原因无法逃逸，也无法阻止已安全分类的外层错误；不安全的分类或日志记录则回退到固定 `SESSION_QUERY_TOOL_FAILED` 代码和消息。本地参数验证和授权错误保留精确的工具自有消息。
+提供方失败会记录可用的诊断信息，但向模型返回固定的 `SESSION_QUERY_TOOL_FAILED` 代码和消息。本地参数校验和授权错误保留精确的工具自有消息。
 
 该包刻意不执行字节或字符截断，也不导入 spill 后端。需要限制内联输出的部署应挂载 `@deepseek-ai/dsh-spill-policy`，它可在执行后替换已渲染文本，同时保留完整结果。
 
diff --git a/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts b/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
index 70ae6d1ac5..a651296449 100644
--- a/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
+++ b/packages/session/session-persistence-jsonl/tests/jsonl.spec.ts
@@ -99,7 +99,6 @@ function appendClosedTurn(session: Session): void {
   session.append('turn/end', { turn: 1, reason: { kind: 'completed' } })
 }
 
-// Run the shared backend contract against the real JSONL backend.
 runPersistenceContract('jsonl-none', async () => {
   const dir = await mkdtemp(join(tmpdir(), 'dsh-jsonl-'))
   const ctx = new Context()
diff --git a/packages/session/session-persistence/src/coordinator.ts b/packages/session/session-persistence/src/coordinator.ts
index 63def62528..c29a7d3674 100644
--- a/packages/session/session-persistence/src/coordinator.ts
+++ b/packages/session/session-persistence/src/coordinator.ts
@@ -1131,8 +1131,7 @@ export class PersistenceCoordinator<TornMarker = unknown> {
     // Session disposal is observe-only, so retirement contains its own failure.
     ctx.on('session/disposed', (session) => { this.retire(session) })
 
-    // HMR: a hot reload does not replay session/created, so seed existing live
-    // sessions (mirrors dsh-invariants).
+    // HMR does not replay session/created, so seed existing live sessions.
     for (const session of ctx.sessions.list()) void this.initFor(session)
   }
 
diff --git a/packages/session/session-persistence/tests/persistence.spec.ts b/packages/session/session-persistence/tests/persistence.spec.ts
index 6c63d72b9f..935fea2903 100644
--- a/packages/session/session-persistence/tests/persistence.spec.ts
+++ b/packages/session/session-persistence/tests/persistence.spec.ts
@@ -239,7 +239,6 @@ class ControlledBackend implements PersistenceBackend<never> {
   }
 }
 
-// Run the shared contract against the in-memory backend.
 runPersistenceContract('memory', async () => {
   const ctx = new Context()
   await ctx.plugin(SessionStore)
diff --git a/packages/session/session-telemetry/src/index.ts b/packages/session/session-telemetry/src/index.ts
index 077da9929d..0715b073f3 100644
--- a/packages/session/session-telemetry/src/index.ts
+++ b/packages/session/session-telemetry/src/index.ts
@@ -133,9 +133,8 @@ export interface SessionTelemetrySink {
 /**
  * Deployment-selected session-sharing policy disclosed by a mounted
  * {@link SessionTelemetryBackend} backend to human-facing acknowledgement surfaces (the
- * `/feedback` command's confirmation text). The seam owns the vocabulary so
- * any backend can disclose a policy without depending on the OTel package;
- * the values mirror the OTel backend's serialized `SessionTelemetryMode` choices.
+ * `/feedback` command's confirmation text). The Service Definition owns the
+ * vocabulary so consumers and backends do not depend on a specific provider.
  */
 export type SessionTelemetrySharingStatus = 'full' | 'feedback-only' | 'disabled'
 
diff --git a/packages/session/session-title-llm/README.i18n.yaml b/packages/session/session-title-llm/README.i18n.yaml
index d75451c2b9..f3be01d147 100644
--- a/packages/session/session-title-llm/README.i18n.yaml
+++ b/packages/session/session-title-llm/README.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/session/session-title-llm/README.md
-README.md: db03205cabf9f723ee9bf6ad122026d75cb92113
-README.zh.md: 7e3a7d30022cd2dec4b59d98b90b9f02e5d6e9b3
+README.md: fd8d4b1166bd33ea9768c9abca74a219fb6725e5
+README.zh.md: 5508f110f1f8a9eb58a56b5b3efd7be4e8a25262
diff --git a/packages/session/session-title-llm/README.md b/packages/session/session-title-llm/README.md
index db03205cab..fd8d4b1166 100644
--- a/packages/session/session-title-llm/README.md
+++ b/packages/session/session-title-llm/README.md
@@ -10,7 +10,7 @@ This package is a library, not a Cordis plugin. The provider plugins call `regis
 
 `provider` and `model` overrides are optional but must be supplied together as non-empty strings. Without that pair, the helper uses the exact provider/model route captured from the current session's logged `request/header`; an explicit refresh before any route exists therefore needs overrides. The helper measures the final JSON-framed user prompt, including seq fields, wrappers, and JSON escaping, against `maxInputBytes` before logging or dispatch instead of truncating it. Timeout and caller cancellation are rechecked while consuming the stream and after it completes, so a late successful result cannot be accepted even if an interceptor or adapter ignores abort. Malformed or empty output, tool calls, and non-stop finish reasons also reject; the session-title service decides whether that rejection is an automatic warning or an explicit caller failure.
 
-After route and input validation, the helper appends a log-only `session/title-llm-request` event directly through `Session` before model dispatch. It contains the title-provider id, exact source seqs, route, system prompt, message list, and output-token cap used by the call. Persistence observes the record eagerly; the append does not need a title-specific marker, cast, settlement queue, or flush. The dispatched envelope is deep-frozen, carries `purpose: 'session-title'`, and deliberately lacks dsh-agent-loop's process-local request identity. Interceptors stay aligned with the record while loop-only reconstruction observers do not compare it with the conversation header. The DeepSeek adapter maps that purpose to thinking-disabled so the small output budget is reserved for visible title text; other adapters own their purpose-specific behavior. A later model failure leaves the request record intact; validation failures that never become dispatchable requests do not create one. The event stays outside derived model history.
+After route and input validation, the helper records the exact dispatchable request as a log-only `session/title-llm-request` event before model dispatch. The event stays outside derived model history and remains recorded if the model call later fails; validation failures create no event. The request purpose disables thinking for DeepSeek title calls, while other adapters own their purpose-specific behavior.
 
 ## Configuration
 
diff --git a/packages/session/session-title-llm/README.zh.md b/packages/session/session-title-llm/README.zh.md
index 7e3a7d3002..5508f110f1 100644
--- a/packages/session/session-title-llm/README.zh.md
+++ b/packages/session/session-title-llm/README.zh.md
@@ -10,7 +10,7 @@
 
 `provider` 和 `model` 覆盖项都是可选的，但必须同时作为非空字符串提供。如果没有这一对取值，辅助模块会使用当前会话已记录 `request/header` 中捕获的确切提供方／模型路由；因此，在任何路由出现前显式刷新时必须提供覆盖项。辅助模块在记录或分发前，依据 `maxInputBytes` 检查最终 JSON 封装用户提示词的大小，包括 seq 字段、包装层与 JSON 转义，而不是将其截断。消费流期间和流完成后都会重新检查超时与调用方取消，因此即使拦截器或适配器忽略 abort，也不能接受迟到的成功结果。格式错误或空输出、工具调用和非 stop 结束原因同样会导致调用被拒绝；会话标题服务决定该拒绝属于自动警告还是显式调用方失败。
 
-路由与输入验证完成后，辅助模块会在模型分发前直接通过 `Session` 追加仅写入日志的 `session/title-llm-request` 事件。它包含标题提供方 id、确切来源 seq、路由、系统提示词、消息列表，以及该调用使用的输出 token 上限。持久化会立即观察到该记录；追加不需要标题专属标记、类型断言、结算队列或刷写。分发的请求封套会深度冻结，携带 `purpose: 'session-title'`，且有意不包含 dsh-agent-loop 的进程本地请求身份。拦截器会与记录保持一致，而循环专用重建观察者不会把它与对话请求头比较。DeepSeek 适配器会根据该用途禁用思考，使少量输出预算全部用于可见标题文本；其他适配器负责自身用途专用行为。后续模型失败会保留请求记录；从未成为可分发请求的验证失败不会创建记录。该事件始终位于派生模型历史之外。
+路由与输入校验完成后，辅助模块会在模型分发前将确切的可分发请求记录为仅写入日志的 `session/title-llm-request` 事件。该事件不进入派生模型历史；后续模型调用失败时仍会保留，而校验失败不会创建事件。请求用途会使 DeepSeek 标题调用禁用思考，其他适配器则负责自身的用途专用行为。
 
 <a id="configuration"></a>
 
diff --git a/packages/skill/tool-skill/src/index.ts b/packages/skill/tool-skill/src/index.ts
index e2a0cc2dca..596876b5a7 100644
--- a/packages/skill/tool-skill/src/index.ts
+++ b/packages/skill/tool-skill/src/index.ts
@@ -387,7 +387,6 @@ function catalogMessage(
   return undefined
 }
 
-/** Normalized, length-bounded description exactly as the catalog publishes it (unescaped). */
 function catalogDescription(value: string, maxLength: number): string {
   const normalized = value.replaceAll(/\s+/g, ' ').trim()
   return normalized.length <= maxLength ? normalized : `${normalized.slice(0, maxLength - 3)}...`
diff --git a/packages/spill/spill-local/src/store.ts b/packages/spill/spill-local/src/store.ts
index e44418767a..e4451d5268 100644
--- a/packages/spill/spill-local/src/store.ts
+++ b/packages/spill/spill-local/src/store.ts
@@ -1,9 +1,7 @@
 /**
  * Cordis-free storage mechanics for the local spill backend: private
  * session-scoped directory selection, safe-name derivation, path-traversal
- * protection, and the exclusive owner-only write. Kept out of the service class
- * (like `dsh-bash-local`'s `run.ts`) so the filesystem behavior is unit-testable
- * without a `ctx` and without the OS temp dir.
+ * protection, and the exclusive owner-only write.
  *
  * @module @deepseek-ai/dsh-spill-local/store
  */
@@ -29,8 +27,7 @@ export function privateRoot(): string {
   return defaultRoot
 }
 
-// Deliberately mirrors the JSONL path encoder, but keeps spill's empty-name
-// policy (`""` -> `"~"`) local so storage backends stay decoupled.
+// Spill keeps its empty-name policy local so storage backends stay decoupled.
 /* jscpd:ignore-start */
 /**
  * Encode an arbitrary string as one safe path segment, injectively over ALL JS
@@ -40,7 +37,6 @@ export function privateRoot(): string {
  * as `~XXXX`; `~` is itself escaped, so the mapping is reversible and distinct
  * inputs never collide. The whole-segment tokens `.`/`..` are escaped so they
  * can never traverse. An empty string encodes to `~` (never an empty segment).
- * (Mirrors the JSONL persistence backend's `encodeSegment`.)
  *
  * @param raw The untrusted string to encode as one safe path segment.
  * @returns An injective, filesystem-safe single path segment.
diff --git a/packages/subagent/subagent-dsh-sdk/src/run.ts b/packages/subagent/subagent-dsh-sdk/src/run.ts
index 194ce3badf..9caf0cb417 100644
--- a/packages/subagent/subagent-dsh-sdk/src/run.ts
+++ b/packages/subagent/subagent-dsh-sdk/src/run.ts
@@ -1,12 +1,11 @@
 /**
  * Fresh-process SDK subagent client. Drives one child DeepSeek Harness
  * runtime over stdio JSON-RPC through `@deepseek-ai/dsh-sdk-client` and owns
- * cancellation and quiescent disposal. Structure mirrors the ACP backend
- * (`@deepseek-ai/dsh-subagent-acp`): publish after the child handshake,
- * flatten child failures into stop reasons, tear down to quiescence. The
- * child is spawned BY the SDK client rather than through `ctx.subprocess` —
- * the subprocess seam's documented exception for SDK-managed transports —
- * so this driver applies the seam's shared env scrub itself.
+ * cancellation and quiescent disposal. It publishes after the child
+ * handshake, maps child failures to stop reasons, and tears down to
+ * quiescence. The SDK client spawns the child rather than using
+ * `ctx.subprocess` — the subprocess seam's documented exception for
+ * SDK-managed transports — so this driver applies the seam's shared env scrub.
  *
  * @module @deepseek-ai/dsh-subagent-dsh-sdk/run
  */
diff --git a/packages/subagent/subagent-fork-in-process/tests/subagent-fork-in-process.spec.ts b/packages/subagent/subagent-fork-in-process/tests/subagent-fork-in-process.spec.ts
index 6d763b7c0a..8b69711233 100644
--- a/packages/subagent/subagent-fork-in-process/tests/subagent-fork-in-process.spec.ts
+++ b/packages/subagent/subagent-fork-in-process/tests/subagent-fork-in-process.spec.ts
@@ -173,7 +173,6 @@ describe('dsh-subagent-fork-in-process', () => {
     const result = await run.result
     expect(result.stopReason).toBe('completed')
     expect(result.structured).toEqual({ answer: 9 })
-    // Run-scoped runtime: nothing stays registered after the settle.
     expect(ctx.tools.get(STRUCTURED_OUTPUT_TOOL)).toBeUndefined()
     await run.dispose()
   })
diff --git a/packages/subagent/subagent-spawn-in-process/tests/subagent-spawn-in-process.spec.ts b/packages/subagent/subagent-spawn-in-process/tests/subagent-spawn-in-process.spec.ts
index 74aefb4ebd..ae60480c02 100644
--- a/packages/subagent/subagent-spawn-in-process/tests/subagent-spawn-in-process.spec.ts
+++ b/packages/subagent/subagent-spawn-in-process/tests/subagent-spawn-in-process.spec.ts
@@ -310,7 +310,6 @@ describe('dsh-subagent-spawn-in-process', () => {
     const result = await run.result
     expect(result.stopReason).toBe('completed')
     expect(result.structured).toEqual({ answer: 42 })
-    // Run-scoped runtime: the settle released the last acquisition.
     expect(ctx.tools.get(STRUCTURED_OUTPUT_TOOL)).toBeUndefined()
     await run.dispose()
   })
diff --git a/packages/subagent/subagent/src/index.ts b/packages/subagent/subagent/src/index.ts
index 45b96a2311..2f29e32010 100644
--- a/packages/subagent/subagent/src/index.ts
+++ b/packages/subagent/subagent/src/index.ts
@@ -4,10 +4,8 @@
  * child before returning its run, so fulfillment is the single publication and
  * ownership-transfer boundary.
  *
- * Unlike the bash seam (one executor per context, second load throws), MULTIPLE
- * providers coexist here: each registers under a unique name and a caller picks
- * one by name. The shape mirrors the LLM adapter registry
- * (`LlmRuntime.registerAdapter`), not the single-service bash executor.
+ * Multiple providers coexist: each registers under a unique name and callers
+ * select one by name.
  *
  * This package owns the Service Definition role of the capability seam. Service Providers
  * (`@deepseek-ai/dsh-subagent-spawn-in-process`, `-fork`, `-acp`) and the model-facing
@@ -284,7 +282,7 @@ export class SubagentRuntime extends Service {
    * @returns the exact Cordis effect disposer.
    */
   registerContinuableSetup(contribution: ContinuableSetupContribution): () => void {
-    // oxlint-disable-next-line typescript/no-misused-promises -- synchronous cleanup; direct return preserves disposer identity
+    // oxlint-disable-next-line typescript/no-misused-promises -- synchronous disposer
     return this.ctx.effect(
       () => this.setupRegistry.register(contribution),
       'subagents.registerContinuableSetup()',
@@ -384,7 +382,7 @@ export class SubagentRuntime extends Service {
    */
   registerProvider(provider: SubagentProvider): () => void {
     const name = provider.name
-    // oxlint-disable-next-line typescript/no-misused-promises -- synchronous cleanup; direct return preserves disposer identity
+    // oxlint-disable-next-line typescript/no-misused-promises -- synchronous disposer
     return this.ctx.effect(function* (this: SubagentRuntime) {
       if (this.providers.has(name)) {
         throw new SubagentError(`a subagent provider named "${name}" is already registered`, 'DUPLICATE_PROVIDER')
diff --git a/packages/subagent/tool-subagent/src/index.ts b/packages/subagent/tool-subagent/src/index.ts
index 86d00c6d0b..ef0e9941eb 100644
--- a/packages/subagent/tool-subagent/src/index.ts
+++ b/packages/subagent/tool-subagent/src/index.ts
@@ -284,8 +284,8 @@ export function apply(ctx: Context, config: Config): void {
   const backgroundEnabled = config.enableRunInBackground !== false
   const continuable = (config.backgroundMode ?? 'one-shot') === 'continuable'
   const toolName = config.toolName ?? 'subagent'
-  // Mirror provider lifecycle because sibling load order and HMR replacement
-  // can change provider availability while this fiber remains active.
+  // Load order and HMR replacement can change provider availability while
+  // this fiber remains active.
   let disposeTool: (() => void) | undefined
   const mount = (provider: SubagentProvider): void => {
     // A numeric cap the provider cannot enforce is a misconfiguration — fail at
diff --git a/packages/typert/loader/src/index.ts b/packages/typert/loader/src/index.ts
index 7cb73c446f..ce5aa0d54f 100644
--- a/packages/typert/loader/src/index.ts
+++ b/packages/typert/loader/src/index.ts
@@ -11,9 +11,9 @@
  * fails loud — aggregated into this plugin's activation throw for existing
  * entries, contained to a logged error per package in steady state.
  *
- * Scanning is incremental per entry name, mirroring the client-modules node
- * half: every cordis `internal/plugin` emission marks the fiber's entry name
- * dirty and a microtask flush reconciles each dirty name against the live
+ * Scanning is incremental per entry name. Every cordis `internal/plugin`
+ * emission marks the fiber's entry name dirty, and a microtask flush
+ * reconciles each dirty name against the live
  * loader entries; the activation pass seeds the same dirty set with all
  * current entries. Package verdicts and imported manifests are cached per
  * package name and never expire — plugin-set changes take effect on restart.
diff --git a/packages/web/tool-web/src/search.ts b/packages/web/tool-web/src/search.ts
index c5acac7515..f382582172 100644
--- a/packages/web/tool-web/src/search.ts
+++ b/packages/web/tool-web/src/search.ts
@@ -13,9 +13,7 @@ import type {} from '@deepseek-ai/dsh-system-prompt'
 
 /**
  * Default upper bound on returned sources (the `searchMaxResults` config).
- * Owned by the consumer (not the provider or model), mirroring `dsh-tool-fs`'s
- * `READ_LIMIT`. The model just asks a question; the product controls how much
- * context returns. The default `8` aligns with OpenCode's Exa default.
+ * The consumer owns the returned-context limit; providers and models do not.
  */
 export const WEB_SEARCH_MAX_RESULTS = 8
 
diff --git a/packages/web/web-fetch-http/src/index.ts b/packages/web/web-fetch-http/src/index.ts
index 3f8ff13898..a3ce03c9b2 100644
--- a/packages/web/web-fetch-http/src/index.ts
+++ b/packages/web/web-fetch-http/src/index.ts
@@ -1,8 +1,6 @@
 /**
- * `@deepseek-ai/dsh-web-fetch-http`: registers an anonymous public HTTP(S)
- * `WebFetchProvider` with `ctx.web`. A function/namespace plugin (NOT a
- * default-export service): it registers INTO the seam's fetch registry, like the
- * search providers register into the search registry.
+ * Anonymous public HTTP(S) `WebFetchProvider` plugin. It contributes to the
+ * `ctx.web` registry without owning the service.
  *
  * @module @deepseek-ai/dsh-web-fetch-http
  */
diff --git a/packages/web/web-search-exa/src/index.ts b/packages/web/web-search-exa/src/index.ts
index 34a257cd27..a0a75e54ee 100644
--- a/packages/web/web-search-exa/src/index.ts
+++ b/packages/web/web-search-exa/src/index.ts
@@ -1,9 +1,6 @@
 /**
- * `@deepseek-ai/dsh-web-search-exa`: registers an Exa-backed `WebSearchProvider`
- * with `ctx.web`. A function/namespace plugin (NOT a default-export service):
- * a search provider does not own the `ctx.web` key — it registers INTO the
- * seam's provider registry, exactly as `@deepseek-ai/dsh-llm-deepseek`
- * registers an adapter into `ctx.llm`. The key is owned by `@deepseek-ai/dsh-web`.
+ * Exa-backed `WebSearchProvider` plugin. It contributes to the `ctx.web`
+ * registry without owning the service.
  *
  * @module @deepseek-ai/dsh-web-search-exa
  */
diff --git a/packages/web/web-search-perplexity/src/index.ts b/packages/web/web-search-perplexity/src/index.ts
index de20f83747..5584658093 100644
--- a/packages/web/web-search-perplexity/src/index.ts
+++ b/packages/web/web-search-perplexity/src/index.ts
@@ -1,8 +1,6 @@
 /**
- * `@deepseek-ai/dsh-web-search-perplexity`: registers a Perplexity-backed
- * `WebSearchProvider` with `ctx.web`. A function/namespace plugin (NOT a
- * default-export service): it registers INTO the seam's provider registry, like
- * `@deepseek-ai/dsh-llm-deepseek` registers an adapter into `ctx.llm`.
+ * Perplexity-backed `WebSearchProvider` plugin. It contributes to the
+ * `ctx.web` registry without owning the service.
  *
  * @module @deepseek-ai/dsh-web-search-perplexity
  */
diff --git a/packages/workflow/workflow-worker-thread/tests/session.spec.ts b/packages/workflow/workflow-worker-thread/tests/session.spec.ts
index b856a48785..5b323d1638 100644
--- a/packages/workflow/workflow-worker-thread/tests/session.spec.ts
+++ b/packages/workflow/workflow-worker-thread/tests/session.spec.ts
@@ -47,9 +47,7 @@ interface FakeHostOptions {
 /**
  * Drive runWorkerSession IN-PROCESS over a MessageChannel: this is where the
  * worker-side files earn their coverage — code inside a real Worker is
- * invisible to main-process coverage. The fake host mirrors the real host's
- * protocol discipline (one started/start-error per start; settled/disposed
- * follow).
+ * invisible to main-process coverage.
  */
 function fakeHost(options?: FakeHostOptions): FakeHost {
   const channel = new MessageChannel()
@@ -238,7 +236,6 @@ describe('runWorkerSession over an in-process MessageChannel', () => {
     const callId = host.ofType(WorkerToHostType.ChildStart)[0]!.callId
     host.send({ type: HostToWorkerType.ChildStarted, callId, childId: 'child-0' })
     host.send({ type: HostToWorkerType.Cancel, reason: 'stop everything' })
-    // The real host settles the aborted child; mirror it.
     host.send({ type: HostToWorkerType.ChildSettled, callId, result: { output: [], stopReason: 'aborted' } })
     const result = await host.result()
     expect(result.stopReason).toBe('cancelled')
diff --git a/scripts/gen-client-catalog.ts b/scripts/gen-client-catalog.ts
index 854bc75c6d..a4e67886ae 100644
--- a/scripts/gen-client-catalog.ts
+++ b/scripts/gen-client-catalog.ts
@@ -552,7 +552,6 @@ export function main(): void {
   console.log(`gen-client-catalog: wrote ${OUT}.`)
 }
 
-// Run only when invoked as a script, not when imported by a test.
 if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) {
   main()
 }
diff --git a/scripts/gen-config-catalog.ts b/scripts/gen-config-catalog.ts
index 83fe8e7809..9c341f7684 100644
--- a/scripts/gen-config-catalog.ts
+++ b/scripts/gen-config-catalog.ts
@@ -874,7 +874,6 @@ function main(): void {
   console.log(`gen-config-catalog: wrote ${OUT}.`)
 }
 
-// Run only when invoked as a script, not when imported by a test.
 if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) {
   main()
 }
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index 522e98df96..f94c7735e1 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -1008,7 +1008,6 @@ export function main(): void {
   console.log(`gen-cordis-catalog: ${outputs.length} artifact(s) computed, ${changedPages} written, ${recorded} pair record(s) refreshed.`)
 }
 
-// Run only when invoked as a script, not when imported by a test.
 if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) {
   main()
 }
diff --git a/scripts/gen-persistence-catalog.ts b/scripts/gen-persistence-catalog.ts
index 248951def8..b324ed10ec 100644
--- a/scripts/gen-persistence-catalog.ts
+++ b/scripts/gen-persistence-catalog.ts
@@ -466,7 +466,6 @@ function main(): void {
   }
 }
 
-// Run only when invoked as a script, not when imported by a test.
 if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) {
   main()
 }
diff --git a/scripts/gen-third-party-notices.ts b/scripts/gen-third-party-notices.ts
index 3362251f1e..42b7d29c2c 100644
--- a/scripts/gen-third-party-notices.ts
+++ b/scripts/gen-third-party-notices.ts
@@ -768,7 +768,6 @@ function main(): void {
   console.log(`gen-third-party-notices: wrote ${OUT}.`)
 }
 
-// Run only when invoked as a script, not when imported by a test.
 if (process.argv[1] !== undefined && import.meta.filename === resolve(process.argv[1])) {
   main()
 }
diff --git a/scripts/gen-tool-catalog.ts b/scripts/gen-tool-catalog.ts
index 874f564483..c76d735a43 100644
--- a/scripts/gen-tool-catalog.ts
+++ b/scripts/gen-tool-catalog.ts
@@ -808,7 +808,6 @@ async function main(): Promise<void> {
   console.log(`gen-tool-catalog: wrote ${OUT}.`)
 }
 
-// Run only when invoked as a script, not when imported by a test.
 if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) {
   await main()
 }
diff --git a/scripts/release/bump.ts b/scripts/release/bump.ts
index 54aa8c09f1..69f6582838 100644
--- a/scripts/release/bump.ts
+++ b/scripts/release/bump.ts
@@ -40,13 +40,9 @@ const ROOT_MANIFEST = 'package.json'
 
 /** One manifest the bump rewrites, and the tag its new version will carry. */
 interface PlannedVersion {
-  /** Repository-relative manifest path. */
   readonly manifestPath: string
-  /** Label for the log line. */
   readonly label: string
-  /** The version the manifest currently carries. */
   readonly from: string
-  /** The version to write. */
   readonly to: string
   /** The tag this version publishes from, or undefined for a non-published manifest. */
   readonly tag: string | undefined
diff --git a/scripts/release/families.ts b/scripts/release/families.ts
index a847371631..7a73323244 100644
--- a/scripts/release/families.ts
+++ b/scripts/release/families.ts
@@ -38,7 +38,6 @@ const WORKSPACE_ROOT_PACKAGE = '@deepseek-ai/dsh-root'
 
 /** One peer declaration the publish order leaves unordered. */
 interface DroppedPeerEdge {
-  /** Package declaring the peer. */
   readonly consumer: string
   /** The declared peer, which publishes after `consumer` or alongside it in a cycle. */
   readonly peer: string
@@ -52,7 +51,6 @@ interface DroppedPeerEdge {
  * log is the only one who can judge whether a newly dropped edge is expected.
  */
 export interface PublishPlan {
-  /** Members in publish order. */
   readonly order: readonly ReleaseMember[]
   /** Peer declarations left unordered, in the order the traversal reached them. */
   readonly droppedPeerEdges: readonly DroppedPeerEdge[]
@@ -60,13 +58,9 @@ export interface PublishPlan {
 
 /** One publishable package of a release family. */
 export interface ReleaseMember {
-  /** Repository-relative package directory, for example `packages/core/session`. */
   readonly directory: string
-  /** Package name from its manifest. */
   readonly name: string
-  /** Package version from its manifest. */
   readonly version: string
-  /** The parsed manifest, for payload policy and publication checks. */
   readonly manifest: Readonly<Record<string, unknown>>
 }
 
@@ -98,18 +92,16 @@ function requireString(manifest: Record<string, unknown>, field: string, context
 
 /** The executable a family's installed artifacts are driven through. */
 export interface InstalledEntry {
-  /** Package that carries the executable. */
   readonly packageName: string
-  /** Path to the executable inside that package. */
   readonly binPath: string
 }
 
 /** A release sequence: its members, its version baseline, and its tag naming. */
 export abstract class ReleaseFamily {
-  /** Workflow-facing identifier, also the `--family` argument. */
+  /** Workflow-facing `--family` identifier. */
   abstract readonly id: string
 
-  /** Glob patterns, relative to the repository root, that select this family's manifests. */
+  /** Repository-relative glob patterns selecting this family's manifests. */
   abstract readonly patterns: readonly string[]
 
   /** Git tag prefix this family publishes from. */
diff --git a/scripts/release/process.ts b/scripts/release/process.ts
index 392a6cab66..f73d8d53b8 100644
--- a/scripts/release/process.ts
+++ b/scripts/release/process.ts
@@ -9,9 +9,7 @@ import { fileURLToPath } from 'node:url'
 
 /** Where and with what environment a release step runs a command. */
 export interface RunOptions {
-  /** Working directory; defaults to the current one. */
   readonly cwd?: string
-  /** Child environment; defaults to this process's. */
   readonly env?: NodeJS.ProcessEnv
 }
 
@@ -19,9 +17,7 @@ export interface RunOptions {
 export interface CommandResult {
   /** Exit status, or null when a signal ended the process. */
   readonly status: number | null
-  /** Captured standard output. */
   readonly stdout: string
-  /** Captured standard error. */
   readonly stderr: string
 }
 
@@ -39,19 +35,8 @@ export function attempt(command: string, args: readonly string[], options: RunOp
 }
 
 /**
- * Run a command, capture its output, and echo it once the command exits.
- *
- * A step that both shows what a command said and classifies its own failure
- * needs both halves: the output has to reach the workflow log, and the caller has
- * to read it to decide whether a failure is worth retrying.
- *
- * This is not live progress. `spawnSync` returns only after the child exits, so
- * nothing appears while the command runs, and the two streams are echoed one
- * after the other — all of stdout, then all of stderr — which loses their
- * interleaving. For an npm publish that matters in one visible way: `npm notice`
- * lines go to stderr while the `+ name@version` confirmation goes to stdout, so
- * the log shows the confirmation first. Live progress would need an
- * asynchronous spawn with data listeners.
+ * Run a command, then echo and return its captured output. Output is buffered
+ * until exit and stdout precedes stderr.
  * @param command - executable name.
  * @param args - command arguments.
  * @param options - working directory and environment.
@@ -62,8 +47,6 @@ export function attemptEchoed(command: string, args: readonly string[], options:
     cwd: options.cwd,
     env: options.env,
     encoding: 'utf8',
-    // 'inherit' would leave nothing to capture, so the streams are piped and
-    // echoed instead.
     stdio: ['inherit', 'pipe', 'pipe'],
   })
   if (result.error !== undefined) throw result.error
@@ -101,11 +84,7 @@ export function run(command: string, args: readonly string[], options: RunOption
 }
 
 /**
- * Whether this module is the process entry point.
- *
- * The release scripts are both commands and modules: a test imports their pure
- * logic, and importing a module runs its body, so an unguarded `main()` would
- * run the wrong command with the wrong arguments.
+ * Return whether Node started the given module as the process entry point.
  * @param moduleUrl - the caller's `import.meta.url`.
  * @returns True when Node started this module.
  */
diff --git a/scripts/translation-pairing-git.ts b/scripts/translation-pairing-git.ts
index e004c935d7..041a0bdb00 100644
--- a/scripts/translation-pairing-git.ts
+++ b/scripts/translation-pairing-git.ts
@@ -42,9 +42,7 @@ export function runGit(root: string, args: string[], operation: string, input?:
 
 /** One regular stage-zero Git index entry and its exact blob bytes. */
 export interface GitIndexBlob {
-  /** Object ID recorded in the index. */
   objectId: string
-  /** Blob bytes stored under that object ID. */
   content: Buffer
 }
 
diff --git a/scripts/verify-client-packages.ts b/scripts/verify-client-packages.ts
index 17b7c9d7c1..225f944bdf 100644
--- a/scripts/verify-client-packages.ts
+++ b/scripts/verify-client-packages.ts
@@ -22,13 +22,9 @@ const CLIENT_WEB = '@deepseek-ai/dsh-client-web'
 
 /** One workspace package's browser-module declaration. */
 export interface ClientDeclaration {
-  /** npm package name. */
   readonly name: string
-  /** Repository-relative package manifest. */
   readonly manifest: string
-  /** Whether the manifest declares a dynamic dsh.client row. */
   readonly dynamic: boolean
-  /** Exact module-table specifiers requested by the row. */
   readonly external: readonly string[]
   /** Informational package dependencies declared by the row. */
   readonly inject: readonly string[]
@@ -36,43 +32,28 @@ export interface ClientDeclaration {
 
 /** One package directly under packages/client. */
 export interface ClientPackage extends ClientDeclaration {
-  /** Whether its build config uses the staticLinked preset. */
   readonly staticLinked: boolean
-  /** Production source locations grouped by imported package name. */
   readonly sourceUses: Readonly<Record<string, readonly string[]>>
-  /** Production source locations grouped by runtime-imported package name. */
   readonly runtimeSourceUses: Readonly<Record<string, readonly string[]>>
-  /** Installed implementation dependencies. */
   readonly dependencies: Readonly<Record<string, string>>
-  /** Consumer-supplied dependencies. */
   readonly peerDependencies: Readonly<Record<string, string>>
-  /** Dependencies available while developing the package. */
   readonly devDependencies: Readonly<Record<string, string>>
 }
 
 /** Complete source-plane input to the client package verifier. */
 export interface ClientPackageFacts {
-  /** Packages directly under packages/client. */
   readonly packages: readonly ClientPackage[]
-  /** Every workspace package, including packages without a browser row. */
   readonly declarations: readonly ClientDeclaration[]
-  /** Packages whose build config uses the staticLinked preset. */
   readonly staticLinkedPackages: ReadonlySet<string>
-  /** Specifiers the web shell seeds into the module table. */
   readonly platformModules: readonly string[]
-  /** Dynamic factories the HTML parser loads before shell boot. */
   readonly preloadedExternals: readonly string[]
-  /** Package rows whose bundles the HTML parser executes before shell boot. */
   readonly parserPreloadIds: readonly string[]
-  /** Manifest field errors found while reading declarations. */
   readonly malformed: readonly string[]
 }
 
 /** Result of reading every workspace browser-module declaration. */
 export interface ClientDeclarations {
-  /** One declaration record per named workspace manifest. */
   readonly declarations: ClientDeclaration[]
-  /** Manifest field errors that prevent a reliable declaration. */
   readonly malformed: string[]
 }
 
diff --git a/scripts/verify-export-jsdoc.ts b/scripts/verify-export-jsdoc.ts
index f1efd361bb..ae92d07ac1 100644
--- a/scripts/verify-export-jsdoc.ts
+++ b/scripts/verify-export-jsdoc.ts
@@ -22,37 +22,28 @@ const PROTOCOL_EXPORTS = new Set(['Config', 'inject', 'name', 'reusable', 'apply
 
 /** Per-file walk state threaded through the scope recursion. */
 interface Walk {
-  /** Repo-relative path of the file being walked. */
   rel: string
-  /** The parsed source file. */
   sf: ts.SourceFile
-  /** Raw file text (rawJsDoc reads comment ranges out of it). */
   text: string
-  /** The program's checker, consulted only for heritage-member lookups. */
   checker: ts.TypeChecker
-  /** The aggregate violation list, appended in place. */
   violations: string[]
 }
 
-/** True when a statement carries the `export` modifier. */
 function isExported(stmt: ts.Statement): boolean {
   return ts.canHaveModifiers(stmt) && (ts.getModifiers(stmt)?.some(m => m.kind === ts.SyntaxKind.ExportKeyword) ?? false)
 }
 
-/** True for a class member a consumer cannot reach: `private`/`protected`/`#name`. */
 function isNonPublic(member: ts.ClassElement): boolean {
   const mods = ts.canHaveModifiers(member) ? ts.getModifiers(member) : undefined
   return (mods?.some(m => m.kind === ts.SyntaxKind.PrivateKeyword || m.kind === ts.SyntaxKind.ProtectedKeyword) ?? false)
     || ('name' in member && ts.isPrivateIdentifier(member.name))
 }
 
-/** True when a class member carries the `static` modifier. */
 function isStatic(member: ts.ClassElement): boolean {
   const mods = ts.canHaveModifiers(member) ? ts.getModifiers(member) : undefined
   return mods?.some(m => m.kind === ts.SyntaxKind.StaticKeyword) ?? false
 }
 
-/** The `this`-receiver exemption every function-like check shares. */
 function thisReceiver(p: ts.ParameterDeclaration): boolean {
   return ts.isIdentifier(p.name) && p.name.text === 'this'
 }
@@ -611,7 +602,6 @@ function main(): void {
   process.exit(1)
 }
 
-// Run only when invoked as a script, not when imported by a test.
 if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) {
   main()
 }
diff --git a/scripts/verify-md-links.ts b/scripts/verify-md-links.ts
index 63ea5e531a..e8f0e94850 100644
--- a/scripts/verify-md-links.ts
+++ b/scripts/verify-md-links.ts
@@ -195,7 +195,6 @@ export function findViolations(
   return out
 }
 
-// Run only when invoked as a script, not when imported by the spec.
 if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) {
   // Archived notes remain valid link targets, but their historical outbound links are frozen.
   const files = uniqueRepoFiles(root, PATTERNS, isArchivedAgentNotePath)
diff --git a/scripts/verify-optional-dependency-imports.ts b/scripts/verify-optional-dependency-imports.ts
index e7e16d7aab..11314f36e0 100644
--- a/scripts/verify-optional-dependency-imports.ts
+++ b/scripts/verify-optional-dependency-imports.ts
@@ -208,7 +208,6 @@ function main(): void {
   process.exit(1)
 }
 
-// Run only when invoked as a script, not when imported by a test.
 if (process.argv[1] && import.meta.filename === resolve(process.argv[1])) {
   main()
 }