From d2582b8dc13ac8229a1ee46da8a862f1da2c201b Mon Sep 17 00:00:00 2001 From: Chinesezjc Date: Thu, 30 Jul 2026 16:11:59 +0800 Subject: [PATCH 01/12] feat(web): render write/edit tool output as a diff card The write/edit tools already declare card:'diff' with applied hunks on callView/resultView, but the Web client discarded it: a mutation landed on GenericToolCard and the details panel flattened the result to a 
. Add
DiffBlock (ui-primitives), diff-card-model (the single callView/resultView
derivation), and FileMutationRow (keyed under write and edit), and make the
generic fallback row and the details panel diff-aware. The +/- block form,
per-file path header, same-file gap, and footer mirror the TUI diff card;
the chat row caps at CHAT_DIFF_MAX_LINES against the panel's full height.
---
 .../2026-07-30-web-diff-card.i18n.yaml        |   6 +
 .../feature/2026-07-30-web-diff-card.md       |  56 ++++
 .../feature/2026-07-30-web-diff-card.zh.md    |  56 ++++
 .../client/connection/src/client/fixture.ts   |  28 +-
 .../client/ui-conversation/README.i18n.yaml   |   4 +-
 packages/client/ui-conversation/README.md     |   2 +
 packages/client/ui-conversation/README.zh.md  |   2 +
 .../ui-conversation/src/client/apply.ts       |   6 +
 .../src/client/chat/GenericToolCard.tsx       |   7 +-
 .../src/client/chat/ToolRow.tsx               |  31 ++-
 .../src/client/contract/diff-card-model.ts    |  66 +++++
 .../src/client/skeleton/DetailsPanel.tsx      |  11 +-
 .../toolviews/file-mutation-row.module.css    | 119 +++++++++
 .../client/toolviews/file-mutation-row.tsx    |  97 +++++++
 .../ui-conversation/tests/diff-card.spec.tsx  | 248 ++++++++++++++++++
 .../client/ui-primitives/README.i18n.yaml     |   4 +-
 packages/client/ui-primitives/README.md       |   6 +-
 packages/client/ui-primitives/README.zh.md    |   6 +-
 .../ui-primitives/src/DiffBlock.module.css    | 103 ++++++++
 .../client/ui-primitives/src/DiffBlock.tsx    | 171 ++++++++++++
 packages/client/ui-primitives/src/index.ts    |   2 +
 .../ui-primitives/tests/diff-block.spec.tsx   | 162 ++++++++++++
 22 files changed, 1173 insertions(+), 20 deletions(-)
 create mode 100644 .agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml
 create mode 100644 .agents/notes/implemented/feature/2026-07-30-web-diff-card.md
 create mode 100644 .agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
 create mode 100644 packages/client/ui-conversation/src/client/contract/diff-card-model.ts
 create mode 100644 packages/client/ui-conversation/src/client/toolviews/file-mutation-row.module.css
 create mode 100644 packages/client/ui-conversation/src/client/toolviews/file-mutation-row.tsx
 create mode 100644 packages/client/ui-conversation/tests/diff-card.spec.tsx
 create mode 100644 packages/client/ui-primitives/src/DiffBlock.module.css
 create mode 100644 packages/client/ui-primitives/src/DiffBlock.tsx
 create mode 100644 packages/client/ui-primitives/tests/diff-block.spec.tsx

diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml
new file mode 100644
index 0000000000..18f2d5178b
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# 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/feature/2026-07-30-web-diff-card.md
+2026-07-30-web-diff-card.md: 5e43d5d29f7f4000efebc166724ec9d921d2b441
+2026-07-30-web-diff-card.zh.md: aac577cfa8dd9e0bf5f17a729d049d207a64d374
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md
new file mode 100644
index 0000000000..5e43d5d29f
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md
@@ -0,0 +1,56 @@
+# Agent Note: Web diff card — the write/edit render intent reaches the browser
+
+Status: implemented
+
+English | [中文](2026-07-30-web-diff-card.zh.md)
+
+## Problem
+
+The `write` and `edit` tools declare `card: 'diff'` for both their call and their result ([render-intent union](../architecture/2026-07-02-tool-render-intent-union.md)): the call view carries the intended change derived from the arguments, and the result view carries the applied contextual hunks (`FileDiff[]`, computed by `packages/fs/tool-fs/src/diff.ts` and persisted in the result `meta` so replay reproduces it). That view already reaches the browser — host, connection, and runtime deliver it onto `ConversationSnapshot` as `callView`/`resultView` — and the TUI already renders it as per-file `+`/`-` blocks with a `+A -R · N file(s)` footer.
+
+The Web client ignored it. A write/edit call landed on `GenericToolCard`, whose row is derived from raw tool args, and the details panel flattened the result's content blocks into one `
`. The `diffs` payload — the whole point of the result — was discarded, so a file mutation read as a one-line confirmation with no visible change.
+
+This is the [terminal card](2026-07-28-web-terminal-card.md) done for the `diff` arm: that change made the Web client a consumer of the `terminal` render intent; this one makes it a consumer of the `diff` render intent, reusing the same four-layer shape.
+
+## Decision
+
+`DiffBlock` is a `ui-primitives` component that renders a file mutation as an inline diff surface, and both Web render sites for a write/edit call consume the diff render intent through it: the chat tool row's body and the details panel's Output section. `ui-conversation/src/client/contract/diff-card-model.ts` is the single place that turns the snapshot's `callView`/`resultView` pair into the component's props, so the two sites cannot disagree about a change. It returns null — the generic path — whenever neither side declares `card: 'diff'`, including a `card` value this client version does not know, and whenever a settled call's result view is generic, which is how write/edit keep their execution errors on the generic path. The result side is authoritative once the call settles: the applied hunks replace the call-time diff derived from the arguments alone. A paging window that drops the call head still renders, because the result view carries the whole change.
+
+The component's contract mirrors the TUI's `diffLines` (`packages/ui/tui/src/components/transcript.ts`) so a diff reads the same across front ends:
+
+- **One path header per file.** A new file opens a bold path header; a same-file second hunk (a scattered edit, or a `replace_all`) opens with a `⋯` gap instead of repeating the path. The `N file(s)` footer counts distinct paths.
+- **The change in the diff's own colors.** A removed line is `- ` on the error token, an added line is `+ ` on the success token, drawn verbatim with `white-space: pre` inside a horizontally scrolling box — a source line is read by its indentation, so it scrolls rather than folds. A create (`oldText: null`) has no removed side.
+- **Height cap with an expand control.** A diff longer than `DEFAULT_DIFF_MAX_LINES` (16) shows `ceil(max/2)` head rows plus the remaining tail rows, with a button between reporting the hidden count. The split arithmetic matches `TerminalBlock` and the TUI's collapsed card, so a long diff's head and tail slices agree across front ends.
+- **Footer and copy.** A dim `└ +A -R · N file(s)` footer summarizes the change; `+A -R` are the added/removed line counts, the same per-side counts the TUI footer draws. The copy control copies the prefixed diff text (path headers, `- `/`+ ` lines, the `⋯` gap), so a multi-file copy stays attributable.
+
+Geometry, radius, and fonts mirror `CodeBlock`/`TerminalBlock` so a diff card, a terminal card, and a fenced block read as one family; `white-space: pre` plus horizontal scroll is the deliberate divergence. The copy control floats in the card's top-right corner rather than on a banner row of its own, because a banner carrying only a copy button drew an empty band above the first diff line — the TUI diff card has no banner either, only the footer.
+
+The chat row renders the diff resident under its path-link summary, capped at `CHAT_DIFF_MAX_LINES` (8) against the panel's 16 — the same inline-output decision and the same in-flow-vs-reading-surface split recorded for the [terminal card](2026-07-28-web-terminal-card.md#inline-output-in-the-chat-row-reverses-a-stated-convention). A write/edit row is single-file, so its summary stays an openable path link AND its diff card expands; the two coexist because the card is not the path's args body.
+
+## Alternatives considered
+
+**A side-by-side (two-column) diff.** Rejected for now by the owner: it is denser but does not fit the narrow chat row, and the goal was parity with the TUI's single-column unified form. A two-column mode in the details panel is a later props change, not a redesign.
+
+**Git-style line-number gutters.** The `FileDiff` contract carries only `{ path, oldText, newText }` — `structuredPatch`'s hunk start lines are dropped in `diff.ts`, so no line number reaches the client. Rendering a numbered gutter needs a backend contract change (carry `oldStart`/`newStart`) and a matching TUI upgrade to stay consistent; deferred so this PR stays a pure Web consumer of the existing contract.
+
+**Reuse `CodeBlock`.** Rejected for the same reason the terminal card was: `CodeBlock` soft-wraps and has no per-line `+`/`-` role, no path headers, and no footer. The two share geometry and font tokens, which is the only part where one implementation is correct for both.
+
+## Consequences
+
+`DiffBlock` reads only the diff view's fields, so it stays a pure function of what the render intent carries — replay-safe like the presenters that produce the view. A UI without the diff capability still gets the bridge's generic fallback; nothing about the tool's result shape changed. No new runtime dependency: unlike the terminal card's `anser`, a diff needs no parser.
+
+The multi-file arm of `DiffBlock` (one card, several path headers) has no producer today: `write`/`edit` each mutate one file per call, so a real card shows one file with one or more hunks. The arm is built and tested for a future multi-file mutation tool, not for a current consumer.
+
+## Testing
+
+`packages/client/ui-primitives/tests/diff-block.spec.tsx` pins the component: the create arm (added-only, no removed side), the edit arm (removed above added), the same-file `⋯` gap versus a new file's own header, the empty-diffs null render, the footer counts and their singular/plural, the head/tail cap with its `aria-expanded` toggle, and the copy control asserting the prefixed diff text on both the accepted and refused clipboard paths. Per-file 100%.
+
+`packages/client/ui-conversation/tests/diff-card.spec.tsx` pins the wiring at every render site: `diffCardModel`'s derivation and each of its null arms, the result hunks replacing the call-time diff, a window-truncated call still rendering from the result, the chat row's diff body, `FileMutationRow`'s resident card and its path link opening cwd-resolved through the host, its registration under both `write` and `edit`, and the panel's Output section.
+
+The fixture (`packages/client/connection/src/client/fixture.ts`) carries three diff turns so the built-boot snapshot pins all three arms at both render sites: a single-hunk edit (turn 62, keyed `FileMutationRow`), a create/write (turn 63), and a multi-hunk edit (turn 67, the `⋯` gap between two scattered hunks in one file).
+
+## Related
+
+- [Web terminal card](2026-07-28-web-terminal-card.md) — the same four-layer shape for the `terminal` arm; this note reuses its inline-output decision and its head/tail cap arithmetic.
+- [Tagged render-intent union for tool-call presentation](../architecture/2026-07-02-tool-render-intent-union.md) — the `card`-tagged vocabulary this consumes; the Web client is now a consumer of the `diff` arm too.
+- [Web client architecture](../architecture/2026-07-19-gui-web-client-architecture.md) — the slot and snapshot layering the two render sites sit in.
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
new file mode 100644
index 0000000000..aac577cfa8
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
@@ -0,0 +1,56 @@
+# Agent Note: Web diff 卡片 —— write/edit 渲染意图抵达浏览器
+
+Status: implemented
+
+[English](2026-07-30-web-diff-card.md) | 中文
+
+## Problem
+
+`write` 和 `edit` 工具为其 call 和 result 都声明了 `card: 'diff'`（[render-intent union](../architecture/2026-07-02-tool-render-intent-union.md)）：call view 携带从参数推导的预期改动，result view 携带已应用的上下文 hunk（`FileDiff[]`，由 `packages/fs/tool-fs/src/diff.ts` 计算，并持久化在 result `meta` 中以便回放重建）。该视图早已抵达浏览器 —— host、connection、runtime 将它作为 `callView`/`resultView` 投递到 `ConversationSnapshot` —— TUI 也已将其渲染为按文件分组的 `+`/`-` 块加 `+A -R · N file(s)` 页脚。
+
+Web 客户端忽略了它。write/edit 调用落到 `GenericToolCard`，其行从原始工具参数推导，详情面板把 result 的 content block 摊平进一个 `
`。`diffs` 载荷 —— result 的全部意义 —— 被丢弃，于是一次文件改动读起来只是一行确认、看不到任何改动。
+
+这是把 [terminal 卡片](2026-07-28-web-terminal-card.md) 对 `diff` 这一支重做一遍：那次改动让 Web 客户端成为 `terminal` 渲染意图的消费者；这次让它成为 `diff` 渲染意图的消费者，复用同一套四层结构。
+
+## Decision
+
+`DiffBlock` 是一个 `ui-primitives` 组件，把文件改动渲染为内联 diff 表面，write/edit 调用的两个 Web 渲染点都通过它消费 diff 渲染意图：chat 工具行的行体和详情面板的 Output 区。`ui-conversation/src/client/contract/diff-card-model.ts` 是唯一把快照的 `callView`/`resultView` 对转成组件 props 的地方，因此两个渲染点不会对一次改动产生分歧。当两侧都未声明 `card: 'diff'` 时它返回 null —— 走通用路径 —— 包括本客户端版本不认识的 `card` 值，以及已结算调用的 result view 是 generic 的情况（write/edit 的执行错误正是这样留在通用路径上的）。调用结算后 result 侧是权威：已应用的 hunk 替换仅从参数推导的 call 时 diff。分页窗口丢弃了 call 头也仍能渲染，因为 result view 携带完整改动。
+
+组件的契约镜像 TUI 的 `diffLines`（`packages/ui/tui/src/components/transcript.ts`），使 diff 在两个前端读起来一致：
+
+- **每个文件一个路径头。** 新文件开启一个粗体路径头；同文件的第二个 hunk（分散编辑，或 `replace_all`）以一个 `⋯` gap 开启，而非重复路径。`N file(s)` 页脚统计去重后的路径数。
+- **改动用 diff 自身的颜色。** 删除行是 error token 上的 `- `，新增行是 success token 上的 `+ `，在横向滚动的盒子里以 `white-space: pre` 逐字绘制 —— 源码行靠缩进阅读，所以滚动而不折行。新建（`oldText: null`）没有删除侧。
+- **高度上限带展开控件。** 长于 `DEFAULT_DIFF_MAX_LINES`（16）的 diff 显示 `ceil(max/2)` 个头部行加剩余尾部行，中间一个按钮报告隐藏行数。分割算术与 `TerminalBlock` 和 TUI 的折叠卡片一致，因此长 diff 的头尾切片在两个前端一致。
+- **页脚与复制。** 暗色 `└ +A -R · N file(s)` 页脚概括改动；`+A -R` 是新增/删除行数，与 TUI 页脚绘制的每侧计数相同。复制控件复制带前缀的 diff 文本（路径头、`- `/`+ ` 行、`⋯` gap），使多文件复制保持可归属。
+
+几何、圆角、字体镜像 `CodeBlock`/`TerminalBlock`，使 diff 卡片、terminal 卡片、代码块读起来是一家；`white-space: pre` 加横向滚动是刻意的分歧。复制控件浮在卡片右上角，而非占据自己的 banner 行，因为只放一个复制按钮的 banner 会在第一行 diff 上方画出一条空带 —— TUI 的 diff 卡片也没有 banner，只有页脚。
+
+chat 行把 diff 常驻渲染在路径链接摘要之下，上限 `CHAT_DIFF_MAX_LINES`（8），对应面板的 16 —— 与 [terminal 卡片](2026-07-28-web-terminal-card.md#inline-output-in-the-chat-row-reverses-a-stated-convention)记录的内联输出决策、以及流内表面对单调阅读表面的同一划分一致。write/edit 行是单文件的，所以它的摘要既是可打开的路径链接，其 diff 卡片又展开；两者共存，因为卡片不是路径的参数体。
+
+## Alternatives considered
+
+**并排（双栏）diff。** owner 目前拒绝：它更密但不适合狭窄的 chat 行，目标是与 TUI 单栏统一形式对齐。详情面板里的双栏模式是后续的 props 改动，不是重设计。
+
+**git 式行号槽。** `FileDiff` 契约只携带 `{ path, oldText, newText }` —— `structuredPatch` 的 hunk 起始行在 `diff.ts` 里被丢弃，所以没有行号抵达客户端。渲染行号槽需要后端契约改动（携带 `oldStart`/`newStart`）并同步升级 TUI 以保持一致；推迟，使本 PR 保持为对既有契约的纯 Web 消费。
+
+**复用 `CodeBlock`。** 因与 terminal 卡片相同的理由拒绝：`CodeBlock` 会折行，且没有每行 `+`/`-` 角色、没有路径头、没有页脚。两者共享几何与字体 token，那是唯一一处一个实现对两者都正确的部分。
+
+## Consequences
+
+`DiffBlock` 只读 diff view 的字段，因此它是渲染意图所携带内容的纯函数 —— 与产出该视图的 presenter 一样回放安全。没有 diff 能力的 UI 仍得到 bridge 的通用回退；工具的 result 形状没有任何改变。无新增运行时依赖：不同于 terminal 卡片的 `anser`，diff 不需要解析器。
+
+`DiffBlock` 的多文件支路（一张卡、多个路径头）今天没有生产者：`write`/`edit` 每次调用各改一个文件，所以真实卡片显示一个文件带一个或多个 hunk。该支路为将来的多文件改动工具而构建并测试，不是为当前消费者。
+
+## Testing
+
+`packages/client/ui-primitives/tests/diff-block.spec.tsx` 钉住组件：新建支路（只有新增、无删除侧）、编辑支路（删除在新增之上）、同文件 `⋯` gap 对比新文件自己的头、空 diffs 的 null 渲染、页脚计数及其单复数、头尾上限及其 `aria-expanded` 切换、以及复制控件在接受与拒绝两条剪贴板路径上断言带前缀的 diff 文本。Per-file 100%。
+
+`packages/client/ui-conversation/tests/diff-card.spec.tsx` 钉住每个渲染点的接线：`diffCardModel` 的派生及其每个 null 支路、result hunk 替换 call 时 diff、窗口截断的 call 仍从 result 渲染、chat 行的 diff 体、`FileMutationRow` 的常驻卡片及其路径链接经 host 以 cwd 解析打开、其在 `write` 与 `edit` 下的注册、以及面板的 Output 区。
+
+fixture（`packages/client/connection/src/client/fixture.ts`）携带三个 diff turn，使 built-boot snapshot 在两个渲染点钉住全部三个支路：单 hunk 编辑（turn 62，keyed `FileMutationRow`）、新建/写入（turn 63）、多 hunk 编辑（turn 67，一个文件内两处分散 hunk 之间的 `⋯` gap）。
+
+## Related
+
+- [Web terminal 卡片](2026-07-28-web-terminal-card.md) —— `terminal` 支路的同一套四层结构；本 note 复用其内联输出决策与头尾上限算术。
+- [工具调用呈现的标签化 render-intent union](../architecture/2026-07-02-tool-render-intent-union.md) —— 本改动消费的 `card` 标签词汇；Web 客户端现在也是 `diff` 支路的消费者。
+- [Web 客户端架构](../architecture/2026-07-19-gui-web-client-architecture.md) —— 两个渲染点所处的 slot 与快照分层。
diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index cb79a6b9a2..4fddf6e9c0 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -232,6 +232,13 @@ function buildAlphaLog(): SessionEvent[] {
   toolTurn(61, 'fx-write', '{"path":"notes/demo.txt","content":"hello fixture\\n"}', 'wrote notes/demo.txt')
   toolTurn(62, 'edit', '{"file_path":"notes/demo.txt","old_string":"hello","new_string":"hello fixture"}', '已编辑')
   toolTurn(63, 'write', '{"file_path":"notes/new-demo.txt","content":"hello fixture\\n"}', '已写入')
+  // Turn 67: a multi-hunk edit — two scattered replacements in one file. Named
+  // `edit` so it lands on the keyed FileMutationRow (the resident diff card the
+  // single-hunk turn 62 also uses), and file_path `src/config.ts` is the marker
+  // the presenter reads to emit the two-hunk sample: the card draws one path
+  // header, the first hunk, a `⋯` gap, then the second (the same-file
+  // second-hunk arm turns 62/63 cannot reach).
+  toolTurn(67, 'edit', '{"file_path":"src/config.ts","old_string":"multi","new_string":"multi"}', '已编辑')
   // Turn 64: one run_code turn with three logged sub-dispatches — the Code
   // Mode acceptance surface (parent code row + nested native-identical rows,
   // including an isError sub-call and a bash sub-call that must hit the same
@@ -333,9 +340,26 @@ function presentCall(name: string, argsRaw: string): ToolCallView | undefined {
         diffs: [{ path: str(args.path), oldText: null, newText: str(args.content) }],
       }
     case 'edit':
-      return { card: 'generic', title: `Edit ${str(args.file_path)}`, kind: 'edit', rawInput: args }
+      // The multi-hunk sample (turn 67) is keyed on its file_path, so the two
+      // scattered hunks share one path header and the card draws the `⋯` gap.
+      if (str(args.file_path) === 'src/config.ts') {
+        return {
+          card: 'diff', title: `Edit ${str(args.file_path)}`,
+          diffs: [
+            { path: str(args.file_path), oldText: 'const timeout = 30', newText: 'const timeout = 60' },
+            { path: str(args.file_path), oldText: 'retries: 1', newText: 'retries: 3' },
+          ],
+        }
+      }
+      return {
+        card: 'diff', title: `Edit ${str(args.file_path)}`,
+        diffs: [{ path: str(args.file_path), oldText: str(args.old_string), newText: str(args.new_string) }],
+      }
     case 'write':
-      return { card: 'generic', title: `Write ${str(args.file_path)}`, kind: 'edit', rawInput: args }
+      return {
+        card: 'diff', title: `Write ${str(args.file_path)}`,
+        diffs: [{ path: str(args.file_path), oldText: null, newText: str(args.content) }],
+      }
     default:
       return undefined // echo et al: the documented no-view fallback path
   }
diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 654722b589..a8ec59bb6a 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/client/ui-conversation/README.md
-README.md: 3973c14f2b8fe746549bb74af85a7a60a7d66aea
-README.zh.md: a6bb15c4cdd53d05bf28147b97d9d64d1c59da2b
+README.md: d3cd5cc268b60b58bb4dbb6c3b6c118084c0def8
+README.zh.md: f3a835ed82ecbd266b9f0829acc6182209940cb5
diff --git a/packages/client/ui-conversation/README.md b/packages/client/ui-conversation/README.md
index 3973c14f2b..d3cd5cc268 100644
--- a/packages/client/ui-conversation/README.md
+++ b/packages/client/ui-conversation/README.md
@@ -14,6 +14,8 @@ Generic tool rows classify the built-in bash, read, search, write, edit, and run
 
 A tool call declaring the `terminal` render intent renders its command output inline, at both conversation render sites, through ui-primitives' `TerminalBlock`. `contract/terminal-card-model.ts` is the single derivation from the snapshot's `callView`/`resultView` pair, so the sites cannot disagree about a command, its cwd, or its exit status; it yields null — the generic path — for any other card tag, including one this client version does not know. Both sites therefore also show the card's run-state dot, which is the same `StateDot` semantic a tool row's leading icon carries, so a row and its own card always agree about one command's state. A multi-line command gets one prompt row per line, with the dot marking the call once on the first row — the exit status is the whole call's, so a dot per line would claim a per-line outcome bash does not report. The keyed `BashRow` carries the card resident below its summary row; since tool rows are no longer details-panel click targets, the card's copy and expand controls are the row's only interactions. The render-site fallback row keeps the card behind its existing expand control. Rows cap at `CHAT_TERMINAL_MAX_LINES` (8) against the panel's 16, which is what keeps a summary surface bounded — the panel stays the single-call reading surface. Inline output is licensed for this intent alone; a generic tool's content remains panel-only ([decision](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md)).
 
+A tool call declaring the `diff` render intent (the `write`/`edit` tools) renders its applied change inline through ui-primitives' `DiffBlock`, the same four-layer shape. `contract/diff-card-model.ts` is the single derivation from the `callView`/`resultView` pair; the settled result's hunks replace the call-time diff, and it yields null — the generic path — for any other card tag or a generic result view (write/edit's execution errors). The keyed `FileMutationRow` (registered under both `write` and `edit`) carries the card resident below its summary, whose path link still opens the file through the host; the render-site fallback and the details panel are diff-aware too. Rows cap at `CHAT_DIFF_MAX_LINES` (8) against the panel's 16 ([decision](../../../.agents/notes/implemented/feature/2026-07-30-web-diff-card.md)).
+
 Tool rows are slots too — the standalone tool ring (`ToolViewRegistry`/`ctx.toolviews`/outlet) is retired. The chat entry declares the keyed `'conversation.chat.toolview'` hole (session scope; the key space is runtime-open); its render site dispatches per row via `entryKey: toolName` with `GenericToolCard` as the call-site `fallback`. The owner payload is the uniform `ToolRowOwnerProps` (`callId`/`toolName`/`block`/`openFile`) and `ToolRowProps` pre-composes it with the session standard kit. A registrant is a plain plugin: `ctx.slots.register({ name: 'conversation.chat.toolview', key: '', inject? }, Row)` with `inject: ['slots', 'conversation']` as the load-order seam (apply mounts ConversationService after the chat registration, so the service being present guarantees the slot is declared); session differentiation happens inside the component (`useSessions` reading `parentId` — the bash sample is the third-party-posture exemplar). Trajectory/waterfall toolview slots share this shape and land with their own render sites (RendersCheck rejects a declaration nobody renders).
 
 The todo surfaces are two registrations over that shape, both plain registrant plugins with `inject: ['slots', 'conversation']`. `TodoRow` takes the `'conversation.chat.toolview'` key `todo_write` and summarizes what the call attempted (`/ 已完成 · ` parsed from its args, falling back to the generic summary on malformed or wrongly-shaped model JSON, and keeping the generic dot for non-ok execution states so a cancelled call never reads as a completed update). `TodoDock` takes the `'conversation.input.dock'` list slot at `order: -1` — above the queue rows — and is the plan strip: it reads the host-computed `todos` projection via `useProjection` (standing plan: latest `todo/write` with no later `turn/start`) and renders `TodoPanel`, which takes the plain list, hides itself while the list is empty, and starts collapsed as a header of title plus `"/ tasks ·  in progress"` (status glyphs are the figma check / progress / dashed-pending set). The dock adapter owns the selection so the panel stays a pure function of its props; the standing list lives here rather than in the row so the row stays one line. Anything the input-zone composer chain hides (a `conversation.composer` takeover such as ui-question's) hides the whole dock, this strip included.
diff --git a/packages/client/ui-conversation/README.zh.md b/packages/client/ui-conversation/README.zh.md
index a6bb15c4cd..f3a835ed82 100644
--- a/packages/client/ui-conversation/README.zh.md
+++ b/packages/client/ui-conversation/README.zh.md
@@ -12,6 +12,8 @@
 
 声明 `terminal` 渲染意图的工具调用，会在两个对话渲染点上都通过 ui-primitives 的 `TerminalBlock` 内联渲染其命令输出。`contract/terminal-card-model.ts` 是从快照的 `callView`／`resultView` 对推导的唯一位置，因此两个渲染点不可能在命令、cwd 或退出状态上产生分歧；对任何其他 card 标签——包括当前客户端版本不认识的标签——它返回 null，落回通用路径。因此两个渲染点也都显示卡片的运行状态点，它与工具行行首图标承载同一套 `StateDot` 语义，所以一行与其自身的卡片对同一条命令的状态总是一致。多行命令的每一行各占一个提示行，状态点只在第一行为整次调用标记一次——退出状态属于整次调用，因此每行一枚就会声称一个 bash 并不报告的逐行结果。键控的 `BashRow` 把卡片常驻在摘要行下方；由于工具行已不再是详情面板的点击目标，卡片的复制与展开控件就是该行唯一的交互。渲染点兜底行则保持其既有的展开控件。行的上限是 `CHAT_TERMINAL_MAX_LINES`（8），面板为 16，正是这一点让摘要面保持有界——面板仍是单次调用的阅读面。内联输出只对该意图开放；通用工具的内容仍然只在面板中呈现（[决策](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md)）。
 
+声明 `diff` 渲染意图的工具调用（`write`／`edit` 工具），通过 ui-primitives 的 `DiffBlock` 内联渲染其已应用的改动，采用同一套四层结构。`contract/diff-card-model.ts` 是从 `callView`／`resultView` 对推导的唯一位置；已结算 result 的 hunk 替换 call 时 diff，对任何其他 card 标签或 generic result view（write/edit 的执行错误）它返回 null，落回通用路径。键控的 `FileMutationRow`（在 `write` 与 `edit` 下都注册）把卡片常驻在摘要之下，其路径链接仍经 host 打开文件；渲染点兜底行与详情面板同样感知 diff。行的上限是 `CHAT_DIFF_MAX_LINES`（8），面板为 16（[决策](../../../.agents/notes/implemented/feature/2026-07-30-web-diff-card.md)）。
+
 工具行同样是 slot：独立工具环（`ToolViewRegistry`／`ctx.toolviews`／outlet）已经退役。聊天配置项声明键控的 `'conversation.chat.toolview'` 空位（Session scope；key 空间在运行时开放）；其渲染点逐行通过 `entryKey: toolName` 分发，并以 `GenericToolCard` 作为调用点 `fallback`。owner 载荷是统一的 `ToolRowOwnerProps`（`callId`／`toolName`／`block`／`openFile`），`ToolRowProps` 则预先将其与 Session 标准工具包组合。注册方只是普通插件：`ctx.slots.register({ name: 'conversation.chat.toolview', key: '', inject? }, Row)`，以 `inject: ['slots', 'conversation']` 作为加载顺序 seam（apply 在聊天注册后挂载 ConversationService，因此服务存在即可保证 slot 已声明）；Session 区分在组件内部完成（`useSessions` 读取 `parentId`，bash 示例是第三方姿态的范例）。Trajectory/waterfall 工具视图 slot 共享此形状，并随各自的渲染点落地（RendersCheck 会拒绝没有任何渲染方的声明）。
 
 审批经由本包声明的链接管编辑器：`ApprovalPanel` 注册为按选择器路由的 `'conversation.composer'` 配置项（ui-question 模式），在审批等待未决期间取代 InputBar 占据编辑器（琥珀色条、理由标题、来自运行中调用参数的配对命令行、一次性的拒绝／允许）。`contract/slots.ts` 中的 `PendingApproval` 领域面在运行时 `PendingWait` 载体之上拥有 wire 编码——带审计关联的 `ApprovalResponsePayload` 值；广播的 `approval/resolved` 帧使等待落定并恢复编辑器。侧边栏通过 manager 跟踪的 `waitingApproval` 列表位（未实例化会话同样点亮）镜像该阻塞状态，其优先级高于运行中圆环，直至问题解决。未决等待完全离开消息流：问题（ui-question）与审批（ApprovalPanel）都经编辑器接管作答，不再保留只读占位卡。编辑器底行的 Access 席位挂载 `PermissionSelect`，由 host 计算的 `permissions` 投影经标准工具包 `useProjection` 供数（key 缺席即隐藏 chip）；chip 打开 Menu 原语下拉，kebab-case 预设名渲染为 Title Case 标签（与 `/permission` popup 的显示变换孪生），选中会经由输入栏注入的 `command` 回调提交 `/permission ` 命令行。
diff --git a/packages/client/ui-conversation/src/client/apply.ts b/packages/client/ui-conversation/src/client/apply.ts
index 7f3aeb38cc..75f8ade379 100644
--- a/packages/client/ui-conversation/src/client/apply.ts
+++ b/packages/client/ui-conversation/src/client/apply.ts
@@ -19,6 +19,7 @@ import { InputBar } from './skeleton/InputBar.tsx'
 import { ChatView } from './chat/ChatView.tsx'
 import { StatsLine } from './chat/StatsLine.tsx'
 import { bashToolviewSample } from './toolviews/bash-sample.tsx'
+import { fileMutationToolview } from './toolviews/file-mutation-row.tsx'
 import { ApprovalPanel } from './skeleton/ApprovalPanel.tsx'
 import { todoToolview } from './toolviews/todo-row.tsx'
 import { todoDockEntry } from './skeleton/TodoPanel.tsx'
@@ -254,6 +255,11 @@ export function apply(ctx: Context): void {
   // (ToolRow-matching Bash · {description} chrome; scoped badge in child sessions).
   ctx.plugin(bashToolviewSample)
 
+  // The write/edit rows ride the same seam: a file-mutation call declares the
+  // diff render intent, so these rows stack the applied diff card under their
+  // path-link summary (the terminal card's posture, applied to diffs).
+  ctx.plugin(fileMutationToolview)
+
   // The todo_write row rides the same seam (a product registration, not a sample).
   ctx.plugin(todoToolview)
 
diff --git a/packages/client/ui-conversation/src/client/chat/GenericToolCard.tsx b/packages/client/ui-conversation/src/client/chat/GenericToolCard.tsx
index ce55d84f57..8a707045e8 100644
--- a/packages/client/ui-conversation/src/client/chat/GenericToolCard.tsx
+++ b/packages/client/ui-conversation/src/client/chat/GenericToolCard.tsx
@@ -10,6 +10,7 @@ import {
   IconThinkOutline14,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ToolRowOwnerProps } from '../contract/slots.ts'
+import { diffCardModel } from '../contract/diff-card-model.ts'
 import { terminalCardModel } from '../contract/terminal-card-model.ts'
 import { toolRowModel, type ToolRowVariant } from '../contract/tool-call-model.ts'
 import { ToolRow } from './ToolRow.tsx'
@@ -29,6 +30,7 @@ const VARIANT_ICONS: Record = {
 export function GenericToolCard({ toolName, block, cwd, openFile }: ToolRowOwnerProps) {
   const model = toolRowModel(toolName, block, cwd)
   const terminal = terminalCardModel(block, cwd)
+  const diff = diffCardModel(block)
   const singleFile = model.filePath !== undefined
   return (
     
-        : variant === 'code'
-          ? 
-          : 
{text}
)}
+        : diffBody !== null
+          ? 
+          : variant === 'code'
+            ? 
+            : 
{text}
)}
     
   )
 }
diff --git a/packages/client/ui-conversation/src/client/contract/diff-card-model.ts b/packages/client/ui-conversation/src/client/contract/diff-card-model.ts
new file mode 100644
index 0000000000..f02ccd5930
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/contract/diff-card-model.ts
@@ -0,0 +1,66 @@
+/**
+ * Pure derivation of the diff-card props from a frozen call slice: the
+ * `card:'diff'` render intent the write/edit tools declare arrives on the
+ * snapshot as `callView`/`resultView`, and this is the one place that turns
+ * that pair into what {@link DiffBlock} draws. Both conversation render sites
+ * (the chat tool row's expanded body and the details panel's Output section)
+ * call this, so the hunks they show are derived once.
+ * @module
+ */
+import type { DiffBlockProps } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { ToolCallBlock } from './tool-call-model.ts'
+
+/**
+ * Diff-body lines the chat row shows before collapsing the middle — half the
+ * primitive's own default, which the details panel keeps. A chat row is a
+ * summary surface inside the message flow: the flow must stay scannable across
+ * many calls, while the details panel is the single-call reading surface. The
+ * same split {@link CHAT_TERMINAL_MAX_LINES} draws for a terminal card, so the
+ * two card kinds cap a long body at the same place in the flow. A design
+ * constant of this UI's row geometry, not a deployment choice.
+ */
+export const CHAT_DIFF_MAX_LINES = 8
+
+/**
+ * The {@link DiffBlock} props this derivation owns. Picked off the primitive's
+ * props so the two stay in step; `maxLines`/`className` belong to each render
+ * site.
+ */
+export interface DiffCardModel {
+  /**
+   * The props {@link DiffBlock} draws. Held as a nested object so a render site
+   * spreads exactly the primitive's own surface and can never leak a
+   * neighbouring field into it.
+   */
+  card: Pick
+}
+
+/**
+ * Derive the diff-card props for a tool call, or null when this call is not a
+ * diff card and belongs on the generic path.
+ *
+ * The result side is authoritative once the call settles: the write/edit tools
+ * return the applied contextual hunks there (an edit's real before/after, a
+ * create's whole-file diff), which replace the call-time diff derived from the
+ * arguments alone. While the call is still running only the call side exists,
+ * so a running write/edit shows its intended change. Null is the documented
+ * generic-card default and covers every non-diff card — including a `card`
+ * value this UI version does not know, which arrives over the wire and cannot
+ * be trusted to be one of the compiled variants — and a settled call whose
+ * result view is generic (how write/edit keep their execution errors on the
+ * generic path).
+ * @param block - RunningToolCall or ToolResultNode off the snapshot caches.
+ * @returns the diff-card props, or null for the generic path.
+ */
+export function diffCardModel(block: ToolCallBlock): DiffCardModel | null {
+  if (!('kind' in block)) {
+    // Running: the call view may carry the intended diff; the result is absent.
+    const call = block.callView?.card === 'diff' ? block.callView : null
+    return call === null ? null : { card: { diffs: call.diffs } }
+  }
+  // Settled: the result view's applied hunks replace the call-time diff. A
+  // window that dropped the call head leaves only the result, which still
+  // renders — the result view carries the whole change.
+  const result = block.resultView?.card === 'diff' ? block.resultView : null
+  return result === null ? null : { card: { diffs: result.diffs } }
+}
diff --git a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
index 9fc5a04ff6..d09d3ea256 100644
--- a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
@@ -7,10 +7,11 @@
 // share the store seat exists for) and derives the call material from the
 // session snapshot — no data of its own.
 
-import { CodeBlock, TerminalBlock } from '@deepseek-ai/dsh-client-ui-primitives'
+import { CodeBlock, DiffBlock, TerminalBlock } from '@deepseek-ai/dsh-client-ui-primitives'
 import { shallowEqual } from '@deepseek-ai/dsh-client-runtime/client'
 import type { ConversationSnapshot, RunningToolCall, ToolResultNode } from '@deepseek-ai/dsh-client-runtime/client'
 import type { DetailsSlotProps } from '../contract/slots.ts'
+import { diffCardModel } from '../contract/diff-card-model.ts'
 import { terminalCardModel } from '../contract/terminal-card-model.ts'
 import type { ToolCallBlock } from '../contract/tool-call-model.ts'
 import css from './DetailsPanel.module.css'
@@ -127,8 +128,10 @@ export function DetailsPanel({ useSession, useSessions, sessionId, useStore, clo
  * The Output section's body for the selected call. A terminal-card call — a
  * shell command's call/result views — renders through the shared TerminalBlock
  * at the primitive's own full height allowance, so column-aligned output keeps
- * its alignment and scrolls sideways instead of folding. Every other call, and
- * a running call with no terminal card yet, keeps the flattened text form.
+ * its alignment and scrolls sideways instead of folding. A diff-card call — a
+ * write/edit's applied change — renders through the shared DiffBlock at the same
+ * full height. Every other call, and a running call with neither card yet, keeps
+ * the flattened text form.
  * @param props.material - the selected call's material from {@link materialFor}.
  * @param props.cwd - the session workspace root, resolving the terminal view's cwd.
  * @returns the Output section's body element.
@@ -147,6 +150,8 @@ function OutputBody({ material, cwd }: { material: CallMaterial; cwd: string | u
       
     )
   }
+  const diff = diffCardModel(material.block)
+  if (diff !== null) return 
   // A settled call always carries the result node the flattened form needs;
   // the running shape has no result to flatten.
   if (!('kind' in material.block)) return 
运行中…

diff --git a/packages/client/ui-conversation/src/client/toolviews/file-mutation-row.module.css b/packages/client/ui-conversation/src/client/toolviews/file-mutation-row.module.css
new file mode 100644
index 0000000000..b87103aa3a
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/toolviews/file-mutation-row.module.css
@@ -0,0 +1,119 @@
+/* File-mutation toolview: same geometry/tokens as ToolRow (figma
+   {Edit,Write} · path), plus the diff card the row stacks under its summary
+   line. Mirrors bash-sample.module.css, whose terminal card this replaces with
+   a diff card. */
+
+/* Summary line over the diff card; the summary row keeps its own 24px height,
+   so the card is a column around it rather than a change to it. */
+.card {
+  display: flex;
+  flex-direction: column;
+}
+
+/* Row indentation matches ToolRow's expanded bodies (16px leading + 6px gap),
+   and replaces the primitive's standalone vertical margin with the flow's. */
+.diff {
+  margin: 4px 0 4px 22px;
+}
+
+.root {
+  position: relative; /* sweep-glare overlay anchor */
+  overflow: hidden;
+  display: flex;
+  align-items: center;
+  height: 24px;
+  min-width: 0;
+}
+
+/* Running sweep glare — same deepsuite ShimmerText pattern as ToolRow. */
+.root[data-state='running']::after {
+  content: '';
+  position: absolute;
+  top: 0;
+  bottom: 0;
+  left: 0;
+  width: 300px;
+  background: linear-gradient(
+    90deg,
+    transparent 0%,
+    color-mix(in srgb, var(--dsw-alias-bg-base) 60%, transparent) 55%,
+    transparent 100%
+  );
+  animation: dsh-file-mutation-row-sweep 2.6s ease-out infinite;
+  pointer-events: none;
+}
+
+@keyframes dsh-file-mutation-row-sweep {
+  0% { left: -300px; }
+  90%, 100% { left: 100%; }
+}
+
+.leading {
+  flex: none;
+  width: 16px;
+  height: 16px;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  margin-right: 6px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.title {
+  flex: none;
+  font-size: 14px;
+  line-height: 24px;
+  color: var(--dsw-alias-label-secondary);
+}
+
+.sep {
+  flex: none;
+  width: 2px;
+  height: 2px;
+  border-radius: 1px;
+  margin: 0 8px;
+  background: var(--dsw-alias-label-caption);
+}
+
+.summary {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font-size: 14px;
+  line-height: 24px;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+/* File-tool path: same geometry as .summary; hover underline + pointer. */
+.fileLink {
+  flex: 1 1 auto;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  margin: 0;
+  padding: 0;
+  border: none;
+  background: none;
+  font: inherit;
+  text-align: left;
+  font-size: 14px;
+  line-height: 24px;
+  color: var(--dsw-alias-label-tertiary);
+  cursor: pointer;
+}
+
+.fileLink:hover {
+  text-decoration: underline;
+}
+
+.visuallyHidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  white-space: nowrap;
+}
diff --git a/packages/client/ui-conversation/src/client/toolviews/file-mutation-row.tsx b/packages/client/ui-conversation/src/client/toolviews/file-mutation-row.tsx
new file mode 100644
index 0000000000..0862eb4fd5
--- /dev/null
+++ b/packages/client/ui-conversation/src/client/toolviews/file-mutation-row.tsx
@@ -0,0 +1,97 @@
+// File-mutation toolview registrant: third-party posture over the keyed
+// toolview hole (ctx.slots.register + ToolRowProps only — never imports the
+// chat domain), registered under both `edit` and `write`. Product chrome
+// matches ToolRow (figma: {Edit,Write} · {path}).
+//
+// A write/edit call declares the diff render intent, so this row renders the
+// applied change through DiffBlock resident below its summary line — the same
+// posture BashRow gives a terminal card. The row has no expand control and is
+// not a details-panel target (tool rows stopped being one), so the diff body
+// is resident rather than expand-gated, and the card's own copy and expand
+// controls are the row's only interactions. CHAT_DIFF_MAX_LINES caps the body
+// against the message flow; the details panel keeps the block's full default.
+// The summary stays a path link (the file-tool interaction) that opens through
+// the host.
+
+import type { Context } from 'cordis'
+import { DiffBlock, IconEditOutline16, StateDot } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { ToolRowProps } from '../contract/slots.ts'
+import { CHAT_DIFF_MAX_LINES, diffCardModel } from '../contract/diff-card-model.ts'
+import { resolveToolPath, toolRowModel, type ToolRowState } from '../contract/tool-call-model.ts'
+import css from './file-mutation-row.module.css'
+
+function leadingFor(state: ToolRowState) {
+  switch (state) {
+    case 'error': return 
+    case 'stopped': return 
+    // Running keeps the icon — the row sweep carries the in-flight signal.
+    default: return 
+  }
+}
+
+/** Visually hidden status — StateDot is aria-hidden; AT needs a text label. */
+function stateStatus(state: ToolRowState): string | null {
+  switch (state) {
+    case 'running': return '运行中'
+    case 'error': return '失败'
+    case 'stopped': return '已停止'
+    default: return null
+  }
+}
+
+/**
+ * File-mutation row: icon + {Edit,Write} · {path} in the shared ToolRow chrome,
+ * with the applied diff resident below it. The summary is a path link (a file
+ * tool's interaction) resolved against the session cwd and opened through the
+ * host; the card's copy and expand controls are the row's only other actions.
+ */
+export function FileMutationRow({ toolName, block, cwd, openFile }: ToolRowProps) {
+  const model = toolRowModel(toolName, block, cwd)
+  const diff = diffCardModel(block)
+  const status = stateStatus(model.state)
+  const filePath = model.filePath
+  return (
+    

+      

+        {leadingFor(model.state)}
+        {status !== null && {status}}
+        {model.title}
+        
+        {filePath !== undefined ? (
+          
+        ) : (
+          {model.summary}
+        )}
+      

+      {diff !== null && (
+        
+      )}
+    

+  )
+}
+
+/**
+ * The file-mutation rows as a plain registrant plugin. `inject` carries the
+ * load-order seam: requiring the conversation service guarantees the chat entry
+ * (and with it the 'conversation.chat.toolview' declaration) is registered —
+ * ui-conversation's apply mounts the service after the chat entry.
+ */
+export const fileMutationToolview = {
+  name: 'file-mutation-toolview',
+  inject: ['slots', 'conversation'],
+  /**
+   * Register the file-mutation row into the chat view's keyed toolview hole
+   * under both mutation tool names.
+   * @param ctx - registrant context (disposal rides ctx.effect inside slots.register).
+   */
+  apply(ctx: Context): void {
+    ctx.slots.register({ name: 'conversation.chat.toolview', key: 'edit' }, FileMutationRow)
+    ctx.slots.register({ name: 'conversation.chat.toolview', key: 'write' }, FileMutationRow)
+  },
+}
diff --git a/packages/client/ui-conversation/tests/diff-card.spec.tsx b/packages/client/ui-conversation/tests/diff-card.spec.tsx
new file mode 100644
index 0000000000..77b762c38b
--- /dev/null
+++ b/packages/client/ui-conversation/tests/diff-card.spec.tsx
@@ -0,0 +1,248 @@
+// @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'
+import { bindSnapshotSelector } from '@deepseek-ai/dsh-client-web-react'
+import { createSnapshotStore } from '@deepseek-ai/dsh-client-runtime/client'
+import type {
+  ConversationSnapshot, RunningToolCall, SessionId, SessionListState, ToolResultNode, WorkspaceListState,
+} from '@deepseek-ai/dsh-client-runtime/client'
+import type { ToolCallView, ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
+import type { SelectionTarget, ToolRowOwnerProps, ToolRowProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { CHAT_DIFF_MAX_LINES, diffCardModel } from '../src/client/contract/diff-card-model.ts'
+import { createChatStore } from '../src/client/stores.ts'
+import { GenericToolCard } from '../src/client/chat/GenericToolCard.tsx'
+import { DetailsPanel } from '../src/client/skeleton/DetailsPanel.tsx'
+import { FileMutationRow } from '../src/client/toolviews/file-mutation-row.tsx'
+
+afterEach(cleanup)
+
+const SID = 's1' as SessionId
+
+const ARGS = '{"file_path":"notes/demo.txt","old_string":"hello","new_string":"hello fixture"}'
+
+/** The edit tool's own call view (a call-time diff derived from the arguments). */
+const callDiff = (over?: Partial>): ToolCallView => ({
+  card: 'diff', title: 'Edit notes/demo.txt',
+  diffs: [{ path: 'notes/demo.txt', oldText: 'hello', newText: 'hello fixture' }], ...over,
+})
+
+/** The edit tool's own result view (the applied hunk diff). */
+const resultDiff = (over?: Partial>): ToolResultView => ({
+  card: 'diff', title: 'Edit notes/demo.txt',
+  diffs: [{ path: 'notes/demo.txt', oldText: 'hello', newText: 'hello fixture' }], ...over,
+})
+
+const running = (over?: Partial): RunningToolCall => ({
+  callId: 'c1', name: 'edit', argsRaw: ARGS,
+  turn: 1, step: 1, time: 1_000, callView: callDiff(), ...over,
+})
+
+const settled = (over?: Partial): ToolResultNode => ({
+  kind: 'tool-result', seq: 10, time: 2_000, callId: 'c1',
+  call: { name: 'edit', argsRaw: ARGS },
+  callTime: 1_000,
+  content: [{ type: 'text', text: 'The file notes/demo.txt has been updated successfully.' }], isError: false,
+  callView: callDiff(), resultView: resultDiff(), ...over,
+})
+
+describe('diffCardModel', () => {
+  it('derives a running card from the call view alone', () => {
+    expect(diffCardModel(running())).toEqual({
+      card: { diffs: [{ path: 'notes/demo.txt', oldText: 'hello', newText: 'hello fixture' }] },
+    })
+  })
+
+  it('derives a settled card from the result view, which replaces the call-time diff', () => {
+    // The applied hunks (result) win over the args-derived call diff.
+    expect(diffCardModel(settled({
+      resultView: resultDiff({ diffs: [{ path: 'notes/demo.txt', oldText: 'a', newText: 'b' }] }),
+    }))).toEqual({
+      card: { diffs: [{ path: 'notes/demo.txt', oldText: 'a', newText: 'b' }] },
+    })
+  })
+
+  it('renders a settled diff even when the window dropped the call head', () => {
+    // A truncated call carries only the result view, which holds the whole change.
+    expect(diffCardModel(settled({ call: null, callView: null }))?.card.diffs).toHaveLength(1)
+  })
+
+  it('returns null for every non-diff call: no views, generic views, unknown cards', () => {
+    expect(diffCardModel(running({ callView: null }))).toBeNull()
+    expect(diffCardModel(settled({ callView: null, resultView: null }))).toBeNull()
+    expect(diffCardModel(running({ callView: { card: 'generic', title: 'read x' } }))).toBeNull()
+    // A generic result settles a diff call on the generic path (write/edit's
+    // own execution-error arm).
+    expect(diffCardModel(settled({ resultView: { card: 'generic' } }))).toBeNull()
+    // A card tag this UI version does not know arrives over the wire; the
+    // documented generic-card default takes it, not a crash.
+    const future = { card: 'chart', title: 'plot' } as unknown as ToolCallView
+    expect(diffCardModel(running({ callView: future }))).toBeNull()
+    expect(diffCardModel(settled({
+      callView: future, resultView: { card: 'chart' } as unknown as ToolResultView,
+    }))).toBeNull()
+  })
+})
+
+describe('chat row diff body', () => {
+  const ownerProps = (block: RunningToolCall | ToolResultNode): ToolRowOwnerProps => ({
+    callId: 'c1', toolName: 'edit', block, openFile: vi.fn(),
+  })
+
+  it('the expanded body is the applied diff, capped tighter than the panel', () => {
+    expect(CHAT_DIFF_MAX_LINES).toBeLessThan(16)
+    const view = render()
+    // Collapsed: the summary row (path) only, no diff body.
+    expect(view.queryByText('hello fixture')).toBeNull()
+    // The path link is not the expand control; the leading toggle is.
+    fireEvent.click(view.container.querySelector('button[aria-expanded]')!)
+    expect(view.container.querySelector('[data-diff]')).not.toBeNull()
+    expect(view.getByText('hello fixture')).toBeTruthy()
+  })
+
+  it('a running diff call expands to its intended change', () => {
+    const view = render()
+    fireEvent.click(view.container.querySelector('button[aria-expanded]')!)
+    expect(view.container.querySelector('[data-diff]')).not.toBeNull()
+  })
+
+  it('a non-diff call keeps the args-JSON text body', () => {
+    // A non-file tool name so the row is not single-file (no path link), and its
+    // args body is the fallback the diff card must not have replaced.
+    const view = render()
+    fireEvent.click(view.container.querySelector('button[aria-expanded]')!)
+    expect(view.container.querySelector('[data-diff]')).toBeNull()
+    expect(view.getByText(/"foo"/)).toBeTruthy()
+  })
+})
+
+describe('FileMutationRow diff card', () => {
+  const list = () => createSnapshotStore({
+    ids: [SID],
+    byId: { [SID]: { id: SID, displayTitle: 'r', running: false, blank: false, waitingApproval: false, updatedAt: 0, cwd: '/w/app' } },
+    current: SID,
+    phase: 'ready',
+  })
+
+  const rowProps = (block: RunningToolCall | ToolResultNode, toolName = 'edit'): ToolRowProps => ({
+    callId: 'c1', toolName, block, openFile: vi.fn(), cwd: '/w/app',
+    sessionId: SID, useSessions: bindSnapshotSelector(list()),
+  } as unknown as ToolRowProps)
+
+  it('renders the applied diff under the summary row, without an expand gesture', () => {
+    const view = render()
+    // The diff card is resident (no expand toggle needed).
+    expect(view.container.querySelector('[data-diff]')).not.toBeNull()
+    expect(view.getByText('hello fixture')).toBeTruthy()
+    expect(view.getByText('复制')).toBeTruthy()
+  })
+
+  it('the summary is a path link that opens through the host, cwd-resolved', () => {
+    const openFile = vi.fn()
+    const view = render()
+    fireEvent.click(view.getByRole('button', { name: 'notes/demo.txt' }))
+    expect(openFile).toHaveBeenCalledWith('/w/app/notes/demo.txt')
+  })
+
+  it('registers under write too, rendering a create as an added-only diff', () => {
+    const writeArgs = '{"file_path":"notes/new.txt","content":"hello fixture\\n"}'
+    const view = render()
+    expect(view.getByText('└ +1 -0 · 1 file')).toBeTruthy()
+  })
+
+  it('reflects the run state on its leading slot', () => {
+    const runningView = render()
+    expect(runningView.container.querySelector('[data-state="running"]')).not.toBeNull()
+    cleanup()
+    const errorView = render()
+    expect(errorView.container.querySelector('[data-state="error"]')).not.toBeNull()
+  })
+
+  it('a mutation call with no diff view renders the summary row alone', () => {
+    const view = render()
+    expect(view.container.querySelector('[data-diff]')).toBeNull()
+  })
+})
+
+describe('DetailsPanel diff Output section', () => {
+  function mount(snapshot: ConversationSnapshot, selection: SelectionTarget | null, cwd?: string) {
+    localStorage.clear()
+    const chat = createChatStore().create()
+    if (selection !== null) chat.actions.select(selection)
+    const sessions = createSnapshotStore(cwd === undefined
+      ? { ids: [], byId: {}, current: undefined, phase: 'ready' }
+      : {
+        ids: [SID],
+        byId: { [SID]: { id: SID, displayTitle: 'r', running: false, blank: false, waitingApproval: false, updatedAt: 0, cwd } },
+        current: SID,
+        phase: 'ready',
+      })
+    const workspaces = createSnapshotStore({
+      items: [], state: 'idle', phase: 'ready', error: null,
+      baselinesReady: true, recentWorkspaceId: undefined,
+    })
+    return render(
+       snapshot, subscribe: () => () => {} })}
+        useSessions={bindSnapshotSelector(sessions)}
+        useWorkspaces={bindSnapshotSelector(workspaces)}
+        useInput={(() => { throw new Error('unused') })}
+        inputActions={{ setDraft: () => {}, submit: () => {} }}
+        useProjection={(() => undefined)}
+        useStore={bindSnapshotSelector(chat)}
+        actions={chat.actions}
+        closeDetails={vi.fn()}
+      />,
+    )
+  }
+
+  function snapshot(over: Partial = {}): ConversationSnapshot {
+    return {
+      sessionId: SID, nodes: [], foldDegraded: false, partial: null, runningCalls: [], codeDispatches: new Map(),
+      pending: [], queue: [], running: false, composerPhase: 'active', removed: false,
+      openState: 'open', openError: null, hasMore: false, loadingOlder: false,
+      promptError: null, blank: false, lastAgentError: null, ...over,
+    }
+  }
+
+  const target: SelectionTarget = { turnSeq: 10, callId: 'c1', toolName: 'edit' }
+
+  it('renders the applied diff at full height, keeping the JSON Input section', () => {
+    const view = mount(snapshot({ nodes: [settled()] }), target)
+    expect(view.getByText(/"file_path"/)).toBeTruthy()
+    expect(view.container.querySelector('[data-diff]')).not.toBeNull()
+    expect(view.getByText('hello fixture')).toBeTruthy()
+  })
+
+  it('a running diff call renders its intended change, not the 运行中… placeholder', () => {
+    const view = mount(snapshot({ runningCalls: [running()] }), target)
+    expect(view.container.querySelector('[data-diff]')).not.toBeNull()
+    expect(view.queryByText('运行中…')).toBeNull()
+  })
+
+  it('a non-diff result keeps the flattened pre', () => {
+    const view = mount(snapshot({
+      nodes: [settled({
+        callView: null, resultView: null,
+        content: [{ type: 'text', text: 'permission denied' }],
+      })],
+    }), target)
+    expect(view.container.querySelector('[data-diff]')).toBeNull()
+    expect(view.getByText('Output').closest('section')?.querySelector('pre')?.textContent).toBe('permission denied')
+  })
+})
diff --git a/packages/client/ui-primitives/README.i18n.yaml b/packages/client/ui-primitives/README.i18n.yaml
index b5e4b5c078..ba6010f6c7 100644
--- a/packages/client/ui-primitives/README.i18n.yaml
+++ b/packages/client/ui-primitives/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/client/ui-primitives/README.md
-README.md: 0ef3c20f848b3d331c007911d0837f11cd72c024
-README.zh.md: af94551bfb9e12dbadcef6a96a54f9bf7ea71299
+README.md: 58c8ddcf0343216979ffdae7749c5368e26c45e5
+README.zh.md: 2d775f6591d3e2f5305cd517a38effb2cf25becf
diff --git a/packages/client/ui-primitives/README.md b/packages/client/ui-primitives/README.md
index 0ef3c20f84..58c8ddcf03 100644
--- a/packages/client/ui-primitives/README.md
+++ b/packages/client/ui-primitives/README.md
@@ -2,7 +2,7 @@
 
 English | [中文](README.zh.md)
 
-Pure React atoms (zero cordis): StateDot, ic_ds_* icons, Button/Pill/Menu/Modal/Input, the markdown family (MessageText/MarkdownText/JsonBlock), the read-only JsonTree inspector, the `useAnchoredMaxHeight` hook that clamps a bottom-anchored overlay to the viewport space above its anchor (re-measured on resize, scroll, and a caller-supplied dependency), and TerminalBlock. Contract: api-contracts v3 §8.
+Pure React atoms (zero cordis): StateDot, ic_ds_* icons, Button/Pill/Menu/Modal/Input, the markdown family (MessageText/MarkdownText/JsonBlock), the read-only JsonTree inspector, the `useAnchoredMaxHeight` hook that clamps a bottom-anchored overlay to the viewport space above its anchor (re-measured on resize, scroll, and a caller-supplied dependency), TerminalBlock, and DiffBlock. Contract: api-contracts v3 §8.
 
 ## Markdown rendering
 
@@ -12,6 +12,10 @@ Pure React atoms (zero cordis): StateDot, ic_ds_* icons, Button/Pill/Menu/Modal/
 
 `TerminalBlock` renders a shell command as a terminal surface: one prompt row per line of the command (the shortened `cwd` label on the first row only, since the view knows one working directory and a `cd` moves later lines elsewhere, then that line), the command's output, a status pill for a non-zero exit code or a terminating signal, and a copy control that writes the raw `output` prop. A run-state `StateDot` marks the call once, on the first row, out of flow in a gutter the card reserves as its own left padding, so the dot sits inside the card box yet left of the prompt text. It reaches three of `StateDot`'s states — the chase while `running`, red for the same exit status that renders the pill, green otherwise — so a card states whether its command is still running rather than leaving that to be inferred from the presence of output; it carries one visually hidden text label because `StateDot` is `aria-hidden`. One dot regardless of line count is deliberate: the exit status is the whole call's, so a dot per line would claim a per-line outcome the view does not carry. Command text is `white-space: pre`, so repeated spaces, tabs, and an indented continuation render verbatim while the row stays single-line and ellipsizes. ANSI escape sequences are parsed with the `anser` runtime dependency into React spans; cursor movements replay into a per-line column buffer before inert controls are stripped, since carriage return and backspace only MOVE the cursor: `100%` + CR + `OK` alone shows `OK0%`, while the `\x1b[K` a spinner writes with its redraw erases the tail so `100%\r\x1b[KOK` shows `OK`. Erase-in-line is honored in all three parameter forms, the cursor advances by terminal columns (8-column tab stops, two for emoji and CJK, none for a combining mark), and SGR state is normalized per cell as a terminal stores it, threading across lines and closing at the state the line ended in; basic-16 foreground colors map onto `--dsw-*` tokens, while 256-palette and truecolor values pass through as literal rgb. Output keeps `white-space: pre` with horizontal scrolling, so column-aligned output holds its alignment instead of soft-wrapping, and collapses to a head slice plus a tail slice past `maxLines` (default 16, the TUI transcript's split arithmetic) behind an expand button. Rationale: [the web terminal card note](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md).
 
+## Diff rendering
+
+`DiffBlock` renders a file mutation as an inline diff surface: one bold path header per file, the removed lines (`- `, error token) above the added lines (`+ `, success token), a `⋯` gap before a same-file second hunk, and a dim `└ +A -R · N file(s)` footer. Lines are `white-space: pre` with horizontal scrolling, so a source line holds its indentation instead of soft-wrapping, and the body collapses to a head slice plus a tail slice past `maxLines` (default 16, `TerminalBlock`'s split arithmetic) behind an expand button. A create (`oldText: null`) has no removed side. The copy control writes the prefixed diff text (path headers, `- `/`+ ` lines, the gap) so a multi-file copy stays attributable, and floats in the top-right corner rather than on a banner row of its own. Geometry mirrors `CodeBlock`/`TerminalBlock`. The `+`/`-` block form mirrors the TUI transcript's diff card so a diff reads the same across front ends. Rationale: [the web diff card note](../../../.agents/notes/implemented/feature/2026-07-30-web-diff-card.md).
+
 ## Model Experience
 
 None, as the package renders pure React atoms in the browser; nothing here reaches a model request.
diff --git a/packages/client/ui-primitives/README.zh.md b/packages/client/ui-primitives/README.zh.md
index af94551bfb..2d775f6591 100644
--- a/packages/client/ui-primitives/README.zh.md
+++ b/packages/client/ui-primitives/README.zh.md
@@ -2,7 +2,7 @@
 
 [English](README.md) | 中文
 
-纯 React 原子组件（零 cordis）：StateDot、ic_ds_* 图标、Button/Pill/Menu/Modal/Input、markdown 家族（MessageText/MarkdownText/JsonBlock）、只读 JsonTree 检查器、`useAnchoredMaxHeight` hook（把底部锚定的浮层高度收敛到锚点上方的视口空间，并在 resize、scroll 与调用方提供的依赖变化时重新测量），以及 TerminalBlock。契约：api-contracts v3 §8。
+纯 React 原子组件（零 cordis）：StateDot、ic_ds_* 图标、Button/Pill/Menu/Modal/Input、markdown 家族（MessageText/MarkdownText/JsonBlock）、只读 JsonTree 检查器、`useAnchoredMaxHeight` hook（把底部锚定的浮层高度收敛到锚点上方的视口空间，并在 resize、scroll 与调用方提供的依赖变化时重新测量）、TerminalBlock，以及 DiffBlock。契约：api-contracts v3 §8。
 
 ## Markdown 渲染
 
@@ -11,6 +11,10 @@
 
 `TerminalBlock` 将一条 shell 命令渲染为终端表层：命令的每一行各占一个提示行（缩短后的 `cwd` 标签只出现在第一行，因为视图只知道一个工作目录，而一个 `cd` 就会让后面的行去到别处，标签之后是该行）、命令输出、非零退出码或终止信号对应的状态胶囊，以及写入原始 `output` prop 的复制控件。一枚运行状态 `StateDot` 为整次调用标记一次，位于第一行，以脱离文档流的方式落在卡片以自身左内边距预留的落区中，因此它位于卡片盒之内、提示文字之左。它用到 `StateDot` 的三种状态——`running` 期间为追逐动画，与渲染状态胶囊相同的退出状态为红色，其余为绿色——因此卡片直接陈述其命令是否仍在运行，而不是让人从有无输出中推断；由于 `StateDot` 是 `aria-hidden`，它携带一处视觉隐藏的文本标签。无论多少行都只有一枚状态点是有意为之：退出状态属于整次调用，因此每行一枚就会声称一个视图并不携带的逐行结果。命令文本使用 `white-space: pre`，因此重复空格、制表符与缩进续行都原样呈现，同时该行仍保持单行并以省略号截断。ANSI 转义序列通过运行时依赖 `anser` 解析为 React span；光标移动在剥除无显示意义控制符之前先重放进逐行的列缓冲，因为回车与退格**只移动**光标：单是 `100%` 加回车再加 `OK` 显示为 `OK0%`，而 spinner 随重绘写出的 `\x1b[K` 会擦掉尾巴，因此 `100%\r\x1b[KOK` 显示为 `OK`。行内擦除的三种参数形式都被遵循，光标按终端列推进（8 列制表位；emoji 与 CJK 占两列；组合标记不占列），SGR 状态按单元格归一化存储，与终端一致，并跨行延续、在行结束时的状态处收束；基础 16 色前景色映射到 `--dsw-*` token，而 256 色板与真彩色值按字面 rgb 透传。输出保持 `white-space: pre` 并支持横向滚动，因此按列对齐的输出保留其对齐而不会软换行；超过 `maxLines`（默认 16，与 TUI 转录相同的切分算法）时折叠为头部切片加尾部切片，由展开按钮控制。原理：[Web 终端卡片笔记](../../../.agents/notes/implemented/feature/2026-07-28-web-terminal-card.md)。
 
+## Diff 渲染
+
+`DiffBlock` 将一次文件改动渲染为内联 diff 表层：每个文件一个粗体路径头、删除行（`- `，error token）在新增行（`+ `，success token）之上、同文件第二个 hunk 前一个 `⋯` gap，以及暗色 `└ +A -R · N file(s)` 页脚。各行使用 `white-space: pre` 并横向滚动，因此源码行保留其缩进而不软换行；超过 `maxLines`（默认 16，与 `TerminalBlock` 相同的切分算法）时折叠为头部切片加尾部切片，由展开按钮控制。新建（`oldText: null`）没有删除侧。复制控件写入带前缀的 diff 文本（路径头、`- `/`+ ` 行、gap），使多文件复制保持可归属，并浮在右上角而非占据自己的 banner 行。几何镜像 `CodeBlock`/`TerminalBlock`。`+`/`-` 块形式镜像 TUI 转录的 diff 卡片，使 diff 在两个前端读起来一致。原理：[Web diff 卡片笔记](../../../.agents/notes/implemented/feature/2026-07-30-web-diff-card.md)。
+
 ## 模型体验
 
 无。该包（package）在浏览器中渲染纯 React 原子组件；这里没有任何内容进入模型请求。
diff --git a/packages/client/ui-primitives/src/DiffBlock.module.css b/packages/client/ui-primitives/src/DiffBlock.module.css
new file mode 100644
index 0000000000..8794dbb87e
--- /dev/null
+++ b/packages/client/ui-primitives/src/DiffBlock.module.css
@@ -0,0 +1,103 @@
+/* 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;
+
+  position: relative;
+  margin: 16px 0;
+  color: var(--dsw-alias-label-primary);
+  background: var(--dsw-alias-markdown-code-block);
+  border-radius: var(--dsl-diff-radius);
+}
+
+/* The copy control floats in the top-right corner over the body, so the card
+   has no empty banner row above its first diff line (the TUI diff card has no
+   banner either — only the footer). The block is position: relative, so this
+   anchors to the card. */
+.copyButton {
+  position: absolute;
+  top: 8px;
+  right: 12px;
+  z-index: 1;
+  background-color: transparent;
+  border: none;
+  padding: 0;
+  margin: 0;
+  color: var(--dsw-alias-label-secondary);
+  cursor: pointer;
+  font: var(--dsw-font-xs-13);
+}
+
+.body {
+  padding: 12px 14px;
+  font: var(--dsw-font-markdown-code-block);
+  overflow-x: auto;
+  overflow-y: hidden;
+}
+
+/* No wrapping, no word-break: a diff is read by its indentation. */
+.line {
+  min-height: var(--dsl-diff-line-height);
+  white-space: pre;
+}
+
+/* A file header: the path in the primary tone, set apart by weight. */
+.path {
+  color: var(--dsw-alias-label-primary);
+  font-weight: 600;
+}
+
+/* A same-file second hunk's separator (a scattered edit), in the dim tone. */
+.gap {
+  color: var(--dsw-alias-label-tertiary);
+}
+
+/* The diff's own meaning-carrying colors: removed on the error token, added on
+   the success token. A `- `/`+ ` prefix is drawn here so a copied line and the
+   shown line agree, and so the sign reads without relying on color alone. */
+.del::before {
+  content: '- ';
+  color: var(--dsw-alias-state-error-primary);
+}
+
+.del {
+  color: var(--dsw-alias-state-error-primary);
+}
+
+.add::before {
+  content: '+ ';
+  color: var(--dsw-alias-state-success-primary);
+}
+
+.add {
+  color: var(--dsw-alias-state-success-primary);
+}
+
+.expand {
+  display: block;
+  width: 100%;
+  padding: 0;
+  border: none;
+  background-color: transparent;
+  color: var(--dsw-alias-label-tertiary);
+  cursor: pointer;
+  font: inherit;
+  text-align: left;
+}
+
+.expand:hover {
+  color: var(--dsw-alias-label-secondary);
+}
+
+/* The change summary, dim under the body: `└ +A -R · N file(s)`, the same
+   footer the TUI transcript's diff card draws. */
+.footer {
+  padding: 0 14px 12px;
+  font: var(--dsw-font-markdown-code-block);
+  color: var(--dsw-alias-label-tertiary);
+}
diff --git a/packages/client/ui-primitives/src/DiffBlock.tsx b/packages/client/ui-primitives/src/DiffBlock.tsx
new file mode 100644
index 0000000000..ab1700b7b5
--- /dev/null
+++ b/packages/client/ui-primitives/src/DiffBlock.tsx
@@ -0,0 +1,171 @@
+// 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. The +/- block form mirrors
+// the TUI transcript's diff card (packages/ui/tui: diffLines) so a diff reads
+// the same across front ends: the removed side is the old text in full, the
+// added side the new text in full. 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.
+ */
+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).
+ */
+export interface DiffHunk {
+  /** The changed file's path (as the tool operated on it; the bridge relativizes it). */
+  path: string
+  /** Prior content, or `null` for a new file / an overwrite (nothing on the removed side). */
+  oldText: string | null
+  /** Content after the change (the added side). */
+  newText: string
+}
+
+export interface DiffBlockProps {
+  /** One entry per applied hunk, in file order; empty renders nothing. */
+  diffs: DiffHunk[]
+  /** Height cap in body lines before the middle collapses (default {@link DEFAULT_DIFF_MAX_LINES}). */
+  maxLines?: number | undefined
+  /** Extra class merged onto the wrapper (callers position; this component draws). */
+  className?: string | undefined
+}
+
+/** A single rendered body line and its role, so the height cap slices a flat list. */
+interface DiffRow {
+  kind: 'path' | 'del' | 'add' | 'gap'
+  text: string
+}
+
+/** The dim class per row kind (path/gap chrome vs the diff's own +/- colors). */
+const ROW_CLASS: Record = {
+  path: css.path,
+  del: css.del,
+  add: css.add,
+  gap: css.gap,
+}
+
+/**
+ * Flatten the hunks into the body's rows plus the footer counts. A path header
+ * opens each new file; a same-file second hunk (a scattered edit) opens with a
+ * `⋯` gap instead of repeating the path. Every old-side line counts toward
+ * `removed` and every new-side line toward `added`, the same per-side line count
+ * the TUI footer draws, so the two front ends agree on a change's size.
+ * @param diffs - the hunks to render.
+ * @returns the body rows, the +/- totals, and the distinct-file count.
+ */
+function buildRows(diffs: DiffHunk[]): { rows: DiffRow[]; added: number; removed: number; files: number } {
+  const rows: DiffRow[] = []
+  const paths = new Set()
+  let added = 0
+  let removed = 0
+  let prevPath: string | undefined
+  for (const diff of diffs) {
+    paths.add(diff.path)
+    if (diff.path !== prevPath) rows.push({ kind: 'path', text: diff.path })
+    else rows.push({ kind: 'gap', text: '⋯' })
+    prevPath = diff.path
+    if (diff.oldText !== null) {
+      for (const line of diff.oldText.split('\n')) {
+        rows.push({ kind: 'del', text: line })
+        removed++
+      }
+    }
+    for (const line of diff.newText.split('\n')) {
+      rows.push({ kind: 'add', text: line })
+      added++
+    }
+  }
+  return { rows, added, removed, files: paths.size }
+}
+
+/**
+ * The diff text a reader copies: each row's `-`/`+`/path/gap prefix and its
+ * content, exactly what the card shows. The removed and added blocks are the
+ * change; the path headers keep a multi-file copy attributable.
+ * @param rows - the flattened body rows.
+ * @returns the diff as plain text.
+ */
+function copyText(rows: DiffRow[]): string {
+  return rows.map((row) => {
+    switch (row.kind) {
+      case 'del': return `- ${row.text}`
+      case 'add': return `+ ${row.text}`
+      case 'gap': return row.text
+      default: return row.text
+    }
+  }).join('\n')
+}
+
+/**
+ * Render a file mutation as an inline diff surface.
+ * @param props - see {@link DiffBlockProps}.
+ * @returns the diff block element.
+ */
+export function DiffBlock({ diffs, maxLines = DEFAULT_DIFF_MAX_LINES, className }: DiffBlockProps) {
+  const { rows, added, removed, files } = useMemo(() => buildRows(diffs), [diffs])
+  const [expanded, setExpanded] = useState(false)
+  const [copied, setCopied] = useState(false)
+
+  const onCopy = useCallback(() => {
+    if (copied) return
+    void writeClipboard(copyText(rows)).then((ok) => {
+      if (!ok) return
+      setCopied(true)
+      window.setTimeout(() => { setCopied(false) }, 1000)
+    })
+  }, [copied, rows])
+
+  const onToggle = useCallback(() => { setExpanded(value => !value) }, [])
+
+  if (rows.length === 0) return null
+
+  const hidden = rows.length - maxLines
+  const capped = hidden > 0 && !expanded
+  // Same split arithmetic as TerminalBlock and the TUI transcript's collapsed
+  // card, so a body's head and tail slices agree across the front ends.
+  const headLines = Math.ceil(maxLines / 2)
+  const tailLines = maxLines - headLines
+  const head = capped ? rows.slice(0, headLines) : rows
+  const tail = capped ? rows.slice(rows.length - tailLines) : []
+
+  return (
+    

+      
+      

+        {head.map((row, index) => (
+          
{row.text}

+        ))}
+        {hidden > 0 && (
+          
+        )}
+        {tail.map((row, index) => (
+          
{row.text}

+        ))}
+      

+      
└ +{added} -{removed} · {files} file{files === 1 ? '' : 's'}

+    

+  )
+}
diff --git a/packages/client/ui-primitives/src/index.ts b/packages/client/ui-primitives/src/index.ts
index aa674f7a1a..fc0d08b76e 100644
--- a/packages/client/ui-primitives/src/index.ts
+++ b/packages/client/ui-primitives/src/index.ts
@@ -22,6 +22,8 @@ export { JsonTree } from './JsonTree.tsx'
 export type { JsonTreeProps } from './JsonTree.tsx'
 export { TerminalBlock, DEFAULT_TERMINAL_MAX_LINES } from './TerminalBlock.tsx'
 export type { TerminalBlockProps } from './TerminalBlock.tsx'
+export { DiffBlock, DEFAULT_DIFF_MAX_LINES } from './DiffBlock.tsx'
+export type { DiffBlockProps, DiffHunk } from './DiffBlock.tsx'
 export { CodeBlock } from './markdown/CodeBlock.tsx'
 export { JsonBlock } from './markdown/JsonBlock.tsx'
 export { MarkdownText } from './markdown/MarkdownText.tsx'
diff --git a/packages/client/ui-primitives/tests/diff-block.spec.tsx b/packages/client/ui-primitives/tests/diff-block.spec.tsx
new file mode 100644
index 0000000000..d732a13315
--- /dev/null
+++ b/packages/client/ui-primitives/tests/diff-block.spec.tsx
@@ -0,0 +1,162 @@
+// @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 seam), 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'
+import { DEFAULT_DIFF_MAX_LINES, DiffBlock, type DiffHunk } from '../src/index.ts'
+
+afterEach(cleanup)
+
+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')
+}
+
+describe('DiffBlock structure', () => {
+  it('renders a create as a path header and an added block (no removed side)', () => {
+    const diffs: DiffHunk[] = [{ path: 'notes/new.txt', oldText: null, newText: 'hello\nworld' }]
+    const { container } = render()
+    expect(screen.getByText('notes/new.txt')).toBeTruthy()
+    // No removed rows: both change lines are added.
+    expect(changeRows(container)).toEqual(['hello', 'world'])
+    expect(container.querySelectorAll('[class*="_del_"]').length).toBe(0)
+    expect(container.querySelectorAll('[class*="_add_"]').length).toBe(2)
+  })
+
+  it('renders an edit as a removed block above an added block', () => {
+    const diffs: DiffHunk[] = [{ path: 'a.ts', oldText: 'old', newText: 'new' }]
+    const { container } = render()
+    expect(container.querySelectorAll('[class*="_del_"]').length).toBe(1)
+    expect(container.querySelectorAll('[class*="_add_"]').length).toBe(1)
+    expect(changeRows(container)).toEqual(['old', 'new'])
+  })
+
+  it('opens a same-file second hunk with a gap instead of repeating the path', () => {
+    const diffs: DiffHunk[] = [
+      { path: 'a.ts', oldText: 'x', newText: 'y' },
+      { path: 'a.ts', oldText: 'p', newText: 'q' },
+    ]
+    const { container } = render()
+    // One path header, one gap row.
+    expect(container.querySelectorAll('[class*="_path_"]').length).toBe(1)
+    expect(container.querySelectorAll('[class*="_gap_"]').length).toBe(1)
+  })
+
+  it('opens a new file with its own path header', () => {
+    const diffs: DiffHunk[] = [
+      { path: 'a.ts', oldText: 'x', newText: 'y' },
+      { path: 'b.ts', oldText: 'p', newText: 'q' },
+    ]
+    const { container } = render()
+    expect(container.querySelectorAll('[class*="_path_"]').length).toBe(2)
+    expect(container.querySelectorAll('[class*="_gap_"]').length).toBe(0)
+  })
+
+  it('renders nothing for empty diffs', () => {
+    const { container } = render()
+    expect(container.firstChild).toBeNull()
+  })
+})
+
+describe('DiffBlock footer', () => {
+  it('counts added and removed lines and one file', () => {
+    const diffs: DiffHunk[] = [{ path: 'a.ts', oldText: 'a\nb', newText: 'c' }]
+    render()
+    expect(screen.getByText('└ +1 -2 · 1 file')).toBeTruthy()
+  })
+
+  it('pluralizes the distinct-file count', () => {
+    const diffs: DiffHunk[] = [
+      { path: 'a.ts', oldText: null, newText: 'x' },
+      { path: 'b.ts', oldText: null, newText: 'y' },
+    ]
+    render()
+    expect(screen.getByText('└ +2 -0 · 2 files')).toBeTruthy()
+  })
+})
+
+describe('DiffBlock height cap', () => {
+  it('shows head and tail with an expand control past the cap, then all lines expanded', () => {
+    // One added line over the default cap forces the collapse.
+    const diffs: DiffHunk[] = [{ path: 'a.ts', oldText: null, newText: added(DEFAULT_DIFF_MAX_LINES) }]
+    // The path header counts as a row, so a body of maxLines added lines plus
+    // the header is one over the cap.
+    const { container } = render()
+    const toggle = screen.getByRole('button', { name: /展开其余/ })
+    expect(toggle.getAttribute('aria-expanded')).toBe('false')
+    // Collapsed shows fewer rows than the full body.
+    const collapsedCount = bodyRows(container).length
+    expect(collapsedCount).toBeLessThan(DEFAULT_DIFF_MAX_LINES + 1)
+    fireEvent.click(toggle)
+    expect(screen.getByRole('button', { name: '收起差异' }).getAttribute('aria-expanded')).toBe('true')
+    expect(bodyRows(container).length).toBeGreaterThan(collapsedCount)
+  })
+
+  it('shows no expand control at or under the cap', () => {
+    const diffs: DiffHunk[] = [{ path: 'a.ts', oldText: null, newText: added(4) }]
+    render()
+    expect(screen.queryByRole('button', { name: /展开其余|收起差异/ })).toBeNull()
+  })
+})
+
+describe('DiffBlock copy', () => {
+  it('copies the prefixed diff text and flips the label on success', async () => {
+    vi.useFakeTimers()
+    const writeText = vi.fn().mockResolvedValue(undefined)
+    Object.defineProperty(navigator, 'clipboard', { configurable: true, value: { writeText } })
+    const diffs: DiffHunk[] = [
+      { path: 'a.ts', oldText: 'old', newText: 'new' },
+      { path: 'a.ts', oldText: 'p', newText: 'q' },
+    ]
+    render()
+    const copy = screen.getByRole('button', { name: '复制' })
+    await act(async () => { fireEvent.click(copy) })
+    // Path header, del/add prefixes, and the same-file gap all reach the clipboard.
+    expect(writeText).toHaveBeenCalledWith('a.ts\n- old\n+ new\n⋯\n- p\n+ q')
+    expect(screen.getByRole('button', { name: '复制成功' })).toBeTruthy()
+    await act(async () => { await vi.advanceTimersByTimeAsync(1000) })
+    expect(screen.getByRole('button', { name: '复制' })).toBeTruthy()
+  })
+
+  it('keeps the label on a refused clipboard write', async () => {
+    Object.defineProperty(navigator, 'clipboard', {
+      configurable: true,
+      value: { writeText: vi.fn().mockRejectedValue(new Error('denied')) },
+    })
+    render()
+    const copy = screen.getByRole('button', { name: '复制' })
+    await act(async () => { fireEvent.click(copy) })
+    expect(screen.getByRole('button', { name: '复制' })).toBeTruthy()
+  })
+
+  it('ignores a second click while the copied label is showing', async () => {
+    vi.useFakeTimers()
+    const writeText = vi.fn().mockResolvedValue(undefined)
+    Object.defineProperty(navigator, 'clipboard', { configurable: true, value: { writeText } })
+    render()
+    const copy = screen.getByRole('button', { name: '复制' })
+    await act(async () => { fireEvent.click(copy) })
+    await act(async () => { fireEvent.click(screen.getByRole('button', { name: '复制成功' })) })
+    expect(writeText).toHaveBeenCalledTimes(1)
+  })
+})

From d7e46bea355d6246cfc9e0c3bd2c8696b7464da8 Mon Sep 17 00:00:00 2001
From: Chinesezjc 
Date: Thu, 30 Jul 2026 16:45:00 +0800
Subject: [PATCH 02/12] test(web): update chat-apply keyed-entry assertion for
 the file-mutation rows

The diff card registers edit and write into the keyed toolview hole, so the
mounted-entry set is now ['bash', 'edit', 'write', 'todo_write'].
---
 .../client/ui-conversation/tests/chat-apply.spec.tsx     | 9 +++++----
 1 file changed, 5 insertions(+), 4 deletions(-)

diff --git a/packages/client/ui-conversation/tests/chat-apply.spec.tsx b/packages/client/ui-conversation/tests/chat-apply.spec.tsx
index d7b9125b34..33f8af938d 100644
--- a/packages/client/ui-conversation/tests/chat-apply.spec.tsx
+++ b/packages/client/ui-conversation/tests/chat-apply.spec.tsx
@@ -80,12 +80,13 @@ describe('apply wiring', () => {
     await b.runtime.dispose()
   })
 
-  it('mounts the bash sample and the todo row as keyed entries through the load-order seam', async () => {
+  it('mounts the bash sample, the file-mutation rows, and the todo row as keyed entries through the load-order seam', async () => {
     const b = await bench()
-    // Both registrant plugins' inject: ['slots', 'conversation'] resolved — the
-    // service being present implies the chat entry declared the hole first.
+    // Each registrant plugin's inject: ['slots', 'conversation'] resolved — the
+    // service being present implies the chat entry declared the hole first. The
+    // file-mutation registrant claims both write and edit for the diff card.
     const entries = b.slots.entries('conversation.chat.toolview')
-    expect(entries.map(e => e.options.key)).toEqual(['bash', 'todo_write'])
+    expect(entries.map(e => e.options.key)).toEqual(['bash', 'edit', 'write', 'todo_write'])
     // Stats stick with the composer (not inside ChatView).
     expect(b.slots.entries('conversation.composer.dock').map(e => e.options.id)).toEqual(['stats'])
     await b.runtime.dispose()

From 8c5c4b46c83562611eb4bf3fe9adf60fdc35c81b Mon Sep 17 00:00:00 2001
From: Chinesezjc 
Date: Thu, 30 Jul 2026 18:32:55 +0800
Subject: [PATCH 03/12] =?UTF-8?q?fix(web):=20address=20diff=20card=20revie?=
 =?UTF-8?q?w=20=E2=80=94=20split=20terminator,=20error=20arm,=20wire=20nar?=
 =?UTF-8?q?rowing?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- DiffBlock: an empty side contributes zero lines and a trailing newline is a
  terminator, so a create ending in a newline draws one added line (not a
  phantom empty one) and a full deletion draws no phantom + line.
- diffCardModel: narrow the wire diffs payload (card is the only validated
  field) so a malformed diff card falls back to the generic path instead of
  throwing inside DiffBlock.
- FileMutationRow: surface the result text when an errored mutation has no diff
  card, so a failed edit/write is more than a red dot.
- copyText ends its closed union on assertNever.
- Docs: drop the "bridge relativizes" claim, record the file-count divergence
  from the TUI footer, correct the built-boot overclaim, note why the row title
  outranks the view title, and make fixture turn 67 args self-consistent.
- Tests: terminator/empty-side/interior-blank rows, wire-narrowing null arms,
  the error-text arm and its name/code fallback, stopped state, no-path summary,
  and the registration/disposal shape.
---
 .../2026-07-30-web-diff-card.i18n.yaml        |  4 +-
 .../feature/2026-07-30-web-diff-card.md       |  6 +-
 .../feature/2026-07-30-web-diff-card.zh.md    |  6 +-
 .../client/connection/src/client/fixture.ts   |  2 +-
 .../src/client/contract/diff-card-model.ts    | 40 ++++++++-
 .../toolviews/file-mutation-row.module.css    | 11 +++
 .../client/toolviews/file-mutation-row.tsx    | 25 ++++++
 .../ui-conversation/tests/diff-card.spec.tsx  | 90 ++++++++++++++++++-
 .../client/ui-primitives/src/DiffBlock.tsx    | 36 ++++++--
 .../ui-primitives/tests/diff-block.spec.tsx   | 20 +++++
 10 files changed, 221 insertions(+), 19 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml
index 18f2d5178b..7ed620736c 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.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/feature/2026-07-30-web-diff-card.md
-2026-07-30-web-diff-card.md: 5e43d5d29f7f4000efebc166724ec9d921d2b441
-2026-07-30-web-diff-card.zh.md: aac577cfa8dd9e0bf5f17a729d049d207a64d374
+2026-07-30-web-diff-card.md: 8087ce698e65f78c7c6f51211ef00e3b0ab58ed9
+2026-07-30-web-diff-card.zh.md: d85ac1f2e13c7fb3732b327b40122076337ac538
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md
index 5e43d5d29f..8087ce698e 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md
@@ -16,9 +16,9 @@ This is the [terminal card](2026-07-28-web-terminal-card.md) done for the `diff`
 
 `DiffBlock` is a `ui-primitives` component that renders a file mutation as an inline diff surface, and both Web render sites for a write/edit call consume the diff render intent through it: the chat tool row's body and the details panel's Output section. `ui-conversation/src/client/contract/diff-card-model.ts` is the single place that turns the snapshot's `callView`/`resultView` pair into the component's props, so the two sites cannot disagree about a change. It returns null — the generic path — whenever neither side declares `card: 'diff'`, including a `card` value this client version does not know, and whenever a settled call's result view is generic, which is how write/edit keep their execution errors on the generic path. The result side is authoritative once the call settles: the applied hunks replace the call-time diff derived from the arguments alone. A paging window that drops the call head still renders, because the result view carries the whole change.
 
-The component's contract mirrors the TUI's `diffLines` (`packages/ui/tui/src/components/transcript.ts`) so a diff reads the same across front ends:
+The component's contract follows the TUI's `diffLines` (`packages/ui/tui/src/components/transcript.ts`) so a diff reads the same shape across front ends, with one deliberate divergence noted below (the file count):
 
-- **One path header per file.** A new file opens a bold path header; a same-file second hunk (a scattered edit, or a `replace_all`) opens with a `⋯` gap instead of repeating the path. The `N file(s)` footer counts distinct paths.
+- **One path header per file.** A new file opens a bold path header; a same-file second hunk (a scattered edit, or a `replace_all`) opens with a `⋯` gap instead of repeating the path. The `N file(s)` footer counts DISTINCT paths — the divergence from the TUI, whose footer uses `diffs.length` and so reads two hunks in one file as `2 files` where this reads `1 file`.
 - **The change in the diff's own colors.** A removed line is `- ` on the error token, an added line is `+ ` on the success token, drawn verbatim with `white-space: pre` inside a horizontally scrolling box — a source line is read by its indentation, so it scrolls rather than folds. A create (`oldText: null`) has no removed side.
 - **Height cap with an expand control.** A diff longer than `DEFAULT_DIFF_MAX_LINES` (16) shows `ceil(max/2)` head rows plus the remaining tail rows, with a button between reporting the hidden count. The split arithmetic matches `TerminalBlock` and the TUI's collapsed card, so a long diff's head and tail slices agree across front ends.
 - **Footer and copy.** A dim `└ +A -R · N file(s)` footer summarizes the change; `+A -R` are the added/removed line counts, the same per-side counts the TUI footer draws. The copy control copies the prefixed diff text (path headers, `- `/`+ ` lines, the `⋯` gap), so a multi-file copy stays attributable.
@@ -47,7 +47,7 @@ The multi-file arm of `DiffBlock` (one card, several path headers) has no produc
 
 `packages/client/ui-conversation/tests/diff-card.spec.tsx` pins the wiring at every render site: `diffCardModel`'s derivation and each of its null arms, the result hunks replacing the call-time diff, a window-truncated call still rendering from the result, the chat row's diff body, `FileMutationRow`'s resident card and its path link opening cwd-resolved through the host, its registration under both `write` and `edit`, and the panel's Output section.
 
-The fixture (`packages/client/connection/src/client/fixture.ts`) carries three diff turns so the built-boot snapshot pins all three arms at both render sites: a single-hunk edit (turn 62, keyed `FileMutationRow`), a create/write (turn 63), and a multi-hunk edit (turn 67, the `⋯` gap between two scattered hunks in one file).
+The fixture (`packages/client/connection/src/client/fixture.ts`) carries three diff turns so a `?fixture` server and the per-package wiring suite exercise all three arms at both render sites: a single-hunk edit (turn 62, keyed `FileMutationRow`), a create/write (turn 63), and a multi-hunk edit (turn 67, the `⋯` gap between two scattered hunks in one file). The built-boot snapshot (`apps/web/tests/built-boot.snapshot.ts`) is a boot-assembly smoke that asserts only that the graph mounts and reaches chat content (`data-sample="bash-global"`); by its own contract it carries no diff-behavior assertions, which the wiring suite owns.
 
 ## Related
 
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
index aac577cfa8..d85ac1f2e1 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
@@ -16,9 +16,9 @@ Web 客户端忽略了它。write/edit 调用落到 `GenericToolCard`，其行
 
 `DiffBlock` 是一个 `ui-primitives` 组件，把文件改动渲染为内联 diff 表面，write/edit 调用的两个 Web 渲染点都通过它消费 diff 渲染意图：chat 工具行的行体和详情面板的 Output 区。`ui-conversation/src/client/contract/diff-card-model.ts` 是唯一把快照的 `callView`/`resultView` 对转成组件 props 的地方，因此两个渲染点不会对一次改动产生分歧。当两侧都未声明 `card: 'diff'` 时它返回 null —— 走通用路径 —— 包括本客户端版本不认识的 `card` 值，以及已结算调用的 result view 是 generic 的情况（write/edit 的执行错误正是这样留在通用路径上的）。调用结算后 result 侧是权威：已应用的 hunk 替换仅从参数推导的 call 时 diff。分页窗口丢弃了 call 头也仍能渲染，因为 result view 携带完整改动。
 
-组件的契约镜像 TUI 的 `diffLines`（`packages/ui/tui/src/components/transcript.ts`），使 diff 在两个前端读起来一致：
+组件的契约遵循 TUI 的 `diffLines`（`packages/ui/tui/src/components/transcript.ts`），使 diff 在两个前端读起来是同一形态，仅文件计数一处刻意分歧（见下）：
 
-- **每个文件一个路径头。** 新文件开启一个粗体路径头；同文件的第二个 hunk（分散编辑，或 `replace_all`）以一个 `⋯` gap 开启，而非重复路径。`N file(s)` 页脚统计去重后的路径数。
+- **每个文件一个路径头。** 新文件开启一个粗体路径头；同文件的第二个 hunk（分散编辑，或 `replace_all`）以一个 `⋯` gap 开启，而非重复路径。`N file(s)` 页脚统计**去重后的路径数** —— 这是与 TUI 的分歧:TUI 页脚用 `diffs.length`，同文件两个 hunk 在那里读作 `2 files`，此处读作 `1 file`。
 - **改动用 diff 自身的颜色。** 删除行是 error token 上的 `- `，新增行是 success token 上的 `+ `，在横向滚动的盒子里以 `white-space: pre` 逐字绘制 —— 源码行靠缩进阅读，所以滚动而不折行。新建（`oldText: null`）没有删除侧。
 - **高度上限带展开控件。** 长于 `DEFAULT_DIFF_MAX_LINES`（16）的 diff 显示 `ceil(max/2)` 个头部行加剩余尾部行，中间一个按钮报告隐藏行数。分割算术与 `TerminalBlock` 和 TUI 的折叠卡片一致，因此长 diff 的头尾切片在两个前端一致。
 - **页脚与复制。** 暗色 `└ +A -R · N file(s)` 页脚概括改动；`+A -R` 是新增/删除行数，与 TUI 页脚绘制的每侧计数相同。复制控件复制带前缀的 diff 文本（路径头、`- `/`+ ` 行、`⋯` gap），使多文件复制保持可归属。
@@ -47,7 +47,7 @@ chat 行把 diff 常驻渲染在路径链接摘要之下，上限 `CHAT_DIFF_MAX
 
 `packages/client/ui-conversation/tests/diff-card.spec.tsx` 钉住每个渲染点的接线：`diffCardModel` 的派生及其每个 null 支路、result hunk 替换 call 时 diff、窗口截断的 call 仍从 result 渲染、chat 行的 diff 体、`FileMutationRow` 的常驻卡片及其路径链接经 host 以 cwd 解析打开、其在 `write` 与 `edit` 下的注册、以及面板的 Output 区。
 
-fixture（`packages/client/connection/src/client/fixture.ts`）携带三个 diff turn，使 built-boot snapshot 在两个渲染点钉住全部三个支路：单 hunk 编辑（turn 62，keyed `FileMutationRow`）、新建/写入（turn 63）、多 hunk 编辑（turn 67，一个文件内两处分散 hunk 之间的 `⋯` gap）。
+fixture（`packages/client/connection/src/client/fixture.ts`）携带三个 diff turn，使 `?fixture` 服务与 per-package 接线测试套件在两个渲染点演练全部三个支路：单 hunk 编辑（turn 62，keyed `FileMutationRow`）、新建/写入（turn 63）、多 hunk 编辑（turn 67，一个文件内两处分散 hunk 之间的 `⋯` gap）。built-boot snapshot（`apps/web/tests/built-boot.snapshot.ts`）是启动装配 smoke，只断言图挂载并抵达 chat 内容（`data-sample="bash-global"`）；按其自身契约它不带 diff 行为断言，那由接线套件负责。
 
 ## Related
 
diff --git a/packages/client/connection/src/client/fixture.ts b/packages/client/connection/src/client/fixture.ts
index 4fddf6e9c0..4082d469e8 100644
--- a/packages/client/connection/src/client/fixture.ts
+++ b/packages/client/connection/src/client/fixture.ts
@@ -238,7 +238,7 @@ function buildAlphaLog(): SessionEvent[] {
   // the presenter reads to emit the two-hunk sample: the card draws one path
   // header, the first hunk, a `⋯` gap, then the second (the same-file
   // second-hunk arm turns 62/63 cannot reach).
-  toolTurn(67, 'edit', '{"file_path":"src/config.ts","old_string":"multi","new_string":"multi"}', '已编辑')
+  toolTurn(67, 'edit', '{"file_path":"src/config.ts","old_string":"const timeout = 30","new_string":"const timeout = 60"}', '已编辑')
   // Turn 64: one run_code turn with three logged sub-dispatches — the Code
   // Mode acceptance surface (parent code row + nested native-identical rows,
   // including an isError sub-call and a bash sub-call that must hit the same
diff --git a/packages/client/ui-conversation/src/client/contract/diff-card-model.ts b/packages/client/ui-conversation/src/client/contract/diff-card-model.ts
index f02ccd5930..bc914e4820 100644
--- a/packages/client/ui-conversation/src/client/contract/diff-card-model.ts
+++ b/packages/client/ui-conversation/src/client/contract/diff-card-model.ts
@@ -7,7 +7,7 @@
  * call this, so the hunks they show are derived once.
  * @module
  */
-import type { DiffBlockProps } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { DiffBlockProps, DiffHunk } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ToolCallBlock } from './tool-call-model.ts'
 
 /**
@@ -35,6 +35,30 @@ export interface DiffCardModel {
   card: Pick
 }
 
+/**
+ * Narrow a wire `card:'diff'` view's `diffs` to well-formed hunks. The event
+ * view crosses the wire and `toolEventViewSchema` validates only the `card`
+ * string, so a version mismatch or an anomalous plugin can deliver a `diff` card
+ * whose `diffs` is absent, not an array, or carries malformed hunks. Returning
+ * null for any of those routes the block to the generic path instead of letting
+ * DiffBlock's `for...of`/`split` throw and crash the row or the details panel.
+ * @param diffs - the view's `diffs` field, unverified.
+ * @returns the validated hunks, or null when the payload is not usable.
+ */
+function narrowDiffs(diffs: unknown): DiffHunk[] | null {
+  if (!Array.isArray(diffs) || diffs.length === 0) return null
+  const out: DiffHunk[] = []
+  for (const hunk of diffs) {
+    if (typeof hunk !== 'object' || hunk === null) return null
+    const { path, oldText, newText } = hunk as Record
+    if (typeof path !== 'string') return null
+    if (oldText !== null && typeof oldText !== 'string') return null
+    if (typeof newText !== 'string') return null
+    out.push({ path, oldText, newText })
+  }
+  return out
+}
+
 /**
  * Derive the diff-card props for a tool call, or null when this call is not a
  * diff card and belongs on the generic path.
@@ -49,6 +73,14 @@ export interface DiffCardModel {
  * be trusted to be one of the compiled variants — and a settled call whose
  * result view is generic (how write/edit keep their execution errors on the
  * generic path).
+ *
+ * This derivation consumes only `diffs`; the render intent's `title` field is
+ * deliberately dropped. The row supplies its own title (`Edit`/`Write · path`
+ * from the args) and that outranks the view's `title`, matching the TUI diff
+ * branch, which likewise draws no view title. A tool that names its own diff
+ * header therefore does not surface that text on the Web row — an accepted
+ * product choice, recorded here as the one asymmetry with the terminal card,
+ * whose derivation does consume the view's title.
  * @param block - RunningToolCall or ToolResultNode off the snapshot caches.
  * @returns the diff-card props, or null for the generic path.
  */
@@ -56,11 +88,13 @@ export function diffCardModel(block: ToolCallBlock): DiffCardModel | null {
   if (!('kind' in block)) {
     // Running: the call view may carry the intended diff; the result is absent.
     const call = block.callView?.card === 'diff' ? block.callView : null
-    return call === null ? null : { card: { diffs: call.diffs } }
+    const diffs = call === null ? null : narrowDiffs(call.diffs)
+    return diffs === null ? null : { card: { diffs } }
   }
   // Settled: the result view's applied hunks replace the call-time diff. A
   // window that dropped the call head leaves only the result, which still
   // renders — the result view carries the whole change.
   const result = block.resultView?.card === 'diff' ? block.resultView : null
-  return result === null ? null : { card: { diffs: result.diffs } }
+  const diffs = result === null ? null : narrowDiffs(result.diffs)
+  return diffs === null ? null : { card: { diffs } }
 }
diff --git a/packages/client/ui-conversation/src/client/toolviews/file-mutation-row.module.css b/packages/client/ui-conversation/src/client/toolviews/file-mutation-row.module.css
index b87103aa3a..3ecf480adf 100644
--- a/packages/client/ui-conversation/src/client/toolviews/file-mutation-row.module.css
+++ b/packages/client/ui-conversation/src/client/toolviews/file-mutation-row.module.css
@@ -117,3 +117,14 @@
   clip: rect(0 0 0 0);
   white-space: nowrap;
 }
+
+/* The result text for an errored mutation, indented to the card's own column
+   (the diff card's inset) and in the error tone, since it stands in for the diff
+   card the failure path does not produce. */
+.failure {
+  margin: 4px 0 4px 22px;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  font: var(--dsw-font-xs-13);
+  color: var(--dsw-alias-state-error-primary);
+}
diff --git a/packages/client/ui-conversation/src/client/toolviews/file-mutation-row.tsx b/packages/client/ui-conversation/src/client/toolviews/file-mutation-row.tsx
index 0862eb4fd5..e777c78932 100644
--- a/packages/client/ui-conversation/src/client/toolviews/file-mutation-row.tsx
+++ b/packages/client/ui-conversation/src/client/toolviews/file-mutation-row.tsx
@@ -39,6 +39,27 @@ function stateStatus(state: ToolRowState): string | null {
   }
 }
 
+/**
+ * A settled result's text, flattened from its content blocks, for the arm that
+ * shows a failure the diff card cannot: write/edit return `undefined` from
+ * `presentResult` on `result.isError`, so an errored mutation has no diff card,
+ * and the keyed row is not a details-panel target. Without this the failure —
+ * an `old_string` that did not match, a permission denial — would read as a bare
+ * red dot with the model-facing error text nowhere on screen.
+ * @param block - the frozen call slice.
+ * @returns the result text, or null for a running call or an empty result.
+ */
+function errorText(block: ToolRowProps['block']): string | null {
+  if (!('kind' in block)) return null
+  const parts: string[] = []
+  for (const item of block.content) {
+    if (item.type === 'text') parts.push(item.text)
+  }
+  if (parts.length === 0 && block.error !== undefined) parts.push(`${block.error.name}: ${block.error.code}`)
+  const text = parts.join('\n')
+  return text === '' ? null : text
+}
+
 /**
  * File-mutation row: icon + {Edit,Write} · {path} in the shared ToolRow chrome,
  * with the applied diff resident below it. The summary is a path link (a file
@@ -50,6 +71,9 @@ export function FileMutationRow({ toolName, block, cwd, openFile }: ToolRowProps
   const diff = diffCardModel(block)
   const status = stateStatus(model.state)
   const filePath = model.filePath
+  // An errored mutation has no diff card (presentResult returns undefined on
+  // isError); surface its result text so the failure is more than a red dot.
+  const failure = diff === null && model.state === 'error' ? errorText(block) : null
   return (
     

       

@@ -72,6 +96,7 @@ export function FileMutationRow({ toolName, block, cwd, openFile }: ToolRowProps
       {diff !== null && (
         
       )}
+      {failure !== null && 
{failure}
}
     

   )
 }
diff --git a/packages/client/ui-conversation/tests/diff-card.spec.tsx b/packages/client/ui-conversation/tests/diff-card.spec.tsx
index 77b762c38b..031216b9f7 100644
--- a/packages/client/ui-conversation/tests/diff-card.spec.tsx
+++ b/packages/client/ui-conversation/tests/diff-card.spec.tsx
@@ -17,7 +17,7 @@ import { CHAT_DIFF_MAX_LINES, diffCardModel } from '../src/client/contract/diff-
 import { createChatStore } from '../src/client/stores.ts'
 import { GenericToolCard } from '../src/client/chat/GenericToolCard.tsx'
 import { DetailsPanel } from '../src/client/skeleton/DetailsPanel.tsx'
-import { FileMutationRow } from '../src/client/toolviews/file-mutation-row.tsx'
+import { FileMutationRow, fileMutationToolview } from '../src/client/toolviews/file-mutation-row.tsx'
 
 afterEach(cleanup)
 
@@ -86,6 +86,22 @@ describe('diffCardModel', () => {
       callView: future, resultView: { card: 'chart' } as unknown as ToolResultView,
     }))).toBeNull()
   })
+
+  it('falls back to null for a malformed diff payload off the wire', () => {
+    // toolEventViewSchema validates only the `card` string, so a version
+    // mismatch can deliver a diff card with an unusable diffs field. Each shape
+    // routes to the generic path instead of throwing inside DiffBlock.
+    const bad = (diffs: unknown): ToolResultView => ({ card: 'diff', diffs } as unknown as ToolResultView)
+    expect(diffCardModel(settled({ resultView: bad(undefined) }))).toBeNull()
+    expect(diffCardModel(settled({ resultView: bad([]) }))).toBeNull()
+    expect(diffCardModel(settled({ resultView: bad('nope') }))).toBeNull()
+    expect(diffCardModel(settled({ resultView: bad([null]) }))).toBeNull()
+    expect(diffCardModel(settled({ resultView: bad([{ path: 1, oldText: null, newText: 'x' }]) }))).toBeNull()
+    expect(diffCardModel(settled({ resultView: bad([{ path: 'a', oldText: 5, newText: 'x' }]) }))).toBeNull()
+    expect(diffCardModel(settled({ resultView: bad([{ path: 'a', oldText: null, newText: 9 }]) }))).toBeNull()
+    // The running side narrows identically.
+    expect(diffCardModel(running({ callView: { card: 'diff', diffs: 'nope' } as unknown as ToolCallView }))).toBeNull()
+  })
 })
 
 describe('chat row diff body', () => {
@@ -176,6 +192,78 @@ describe('FileMutationRow diff card', () => {
     const view = render()
     expect(view.container.querySelector('[data-diff]')).toBeNull()
   })
+
+  it('surfaces the result text when an errored mutation has no diff card', () => {
+    // write/edit return undefined from presentResult on isError, so the failure
+    // has no diff — the row shows the model-facing error text instead of a bare
+    // red dot.
+    const view = render()
+    expect(view.container.querySelector('[data-diff]')).toBeNull()
+    expect(view.getByText('old_string not found in notes/demo.txt')).toBeTruthy()
+  })
+
+  it('falls back to the error name/code when an errored result has no text block', () => {
+    const view = render()
+    expect(view.getByText('ToolError: sandbox_denied')).toBeTruthy()
+  })
+
+  it('shows no failure text for a successful diff or a running call', () => {
+    const ok = render()
+    expect(ok.container.querySelector('[class*="_failure_"]')).toBeNull()
+    cleanup()
+    const run = render()
+    expect(run.container.querySelector('[class*="_failure_"]')).toBeNull()
+  })
+
+  it('shows the stopped state when the call was interrupted', () => {
+    const view = render()
+    expect(view.container.querySelector('[data-state="stopped"]')).not.toBeNull()
+    // The visually-hidden status label carries the stopped semantic for AT.
+    expect(view.getByText('已停止')).toBeTruthy()
+  })
+
+  it('renders a plain summary span when the call carries no file path', () => {
+    // Empty args leave deriveFilePath undefined, so the summary is not a link.
+    const view = render()
+    expect(view.container.querySelector('[class*="_fileLink_"]')).toBeNull()
+    expect(view.container.querySelector('[class*="_summary_"]')).not.toBeNull()
+  })
+})
+
+describe('fileMutationToolview registration', () => {
+  it('registers one component under both edit and write, and each disposes', () => {
+    const registered: { key: string; disposed: boolean }[] = []
+    const disposers: (() => void)[] = []
+    const ctx = {
+      slots: {
+        register: ({ key }: { name: string; key: string }) => {
+          const entry = { key, disposed: false }
+          registered.push(entry)
+          const dispose = () => { entry.disposed = true }
+          disposers.push(dispose)
+          return dispose
+        },
+      },
+    }
+    fileMutationToolview.apply(ctx as never)
+    expect(registered.map(r => r.key).sort()).toEqual(['edit', 'write'])
+    // The registrant's inject seam is the load-order contract the row relies on.
+    expect(fileMutationToolview.inject).toEqual(['slots', 'conversation'])
+    // Disposal removes each contribution (packages/AGENTS.md registry contract).
+    for (const dispose of disposers) dispose()
+    expect(registered.every(r => r.disposed)).toBe(true)
+  })
 })
 
 describe('DetailsPanel diff Output section', () => {
diff --git a/packages/client/ui-primitives/src/DiffBlock.tsx b/packages/client/ui-primitives/src/DiffBlock.tsx
index ab1700b7b5..12c389c72b 100644
--- a/packages/client/ui-primitives/src/DiffBlock.tsx
+++ b/packages/client/ui-primitives/src/DiffBlock.tsx
@@ -26,7 +26,7 @@ export const DEFAULT_DIFF_MAX_LINES = 16
  * free of the tool contract (the terminal card's decoupling, applied to diffs).
  */
 export interface DiffHunk {
-  /** The changed file's path (as the tool operated on it; the bridge relativizes it). */
+  /** The changed file's path, drawn verbatim as the hunk's header (the tool's model-facing path). */
   path: string
   /** Prior content, or `null` for a new file / an overwrite (nothing on the removed side). */
   oldText: string | null
@@ -49,6 +49,12 @@ interface DiffRow {
   text: string
 }
 
+/** Local exhaustiveness helper — this package does not depend on `dsh-llm`. */
+/* v8 ignore next 3 -- closed-union backstop; only reached if a row kind is forged */
+function assertNever(value: never): never {
+  throw new Error(`unreachable diff row kind: ${String(value)}`)
+}
+
 /** The dim class per row kind (path/gap chrome vs the diff's own +/- colors). */
 const ROW_CLASS: Record = {
   path: css.path,
@@ -61,8 +67,10 @@ const ROW_CLASS: Record = {
  * Flatten the hunks into the body's rows plus the footer counts. A path header
  * opens each new file; a same-file second hunk (a scattered edit) opens with a
  * `⋯` gap instead of repeating the path. Every old-side line counts toward
- * `removed` and every new-side line toward `added`, the same per-side line count
- * the TUI footer draws, so the two front ends agree on a change's size.
+ * `removed` and every new-side line toward `added`. The file count is of
+ * DISTINCT paths, which is the one deliberate divergence from the TUI diff card:
+ * the TUI footer uses `diffs.length`, so two hunks in one file read there as
+ * `2 files`, whereas this counts the one file they belong to.
  * @param diffs - the hunks to render.
  * @returns the body rows, the +/- totals, and the distinct-file count.
  */
@@ -78,12 +86,12 @@ function buildRows(diffs: DiffHunk[]): { rows: DiffRow[]; added: number; removed
     else rows.push({ kind: 'gap', text: '⋯' })
     prevPath = diff.path
     if (diff.oldText !== null) {
-      for (const line of diff.oldText.split('\n')) {
+      for (const line of contentLines(diff.oldText)) {
         rows.push({ kind: 'del', text: line })
         removed++
       }
     }
-    for (const line of diff.newText.split('\n')) {
+    for (const line of contentLines(diff.newText)) {
       rows.push({ kind: 'add', text: line })
       added++
     }
@@ -91,6 +99,21 @@ function buildRows(diffs: DiffHunk[]): { rows: DiffRow[]; added: number; removed
   return { rows, added, removed, files: paths.size }
 }
 
+/**
+ * Split a side's text into its content lines. Empty text is zero lines (a full
+ * deletion's `newText` or a create's absent `oldText` side draws nothing), and a
+ * single trailing newline is a line terminator rather than an extra empty line —
+ * the same terminator rule TerminalBlock applies to command output. An interior
+ * blank line (a genuine `\n\n`) survives.
+ * @param text - the removed or added side's text.
+ * @returns the content lines, without the terminating newline.
+ */
+function contentLines(text: string): string[] {
+  if (text === '') return []
+  const body = text.endsWith('\n') ? text.slice(0, -1) : text
+  return body.split('\n')
+}
+
 /**
  * The diff text a reader copies: each row's `-`/`+`/path/gap prefix and its
  * content, exactly what the card shows. The removed and added blocks are the
@@ -103,8 +126,9 @@ function copyText(rows: DiffRow[]): string {
     switch (row.kind) {
       case 'del': return `- ${row.text}`
       case 'add': return `+ ${row.text}`
+      case 'path': return row.text
       case 'gap': return row.text
-      default: return row.text
+      default: return assertNever(row.kind)
     }
   }).join('\n')
 }
diff --git a/packages/client/ui-primitives/tests/diff-block.spec.tsx b/packages/client/ui-primitives/tests/diff-block.spec.tsx
index d732a13315..bb4a2fdac3 100644
--- a/packages/client/ui-primitives/tests/diff-block.spec.tsx
+++ b/packages/client/ui-primitives/tests/diff-block.spec.tsx
@@ -76,6 +76,26 @@ describe('DiffBlock structure', () => {
     const { container } = render()
     expect(container.firstChild).toBeNull()
   })
+
+  it('treats a trailing newline as a terminator, not an extra blank line', () => {
+    // A create whose newText ends in a newline is one added line, not two, and
+    // the footer counts one — the phantom `+ ` empty line the naive split drew.
+    const { container } = render()
+    expect(changeRows(container)).toEqual(['hello'])
+    expect(screen.getByText('└ +1 -0 · 1 file')).toBeTruthy()
+  })
+
+  it('renders a full deletion as removed-only with no phantom added line', () => {
+    // newText '' is zero added lines: an empty string must contribute nothing.
+    const { container } = render()
+    expect(container.querySelectorAll('[class*="_add_"]').length).toBe(0)
+    expect(screen.getByText('└ +0 -2 · 1 file')).toBeTruthy()
+  })
+
+  it('keeps a genuine interior blank line', () => {
+    const { container } = render()
+    expect(container.querySelectorAll('[class*="_add_"]').length).toBe(3)
+  })
 })
 
 describe('DiffBlock footer', () => {

From a0a9e9733a7af0500046d24213cb44eb9bbba845 Mon Sep 17 00:00:00 2001
From: Chinesezjc 
Date: Thu, 30 Jul 2026 19:04:56 +0800
Subject: [PATCH 04/12] docs: re-record ui-conversation README pairing after
 master merge

---
 packages/client/ui-conversation/README.i18n.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index a8ec59bb6a..bbde233bbc 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/client/ui-conversation/README.md
-README.md: d3cd5cc268b60b58bb4dbb6c3b6c118084c0def8
-README.zh.md: f3a835ed82ecbd266b9f0829acc6182209940cb5
+README.md: 14b754a1a55c5455a068e45077f58411a380d955
+README.zh.md: 554a33779000d773010054766edfa0cb2e9461e0

From 452f11907e0618610bc83ef66d43f14628d0816f Mon Sep 17 00:00:00 2001
From: Chinesezjc 
Date: Thu, 30 Jul 2026 19:42:11 +0800
Subject: [PATCH 05/12] test(ui-primitives): exclude DiffBlock's assertNever
 default arm from coverage

The copyText switch's default arm calls assertNever, the closed-union
backstop that the per-file 100% coverage gate cannot reach without a
forged row kind. The assertNever function itself already carries the
v8 ignore; mark the switch arm that reaches it the same way, matching
TodoPanel's StatusGlyph default arm.
---
 packages/client/ui-primitives/src/DiffBlock.tsx | 1 +
 1 file changed, 1 insertion(+)

diff --git a/packages/client/ui-primitives/src/DiffBlock.tsx b/packages/client/ui-primitives/src/DiffBlock.tsx
index 12c389c72b..5ae28bc9b2 100644
--- a/packages/client/ui-primitives/src/DiffBlock.tsx
+++ b/packages/client/ui-primitives/src/DiffBlock.tsx
@@ -128,6 +128,7 @@ function copyText(rows: DiffRow[]): string {
       case 'add': return `+ ${row.text}`
       case 'path': return row.text
       case 'gap': return row.text
+      /* v8 ignore next -- closed-union backstop; only reached if a row kind is forged */
       default: return assertNever(row.kind)
     }
   }).join('\n')

From b76a551e10777aeab38ab177141d60d5192c507d Mon Sep 17 00:00:00 2001
From: Chinesezjc 
Date: Thu, 30 Jul 2026 20:25:05 +0800
Subject: [PATCH 06/12] docs: re-record ui-conversation README pairing after
 master merge

---
 packages/client/ui-conversation/README.i18n.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 1588367646..78e7d2f143 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/client/ui-conversation/README.md
-README.md: fc466190a744a1c13094ca6ebf62755d5bf49c98
-README.zh.md: f6fbff9c1e5d005b64e928680bbf401d94e4ce79
+README.md: 186ae70d16e9e1f1ffeadac441140ae2e5dfd2b5
+README.zh.md: 42604fde855b9e0fadabae9e871362b488957be2

From 1fd6b5a107124470219687b9a761f40640257db8 Mon Sep 17 00:00:00 2001
From: Chinesezjc 
Date: Thu, 30 Jul 2026 21:36:42 +0800
Subject: [PATCH 07/12] =?UTF-8?q?fix(web):=20diff=20card=20review=20?=
 =?UTF-8?q?=E2=80=94=20TUI=20parity,=20path-header=20overlap,=20double-res?=
 =?UTF-8?q?olve?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Bring the TUI diff footer onto the same terminator rule and distinct-path
count the Web DiffBlock uses (a trailing newline terminates its line; two
hunks in one file read as 1 file), so the two front ends' `+A -R · N file(s)`
footers agree. Reserve space in the diff path header for the floating copy
button so a long path no longer scrolls under it. Pass the tool's raw path to
the injected openFile (which already resolves against cwd) instead of resolving
twice. Rename the shared block-body CSS class to a card-neutral cardBody so a
terminal-spacing tweak cannot silently move the diff card. Add a same-file
two-hunk TUI unit test and an assembled built-boot assertion that the write
turn renders +1 -0 · 1 file end to end.
---
 .../2026-07-30-web-diff-card.i18n.yaml        |  4 +-
 .../feature/2026-07-30-web-diff-card.md       |  5 ++-
 .../feature/2026-07-30-web-diff-card.zh.md    |  5 ++-
 apps/web/tests/built-boot.snapshot.ts         | 11 ++++++
 .../src/client/chat/ToolRow.module.css        | 15 ++++----
 .../src/client/chat/ToolRow.tsx               | 11 +++---
 .../client/skeleton/DetailsPanel.module.css   |  7 ++--
 .../src/client/skeleton/DetailsPanel.tsx      |  4 +-
 .../client/toolviews/file-mutation-row.tsx    |  9 +++--
 .../ui-primitives/src/DiffBlock.module.css    |  6 ++-
 .../client/ui-primitives/src/DiffBlock.tsx    | 12 +++---
 packages/ui/tui/src/components/transcript.ts  | 29 +++++++++++---
 packages/ui/tui/tests/tui.spec.ts             | 38 +++++++++++++++++++
 13 files changed, 116 insertions(+), 40 deletions(-)

diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml
index 7ed620736c..f9b2cfa908 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.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/feature/2026-07-30-web-diff-card.md
-2026-07-30-web-diff-card.md: 8087ce698e65f78c7c6f51211ef00e3b0ab58ed9
-2026-07-30-web-diff-card.zh.md: d85ac1f2e13c7fb3732b327b40122076337ac538
+2026-07-30-web-diff-card.md: 396bdbc2843c1bbed5c6a913be436d8b9e96a81c
+2026-07-30-web-diff-card.zh.md: afdeafa6e94b46b4f0fbd4a065afdac8a93ac57d
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md
index 8087ce698e..396bdbc284 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.md
@@ -16,11 +16,12 @@ This is the [terminal card](2026-07-28-web-terminal-card.md) done for the `diff`
 
 `DiffBlock` is a `ui-primitives` component that renders a file mutation as an inline diff surface, and both Web render sites for a write/edit call consume the diff render intent through it: the chat tool row's body and the details panel's Output section. `ui-conversation/src/client/contract/diff-card-model.ts` is the single place that turns the snapshot's `callView`/`resultView` pair into the component's props, so the two sites cannot disagree about a change. It returns null — the generic path — whenever neither side declares `card: 'diff'`, including a `card` value this client version does not know, and whenever a settled call's result view is generic, which is how write/edit keep their execution errors on the generic path. The result side is authoritative once the call settles: the applied hunks replace the call-time diff derived from the arguments alone. A paging window that drops the call head still renders, because the result view carries the whole change.
 
-The component's contract follows the TUI's `diffLines` (`packages/ui/tui/src/components/transcript.ts`) so a diff reads the same shape across front ends, with one deliberate divergence noted below (the file count):
+The component's contract follows the TUI's `diffLines` (`packages/ui/tui/src/components/transcript.ts`) so a diff reads the same shape across front ends:
 
-- **One path header per file.** A new file opens a bold path header; a same-file second hunk (a scattered edit, or a `replace_all`) opens with a `⋯` gap instead of repeating the path. The `N file(s)` footer counts DISTINCT paths — the divergence from the TUI, whose footer uses `diffs.length` and so reads two hunks in one file as `2 files` where this reads `1 file`.
+- **One path header per file.** A new file opens a bold path header; a same-file second hunk (a scattered edit, or a `replace_all`) opens with a `⋯` gap instead of repeating the path. The `N file(s)` footer counts DISTINCT paths on both front ends — this PR moved the TUI footer off `diffs.length` onto the distinct-path count, so two hunks in one file read as `1 file` in both.
 - **The change in the diff's own colors.** A removed line is `- ` on the error token, an added line is `+ ` on the success token, drawn verbatim with `white-space: pre` inside a horizontally scrolling box — a source line is read by its indentation, so it scrolls rather than folds. A create (`oldText: null`) has no removed side.
 - **Height cap with an expand control.** A diff longer than `DEFAULT_DIFF_MAX_LINES` (16) shows `ceil(max/2)` head rows plus the remaining tail rows, with a button between reporting the hidden count. The split arithmetic matches `TerminalBlock` and the TUI's collapsed card, so a long diff's head and tail slices agree across front ends.
+- **Line terminator.** A side's content splits on `\n` under the terminator rule `TerminalBlock` uses: empty text is zero lines (a full deletion's `newText`, a create's absent `oldText` side), a single trailing newline terminates its last line rather than adding a phantom empty one, and an interior blank line survives. This PR applied the same rule to the TUI diff branch, so the `+A -R` footer counts agree on both front ends for the newline-terminated content real write/edit calls carry.
 - **Footer and copy.** A dim `└ +A -R · N file(s)` footer summarizes the change; `+A -R` are the added/removed line counts, the same per-side counts the TUI footer draws. The copy control copies the prefixed diff text (path headers, `- `/`+ ` lines, the `⋯` gap), so a multi-file copy stays attributable.
 
 Geometry, radius, and fonts mirror `CodeBlock`/`TerminalBlock` so a diff card, a terminal card, and a fenced block read as one family; `white-space: pre` plus horizontal scroll is the deliberate divergence. The copy control floats in the card's top-right corner rather than on a banner row of its own, because a banner carrying only a copy button drew an empty band above the first diff line — the TUI diff card has no banner either, only the footer.
diff --git a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
index d85ac1f2e1..afdeafa6e9 100644
--- a/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-30-web-diff-card.zh.md
@@ -16,11 +16,12 @@ Web 客户端忽略了它。write/edit 调用落到 `GenericToolCard`，其行
 
 `DiffBlock` 是一个 `ui-primitives` 组件，把文件改动渲染为内联 diff 表面，write/edit 调用的两个 Web 渲染点都通过它消费 diff 渲染意图：chat 工具行的行体和详情面板的 Output 区。`ui-conversation/src/client/contract/diff-card-model.ts` 是唯一把快照的 `callView`/`resultView` 对转成组件 props 的地方，因此两个渲染点不会对一次改动产生分歧。当两侧都未声明 `card: 'diff'` 时它返回 null —— 走通用路径 —— 包括本客户端版本不认识的 `card` 值，以及已结算调用的 result view 是 generic 的情况（write/edit 的执行错误正是这样留在通用路径上的）。调用结算后 result 侧是权威：已应用的 hunk 替换仅从参数推导的 call 时 diff。分页窗口丢弃了 call 头也仍能渲染，因为 result view 携带完整改动。
 
-组件的契约遵循 TUI 的 `diffLines`（`packages/ui/tui/src/components/transcript.ts`），使 diff 在两个前端读起来是同一形态，仅文件计数一处刻意分歧（见下）：
+组件的契约遵循 TUI 的 `diffLines`（`packages/ui/tui/src/components/transcript.ts`），使 diff 在两个前端读起来是同一形态：
 
-- **每个文件一个路径头。** 新文件开启一个粗体路径头；同文件的第二个 hunk（分散编辑，或 `replace_all`）以一个 `⋯` gap 开启，而非重复路径。`N file(s)` 页脚统计**去重后的路径数** —— 这是与 TUI 的分歧:TUI 页脚用 `diffs.length`，同文件两个 hunk 在那里读作 `2 files`，此处读作 `1 file`。
+- **每个文件一个路径头。** 新文件开启一个粗体路径头；同文件的第二个 hunk（分散编辑，或 `replace_all`）以一个 `⋯` gap 开启，而非重复路径。`N file(s)` 页脚在两个前端都统计**去重后的路径数** —— 本 PR 把 TUI 页脚从 `diffs.length` 改为去重路径计数，因此同文件两个 hunk 在两端都读作 `1 file`。
 - **改动用 diff 自身的颜色。** 删除行是 error token 上的 `- `，新增行是 success token 上的 `+ `，在横向滚动的盒子里以 `white-space: pre` 逐字绘制 —— 源码行靠缩进阅读，所以滚动而不折行。新建（`oldText: null`）没有删除侧。
 - **高度上限带展开控件。** 长于 `DEFAULT_DIFF_MAX_LINES`（16）的 diff 显示 `ceil(max/2)` 个头部行加剩余尾部行，中间一个按钮报告隐藏行数。分割算术与 `TerminalBlock` 和 TUI 的折叠卡片一致，因此长 diff 的头尾切片在两个前端一致。
+- **行终止符。** 每一侧的内容按 `TerminalBlock` 的终止符规则在 `\n` 上切分：空文本是零行（整文件删除的 `newText`、新建缺失的 `oldText` 侧），单个结尾换行终止其最后一行而非新增一条幻影空行，内部空行保留。本 PR 把同一规则应用到了 TUI diff 分支，因此对于真实 write/edit 调用携带的以换行结尾的内容，两个前端的 `+A -R` 页脚计数一致。
 - **页脚与复制。** 暗色 `└ +A -R · N file(s)` 页脚概括改动；`+A -R` 是新增/删除行数，与 TUI 页脚绘制的每侧计数相同。复制控件复制带前缀的 diff 文本（路径头、`- `/`+ ` 行、`⋯` gap），使多文件复制保持可归属。
 
 几何、圆角、字体镜像 `CodeBlock`/`TerminalBlock`，使 diff 卡片、terminal 卡片、代码块读起来是一家；`white-space: pre` 加横向滚动是刻意的分歧。复制控件浮在卡片右上角，而非占据自己的 banner 行，因为只放一个复制按钮的 banner 会在第一行 diff 上方画出一条空带 —— TUI 的 diff 卡片也没有 banner，只有页脚。
diff --git a/apps/web/tests/built-boot.snapshot.ts b/apps/web/tests/built-boot.snapshot.ts
index 69d5d5cfae..0e1d58f965 100644
--- a/apps/web/tests/built-boot.snapshot.ts
+++ b/apps/web/tests/built-boot.snapshot.ts
@@ -108,6 +108,17 @@ it('boots the built plugin graph and renders a fixture session end to end', asyn
     expect(document.querySelector('[data-sample="bash-global"]')).not.toBeNull()
   }, { timeout: 10_000 })
 
+  // The write/edit turns render a real diff card through the assembled graph
+  // (the keyed FileMutationRow + DiffBlock), not just the fixture's raw text.
+  // The write turn's `hello fixture\n` proves the terminator rule end to end: a
+  // trailing newline terminates its line, so the footer reads `+1` (not a
+  // phantom `+2`) and one distinct file.
+  const diffCards = document.querySelectorAll('[data-diff]')
+  expect(diffCards.length).toBeGreaterThan(0)
+  const footers = [...document.querySelectorAll('[data-diff]')]
+    .map(card => card.textContent ?? '')
+  expect(footers.some(text => text.includes('+ hello fixture') && text.includes('+1 -0 · 1 file'))).toBe(true)
+
   // Every bundle injected its plugin-owned style tag (the loader's CSS path).
   const styleOwners = [...document.head.querySelectorAll('style[data-plugin]')]
     .map(style => style.getAttribute('data-plugin'))
diff --git a/packages/client/ui-conversation/src/client/chat/ToolRow.module.css b/packages/client/ui-conversation/src/client/chat/ToolRow.module.css
index e53b472c50..f1d3e7dd7e 100644
--- a/packages/client/ui-conversation/src/client/chat/ToolRow.module.css
+++ b/packages/client/ui-conversation/src/client/chat/ToolRow.module.css
@@ -113,14 +113,15 @@
   color: var(--dsw-alias-label-tertiary);
 }
 
-/* The two block-shaped expanded bodies: the code variant's run_code program
-   through CodeBlock (shiki-highlighted TypeScript) and a terminal card's
-   command output through TerminalBlock. Both are drawn by the shared
-   primitive, so only the row's indentation is this file's concern — the margin
-   also replaces each primitive's own standalone vertical spacing with the
-   flow's row rhythm. */
+/* The block-shaped expanded bodies: the code variant's run_code program through
+   CodeBlock (shiki-highlighted TypeScript), a terminal card's command output
+   through TerminalBlock, and a write/edit diff through DiffBlock. All are drawn
+   by a shared primitive, so only the row's indentation is this file's concern —
+   the margin also replaces each primitive's own standalone vertical spacing with
+   the flow's row rhythm. Card-neutral: it carries no terminal- or diff-specific
+   value, so it fits every block body. */
 .codeBody,
-.terminalBody {
+.cardBody {
   margin: 4px 0 4px 22px;
 }
 
diff --git a/packages/client/ui-conversation/src/client/chat/ToolRow.tsx b/packages/client/ui-conversation/src/client/chat/ToolRow.tsx
index 52238788d1..b89f537230 100644
--- a/packages/client/ui-conversation/src/client/chat/ToolRow.tsx
+++ b/packages/client/ui-conversation/src/client/chat/ToolRow.tsx
@@ -83,9 +83,10 @@ export function ToolRow({
   // A row that names a single file keeps one interaction (open that path);
   // args expand is off whether or not the open callback is wired yet. A card
   // body (terminal or diff) still expands: only the file variants carry a
-  // path. A write/edit row carries both a file path and a diff card, so its
-  // path link and its expandable card coexist — the card expands, the summary
-  // stays a link.
+  // path. A write/edit row carries both a file path and a diff card, so both
+  // the path link and the expandable card are offered — the collapsed row shows
+  // the path link, and expanding swaps it for the card body (DisclosureRow
+  // renders collapsedContent only while closed).
   const singleFile = filePath !== undefined
   const fileLink = singleFile && onOpenFile !== undefined
   const cardBody = terminalBody !== null || diffBody !== null
@@ -138,9 +139,9 @@ export function ToolRow({
           
{terminalBody.description}

         )}
         {terminalBody !== null
-          ? 
+          ? 
           : diffBody !== null
-            ? 
+            ? 
             : variant === 'code'
               ? 
               : 
{text}
}
diff --git a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.module.css b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.module.css
index 143174fe42..994ae718cb 100644
--- a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.module.css
+++ b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.module.css
@@ -101,8 +101,9 @@
   font: var(--dsw-font-xs-13);
 }
 
-/* The terminal card sits directly under its section label, so it drops the
-   primitive's standalone vertical margin; the section owns the spacing. */
-.terminal {
+/* A card body (terminal or diff) sits directly under its section label, so it
+   drops the primitive's standalone vertical margin; the section owns the
+   spacing. Card-neutral: no terminal- or diff-specific value. */
+.cardBody {
   margin: 0;
 }
diff --git a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
index d09d3ea256..5a5e19179c 100644
--- a/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
+++ b/packages/client/ui-conversation/src/client/skeleton/DetailsPanel.tsx
@@ -146,12 +146,12 @@ function OutputBody({ material, cwd }: { material: CallMaterial; cwd: string | u
         {terminal.description !== undefined && (
           
{terminal.description}

         )}
-        
+        
       
     )
   }
   const diff = diffCardModel(material.block)
-  if (diff !== null) return 
+  if (diff !== null) return 
   // A settled call always carries the result node the flattened form needs;
   // the running shape has no result to flatten.
   if (!('kind' in material.block)) return 
运行中…

diff --git a/packages/client/ui-conversation/src/client/toolviews/file-mutation-row.tsx b/packages/client/ui-conversation/src/client/toolviews/file-mutation-row.tsx
index e777c78932..323a73e77c 100644
--- a/packages/client/ui-conversation/src/client/toolviews/file-mutation-row.tsx
+++ b/packages/client/ui-conversation/src/client/toolviews/file-mutation-row.tsx
@@ -17,7 +17,7 @@ import type { Context } from 'cordis'
 import { DiffBlock, IconEditOutline16, StateDot } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ToolRowProps } from '../contract/slots.ts'
 import { CHAT_DIFF_MAX_LINES, diffCardModel } from '../contract/diff-card-model.ts'
-import { resolveToolPath, toolRowModel, type ToolRowState } from '../contract/tool-call-model.ts'
+import { toolRowModel, type ToolRowState } from '../contract/tool-call-model.ts'
 import css from './file-mutation-row.module.css'
 
 function leadingFor(state: ToolRowState) {
@@ -63,8 +63,9 @@ function errorText(block: ToolRowProps['block']): string | null {
 /**
  * File-mutation row: icon + {Edit,Write} · {path} in the shared ToolRow chrome,
  * with the applied diff resident below it. The summary is a path link (a file
- * tool's interaction) resolved against the session cwd and opened through the
- * host; the card's copy and expand controls are the row's only other actions.
+ * tool's interaction); the host's `openFile` resolves it against the session
+ * cwd, so this passes the tool's own path verbatim. The card's copy and expand
+ * controls are the row's only other actions.
  */
 export function FileMutationRow({ toolName, block, cwd, openFile }: ToolRowProps) {
   const model = toolRowModel(toolName, block, cwd)
@@ -85,7 +86,7 @@ export function FileMutationRow({ toolName, block, cwd, openFile }: ToolRowProps
           
diff --git a/packages/client/ui-primitives/src/DiffBlock.module.css b/packages/client/ui-primitives/src/DiffBlock.module.css
index 8794dbb87e..c5b79006a3 100644
--- a/packages/client/ui-primitives/src/DiffBlock.module.css
+++ b/packages/client/ui-primitives/src/DiffBlock.module.css
@@ -46,10 +46,14 @@
   white-space: pre;
 }
 
-/* A file header: the path in the primary tone, set apart by weight. */
+/* A file header: the path in the primary tone, set apart by weight. The copy
+   button floats over this first row's top-right corner, so reserve space at the
+   line's end for it — a long path scrolls under the button otherwise, and the
+   button's hit area would eat clicks on the path's tail. */
 .path {
   color: var(--dsw-alias-label-primary);
   font-weight: 600;
+  padding-right: 56px;
 }
 
 /* A same-file second hunk's separator (a scattered edit), in the dim tone. */
diff --git a/packages/client/ui-primitives/src/DiffBlock.tsx b/packages/client/ui-primitives/src/DiffBlock.tsx
index 5ae28bc9b2..23c498b1d1 100644
--- a/packages/client/ui-primitives/src/DiffBlock.tsx
+++ b/packages/client/ui-primitives/src/DiffBlock.tsx
@@ -4,9 +4,10 @@
 // color), with a dim `└ +A -R · N file(s)` footer. The +/- block form mirrors
 // the TUI transcript's diff card (packages/ui/tui: diffLines) so a diff reads
 // the same across front ends: the removed side is the old text in full, the
-// added side the new text in full. 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.
+// added side the new text in full, both split on the same terminator rule, and
+// the footer counts distinct paths on both ends. 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'
@@ -68,9 +69,8 @@ const ROW_CLASS: Record = {
  * opens each new file; a same-file second hunk (a scattered edit) opens with a
  * `⋯` gap instead of repeating the path. Every old-side line counts toward
  * `removed` and every new-side line toward `added`. The file count is of
- * DISTINCT paths, which is the one deliberate divergence from the TUI diff card:
- * the TUI footer uses `diffs.length`, so two hunks in one file read there as
- * `2 files`, whereas this counts the one file they belong to.
+ * DISTINCT paths, matching the TUI diff card's footer, so two hunks in one file
+ * read as `1 file` on both front ends.
  * @param diffs - the hunks to render.
  * @returns the body rows, the +/- totals, and the distinct-file count.
  */
diff --git a/packages/ui/tui/src/components/transcript.ts b/packages/ui/tui/src/components/transcript.ts
index 58d3d6a178..c9a505bbb2 100644
--- a/packages/ui/tui/src/components/transcript.ts
+++ b/packages/ui/tui/src/components/transcript.ts
@@ -52,15 +52,28 @@ function pretty(value: unknown): string {
   return displayText(serialized ?? String(value))
 }
 
+/**
+ * A side's content lines under the terminator rule the Web DiffBlock also
+ * applies: empty text is zero lines (a full deletion's `newText`, a create's
+ * absent `oldText`), and a single trailing newline terminates the last line
+ * rather than adding an empty one. An interior blank line survives. Keeping the
+ * two front ends on the same rule holds their `+A -R` footers in step.
+ */
+function diffContentLines(text: string): string[] {
+  if (text === '') return []
+  const body = text.endsWith('\n') ? text.slice(0, -1) : text
+  return body.split('\n')
+}
+
 /** A file diff as colored `+`/`-` lines, optionally prefixed with its path. */
 function diffLines(diff: FileDiff, palette: Palette): string[] {
   // The card header is a fixed `Tool / ` frame that never names a file, so
   // each hunk always carries its own path header (no redundancy to suppress).
   const lines = [palette.bold(displayText(diff.path))]
   if (diff.oldText !== null) {
-    for (const line of displayText(diff.oldText).split('\n')) lines.push(palette.error(`- ${line}`))
+    for (const line of diffContentLines(displayText(diff.oldText))) lines.push(palette.error(`- ${line}`))
   }
-  for (const line of displayText(diff.newText).split('\n')) lines.push(palette.success(`+ ${line}`))
+  for (const line of diffContentLines(displayText(diff.newText))) lines.push(palette.success(`+ ${line}`))
   return lines
 }
 
@@ -488,15 +501,19 @@ export class ToolCardComponent implements Component {
     }
     if (view.card === 'diff') {
       // The header no longer names the file, so each diff keeps its own path
-      // header. A trailing footer summarizes the change (`+A -R · N file(s)`).
+      // header. A trailing footer summarizes the change (`+A -R · N file(s)`),
+      // on the same terminator rule and distinct-path count the Web DiffBlock
+      // uses, so the two front ends' footers agree.
       let added = 0
       let removed = 0
+      const paths = new Set()
       const hunks = view.diffs.flatMap((diff, index) => {
-        if (diff.oldText !== null) removed += displayText(diff.oldText).split('\n').length
-        added += displayText(diff.newText).split('\n').length
+        paths.add(diff.path)
+        if (diff.oldText !== null) removed += diffContentLines(displayText(diff.oldText)).length
+        added += diffContentLines(displayText(diff.newText)).length
         return [...index > 0 ? [''] : [], ...diffLines(diff, this.palette)]
       })
-      const files = view.diffs.length
+      const files = paths.size
       const footer = this.palette.dim(`└ +${added} -${removed} · ${files} file${files === 1 ? '' : 's'}`)
       // A diff's own `+`/`-` colors carry its meaning, so it renders verbatim
       // rather than under the dim result-output color.
diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts
index d99780dedb..c03d40f098 100644
--- a/packages/ui/tui/tests/tui.spec.ts
+++ b/packages/ui/tui/tests/tui.spec.ts
@@ -4317,6 +4317,21 @@ describe('tool cards and surface replay', () => {
         diffs: [{ path: 'src/only.ts', oldText: 'old', newText: 'new' }],
       }),
     },
+    scatteredDiff: {
+      name: 'scatteredDiff', description: '', parameters: {}, output: UNUSED_TOOL_OUTPUT, execute: async () => [],
+      // Two hunks in ONE file, each side ending in the terminator newline real
+      // write/edit content carries. The footer must read `+2 -0 · 1 file`: the
+      // trailing newline terminates its line rather than adding a phantom empty
+      // one, and the two hunks count as the single distinct path they touch.
+      presentCall: () => ({
+        card: 'diff',
+        title: 'Edit src/scatter.ts',
+        diffs: [
+          { path: 'src/scatter.ts', oldText: null, newText: 'first\n' },
+          { path: 'src/scatter.ts', oldText: null, newText: 'second\n' },
+        ],
+      }),
+    },
     generic: {
       name: 'generic', description: '', parameters: {}, output: UNUSED_TOOL_OUTPUT, execute: async () => [],
       presentCall: () => ({ card: 'generic', title: 'Inspect value', rawInput: { alpha: 1 } }),
@@ -4621,6 +4636,29 @@ describe('tool cards and surface replay', () => {
     await dispose(result)
   })
 
+  it('counts a same-file diff once and terminates its trailing newline', async () => {
+    const result = await setup({ tools })
+    appendUser(result.session, 'scatter edits in one file')
+    appendAssistant(result.session, [
+      { type: 'text', text: 'Editing' },
+      { type: 'tool-call', id: 'scatter' as never, name: 'scatteredDiff', arguments: '{}' },
+    ])
+    result.session.append('tool/call', {
+      turn: 1, step: 1, callId: 'scatter' as never, name: 'scatteredDiff', arguments: '{}',
+    })
+    await tick()
+    const output = result.terminal.output
+    // Two hunks, one path: distinct-path count, same as the Web DiffBlock.
+    expect(output).toContain('· 1 file')
+    expect(output).not.toContain('· 2 files')
+    // The `first\n`/`second\n` sides each contribute exactly one added line —
+    // the trailing newline terminates rather than adding a phantom empty `+ `.
+    expect(output).toContain('+ first')
+    expect(output).toContain('+ second')
+    expect(output).toContain('+2 -0')
+    await dispose(result)
+  })
+
   it('drops blank rows from a terminal card result that the dim styling wraps', async () => {
     const blankRowTools: Record = {
       trailing: {

From 568c564db47982980691c451e40f986e3e663b8e Mon Sep 17 00:00:00 2001
From: Chinesezjc 
Date: Thu, 30 Jul 2026 21:51:27 +0800
Subject: [PATCH 08/12] fix(web): update diff-card tests for the openFile
 no-double-resolve contract
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The coverage lane caught a regression in the prior commit: FileMutationRow now
passes the tool's raw path to the injected openFile (which resolves against cwd
in apply.ts), but diff-card.spec still asserted the row pre-resolved. Assert on
the raw path instead. Also fix the built-boot diff assertion to match on the
line body and footer text — the `+ ` prefix is a CSS ::before, absent from
textContent.
---
 apps/web/tests/built-boot.snapshot.ts                  | 10 +++++-----
 .../client/ui-conversation/tests/diff-card.spec.tsx    |  6 ++++--
 2 files changed, 9 insertions(+), 7 deletions(-)

diff --git a/apps/web/tests/built-boot.snapshot.ts b/apps/web/tests/built-boot.snapshot.ts
index 0e1d58f965..6500305cd8 100644
--- a/apps/web/tests/built-boot.snapshot.ts
+++ b/apps/web/tests/built-boot.snapshot.ts
@@ -112,12 +112,12 @@ it('boots the built plugin graph and renders a fixture session end to end', asyn
   // (the keyed FileMutationRow + DiffBlock), not just the fixture's raw text.
   // The write turn's `hello fixture\n` proves the terminator rule end to end: a
   // trailing newline terminates its line, so the footer reads `+1` (not a
-  // phantom `+2`) and one distinct file.
-  const diffCards = document.querySelectorAll('[data-diff]')
+  // phantom `+2`) and one distinct file. The `+ ` prefix is a CSS ::before, so
+  // it is absent from textContent — assert on the line body and the footer.
+  const diffCards = [...document.querySelectorAll('[data-diff]')]
   expect(diffCards.length).toBeGreaterThan(0)
-  const footers = [...document.querySelectorAll('[data-diff]')]
-    .map(card => card.textContent ?? '')
-  expect(footers.some(text => text.includes('+ hello fixture') && text.includes('+1 -0 · 1 file'))).toBe(true)
+  const footers = diffCards.map(card => card.textContent ?? '')
+  expect(footers.some(text => text.includes('hello fixture') && text.includes('+1 -0 · 1 file'))).toBe(true)
 
   // Every bundle injected its plugin-owned style tag (the loader's CSS path).
   const styleOwners = [...document.head.querySelectorAll('style[data-plugin]')]
diff --git a/packages/client/ui-conversation/tests/diff-card.spec.tsx b/packages/client/ui-conversation/tests/diff-card.spec.tsx
index 031216b9f7..bf29f889ae 100644
--- a/packages/client/ui-conversation/tests/diff-card.spec.tsx
+++ b/packages/client/ui-conversation/tests/diff-card.spec.tsx
@@ -163,11 +163,13 @@ describe('FileMutationRow diff card', () => {
     expect(view.getByText('复制')).toBeTruthy()
   })
 
-  it('the summary is a path link that opens through the host, cwd-resolved', () => {
+  it('the summary is a path link that opens the tool path through the host', () => {
     const openFile = vi.fn()
     const view = render()
     fireEvent.click(view.getByRole('button', { name: 'notes/demo.txt' }))
-    expect(openFile).toHaveBeenCalledWith('/w/app/notes/demo.txt')
+    // The row passes the tool's own path; the injected openFile resolves it
+    // against the session cwd (apply.ts), so the row must not resolve twice.
+    expect(openFile).toHaveBeenCalledWith('notes/demo.txt')
   })
 
   it('registers under write too, rendering a create as an added-only diff', () => {

From 1ea5f0b124c51f17471278acf96bebbbe608d2a4 Mon Sep 17 00:00:00 2001
From: Chinesezjc 
Date: Thu, 30 Jul 2026 22:24:29 +0800
Subject: [PATCH 09/12] test(tui): cover diffContentLines empty-side arm
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The coverage lane flagged transcript.ts line 63 (diffContentLines' empty-text
return) uncovered: the same-file diff test only fed newline-terminated sides.
Add a third hunk removing a line with an empty added side (a full deletion), so
the empty arm runs and the footer proves the empty side draws no `+ ` row
(+2 -1 · 1 file). Raise the test's line budget so every hunk row stays visible.
---
 packages/ui/tui/tests/tui.spec.ts | 26 ++++++++++++++++++--------
 1 file changed, 18 insertions(+), 8 deletions(-)

diff --git a/packages/ui/tui/tests/tui.spec.ts b/packages/ui/tui/tests/tui.spec.ts
index 457b2c25ac..2354a6d51b 100644
--- a/packages/ui/tui/tests/tui.spec.ts
+++ b/packages/ui/tui/tests/tui.spec.ts
@@ -4320,16 +4320,20 @@ describe('tool cards and surface replay', () => {
     },
     scatteredDiff: {
       name: 'scatteredDiff', description: '', parameters: {}, output: UNUSED_TOOL_OUTPUT, execute: async () => [],
-      // Two hunks in ONE file, each side ending in the terminator newline real
-      // write/edit content carries. The footer must read `+2 -0 · 1 file`: the
-      // trailing newline terminates its line rather than adding a phantom empty
-      // one, and the two hunks count as the single distinct path they touch.
+      // Three hunks in ONE file. The first two sides end in the terminator
+      // newline real write/edit content carries; the third removes a line and
+      // leaves an EMPTY added side (a full deletion), so `diffContentLines('')`
+      // returns zero lines. The footer must read `+2 -1 · 1 file`: each trailing
+      // newline terminates its line rather than adding a phantom empty one, the
+      // empty side contributes no `+ ` row, and the three hunks count as the
+      // single distinct path they touch.
       presentCall: () => ({
         card: 'diff',
         title: 'Edit src/scatter.ts',
         diffs: [
           { path: 'src/scatter.ts', oldText: null, newText: 'first\n' },
           { path: 'src/scatter.ts', oldText: null, newText: 'second\n' },
+          { path: 'src/scatter.ts', oldText: 'gone\n', newText: '' },
         ],
       }),
     },
@@ -4638,7 +4642,10 @@ describe('tool cards and surface replay', () => {
   })
 
   it('counts a same-file diff once and terminates its trailing newline', async () => {
-    const result = await setup({ tools })
+    // A budget past the card's row count so every hunk row stays visible (the
+    // collapse arithmetic is covered elsewhere); this test is about the
+    // terminator rule and the distinct-path footer count.
+    const result = await setup({ tools, config: { maxToolOutputLines: 20 } })
     appendUser(result.session, 'scatter edits in one file')
     appendAssistant(result.session, [
       { type: 'text', text: 'Editing' },
@@ -4649,14 +4656,17 @@ describe('tool cards and surface replay', () => {
     })
     await tick()
     const output = result.terminal.output
-    // Two hunks, one path: distinct-path count, same as the Web DiffBlock.
+    // Three hunks, one path: distinct-path count, same as the Web DiffBlock.
     expect(output).toContain('· 1 file')
-    expect(output).not.toContain('· 2 files')
+    expect(output).not.toContain('· 3 files')
     // The `first\n`/`second\n` sides each contribute exactly one added line —
     // the trailing newline terminates rather than adding a phantom empty `+ `.
     expect(output).toContain('+ first')
     expect(output).toContain('+ second')
-    expect(output).toContain('+2 -0')
+    // The third hunk removes `gone` and leaves an empty added side, which
+    // contributes no `+ ` row (diffContentLines('') is zero lines).
+    expect(output).toContain('- gone')
+    expect(output).toContain('+2 -1')
     await dispose(result)
   })
 

From f9a40d555f2667b35b165a639bf2621a3524560b Mon Sep 17 00:00:00 2001
From: Chinesezjc 
Date: Thu, 30 Jul 2026 22:59:34 +0800
Subject: [PATCH 10/12] docs: record ui-conversation README pairing hash after
 master merge

---
 packages/client/ui-conversation/README.i18n.yaml | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/client/ui-conversation/README.i18n.yaml b/packages/client/ui-conversation/README.i18n.yaml
index 0f0529e337..96db5f7c1a 100644
--- a/packages/client/ui-conversation/README.i18n.yaml
+++ b/packages/client/ui-conversation/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/client/ui-conversation/README.md
-README.md: e3625f40a1f6b0d4097cbef51818c250c88cd0e8
-README.zh.md: a1c10c085d30dd5241823492d666f3c0b58d7942
+README.md: fa4a19c6e97e423dc01bc037c7784b30c5d4c0e6
+README.zh.md: e09e1c85d7f8ac48b5d86ee9b81d3ba3f6da268e

From 6991650fce41ffe0c74fb0c1b45a8e0f7492c65e Mon Sep 17 00:00:00 2001
From: Chinesezjc 
Date: Thu, 30 Jul 2026 23:53:11 +0800
Subject: [PATCH 11/12] fix(config): map dsh-host-directory-picker-auto to
 workspace source

web.cordis.yml references @deepseek-ai/dsh-host-directory-picker-auto but
tsconfig.base.json had no paths entry for it, so the tsx source launch fell
back to built lib/ and verify-cordis-config failed. Add the mapping alongside
its -browse/-native siblings.
---
 tsconfig.base.json | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/tsconfig.base.json b/tsconfig.base.json
index f5f5c0a3ba..9bdaa91652 100644
--- a/tsconfig.base.json
+++ b/tsconfig.base.json
@@ -125,6 +125,8 @@
       "@deepseek-ai/dsh-host-directory-picker-browse/*": ["./packages/host/directory-picker-browse/src/*"],
       "@deepseek-ai/dsh-host-directory-picker-native": ["./packages/host/directory-picker-native/src"],
       "@deepseek-ai/dsh-host-directory-picker-native/*": ["./packages/host/directory-picker-native/src/*"],
+      "@deepseek-ai/dsh-host-directory-picker-auto": ["./packages/host/directory-picker-auto/src"],
+      "@deepseek-ai/dsh-host-directory-picker-auto/*": ["./packages/host/directory-picker-auto/src/*"],
       "@deepseek-ai/dsh-host-apiproxy/client": ["./packages/host/apiproxy/src/fetch/client.ts"],
       "@deepseek-ai/dsh-host-apiproxy/*": ["./packages/host/apiproxy/src/*"],
       "@deepseek-ai/dsh-host-webserver": ["./packages/host/webserver/src"],

From 322950487ee777673c067c71dbeea989751582d7 Mon Sep 17 00:00:00 2001
From: Hypatia May 
Date: Fri, 31 Jul 2026 11:51:44 +0800
Subject: [PATCH 12/12] fix(apiproxy): let commands outlive unary deadline

---
 ...19-gui-layering-and-rpc-protocol.i18n.yaml |  4 +-
 ...026-07-19-gui-layering-and-rpc-protocol.md |  5 +-
 ...-07-19-gui-layering-and-rpc-protocol.zh.md |  5 +-
 packages/host/apiproxy/README.i18n.yaml       |  4 +-
 packages/host/apiproxy/README.md              |  4 +-
 packages/host/apiproxy/README.zh.md           |  4 +-
 packages/host/apiproxy/src/fetch/client.ts    | 34 ++++++----
 .../host/apiproxy/tests/fetch-carrier.spec.ts | 62 +++++++++++++++++++
 8 files changed, 98 insertions(+), 24 deletions(-)

diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
index 70618612a2..e603129715 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.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/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
-2026-07-19-gui-layering-and-rpc-protocol.md: b9718da4725316c64686adef24827e2984d8723d
-2026-07-19-gui-layering-and-rpc-protocol.zh.md: 2add148054e8f97c65600cd719fb4f8e0283f52d
+2026-07-19-gui-layering-and-rpc-protocol.md: b7081591cf7e5e3c586c74c5a71b4317376135cb
+2026-07-19-gui-layering-and-rpc-protocol.zh.md: 89557182ca7781f4fb59b8daf866aaca96cf20ee
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
index b9718da472..b7081591cf 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.md
@@ -204,7 +204,7 @@ The same domain tree as `ApiProxy`, but unary methods **take the business payloa
 | `callUnary` | mint → tap → POST full form → `serverResponseSchema` parse → **rpcId echo check** (mismatch throws) → tap → emit narrow form |
 | `readSse` | streaming fetch (not EventSource), `\n\n` framing, `data:` concatenation, ServerRequest full-form parse, tap, emit narrow `RpcRequest` |
 | `respond` | client-response passthrough (rpcId is an echo — never minted here); response body parsed by `rpcReceiptSchema` |
-| unary timeout | `AbortSignal.timeout` (default 30s, constructor-tunable); streams have no timeout (long-lived by nature) |
+| unary deadline | Ordinary unary calls use `AbortSignal.timeout` (default 30s, constructor-tunable); user-paced `host.pickDirectory` and `command.execute` omit that deadline but keep caller/connection cancellation; streams have no deadline |
 | `resolveBase` | browser = same-origin origin; no-location environment (Node) = the `http://dsh.internal` fake authority |
 
 ### The instance-level envelope observation aspect
@@ -234,7 +234,7 @@ All four quadrant full forms pass through `onEnvelope`; the base implementation
 
 ## Consequences
 
-Every client shape consumes one contract: adding a unary method is a five-step mechanical change radiating from a single signature, swapping a carrier touches only a `doFetch` subclass, and every wire message is zod-validated, observable through the envelope tap, and reconcilable by rpcId. The accepted costs: two groups of packages need explicit tsconfig paths entries, and the reserved seams (fork/inject/task.list/listModels/hostInstanceId) stay dormant until a real consumer arrives.
+Every client shape consumes one contract: adding a unary method is a five-step mechanical change radiating from a single signature, swapping a carrier touches only a `doFetch` subclass, and every wire message is zod-validated, observable through the envelope tap, and reconcilable by rpcId. Ordinary unary calls remain bounded, while `host.pickDirectory` and `command.execute` may stay pending until the operation finishes or caller/connection cancellation arrives; this accepts that a non-cooperative user-paced operation can hang its request rather than treating valid operation duration as transport failure. The other accepted costs: two groups of packages need explicit tsconfig paths entries, and the reserved seams (fork/inject/task.list/listModels/hostInstanceId) stay dormant until a real consumer arrives.
 
 ## Alternatives considered
 
@@ -252,3 +252,4 @@ Every client shape consumes one contract: adding a unary method is a five-step m
 | A DTO layer (a second wire-only structure set) | Core types reach the browser type-only at zero cost; a DTO is a permanent two-way synchronization tax |
 | Cursor resumption (implementing mux since) | Reconnect = rebuild (opencode-style) covers all v1 needs; the signature keeps the seat, implementation waits for a real consumer |
 | A createApiClient factory function (the original implementation) | Platform differences (transport/observation) are inheritance aspects, not parameters; the class family lets the fixture substitute at the protocol layer instead of wrapping a fake envelope |
+| Applying the 30-second transport deadline to `command.execute` | Command duration is operation work, not a transport-health budget; the deadline kills valid long-running handlers, while caller/connection cancellation already supplies the required stop path |
diff --git a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
index 2add148054..89557182ca 100644
--- a/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
+++ b/.agents/notes/implemented/architecture/2026-07-19-gui-layering-and-rpc-protocol.zh.md
@@ -202,7 +202,7 @@ export type ResponseValue =
 | `callUnary` | mint → tap → POST 全形 → `serverResponseSchema` parse → **rpcId 回显校验**（不符即 throw）→ tap → 吐窄形 |
 | `readSse` | streaming fetch（非 EventSource）、`\n\n` 分帧、`data:` 拼接、ServerRequest 全形 parse、tap、吐窄形 `RpcRequest<帧>` |
 | `respond` | client-response 透传（rpcId 是回填，此处不 mint）；应答体 `rpcReceiptSchema` parse |
-| unary 超时 | `AbortSignal.timeout`（默认 30s，构造参数可调）；流不设超时（长连接本性） |
+| unary 时限 | 普通 unary 调用使用 `AbortSignal.timeout`（默认 30s，构造参数可调）；由用户掌控节奏的 `host.pickDirectory` 和 `command.execute` 不设该时限，但保留调用方／连接取消；流不设时限 |
 | `resolveBase` | 浏览器=同源 origin；无 location 环境（Node）=`http://dsh.internal` 假 authority |
 
 ### 实例级 envelope 观测切面
@@ -232,7 +232,7 @@ export type ResponseValue =
 
 ## Consequences
 
-所有 client 形态消费同一契约：加一个 unary 方法是从单一签名辐射的五步机械改动，换载体只动一个 `doFetch` 子类，wire 上每条消息可 zod 校验、可经 envelope tap 观测、可按 rpcId 对账。接受的代价：两组包需要显式 tsconfig paths 条目；预留接缝（fork/inject/task.list/listModels/hostInstanceId）在真实消费者出现前保持休眠。
+所有 client 形态消费同一契约：加一个 unary 方法是从单一签名辐射的五步机械改动，换载体只动一个 `doFetch` 子类，wire 上每条消息可 zod 校验、可经 envelope tap 观测、可按 rpcId 对账。普通 unary 调用仍受时限约束，而 `host.pickDirectory` 与 `command.execute` 可保持挂起，直到操作完成或调用方／连接取消到来；若由用户掌控节奏的操作不自行结束，请求可能一直挂起，这是为避免把合理的操作时长视为传输失败而接受的代价。其余接受的代价：两组包需要显式 tsconfig paths 条目；预留接缝（fork/inject/task.list/listModels/hostInstanceId）在真实消费者出现前保持休眠。
 
 ## Alternatives considered
 
@@ -250,3 +250,4 @@ export type ResponseValue =
 | DTO 层（wire 专用第二套结构） | core 类型 type-only 直达浏览器零成本；DTO 是永久的双向同步税 |
 | cursor 续传（mux since 实装） | 重连=重建（opencode 同款）覆盖 v1 全部需求；签名留座，实装等真实消费者 |
 | createApiClient 工厂函数（原实现） | 平台差异（传输/观测）是继承切面不是参数；类体系让 fixture 在协议层替换而不是包一层假信封 |
+| 对 `command.execute` 应用 30 秒传输时限 | 命令耗时属于操作本身，而非传输健康预算；该时限会终止本应继续运行的长时处理器，调用方／连接取消已提供所需的停止路径 |
diff --git a/packages/host/apiproxy/README.i18n.yaml b/packages/host/apiproxy/README.i18n.yaml
index 02cf787a27..780e584de7 100644
--- a/packages/host/apiproxy/README.i18n.yaml
+++ b/packages/host/apiproxy/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/host/apiproxy/README.md
-README.md: 73d8afb32f868ca82dfa2d350df089a5d0b9b358
-README.zh.md: 47af18f76302e261e18f682e0d3cf0ee903933db
+README.md: 926c631e4784d5ca9b52b1af93487ce4887511b1
+README.zh.md: 030e6f9dab7e659e8ea6bc2543c676f35ade4b39
diff --git a/packages/host/apiproxy/README.md b/packages/host/apiproxy/README.md
index 73d8afb32f..926c631e47 100644
--- a/packages/host/apiproxy/README.md
+++ b/packages/host/apiproxy/README.md
@@ -28,11 +28,11 @@ Workspace and Session lists are separate reconnect baselines. `workspace.create`
 
 A stale continuation discards every partial result, deduplication entry, and cursor from that provider attempt, then restarts at the first page against the original list-derived visibility snapshot without discarding the learned provider page size. Limit probes and stale retries share the same limit of at most 100 provider calls (and therefore at most 2,000 inspected hits); a page larger than its requested limit, a repeated continuation cursor, or a still-unexhausted stream at that call budget fails closed as an `internal` business error. The carrier request signal cancels persistence listing, cold-summary collection, and every search call, including a limit or stale rejection observed concurrently with cancellation. A deployment without the service, or any unrecovered index/query failure, also returns an `internal` business error so clients can retain metadata-only matches.
 
-Directory picking delegates to the composed `ctx.directoryPicker` backend ([the directory-picker seam](../directory-picker/README.md)); a method called outside the composed capability's kind fails with `directory-picker-unavailable` (the client needs no advertisement — the composed picker package's own client half renders the matching interaction). Under `native`, `host.pickDirectory` opens one native chooser and returns its selected path (`null` on cancel); this user-paced method is the sole unary call exempt from the default 30-second timeout, and caller/connection aborts still propagate to the native process. Under `browse`, `host.listDirectory` returns one name-sorted directory level with breadcrumb ancestry, a `home` anchor, and host-owned `hidden` flags (absent path = home directory), and `host.createDirectory` creates one validated child segment; the backend's typed failures map 1:1 onto the `directory-unreadable`/`directory-exists`/`directory-create-failed` codes. The browser carrier's prefix-wide trust fence (dsh-client-connection) covers all of these like every other `/api` request.
+Directory picking delegates to the composed `ctx.directoryPicker` backend ([the directory-picker seam](../directory-picker/README.md)); a method called outside the composed capability's kind fails with `directory-picker-unavailable` (the client needs no advertisement — the composed picker package's own client half renders the matching interaction). Under `native`, `host.pickDirectory` opens one native chooser and returns its selected path (`null` on cancel); this user-paced method does not use the default 30-second unary timeout, while caller/connection aborts still propagate to the native process. Under `browse`, `host.listDirectory` returns one name-sorted directory level with breadcrumb ancestry, a `home` anchor, and host-owned `hidden` flags (absent path = home directory), and `host.createDirectory` creates one validated child segment; the backend's typed failures map 1:1 onto the `directory-unreadable`/`directory-exists`/`directory-create-failed` codes. The browser carrier's prefix-wide trust fence (dsh-client-connection) covers all of these like every other `/api` request.
 
 `host.openPath` opens a filesystem path with the operating system's default application (`open` on macOS, `Invoke-Item` on Windows, `xdg-open` on Linux). The opener is injectable for tests. The browser carrier applies the same loopback, same-origin restriction as `host.pickDirectory`.
 
-The `command.*` and `skill.*` domains expose the host command registry and skill catalog to clients. Every method addresses one session's agent by `sessionId` (a served session always has an Agent; `command.*` resumes cold sessions through the same path as `session.*`, while `skill.list` resolves the project root from the session header without touching the Agent registry). `skill.list` serves the browser's user-selected model-reference path, so it returns only skills that are both model-invocable and user-invocable; this domain has no direct skill-loading RPC. `command.execute` runs a slash-command line host-side with pure admission semantics: the response reports whether the line resolved to a handler plus the minted lifecycle `commandId` when it did (correlating the acknowledgment with the flow node), while the outcome rides the durably logged `command/run`/`command/done` lifecycle pair broadcast on the mux stream; the carrier's request signal cancels the running handler. `host/commands-changed` is the catalog invalidation frame: clients refetch `command.list` instead of diffing.
+The `command.*` and `skill.*` domains expose the host command registry and skill catalog to clients. Every method addresses one session's agent by `sessionId` (a served session always has an Agent; `command.*` resumes cold sessions through the same path as `session.*`, while `skill.list` resolves the project root from the session header without touching the Agent registry). `skill.list` serves the browser's user-selected model-reference path, so it returns only skills that are both model-invocable and user-invocable; this domain has no direct skill-loading RPC. `command.execute` runs a slash-command line host-side with pure admission semantics: the response reports whether the line resolved to a handler plus the minted lifecycle `commandId` when it did (correlating the acknowledgment with the flow node), while the outcome rides the durably logged `command/run`/`command/done` lifecycle pair broadcast on the mux stream. Command handlers may legitimately outlast the 30-second transport health deadline, so `command.execute` carries only caller/connection cancellation; that signal cancels the running handler. `host/commands-changed` is the catalog invalidation frame: clients refetch `command.list` instead of diffing.
 
 The `settings.*`, `credentials.*`, and `llm.*` domains are the configuration-page wire. The settings domain serves exactly the namespaces a registered configurable provider addresses (`ctx.llm.listConfigurableProviders()`): the seam is general, but this plane is the model-provider surface, so a namespace nothing in the directory names is neither described nor writable here and answers `settings-not-exposed` — the same answer an unregistered namespace gets, so no caller can enumerate the registry by probing. `settings.describe` returns each exposed namespace's serialized schemastery schema, redacted layered values (resolved/`base`/`user` — a field's presence in `user` marks it user-overridden), the `secrets` slot list, and the section's `revision`. `settings.update`/`settings.replace` write the user layer; `settings.mutate` applies path ops (`set`/`unset`) against the section as stored, which is the removal path for a client holding the redacted view — rebuilding a section from it and replacing wholesale would delete the secrets the wire never returned. Any write may carry `expectedRevision`; a stale one answers `settings-conflict` with both revisions rather than overwriting the writer that landed first, and every other seam refusal folds into `settings-rejected`. Secret-role values never ride any response in any layer; a secret crosses the wire in exactly one direction — inside an `update`/`mutate` payload or `credentials.set`. `credentials.describe` returns value-free views (`configured`/`source`/`writable`), and `credentials.set`/`credentials.unset` map a shadowed-reference refusal onto `credential-rejected`. `llm.providers` merges the configurable-provider directory with live routes (dormant entries carry `active: false`; undeclared live routes append with no settings address) and `llm.models` is the session-independent catalog. Three invalidation frames keep every surface converged without polling: `host/settings-changed {ns}` (`settings/document-updated` passthrough, so a raw change whose resolved value is unchanged still reaches clients), `host/credentials-changed {ref}` (reference names only, never values), and `host/models-changed` — fired both by `llm/adapters-updated` and by a change to an exposed provider namespace, whose settings carry that provider's catalog and endpoint. The browser carrier restricts the whole configuration plane, reads included (`settings.describe`/`update`/`replace`/`mutate`, `credentials.describe`/`set`/`unset`), to loopback same-origin requests — the `host.pickDirectory` privileged set. A composition without a settings or credential provider answers those domains with an actionable `internal` error naming the missing plugin.
 
diff --git a/packages/host/apiproxy/README.zh.md b/packages/host/apiproxy/README.zh.md
index 47af18f763..030e6f9dab 100644
--- a/packages/host/apiproxy/README.zh.md
+++ b/packages/host/apiproxy/README.zh.md
@@ -28,11 +28,11 @@ Workspace 列表与 Session 列表是相互独立的重连基线。`workspace.cr
 
 陈旧的续传会丢弃该提供方尝试中的所有部分结果、去重条目和游标，然后依据最初从列表推导的可见性快照从第一页重新开始，但不会丢弃探测所得的提供方页面大小。上限探测与陈旧重试共用最多 100 次提供方调用的限制（因此最多检查 2,000 个命中）；如果某页命中数超过其请求的上限、续传游标重复，或用尽该调用预算后结果流仍未耗尽，都会直接返回 `internal` 业务错误，不返回部分结果。载体请求信号可取消持久化列表枚举、冷会话摘要收集和每一次搜索调用；即使同时收到上限拒绝或陈旧拒绝，也以取消为准。部署若未挂载该服务，或索引／查询故障无法恢复，也会返回 `internal` 业务错误，以便客户端保留仅基于元数据的匹配项。
 
-目录选择委托给组合的 `ctx.directoryPicker` 后端（[目录选择 seam](../directory-picker/README.md)）；调用组合能力 kind 之外的方法会以 `directory-picker-unavailable` 失败（客户端不需要广播——组合的选择器包自己的 client half 渲染匹配的交互）。在 `native` 下，`host.pickDirectory` 打开一个原生选择器并返回选中路径（取消为 `null`）；该方法需等待用户完成操作，是唯一不受默认 30 秒超时限制的一元调用，调用方与连接的中止仍会传播至原生进程。在 `browse` 下，`host.listDirectory` 返回一个按名称排序的目录层级，携带面包屑祖先链、`home` 锚点与宿主判定的 `hidden` 标志（不带路径即家目录），`host.createDirectory` 创建一个经校验的子段；后端的类型化失败 1:1 映射为 `directory-unreadable`／`directory-exists`／`directory-create-failed` 错误码。浏览器载体的前缀级信任栅栏（dsh-client-connection）像覆盖其他所有 `/api` 请求一样覆盖上述全部方法。
+目录选择委托给组合的 `ctx.directoryPicker` 后端（[目录选择 seam](../directory-picker/README.md)）；调用组合能力 kind 之外的方法会以 `directory-picker-unavailable` 失败（客户端不需要广播——组合的选择器包自己的 client half 渲染匹配的交互）。在 `native` 下，`host.pickDirectory` 打开一个原生选择器并返回选中路径（取消为 `null`）；该方法需等待用户完成操作，不使用默认的 30 秒一元调用超时，而调用方与连接的中止仍会传播至原生进程。在 `browse` 下，`host.listDirectory` 返回一个按名称排序的目录层级，携带面包屑祖先链、`home` 锚点与宿主判定的 `hidden` 标志（不带路径即家目录），`host.createDirectory` 创建一个经校验的子段；后端的类型化失败 1:1 映射为 `directory-unreadable`／`directory-exists`／`directory-create-failed` 错误码。浏览器载体的前缀级信任栅栏（dsh-client-connection）像覆盖其他所有 `/api` 请求一样覆盖上述全部方法。
 
 `host.openPath` 会用操作系统的默认应用打开一个文件系统路径（macOS 为 `open`，Windows 为 `Invoke-Item`，Linux 为 `xdg-open`）。打开器可在测试中注入。浏览器载体对其施加与 `host.pickDirectory` 相同的回环、同源限制。
 
-`command.*` 与 `skill.*` 领域向客户端暴露宿主命令注册表和技能目录。每个方法都通过 `sessionId` 寻址一个会话的 Agent（被服务的会话必有 Agent；`command.*` 经由与 `session.*` 相同的路径恢复冷会话，而 `skill.list` 从会话头解析项目根目录，不触碰 Agent 注册表）。`skill.list` 服务于浏览器中由用户选择的模型引用路径，因此仅返回模型和用户均可调用的 skill；该领域没有直接加载 skill 的 RPC。`command.execute` 在宿主侧运行一条斜杠命令行，语义为纯准入：响应报告该行是否解析到处理器，并在解析到时回带铸造的生命周期 `commandId`（将本次确认与流节点关联）；结局经由持久落账并在 mux 流广播的 `command/run`/`command/done` 生命周期事件对承载；载体的请求信号可取消正在运行的处理器。`host/commands-changed` 是目录失效帧：客户端重新拉取 `command.list` 而不是做差分。
+`command.*` 与 `skill.*` 领域向客户端暴露宿主命令注册表和技能目录。每个方法都通过 `sessionId` 寻址一个会话的 Agent（被服务的会话必有 Agent；`command.*` 经由与 `session.*` 相同的路径恢复冷会话，而 `skill.list` 从会话头解析项目根目录，不触碰 Agent 注册表）。`skill.list` 服务于浏览器中由用户选择的模型引用路径，因此仅返回模型和用户均可调用的 skill；该领域没有直接加载 skill 的 RPC。`command.execute` 在宿主侧运行一条斜杠命令行，语义为纯准入：响应报告该行是否解析到处理器，并在解析到时回带铸造的生命周期 `commandId`（将本次确认与流节点关联）；结局经由持久落账并在 mux 流广播的 `command/run`/`command/done` 生命周期事件对承载。命令处理器运行超过 30 秒的传输健康时限仍属正常，因此 `command.execute` 仅携带调用方／连接取消信号；该信号可取消正在运行的处理器。`host/commands-changed` 是目录失效帧：客户端重新拉取 `command.list` 而不是做差分。
 
 `settings.*`、`credentials.*` 与 `llm.*` 领域是配置页协议。settings 领域只服务于已注册可配置提供方所指向的那些 namespace（`ctx.llm.listConfigurableProviders()`）：seam 本身是通用的，但这个面是模型提供方表层，因此目录中无人点名的 namespace 在这里既不会被描述也不可写入，只会得到 `settings-not-exposed`——未注册的 namespace 得到的是同一个答复，因此没有调用方能靠逐个探测把注册表枚举出来。`settings.describe` 为每个已暴露 namespace 提供其序列化 schemastery schema、脱敏后的分层值（resolved/`base`/`user`——字段出现在 `user` 中即标记其被用户覆盖）、`secrets` 槽位列表，以及该分节的 `revision`。`settings.update`/`settings.replace` 写入用户层；`settings.mutate` 则在已存分节上施加路径 op（`set`/`unset`），这是持有脱敏视图的客户端的删除路径——据此重建分节再整体替换，会删掉协议从未回传过的那些机密。任何写入都可携带 `expectedRevision`；过期的期望值会以 `settings-conflict` 连同两个 revision 作答，而不是覆盖先落地的那个写方，其余每种 seam 拒绝则折叠为 `settings-rejected`。secret 角色的值绝不在任何一层搭乘任何响应；secret 只沿一个方向跨越协议——在 `update`/`mutate` 载荷或 `credentials.set` 之内。`credentials.describe` 返回不含值的视图（`configured`/`source`/`writable`），`credentials.set`/`credentials.unset` 则把被遮蔽引用的拒绝映射为 `credential-rejected`。`llm.providers` 把可配置提供方目录与存活路由合并（休眠条目携带 `active: false`；未声明的存活路由追加在后，不带 settings 地址），`llm.models` 则是与会话无关的目录。三个失效帧让每个面无需轮询即保持收敛：`host/settings-changed {ns}`（`settings/document-updated` 透传，因此解析值未变的原始变更同样能到达客户端）、`host/credentials-changed {ref}`（只带引用名，绝不带值），以及 `host/models-changed`——它既由 `llm/adapters-updated` 触发，也由某个已暴露提供方 namespace 的变更触发，因为该提供方的设置正承载着它的目录与端点。浏览器载体把整个配置面（含读取：`settings.describe`/`update`/`replace`/`mutate` 与 `credentials.describe`/`set`/`unset`）限制为仅接受来自回环地址的同源请求——即 `host.pickDirectory` 所在的特权集合。未装 settings 或凭据 provider 的组合会以指名缺失插件、包含解决建议的 `internal` 错误应答这些领域。
 
diff --git a/packages/host/apiproxy/src/fetch/client.ts b/packages/host/apiproxy/src/fetch/client.ts
index 97037c10eb..5261658ee0 100644
--- a/packages/host/apiproxy/src/fetch/client.ts
+++ b/packages/host/apiproxy/src/fetch/client.ts
@@ -59,9 +59,10 @@ import { llmModelsValueSchema, llmProvidersValueSchema } from '../api/llm.schema
  * Client consumption face of the contract (shape a): same domain tree as ApiProxy, but unary
  * methods take the business payload directly — the carrier mints the rpcId and wraps the
  * envelope. Business code needing the call's rpcId reads it from the RpcResponse echo.
- * Unary methods and respond accept an optional external AbortSignal as the last parameter
- * (merged with the instance timeout via AbortSignal.any; same "signal rides beside the
- * request, never on the wire" discipline as the stream signatures).
+ * Unary methods and respond accept an optional external AbortSignal as the last parameter.
+ * Bounded calls merge it with the instance timeout via AbortSignal.any; user-paced calls
+ * carry only that external signal. In both cases the signal rides beside the request, never
+ * on the wire, like the stream signatures.
  * Stream methods accept an optional onOpen callback: it fires once the SSE transport is
  * readable (response headers received, before any frame) — the "stream established" signal
  * connection controllers need for the readiness handshake. Generators are lazy, so the
@@ -182,9 +183,12 @@ const UNARY_VALUE_SCHEMAS: { [K in keyof RpcMethodMap]: z.ZodType void>()
 
-  /** @param timeoutMs - unary timeout; streams never time out (long-lived by nature). */
+  /** @param timeoutMs - timeout for bounded unary calls; user-paced calls and streams do not use it. */
   constructor(protected readonly timeoutMs: number = DEFAULT_TIMEOUT_MS) {}
 
   /** Transport aspect: browser fetch, injected handler.fetch, IPC bridge, ... */
@@ -257,15 +261,15 @@ export abstract class AbstractApiClient implements IApiClient {
 
   /**
    * Shared POST leg of both C→S carriers (callUnary/respond): JSON body,
-   * timeout merged with the caller's optional external signal, non-2xx → transport throw.
+   * optional default timeout merged with the caller's external signal, non-2xx → transport throw.
    */
   private async postJson(
     path: string,
     body: ClientRequest | ClientResponse,
     signal: AbortSignal | undefined,
-    useDefaultTimeout = true,
+    timeoutPolicy: UnaryTimeoutPolicy = 'default',
   ): Promise {
-    const requestSignal = useDefaultTimeout
+    const requestSignal = timeoutPolicy === 'default'
       ? signal === undefined
         ? AbortSignal.timeout(this.timeoutMs)
         : AbortSignal.any([AbortSignal.timeout(this.timeoutMs), signal])
@@ -289,11 +293,11 @@ export abstract class AbstractApiClient implements IApiClient {
     method: K,
     payload: RequestPayload,
     signal?: AbortSignal,
-    useDefaultTimeout = true,
+    timeoutPolicy: UnaryTimeoutPolicy = 'default',
   ): Promise>> {
     const message: ClientRequest = { type: 'client-request', rpcId: this.mintRpcId(), method, payload }
     this.onEnvelope(message)
-    const response = await this.postJson(`/api/${method}`, message, signal, useDefaultTimeout)
+    const response = await this.postJson(`/api/${method}`, message, signal, timeoutPolicy)
     const full = serverResponseSchema.parse(await response.json())
     this.onEnvelope(full)
     if (full.rpcId !== message.rpcId) throw new Error(`rpcId mismatch for ${method}: sent ${message.rpcId}, got ${full.rpcId}`)
@@ -382,7 +386,9 @@ export abstract class AbstractApiClient implements IApiClient {
     describe: (payload, signal) => this.callUnary('host.describe', payload, signal),
     // A native system dialog is user-paced and may legitimately stay open
     // longer than the normal unary deadline. Caller/connection aborts remain.
-    pickDirectory: (payload, signal) => this.callUnary('host.pickDirectory', payload, signal, false),
+    pickDirectory: (payload, signal) => this.callUnary(
+      'host.pickDirectory', payload, signal, 'caller-signal-only',
+    ),
     listDirectory: (payload, signal) => this.callUnary('host.listDirectory', payload, signal),
     createDirectory: (payload, signal) => this.callUnary('host.createDirectory', payload, signal),
     openPath: (payload, signal) => this.callUnary('host.openPath', payload, signal),
@@ -398,7 +404,11 @@ export abstract class AbstractApiClient implements IApiClient {
 
   readonly commands: IApiClient['commands'] = {
     list: (payload, signal) => this.callUnary('command.list', payload, signal),
-    execute: (payload, signal) => this.callUnary('command.execute', payload, signal),
+    // Command handlers are user-driven operations and may legitimately exceed
+    // the transport health deadline. Caller/connection aborts remain.
+    execute: (payload, signal) => this.callUnary(
+      'command.execute', payload, signal, 'caller-signal-only',
+    ),
   }
 
   readonly skills: IApiClient['skills'] = {
diff --git a/packages/host/apiproxy/tests/fetch-carrier.spec.ts b/packages/host/apiproxy/tests/fetch-carrier.spec.ts
index 2390d628ac..3a21d6d1ce 100644
--- a/packages/host/apiproxy/tests/fetch-carrier.spec.ts
+++ b/packages/host/apiproxy/tests/fetch-carrier.spec.ts
@@ -349,6 +349,68 @@ describe('unary round trip (handler ⇄ client, no network)', () => {
     expect(skills.result).toEqual({ ok: true, value: { skills: [{ name: 'commit-helper', description: 'Git commits' }] } })
   })
 
+  it('lets command.execute finish after the 30-second default unary deadline', async () => {
+    vi.useFakeTimers()
+    const timeoutSpy = vi.spyOn(AbortSignal, 'timeout').mockImplementation((milliseconds) => {
+      const controller = new AbortController()
+      setTimeout(() => {
+        controller.abort(new DOMException('The operation was aborted due to timeout', 'TimeoutError'))
+      }, milliseconds)
+      return controller.signal
+    })
+    try {
+      const api = fakeApi()
+      api.commands.execute = async (request) => {
+        await new Promise(resolve => setTimeout(resolve, 30_001))
+        return {
+          rpcId: request.rpcId,
+          result: { ok: true, value: { matched: true, commandId: CommandId('cmd-slow') } },
+        }
+      }
+      const execution = client(api).commands.execute({ sessionId: 's' as never, line: '/slow' })
+      const assertion = expect(execution).resolves.toMatchObject({
+        result: { ok: true, value: { matched: true, commandId: 'cmd-slow' } },
+      })
+
+      await Promise.all([
+        vi.advanceTimersByTimeAsync(30_001),
+        assertion,
+      ])
+      expect(timeoutSpy).not.toHaveBeenCalled()
+    } finally {
+      timeoutSpy.mockRestore()
+      vi.useRealTimers()
+    }
+  })
+
+  it('keeps caller and connection aborts on command.execute', async () => {
+    const api = fakeApi()
+    const started = Promise.withResolvers()
+    api.commands.execute = async (request, signal) => {
+      started.resolve(signal)
+      if (!signal.aborted) {
+        await new Promise((resolve) => {
+          signal.addEventListener('abort', () => { resolve() }, { once: true })
+        })
+      }
+      return {
+        rpcId: request.rpcId,
+        result: { ok: false, error: { code: 'cancelled', message: 'aborted', details: {} } },
+      }
+    }
+    const controller = new AbortController()
+    const execution = client(api).commands.execute(
+      { sessionId: 's' as never, line: '/hang' },
+      controller.signal,
+    )
+    const handlerSignal = await started.promise
+
+    controller.abort(new Error('connection closed'))
+
+    await expect(execution).rejects.toThrow('connection closed')
+    expect(handlerSignal.aborted).toBe(true)
+  })
+
   it('propagates the carrier Request signal into command.execute', async () => {
     const handler = toFetchHandler(fakeApi())
     const controller = new AbortController()