Merge remote-tracking branch 'origin/master' into worktree/pr799-merge-20260731-final

# Conflicts: # packages/client/ui-conversation/README.i18n.yaml
2026-07-31 17:10:25 +08:00
parent 1974825381 c6b770e681
commit e5232adcf3
53 changed files with 2859 additions and 243 deletions
@@ -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-20-dsh-cli-personal-config.md
-2026-07-20-dsh-cli-personal-config.md: 3331e36c86002d91fb272868268707fed014d01a
-2026-07-20-dsh-cli-personal-config.zh.md: 172d84b075ed7ecc127c317b47e30581db67f89a
+2026-07-20-dsh-cli-personal-config.md: 259c3865a9edcbc77949a9fe401af9a77e1e32c4
+2026-07-20-dsh-cli-personal-config.zh.md: 8f7c15c3c683cc855c6e3b704bfde8f87d4009d2
@@ -39,9 +39,9 @@ Hot-reload interplay: the include re-applies its `patches` on every config re-re
 ## Consequences

 - `dsh` from any directory (and `pnpm run demo:tui`) boots the personal provider/model with zero repo changes; verified end-to-end against a personal Anthropic proxy with Opus 4.8, including a bash tool round trip.
- Because an id-targeted patch replaces the whole `config`, a personal override restates the base fields it keeps and can drift when the base entry changes shape; the loader's entry-not-found/name-mismatch warnings are the only diagnostics.
+- Because an id-targeted patch replaces the whole `config`, a personal override restates the base fields it keeps and can drift when the base entry changes shape; the loader's entry-not-found/name-mismatch warnings and [`dsh --dump-config`](2026-07-30-dsh-dump-config.md) (which prints the composed tree those patches produce) are the diagnostics.
 - Personal patches resolve ids against the booted file's own tree, so nested-include overlays (Code Mode) are not personalized; live-run parity for those leaves is deferred.
- `dsh-app-boot` depends on `js-yaml` (plus a load-only copy of the include's `!!js` YAML type) and, like `apps/cli`, on `@deepseek-ai/dsh-paths` for `resolveDshHome`.
+- `dsh-app-boot` depends on `js-yaml` and imports the include's `!!js` YAML dialect (`entryListSchema`) directly, and, like `apps/cli`, depends on `@deepseek-ai/dsh-paths` for `resolveDshHome`.
 - When PR #443 lands, `apps/cli/src/bin.ts`'s dispatch chain and `apps/cli/package.json`'s dependency list conflict textually; both resolve as unions (their `web`/`-p` branches plus our default-TUI branch).

 ## Testing
@@ -39,9 +39,9 @@ PTY 冒烟测试的启动器把 `$DSH_HOME` 隔离到每个测试自己的目录
 ## Consequences

 - 在任意目录运行 `dsh`（以及 `pnpm run demo:tui`）即可零仓库改动地使用个人提供方/模型；已针对个人 Anthropic 代理与 Opus 4.8 端到端验证，包括一次 bash 工具往返。
- 由于按 id 定位的补丁替换整个 `config`，个人覆盖必须复述它保留的基础字段，并可能随基础配置项形态变化而漂移；loader 的「配置项未找到/名称不匹配」警告是仅有的诊断。
+- 由于按 id 定位的补丁替换整个 `config`，个人覆盖必须复述它保留的基础字段，并可能随基础配置项形态变化而漂移；诊断手段是 loader 的「配置项未找到/名称不匹配」警告和 [`dsh --dump-config`](2026-07-30-dsh-dump-config.md)（打印这些补丁合成出的配置树）。
 - 个人补丁只在被启动文件自身的树里解析 id，因此嵌套 include 的 overlay（Code Mode）不会被个性化；这些叶子的实际运行等价性暂缓。
- `dsh-app-boot` 依赖 `js-yaml`（外加一份只用于加载的 include `!!js` YAML 类型副本），并与 `apps/cli` 一样依赖 `@deepseek-ai/dsh-paths` 以获取 `resolveDshHome`。
+- `dsh-app-boot` 依赖 `js-yaml`，并直接导入 include 的 `!!js` YAML 方言（`entryListSchema`）；与 `apps/cli` 一样依赖 `@deepseek-ai/dsh-paths` 以获取 `resolveDshHome`。
 - PR #443 落地时，`apps/cli/src/bin.ts` 的分发链与 `apps/cli/package.json` 的依赖列表会产生文本冲突；两者都按并集解决（他们的 `web`/`-p` 分支加上我们的默认 TUI 分支）。

 ## Testing
@@ -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-dsh-dump-config.md
+2026-07-30-dsh-dump-config.md: bc6504541c7868bad019a1bcd9f551435109e4c6
+2026-07-30-dsh-dump-config.zh.md: 5e173305a6cd03de3db4c763f26eeda6fba68ec7
@@ -0,0 +1,31 @@
+# Agent Note: dsh --dump-config prints the composed config tree
+
+Status: implemented
+
+English | [中文](2026-07-30-dsh-dump-config.zh.md)
+
+## Problem
+
+The booted tree is a composition the user never sees: the shipped base, a surface overlay, and the `--config` or personal `~/.dsh/config.yaml` overlay apply as sibling patch lists where each id-targeted patch replaces the row's whole `config` and an unmatched id only warns. Debugging a misbehaving personal overlay (a restated field dropped, a row id typo, a patch applying to the wrong surface) required mentally replaying the patch algorithm across three files. There was no way to see the effective tree or to diff it against the shipped defaults.
+
+## Decision
+
+`dsh --dump-config` and `dsh web --dump-config` print the composed entry list — base, surface overlay, then the `--config` or personal overlay, exactly the layers that surface's boot assembles — as YAML on stdout and exit without booting. `dsh --dump-default-config` / `dsh web --dump-default-config` stop at the surface overlay, so diffing the two outputs shows precisely what the user layer changes.
+
+The dump cannot drift from what boots because it shares the mounting code: the vendored include exports its patch algorithm as the pure `applyEntryPatches(data, patches, warn)` (the private `applyPatches` method now delegates to it) and its `!!js` YAML dialect as `entryListSchema`; `dsh-app-boot`'s `renderConfigDump()` composes labeled layers and renders through both, and `apps/cli/src/dump-config.ts` is a thin surface-selection wrapper. `!!js` expressions print verbatim and unevaluated — the dump shows composition, not one process's environment — and a patch whose target row is absent goes to stderr with its layer label, mirroring the Loader's boot-time warning. Launcher-owned boot-context values (session identity, web CLI-flag patches, the frontend dist path) are per-invocation facts outside the config tree and do not appear. The dump flags reject boot-only flags (`-p`, `--resume`, `--config-replace`) and each other, and `--dump-default-config` takes no `--config`.
+
+Each run of same-provenance rows is preceded by a `# ==` comment naming the file that contributed the rows and the layers that patched them (`# == base.cordis.yml, patched by tui.cordis.yml`), so the output shows which section comes from which file while remaining one loadable YAML document. Composition is one flattened `applyEntryPatches` call over all layers — boot's exact call shape, so even patch-visibility corner cases (a later layer targeting a group child that a plain `config` replacement introduced, invisible to the single-pass id index) compose identically; applying one call per layer would rebuild the index between layers and print a tree boot never mounts. Provenance is derived from single-call prefix snapshots (base + layers 1..k) diffed positionally: the patch algorithm only rewrites rows in place or appends, so a top-level index identifies one row across snapshots, and a layer counts as having patched a row when adding it changed that row (config replacement, disable, group insert). Patch lists are cloned per snapshot because `applyEntryPatches` pushes `insert` rows by reference from the patch list.
+
+`dsh-app-boot` previously duplicated the include's `!!js` YAML type for patch parsing; it now imports `entryListSchema`, so the dialect has one owner.
+
+## Alternatives considered
+
+**Boot the tree and dump `ctx.loader.entries()`.** Rejected: booting evaluates `!!js` expressions (leaking one machine's environment into the printed config), starts adapters and sessions as side effects, requires a TTY-independent teardown path, and is slow. The dump is for debugging composition, which is a pure function of the files.
+
+**Reimplement the patch merge in the CLI.** Rejected: a second implementation of `applyPatches` would silently drift from the vendored include — the exact failure mode the feature exists to debug. Exporting the include's own algorithm costs one logged vendor modification and guarantees identity.
+
+**A `/dump-config` TUI command instead of flags.** Rejected as the only form: the primary use is a piped `dsh --dump-config | diff - <(dsh --dump-default-config)` style workflow, which needs a boot-free non-TTY surface. A TUI command can be added later over the same `renderConfigDump`.
+
+## Consequences
+
+Config debugging becomes one command instead of mental patch replay, and support can ask for `--dump-config` output. The vendored include carries one more logged local modification (the `applyEntryPatches`/`entryListSchema` exports; behavior-preserving for mounting) to re-apply on upstream sync. Provenance tracking re-composes one prefix snapshot per layer and diffs rows by JSON stringify, so the dump does extra work proportional to layers² × rows; that cost lives only in the boot-free dump path. `renderConfigDump` is unit-tested for layer ordering, verbatim `!!js` round-tripping, provenance separators and grouping, labeled unmatched-patch warnings, and loud read/parse/shape failures; the built-bin e2e drives all four flag forms through `lib/bin.js` including the personal-overlay layer, its provenance label, and its stderr warning.
@@ -0,0 +1,31 @@
+# Agent Note: dsh --dump-config 打印合成后的配置树
+
+Status: implemented
+
+[English](2026-07-30-dsh-dump-config.md) | 中文
+
+## Problem
+
+启动的配置树是一份用户从未见过的合成结果：已交付的基础配置、界面覆盖层，以及 `--config` 或个人 `~/.dsh/config.yaml` 覆盖层作为同级补丁列表依次应用，其中每个按 id 定向的补丁替换目标行的整个 `config`，未匹配的 id 只产生警告。调试一个行为异常的个人覆盖层（漏掉需要重述的字段、行 id 拼错、补丁应用到了错误的界面）需要在脑中跨三个文件重放补丁算法。既没有办法看到生效的树，也没有办法把它与已交付的默认值做 diff。
+
+## Decision
+
+`dsh --dump-config` 和 `dsh web --dump-config` 把合成后的条目列表——基础配置、界面覆盖层、再叠 `--config` 或个人覆盖层，恰好是该界面启动时组装的那些层——以 YAML 打印到 stdout 后退出，不启动任何东西。`dsh --dump-default-config` / `dsh web --dump-default-config` 止步于界面覆盖层，因此对两份输出做 diff 就能精确看出用户层改了什么。
+
+dump 不可能与实际启动漂移，因为它复用挂载代码：vendored include 把补丁算法导出为纯函数 `applyEntryPatches(data, patches, warn)`（私有的 `applyPatches` 方法现在委托给它），并把 `!!js` YAML 方言导出为 `entryListSchema`；`dsh-app-boot` 的 `renderConfigDump()` 通过这两者对带标签的层完成合成与渲染，`apps/cli/src/dump-config.ts` 只是选择界面的薄封装。`!!js` 表达式原样打印、不求值——dump 展示的是合成结果，不是某个进程的环境——目标行不存在的补丁会连同其层标签报到 stderr，与 Loader 启动时的警告一致。由启动器持有的启动上下文值（会话身份、web 的 CLI 标志补丁、前端 dist 路径）是每次调用的事实，位于配置树之外，不会出现。dump 标志拒绝仅用于启动的标志（`-p`、`--resume`、`--config-replace`）且两个 dump 标志互斥，`--dump-default-config` 不接受 `--config`。
+
+每段来源相同的连续行之前都有一条 `# ==` 注释，标明贡献这些行的文件以及修补过它们的层（`# == base.cordis.yml, patched by tui.cordis.yml`），因此输出既展示每一节来自哪个文件，又仍是一份可加载的 YAML 文档。合成是对所有层展平后的一次 `applyEntryPatches` 调用——与启动的调用形状完全一致，因此即便是补丁可见性的边角情况（后一层定位到前一层通过普通 `config` 替换引入的组内子项，而单遍 id 索引看不到它）也与启动合成完全相同；若按层各调用一次，会在层与层之间重建索引，打印出一棵启动从不挂载的树。来源从单次调用的前缀快照（基础 + 第 1..k 层）按位置 diff 得出：补丁算法只会原地改写行或在末尾追加，因此顶层索引在各快照之间标识同一行；加入某层后该行发生变化（替换 config、禁用、组内插入）即视为该层修补了这一行。每个快照都会克隆补丁列表，因为 `applyEntryPatches` 会把 `insert` 行按引用从补丁列表推入结果。
+
+`dsh-app-boot` 之前为解析补丁复制了 include 的 `!!js` YAML 类型；现在改为导入 `entryListSchema`，方言只有一个归属者。
+
+## Alternatives considered
+
+**启动整棵树后 dump `ctx.loader.entries()`。** 拒绝：启动会求值 `!!js` 表达式（把某台机器的环境泄漏进打印的配置）、以副作用启动适配器和会话、需要独立于 TTY 的拆卸路径，而且慢。dump 是用来调试合成的，而合成是那些文件的纯函数。
+
+**在 CLI 里重新实现补丁合并。** 拒绝：`applyPatches` 的第二个实现会与 vendored include 悄然漂移——这恰恰是该功能要调试的失败模式。导出 include 自己的算法只花费一条记录在案的 vendor 修改，却保证了同一性。
+
+**用 `/dump-config` TUI 命令代替标志。** 作为唯一形式被拒绝：主要用法是 `dsh --dump-config | diff - <(dsh --dump-default-config)` 这类管道工作流，需要免启动、非 TTY 的界面。之后可以在同一个 `renderConfigDump` 之上再加 TUI 命令。
+
+## Consequences
+
+配置调试从脑中重放补丁变成一条命令，支持工作也可以直接索要 `--dump-config` 输出。vendored include 多出一条记录在案的本地修改（导出 `applyEntryPatches`/`entryListSchema`；对挂载行为无影响），上游同步时需重新应用。来源追踪为每层重新合成一次前缀快照并按 JSON stringify 对行做 diff，因此 dump 有与层数²×行数成正比的额外开销；该开销只存在于免启动的 dump 路径。`renderConfigDump` 的单元测试覆盖层叠顺序、`!!js` 原样往返、来源分隔与分组、带标签的未匹配补丁警告，以及读取／解析／形状失败的大声报错；built-bin e2e 通过 `lib/bin.js` 驱动全部四种标志形式，包括个人覆盖层、其来源标签及其 stderr 警告。
@@ -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-search-card.md
+2026-07-30-web-search-card.md: 4c7ae6c8c658f4f10f0667b12853cb2e70df15b1
+2026-07-30-web-search-card.zh.md: 714a2979730dc2c83f6cfc1cf6d21978755a2d95
@@ -0,0 +1,65 @@
+# Agent Note: Web search card — the grep and glob render intent reaches the browser
+
+Status: implemented
+
+English | [中文](2026-07-30-web-search-card.zh.md)
+
+## Problem
+
+The `grep` and `glob` tools declare a result-time `card: 'search'` render intent ([search render card](2026-07-30-search-render-card.md)): a `SearchMatchesResultView` (`shape: 'matches'`) carrying grep's matches grouped by file, or a `SearchPathsResultView` (`shape: 'paths'`) carrying glob's flat path list, both with a `truncated`/`total` capping signal. That view already reaches the browser — host, connection, and runtime deliver it onto `ConversationSnapshot` as `resultView` — but the Web client ignored it: every non-terminal, non-diff tool result fell through to the generic card, which renders the model-facing text. A web frontend that wants an expandable per-file group of matches, or a scannable path list, had only the pre-formatted text.
+
+This is the follow-up the search render card note names: that PR was the backend contract and its two producers; this PR is the web consumer.
+
+## Decision
+
+`SearchBlock` is a `ui-primitives` component that renders a completed search as either shape, and the Web render sites for a `grep`/`glob` call consume the search render intent through it. `ui-conversation/src/client/contract/search-card-model.ts` is the single place that turns the snapshot's `resultView` into the component's props, so no render site re-derives the shape. It returns null — the generic path — whenever the result view is not a search card, including a still-running call (a search card is result-time only, so there is nothing before `execute`), a generic result a `grep`/`glob` failure or a nested `run_code` dispatch produces, a terminal result view, a `card` value this client version does not know, a `card: 'search'` view whose `shape` this version does not compile, and — because `shape` and the grouped/flat contents ride the same untrusted wire frame the host schema only string-checks — a known `shape` whose `files`/`paths` is missing or malformed (which would otherwise crash `SearchBlock` at `.reduce`/`.map`). The result-view discriminant is `shape` (not `kind`, which the backend reserves for the call view's icon-picking tag); `SearchBlock`'s own prop stays `kind`, mapped from `shape` in this derivation.
+
+The asymmetry with the terminal card is deliberate and inherited from the backend contract: `terminalCardModel` reads both `callView` and `resultView` because a command, cwd, and description exist at call time; `searchCardModel` reads only `resultView` because a search's matches or paths exist only after execution. A running search row therefore shows its summary alone, with no card.
+
+One component draws both shapes, discriminated by `kind`, because `grep` and `glob` are the same visual object — a search result. `SearchMatchesBlockProps` (`kind: 'matches'`) and `SearchPathsBlockProps` (`kind: 'paths'`) keep each shape's fields required rather than a single interface with everything optional. The component flattens whichever shape it holds into one list of render rows — a file header row plus its match rows for the matches shape, one path row per path for the paths shape — so the height cap counts a file header as one row exactly as a match line or a path, and the head/tail slice arithmetic is `TerminalBlock`'s (`ceil(max/2)` head, the remainder tail), so a long search result and a long command output cut at the same place across the two cards.
+
+The component's contract:
+
+- **Grouped matches, collapsible per file.** Each file is a header row (a bold path plus its match count, the whole row the collapse control) followed by its `lineNumber: line` rows. Collapsing a group drops its match rows from the flattened list and from the height cap's arithmetic, but never from the copy text.
+- **Flat path list.** The paths shape renders one path per row, no headers.
+- **A capped indicator.** When `truncated`, the banner summary folds the pre-cap total in — `显示 X / 共 N 处匹配 · K 个文件` for grep, `显示 X / 共 N 个路径` for glob — so the card never presents a capped page as the complete result. When not `truncated` the summary is a plain structural count (`{n} 处匹配 · {m} 个文件`, or `{n} 个路径`).
+- **A recovery footer for a capped result.** The card holds only the retained page, but the locator to the rest — grep/glob's `Full … stored at: <locator>` footer — lives only in the raw `tool/result` content (the search view carries no result text; a UI without a card falls back to that raw content), not in the structured matches/paths. Because every render site replaces the raw result with the card, `searchCardModel` surfaces the block's own flattened result text as `SearchCardModel.recovery` when (and only when) the result was capped, and each render site draws it below the card. Without this the one path to the dropped rows would vanish from the UI; an uncapped result carries every row, so its raw text adds nothing and is dropped.
+- **No soft wrapping.** Result rows are `white-space: pre` inside a horizontally scrolling box, so a long match line or a deep path scrolls sideways rather than folding.
+- **Height cap with an expand control.** More than `DEFAULT_SEARCH_MAX_LINES` (16) rows shows a head/tail slice with a button reporting the hidden count, the same shape and arithmetic as `TerminalBlock`.
+- **Copy.** The copy control writes the whole structured result — every file and match, or every path — regardless of the height cap or which groups are collapsed, so the clipboard carries the result rather than what the card happens to be showing.
+
+Geometry, radius, and fonts mirror `CodeBlock` and `TerminalBlock`, so a search card reads as one family with them; `white-space: pre` plus horizontal scroll is the shared deliberate divergence.
+
+### Render sites
+
+Three sites consume the derivation, mirroring the terminal card's placement exactly:
+
+- **The keyed `SearchRow`** (`toolviews/search-row.tsx`) registers ONE component under both `grep` and `glob` in the `conversation.chat.toolview` keyed hole, and renders the card RESIDENT under the summary row, capped at `CHAT_SEARCH_MAX_LINES` (8) — the same posture `BashRow` takes for its terminal card. Both tool names get the same row because the derived `kind` decides the shape, so a second component would duplicate it. A capped result's recovery footer sits below the card. Because the keyed row owns this render slot, a settled call with no search card — an errored search (grep/glob emit no result view on error), a successful nested `run_code` sub-dispatch (the backend computes no `presentationMeta`, so `resultView` is null), or a legacy generic result — would otherwise show only its summary with its content lost; the row surfaces that model-facing text as a fallback body, keyed on `search === null && settled` rather than on the error state alone. (This resident posture matches the current terminal/diff cards; a separate later PR unifies the whole-row collapse/expand interaction and flips all resident cards at once — out of scope here.)
+- **The generic fallback** (`chat/GenericToolCard` → `chat/ToolRow`) threads the derived model as an expand-gated body, the same arm `terminal` uses: a `grep`/`glob` result with no keyed row (none in the shipped app, since both are registered) still renders its card, with the recovery footer, behind the row's expand toggle.
+- **The details panel** (`skeleton/DetailsPanel`) renders the card at the primitive's own full height in the Output section, with the recovery footer below it, keeping the JSON Input section.
+
+`CHAT_SEARCH_MAX_LINES` (8) is the row cap, half the primitive's default the panel keeps, for the same reason as `CHAT_TERMINAL_MAX_LINES`: the chat flow is a summary surface read across many calls, the panel is the single-call reading surface.
+
+## Alternatives considered
+
+**Two card components, one per tool.** Rejected: `grep` and `glob` are the same visual object discriminated only by `kind`, so two components would duplicate the banner, the height cap, the copy control, and the no-wrap geometry. One component switching on `kind` is what the backend's single `card: 'search'` view is for.
+
+**A `SearchCallView` so the row renders a card while the search runs.** Rejected: the backend contract deliberately has no call-time search view — a search has no matches or paths before `execute`. The running row shows its summary alone, and `searchCardModel` returns null for a running block, which is faithful to what exists.
+
+**Reuse `TerminalBlock` or `CodeBlock`.** Rejected: neither models per-file collapsible groups or a folded capped-result summary, and both would need the grouped-matches shape bolted on. The three blocks share their geometry and font tokens instead, which is the only part where one implementation is correct for all.
+
+## Consequences
+
+`SearchBlock` reads only the search view's fields, so it stays a pure function of what the render intent carries — no session lookups, replay-safe like the presenters that produce the view. A UI without the search capability still gets the bridge's fenced fallback; nothing about the tool's result shape changed. Extending `ToolRow` with a `search` body prop adds one arm beside `terminal`; a call carries at most one card kind, so the two are never both present on a row.
+
+## Testing
+
+`packages/client/ui-primitives/tests/search-block.spec.tsx` pins the component at per-file 100%: both kinds, the folded pre-cap total in the summary, the empty arm, per-file collapse/re-expand without touching neighbours, a file header counting as one capped row alongside its matches, the tail slice restoring its owning file header when the cut falls mid-file, the head/tail cap and its expand control across both shapes and the no-tail and default-cap edges, and the copy control writing the whole structured result on the accepted and refused clipboard paths.
+
+`packages/client/ui-conversation/tests/search-card.spec.tsx` pins the wiring at every render site: `searchCardModel`'s derivation for both kinds, the truncation signal, the replacement title, the recovery text surfaced only when capped, each null arm (running, no views, generic, terminal, unknown card, an uncompiled `kind`, and a known kind with a missing/malformed shape); the chat row's expand-gated matches and paths bodies through `GenericToolCard` (with the recovery footer) against the non-search args-JSON body; `SearchRow`'s resident card for both kinds, its recovery footer, its fallback body for both an errored search and a settled cardless result, its agreement with the summary row's run state, the replacement-title precedence, and the keyed registration under both `grep` and `glob` with one component; and the details panel's Output section for both kinds (with the recovery footer) against the non-search flattened form. `packages/client/ui-conversation/src/*` sits on the coverage exclude list, so this file is written against no gate pressure. `packages/client/connection/src/client/fixture.ts` gains a `grep` turn emitting `kind: 'matches'` (three files, twelve rows over the row cap, `truncated` with a spill-recovery footer, so it exercises the head/tail cap and the recovery footer in the assembled snapshot) and a `glob` turn emitting `kind: 'paths'`, both driving the built-boot snapshot and the live `?fixture` server. `apps/web/tests/search-card.snapshot.ts` is the assembled-output check the repo contract asks for: it boots the real built `client.js` bundles through the keyless fixture transport, opens the fixture session, and pins the grep card's assembled shape — kind, truncation summary, the head/tail slice, and its expand control — under `apps/web/tests/snapshots/search-card/`, so a broken SearchRow registration or a dropped card fails a golden the built-boot smoke (boot-only by contract) cannot.
+
+## Related
+
+- [Search render intent — grep and glob emit a structured search card](2026-07-30-search-render-card.md) — the backend contract and its two producers; this is its named web-consumer follow-up.
+- [Web terminal card](2026-07-28-web-terminal-card.md) — the precedent this mirrors: a tool's render intent reaches the browser through a `ui-primitives` block, a single `contract/*-card-model.ts` derivation, and the same three render sites.
+- [Tagged render-intent union for tool-call presentation](../architecture/2026-07-02-tool-render-intent-union.md) — the `card`-tagged vocabulary both cards consume.
@@ -0,0 +1,65 @@
+# Agent Note：Web 搜索卡片 —— grep 与 glob 的 render intent 到达浏览器
+
+Status: implemented
+
+[English](2026-07-30-web-search-card.md) | 中文
+
+## Problem
+
+`grep` 与 `glob` 工具声明了一个仅在结果阶段存在的 `card: 'search'` render intent（[search render card](2026-07-30-search-render-card.md)）：`SearchMatchesResultView`（`shape: 'matches'`）携带 grep 按文件分组的匹配，或 `SearchPathsResultView`（`shape: 'paths'`）携带 glob 的扁平路径列表，两者都带 `truncated`/`total` 截断信号。该视图已经到达浏览器 —— host、connection、runtime 把它作为 `resultView` 投递到 `ConversationSnapshot` 上 —— 但 Web 客户端忽略了它：每个非终端、非 diff 的工具结果都落到 generic 卡片，渲染面向模型的文本。想把搜索结果渲染成可展开的按文件匹配分组、或可扫读的路径列表的 web 前端，只有那段预格式化文本。
+
+这正是 search render card note 指名的后续：那个 PR 是后端契约和它的两个生产者，本 PR 是 web 消费者。
+
+## Decision
+
+`SearchBlock` 是一个 `ui-primitives` 组件，把一次已完成的搜索渲染成两种形态之一，`grep`/`glob` 调用的 Web 渲染点都通过它消费搜索 render intent。`ui-conversation/src/client/contract/search-card-model.ts` 是把 snapshot 的 `resultView` 转成组件 props 的唯一位置，因此没有渲染点重新推导形态。当结果视图不是搜索卡片时它返回 null（走 generic 路径），包括仍在运行的调用（搜索卡片仅在结果阶段存在，`execute` 前无内容）、`grep`/`glob` 失败或嵌套 `run_code` dispatch 产生的 generic 结果、terminal 结果视图、本客户端版本不认识的 `card` 值、`shape` 是本版本无法编译的 `card: 'search'` 视图，以及 —— 因为 `shape` 和分组/扁平内容与 host schema 只做字符串校验的那同一个不可信 wire 帧同行 —— 一个 `shape` 已知但 `files`/`paths` 缺失或格式错误的视图（否则会让 `SearchBlock` 在 `.reduce`/`.map` 处崩溃）。结果视图的判别键是 `shape`（不是 `kind` —— 后端把 `kind` 留给 call view 的选图标签）；`SearchBlock` 自身的 prop 仍是 `kind`，由本推导从 `shape` 映射得到。
+
+与终端卡片的不对称是刻意的，继承自后端契约：`terminalCardModel` 同时读 `callView` 和 `resultView`，因为命令、cwd、description 在调用时就存在；`searchCardModel` 只读 `resultView`，因为搜索的匹配或路径只在执行后存在。因此运行中的搜索行只显示摘要，没有卡片。
+
+一个组件绘制两种形态，用 `kind` 区分，因为 `grep` 和 `glob` 是同一个视觉对象 —— 一个搜索结果。`SearchMatchesBlockProps`（`kind: 'matches'`）和 `SearchPathsBlockProps`（`kind: 'paths'`）让每种形态的字段保持必填，而不是所有字段都可选的单一接口。组件把它持有的形态压平成一个渲染行列表 —— matches 形态是一个文件头行加它的匹配行，paths 形态是每个路径一行 —— 于是高度上限把一个文件头当作一行来计，与一条匹配行或一个路径相同，头/尾切片算术就是 `TerminalBlock` 的（`ceil(max/2)` 头，其余为尾），因此一个长搜索结果和一段长命令输出在两张卡片间在同一处截断。
+
+组件契约：
+
+- **按文件分组的匹配，逐文件可折叠。** 每个文件是一个头行（加粗路径加它的匹配计数，整行即折叠控件），后面跟它的 `lineNumber: line` 行。折叠一个组会把它的匹配行从压平列表和高度上限的算术里去掉，但绝不从复制文本里去掉。
+- **扁平路径列表。** paths 形态每行一个路径，无头行。
+- **截断指示。** `truncated` 时，横幅摘要把截断前总数折入 —— grep 为 `显示 X / 共 N 处匹配 · K 个文件`，glob 为 `显示 X / 共 N 个路径` —— 因此卡片绝不把一个被截断的页面呈现为完整结果。未 `truncated` 时摘要是一个朴素的结构计数（`{n} 处匹配 · {m} 个文件`，或 `{n} 个路径`）。
+- **被截断结果的恢复脚注。** 卡片只持有保留的那一页，但通往其余部分的定位符 —— grep/glob 的 `Full … stored at: <locator>` 脚注 —— 只存在于原始 `tool/result` 内容里（搜索视图不携带结果文本；没有卡片的 UI 回退到那段原始内容），而非结构化的 matches/paths 中。由于每个渲染点都用卡片替换了原始结果，`searchCardModel` 在（且仅在）结果被截断时把 block 自身压平后的结果文本作为 `SearchCardModel.recovery` 暴露出来，每个渲染点把它画在卡片下方。没有它，通往被丢弃行的唯一路径就会从 UI 里消失；未截断的结果携带了每一行，其原始文本不增加任何信息，因此被丢弃。
+- **不软换行。** 结果行在一个横向滚动的盒子里 `white-space: pre`，因此一条长匹配行或一个深路径横向滚动而不折叠。
+- **带展开控件的高度上限。** 超过 `DEFAULT_SEARCH_MAX_LINES`（16）行时显示一个头/尾切片，中间一个按钮报告被隐藏的行数，形状和算术与 `TerminalBlock` 相同。
+- **复制。** 复制控件写入整个结构化结果 —— 每个文件与匹配，或每个路径 —— 无关高度上限或哪些组被折叠，因此剪贴板携带的是结果本身，而不是卡片此刻恰好显示的内容。
+
+几何、圆角、字体镜像 `CodeBlock` 与 `TerminalBlock`，因此搜索卡片与它们读作同一族；`white-space: pre` 加横向滚动是它们共享的刻意分歧。
+
+### 渲染点
+
+三个渲染点消费该推导，与终端卡片的落位完全一致：
+
+- **keyed `SearchRow`**（`toolviews/search-row.tsx`）把一个组件同时注册到 `conversation.chat.toolview` keyed hole 的 `grep` 与 `glob` 键下，并把卡片作为常驻（resident）渲染在摘要行下方，上限为 `CHAT_SEARCH_MAX_LINES`（8）—— 与 `BashRow` 对其终端卡片采取的姿态相同。两个工具名共用同一行，因为推导出的 `kind` 决定形态，第二个组件只会重复它。被截断结果的恢复脚注画在卡片下方。因为 keyed 行占据了这个渲染槽，一个没有搜索卡片的已结算调用 —— 出错的搜索（grep/glob 出错时不产出结果视图）、成功的嵌套 `run_code` 子派发（后端不为其计算 `presentationMeta`，故 `resultView` 为 null）、或旧日志的 generic 结果 —— 否则只会显示摘要而丢失内容；该行把这段面向模型的文本作为 fallback body 暴露出来，判据是 `search === null && 已结算`，而非仅凭错误状态。（该常驻姿态与当前的 terminal/diff 卡片一致；一个单独的后续 PR 会统一整行折叠/展开交互并一次性翻转所有常驻卡片 —— 不在本 PR 范围内。）
+- **generic fallback**（`chat/GenericToolCard` → `chat/ToolRow`）把推导出的 model 作为展开门控的 body 传入，与 `terminal` 用的是同一分支：没有 keyed 行的 `grep`/`glob` 结果（发布应用里没有，因为两者都注册了）仍在行的展开开关后渲染其卡片，并带恢复脚注。
+- **details panel**（`skeleton/DetailsPanel`）在 Output 段以 primitive 自身的完整高度渲染卡片，恢复脚注画在其下方，保留 JSON Input 段。
+
+`CHAT_SEARCH_MAX_LINES`（8）是行内上限，为 primitive 默认值的一半（panel 保留默认值），理由与 `CHAT_TERMINAL_MAX_LINES` 相同：chat 流是跨多次调用扫读的摘要表面，panel 是单次调用的阅读表面。
+
+## Alternatives considered
+
+**两个卡片组件，每个工具一个。** 否决：`grep` 与 `glob` 是仅由 `kind` 区分的同一视觉对象，两个组件会重复横幅、高度上限、复制控件与不换行几何。一个按 `kind` 分支的组件正是后端那个单一 `card: 'search'` 视图的用途。
+
+**加一个 `SearchCallView`，让行在搜索运行时就渲染卡片。** 否决：后端契约刻意没有调用阶段的搜索视图 —— 搜索在 `execute` 前没有匹配或路径。运行中的行只显示摘要，`searchCardModel` 对运行块返回 null，忠实于实际存在的东西。
+
+**复用 `TerminalBlock` 或 `CodeBlock`。** 否决：两者都不建模逐文件可折叠的组或折叠式截断摘要，都需要把按文件分组的形态硬塞进去。三个块转而共享几何与字体 token，那是唯一一处一个实现对三者都正确的部分。
+
+## Consequences
+
+`SearchBlock` 只读搜索视图的字段，因此保持为 render intent 所携内容的纯函数 —— 无会话查询，与产生该视图的 presenter 一样可重放。没有搜索能力的 UI 仍得到 bridge 的围栏回退；工具的结果形态没有任何改变。给 `ToolRow` 扩一个 `search` body prop 只在 `terminal` 旁加一个分支；一次调用至多携带一种卡片，因此两者绝不同时出现在一行。
+
+## Testing
+
+`packages/client/ui-primitives/tests/search-block.spec.tsx` 以 per-file 100% 覆盖固定组件：两种 kind、折入摘要的截断前总数、空结果分支、逐文件折叠/再展开且不影响邻居、一个文件头与其匹配一起计为一个被截断行、切口落在文件中间时尾部切片恢复其所属文件头、跨两种形态的头/尾上限及其展开控件（含无尾与默认上限的边界），以及复制控件在接受与拒绝的剪贴板路径上写入整个结构化结果。
+
+`packages/client/ui-conversation/tests/search-card.spec.tsx` 固定每个渲染点的接线：`searchCardModel` 对两种 kind 的推导、截断信号、替换标题、仅在截断时暴露的恢复文本，以及每个 null 分支（运行中、无视图、generic、terminal、未知卡片、本版本无法编译的 `kind`、以及一个形态缺失/错误的已知 kind）；通过 `GenericToolCard` 的展开门控 matches 与 paths body（含恢复脚注），对照非搜索的 args-JSON body；`SearchRow` 对两种 kind 的常驻卡片、它的恢复脚注、它对出错搜索与已结算无卡片结果两者的 fallback body、它与摘要行运行状态的一致、替换标题优先级，以及一个组件在 `grep` 与 `glob` 两个键下的 keyed 注册；以及 details panel 的 Output 段对两种 kind（含恢复脚注），对照非搜索的压平形态。`packages/client/ui-conversation/src/*` 在覆盖排除清单上，因此该文件不受 gate 压力。`packages/client/connection/src/client/fixture.ts` 新增一个发出 `kind: 'matches'` 的 `grep` turn（三个文件、十二行超过行内上限、`truncated` 且带溢出恢复脚注，因此在组装快照里同时演练头/尾上限与恢复脚注）与一个发出 `kind: 'paths'` 的 `glob` turn，两者都驱动 built-boot snapshot 与实时 `?fixture` 服务。`apps/web/tests/search-card.snapshot.ts` 是仓库契约要求的组装输出检查：它通过 keyless fixture 传输启动真实构建的 `client.js` bundle，打开 fixture 会话，并把 grep 卡片的组装形态——kind、截断摘要、头/尾切片及其展开控件——固定在 `apps/web/tests/snapshots/search-card/` 下，因此一个损坏的 SearchRow 注册或被丢弃的卡片会让一个 golden 失败，而 built-boot smoke（按契约只测启动）无法捕获它。
+
+## Related
+
+- [Search render intent —— grep 与 glob 发出结构化搜索卡片](2026-07-30-search-render-card.md) —— 后端契约与它的两个生产者；本 note 是它指名的 web 消费者后续。
+- [Web 终端卡片](2026-07-28-web-terminal-card.md) —— 本 note 镜像的先例：工具的 render intent 通过一个 `ui-primitives` 块、一个 `contract/*-card-model.ts` 推导、以及同样的三个渲染点到达浏览器。
+- [工具调用呈现的标签化 render-intent 联合](../architecture/2026-07-02-tool-render-intent-union.md) —— 两张卡片都消费的 `card` 标签词汇。
@@ -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 apps/cli/README.md
-README.md: fc5bce195fb10872c605cada1bcb3ed79380265c
-README.zh.md: 2fb1272231abb02e145e5c9925362de27307ca86
+README.md: cf038ad19c631721c7b3182ffe83e75e3837d9ba
+README.zh.md: c790f973a9ab0071253ab161bd8bc7835ebb2e02
@@ -3,7 +3,7 @@
 English | [中文](README.zh.md)


-Argv is parsed once through a [Commander](https://github.com/tj/commander.js) adapter ([`src/args.ts`](src/args.ts)): one program whose default (no subcommand) is the TUI/headless surface (`--config`, `-p`/`--prompt`, `--resume`), whose `meta` subcommand is the same TUI over this checkout, whose `upgrade` subcommand is an option-less guided-session entry, and whose `web` subcommand is the browser UI. `src/bin.ts` switches on the resolved mode and dynamic-imports only that mode's module. `dsh --help` lists every mode and `dsh web --help` renders the web usage, `dsh --version` prints this app's version, and an unknown option or a mistyped `--resume` fails loud (stderr, exit 1) instead of misrouting. Every subcommand that shares no option with the default surface — `upgrade`, `web`, `meta` — rejects a leaked `--config`/`-p`/`--resume` rather than running and dropping it. `dsh web`'s `--host`/`--port` are unvalidated pass-through overrides: the `dsh-host-webserver` schema is the single source of both the default (the shipped Web overlay value when a flag is absent) and validity, and rejects a bad value at boot. `--trusted-host` appends named authorities for the /api browser-trust fence; an all-interfaces bind additionally derives the machine's LAN IP literals itself ([`src/app-cli-entry.ts`](src/app-cli-entry.ts)), so the printed LAN URL works without flags.
+Argv is parsed once through a [Commander](https://github.com/tj/commander.js) adapter ([`src/args.ts`](src/args.ts)): one program whose default (no subcommand) is the TUI/headless surface (`--config`, `-p`/`--prompt`, `--resume`, `--dump-config`, `--dump-default-config`), whose `meta` subcommand is the same TUI over this checkout, whose `upgrade` subcommand is an option-less guided-session entry, and whose `web` subcommand is the browser UI. `src/bin.ts` switches on the resolved mode and dynamic-imports only that mode's module. `dsh --help` lists every mode and `dsh web --help` renders the web usage, `dsh --version` prints this app's version, and an unknown option or a mistyped `--resume` fails loud (stderr, exit 1) instead of misrouting. Every subcommand that shares no option with the default surface — `upgrade`, `web`, `meta` — rejects a leaked `--config`/`-p`/`--resume`/dump flag rather than running and dropping it. `dsh web`'s `--host`/`--port` are unvalidated pass-through overrides: the `dsh-host-webserver` schema is the single source of both the default (the shipped Web overlay value when a flag is absent) and validity, and rejects a bad value at boot. `--trusted-host` appends named authorities for the /api browser-trust fence; an all-interfaces bind additionally derives the machine's LAN IP literals itself ([`src/app-cli-entry.ts`](src/app-cli-entry.ts)), so the printed LAN URL works without flags.

 The TUI surface:

@@ -17,6 +17,8 @@ The TUI surface:

 `dsh upgrade` is a guided fresh-session entry over the default TUI surface: it mints a fresh session in the invoking directory and seeds its first turn with the bundled `dsh-upgrade` skill, exactly as if the user typed `/skill:<name>`. The launcher passes the skill name on the boot context ([`INITIAL_SKILL_KEY`](../../packages/ui/tui/README.md)), which the TUI auto-invokes once the chat is live. Both take no options — `--config`, `-p`, and `--resume` fail loud — and seed only on this first launch, so a later `dsh --resume <id>` of the session is an ordinary TUI session with no re-injection.

+`dsh --dump-config` and `dsh web --dump-config` print the composed config tree — the shipped base, the surface overlay, and the `--config` or personal overlay, exactly the layers that surface would boot — as YAML on stdout and exit without booting; `--dump-default-config` stops at the surface overlay, so diffing the two shows precisely what the user layer changes. Each run of rows is preceded by a `# ==` comment naming the file it comes from and the layers that patched it (e.g. `# == base.cordis.yml, patched by tui.cordis.yml`), so the output shows provenance while staying one loadable document. Composition runs through the include's own patch algorithm and YAML dialect (`applyEntryPatches`/`entryListSchema` from `@cordisjs/plugin-include`), so the dump cannot drift from what boots; `!!js` expressions print verbatim and unevaluated, and a patch whose target row is absent is reported on stderr with its layer, mirroring the Loader's boot-time warning. Launcher-owned boot-context values (session identity, CLI-flag patches) are per-invocation facts outside the config tree and do not appear. The dump flags reject boot-only flags (`-p`, `--resume`, `--config-replace`) rather than silently ignoring them, and `--dump-default-config` takes no `--config`.
+
 The Web and headless surfaces boot `base.cordis.yml` plus `web.cordis.yml`, then apply `$DSH_HOME/config.yaml`; an explicit `--config <path>` replaces that personal overlay. Both surfaces otherwise share the same composition: both treat the invoking directory as the default project and Workspace root, create named Workspaces beneath that root unless `--workspace-root <path>` overrides it, load applicable `AGENTS.md`/`CLAUDE.md` instructions into each agent-loop request prefix with a 65,536-byte render budget, opt into first-message model titles, use the same bounded transient model-request retry policy as the TUI, and mount a disposable in-memory SQLite content-index service. That service is ACTIVE at boot, while its `node:sqlite` module and database handle open only on the first content search. This keeps Node 22 startup output free of SQLite's experimental warning before search is used; the first actual search may still emit the runtime warning. Each service instance owns its database, so parallel invocations neither share unsupported SQLite state nor leave derived index files behind, and the first search lazily reconciles live and persisted logs. Headless differs only in listening on an OS-assigned port (parallel `dsh -p` runs never collide; the stderr-printed URL opens the live session in a browser). Both need the frontend dist and client bundles built (`pnpm run build && pnpm run build:web`).

 The shipped TUI and Web compositions register the native DeepSeek adapter plus pi-ai OpenAI and Anthropic profiles. Credentials and endpoint overrides come from the provider-standard `DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL`, `OPENAI_API_KEY` / `OPENAI_BASE_URL`, and `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL` pairs in the boot's layered environment.
@@ -3,7 +3,7 @@
 [English](README.md) | 中文


-Argv 只会通过 [Commander](https://github.com/tj/commander.js) 适配器（[`src/args.ts`](src/args.ts)）解析一次：同一个程序的默认形式（无子命令）是 TUI／无头界面（`--config`、`-p`/`--prompt`、`--resume`），`meta` 子命令是以本 checkout 为 workspace 的同一个 TUI，`upgrade` 子命令是无选项的引导会话入口，`web` 子命令则是浏览器 UI。`src/bin.ts` 按解析后的 mode 分支，仅动态导入该 mode 的模块。`dsh --help` 列出所有 mode，`dsh web --help` 渲染 Web 用法，`dsh --version` 打印此应用的版本；未知选项或拼错的 `--resume` 会明确报错（stderr，退出码 1），而不会被错路由。凡与默认界面不共享任何选项的子命令（`upgrade`、`web`、`meta`）都会拒绝泄漏进来的 `--config`/`-p`/`--resume`，而不会照常运行并丢弃它。`dsh web` 的 `--host`/`--port` 是未验证的直通覆盖：`dsh-host-webserver` schema 是默认值（标志缺失时使用已交付的 Web 覆盖层值）和有效性的唯一真源，并在启动时拒绝错误值。`--trusted-host` 为 /api 浏览器信任栅栏追加具名权威；全接口绑定还会自行推导本机的 LAN IP 字面量（[`src/app-cli-entry.ts`](src/app-cli-entry.ts)），因此打印出的 LAN URL 无需任何标志即可使用。
+Argv 只会通过 [Commander](https://github.com/tj/commander.js) 适配器（[`src/args.ts`](src/args.ts)）解析一次：同一个程序的默认形式（无子命令）是 TUI／无头界面（`--config`、`-p`/`--prompt`、`--resume`、`--dump-config`、`--dump-default-config`），`meta` 子命令是以本 checkout 为 workspace 的同一个 TUI，`upgrade` 子命令是无选项的引导会话入口，`web` 子命令则是浏览器 UI。`src/bin.ts` 按解析后的 mode 分支，仅动态导入该 mode 的模块。`dsh --help` 列出所有 mode，`dsh web --help` 渲染 Web 用法，`dsh --version` 打印此应用的版本；未知选项或拼错的 `--resume` 会明确报错（stderr，退出码 1），而不会被错路由。凡与默认界面不共享任何选项的子命令（`upgrade`、`web`、`meta`）都会拒绝泄漏进来的 `--config`/`-p`/`--resume`/dump 标志，而不会照常运行并丢弃它。`dsh web` 的 `--host`/`--port` 是未验证的直通覆盖：`dsh-host-webserver` schema 是默认值（标志缺失时使用已交付的 Web 覆盖层值）和有效性的唯一真源，并在启动时拒绝错误值。`--trusted-host` 为 /api 浏览器信任栅栏追加具名权威；全接口绑定还会自行推导本机的 LAN IP 字面量（[`src/app-cli-entry.ts`](src/app-cli-entry.ts)），因此打印出的 LAN URL 无需任何标志即可使用。

 TUI 界面：

@@ -17,6 +17,8 @@ TUI 界面：

 `dsh upgrade` 是默认 TUI 界面之上的引导式全新会话入口：它在调用目录中创建一个全新会话，并以内置 `dsh-upgrade` skill 播种其首轮，效果等同于用户手动键入 `/skill:<name>`。启动器将 skill 名称提供到启动上下文（[`INITIAL_SKILL_KEY`](../../packages/ui/tui/README.md)），TUI 在聊天就绪后自动调用它。两者都不接受任何选项——`--config`、`-p`、`--resume` 都会明确报错——且仅在首次启动时播种，因此之后 `dsh --resume <id>` 恢复该会话时是普通 TUI 会话，不会重复注入。

+`dsh --dump-config` 和 `dsh web --dump-config` 把合成后的配置树——已交付的基础配置、界面覆盖层，以及 `--config` 或个人覆盖层，恰好是该界面启动时组装的那些层——以 YAML 打印到 stdout 后退出，不启动任何东西；`--dump-default-config` 止步于界面覆盖层，因此对两份输出做 diff 就能精确看出用户层改了什么。每段连续的行之前都有一条 `# ==` 注释，标明该段来自哪个文件以及被哪些层修补过（例如 `# == base.cordis.yml, patched by tui.cordis.yml`），因此输出既展示来源，又仍是一份可加载的文档。合成通过 include 自己的补丁算法和 YAML 方言（`@cordisjs/plugin-include` 的 `applyEntryPatches`/`entryListSchema`）完成，因此 dump 不可能与实际启动漂移；`!!js` 表达式原样打印、不求值，目标行不存在的补丁会连同其所在层报到 stderr，与 Loader 启动时的警告一致。由启动器持有的启动上下文值（会话身份、CLI 标志补丁）是每次调用的事实，位于配置树之外，不会出现。dump 标志会拒绝仅用于启动的标志（`-p`、`--resume`、`--config-replace`）而不是静默忽略它们，`--dump-default-config` 不接受 `--config`。
+
 Web 和无头界面启动 `base.cordis.yml` 与 `web.cordis.yml`，随后应用 `$DSH_HOME/config.yaml`；显式的 `--config <path>` 会替代该个人覆盖。除此之外，两者共享同一套组合：两者都将调用目录视为默认项目和 Workspace 根目录，除非通过 `--workspace-root <path>` 覆盖，否则会在该根目录下创建具名 Workspace；它们会把适用的 `AGENTS.md`/`CLAUDE.md` 指令加载到每个 agent-loop 请求前缀中，渲染预算为 65,536 字节，选用首条消息模型标题，采用与 TUI 相同的有界暂时性模型请求重试策略，并挂载一个可丢弃的内存 SQLite 内容索引服务。该服务在启动时处于 ACTIVE 状态，但其 `node:sqlite` 模块与数据库句柄分别要到首次内容搜索才会导入和打开。这样可使 Node 22 在尚未使用搜索时的启动输出不出现 SQLite 实验性警告；首次实际搜索仍可能发出运行时警告。每个服务实例独占自己的数据库，因此并行调用既不会共享不受支持的 SQLite 状态，也不会留下派生索引文件，首次搜索还会惰性对账实时日志与持久化日志。无头界面唯一的差异是监听操作系统分配的端口（并行 `dsh -p` 运行绝不冲突；stderr 打印的 URL 会在浏览器中打开实时会话）。两者都需要先构建前端 dist 和客户端 bundle（`pnpm run build && pnpm run build:web`）。

 已交付的 TUI 和 Web 组合会注册原生 DeepSeek 适配器，以及 pi-ai 的 OpenAI 和 Anthropic 提供方配置。凭据和端点覆盖来自启动分层环境中的提供方标准变量对：`DEEPSEEK_API_KEY` / `DEEPSEEK_BASE_URL`、`OPENAI_API_KEY` / `OPENAI_BASE_URL` 和 `ANTHROPIC_API_KEY` / `ANTHROPIC_BASE_URL`。
@@ -23,6 +23,22 @@ interface TuiInvocation {
  resume?: string
 }

+/**
+ * Print the composed config tree and exit, without booting: `--dump-config`
+ * composes the shipped base, the surface overlay, and the `--config` or
+ * personal overlay — exactly the layers that surface would boot;
+ * `--dump-default-config` stops at the surface overlay (the shipped tree, no
+ * user layer).
+ */
+interface DumpConfigInvocation {
+  mode: 'dump-config'
+  surface: 'tui' | 'web'
+  /** Omit the `--config`/personal layer and print only the shipped composition. */
+  defaultOnly: boolean
+  /** The `--config` overlay to compose instead of the personal one. */
+  config?: string
+}
+
 /** Headless one-shot: `dsh -p "task"`. */
 interface HeadlessInvocation {
  mode: 'headless'
@@ -69,6 +85,7 @@ interface WebInvocation {
 /** The resolved `dsh` invocation: exactly one mode. `--help`/`--version`/errors exit inside {@link parseDshArgs}. */
 export type DshInvocation =
  | TuiInvocation
+  | DumpConfigInvocation
  | HeadlessInvocation
  | MetaInvocation
  | SkillSessionInvocation
@@ -82,6 +99,34 @@ interface WebOptions {
  dev?: boolean
  workspaceRoot?: string
  trustedHost?: string[]
+  dumpConfig?: boolean
+  dumpDefaultConfig?: boolean
+}
+
+/**
+ * Resolve the two dump flags for one surface, or return `undefined` when
+ * neither was passed. Both flags together are contradictory (one includes the
+ * user layer, the other excludes it) and fail loud through `error`.
+ */
+function resolveDump(
+  surface: 'tui' | 'web',
+  options: { config?: string; dumpConfig?: boolean; dumpDefaultConfig?: boolean },
+  error: (message: string) => never,
+): DumpConfigInvocation | undefined {
+  if (options.dumpConfig !== true && options.dumpDefaultConfig !== true) return undefined
+  if (options.dumpConfig === true && options.dumpDefaultConfig === true) {
+    error('error: --dump-config and --dump-default-config are mutually exclusive')
+  }
+  const defaultOnly = options.dumpDefaultConfig === true
+  if (defaultOnly && options.config !== undefined) {
+    error('error: --dump-default-config prints the shipped tree and takes no --config')
+  }
+  return {
+    mode: 'dump-config',
+    surface,
+    defaultOnly,
+    ...options.config !== undefined && { config: options.config },
+  }
 }

 /**
@@ -135,7 +180,26 @@ Examples:
    .option('--resume <id>', 'continue a past session by id')
    .option('--config <path>', 'apply this overlay of loader patches instead of the personal one')
    .option('--config-replace <path>', 'boot this file as the entire tree, ignoring the shipped and personal configuration')
-    .action((options: { config?: string; configReplace?: string; prompt?: string; resume?: string }) => {
+    .option('--dump-config', 'print the composed config tree (base + surface + --config/personal overlay) and exit')
+    .option('--dump-default-config', 'print the shipped config tree (base + surface overlay, no user layer) and exit')
+    .action((options: {
+      config?: string
+      configReplace?: string
+      prompt?: string
+      resume?: string
+      dumpConfig?: boolean
+      dumpDefaultConfig?: boolean
+    }) => {
+      const dump = resolveDump('tui', options, message => program.error(message))
+      if (dump !== undefined) {
+        // The dump prints composition; a boot-only flag alongside it would be
+        // silently ignored, so reject the mix loud.
+        if (options.prompt !== undefined || options.resume !== undefined || options.configReplace !== undefined) {
+          program.error('error: --dump-config/--dump-default-config take none of -p/--prompt, --resume, or --config-replace')
+        }
+        resolved = dump
+        return
+      }
      if (options.prompt !== undefined) {
        // A headless prompt owns the invocation; an empty task has nothing to
        // run, and --config/--resume are TUI inputs that must not silently
@@ -168,10 +232,18 @@ Examples:
  // a leaked config/prompt/resume option is a mistyped invocation that must fail
  // loud rather than silently run and drop the input.
  const rejectParentOptions = (command: string): void => {
-    const parent = program.opts<{ config?: string; configReplace?: string; prompt?: string; resume?: string }>()
+    const parent = program.opts<{
+      config?: string
+      configReplace?: string
+      prompt?: string
+      resume?: string
+      dumpConfig?: boolean
+      dumpDefaultConfig?: boolean
+    }>()
    if (parent.config !== undefined || parent.configReplace !== undefined
-      || parent.prompt !== undefined || parent.resume !== undefined) {
-      program.error(`error: ${command} takes none of --config, --config-replace, -p/--prompt, or --resume`)
+      || parent.prompt !== undefined || parent.resume !== undefined
+      || parent.dumpConfig !== undefined || parent.dumpDefaultConfig !== undefined) {
+      program.error(`error: ${command} takes none of --config, --config-replace, -p/--prompt, --resume, --dump-config, or --dump-default-config`)
    }
  }

@@ -198,8 +270,15 @@ Examples:
    .option('--dev', 'developer mode: hot-reload the browser client')
    .option('--workspace-root <path>', 'parent directory for workspaces created from the browser UI')
    .option('--trusted-host <authority...>', 'extra authority the /api browser-trust fence accepts (host or host:port; repeatable)')
+    .option('--dump-config', 'print the composed config tree (base + web + --config/personal overlay) and exit')
+    .option('--dump-default-config', 'print the shipped config tree (base + web overlay, no user layer) and exit')
    .action((options: WebOptions) => {
      rejectParentOptions('web')
+      const dump = resolveDump('web', options, message => program.error(message))
+      if (dump !== undefined) {
+        resolved = dump
+        return
+      }
      resolved = resolveWeb(options)
    })

@@ -43,6 +43,11 @@ switch (invocation.mode) {
    await runTui(invocation.config, invocation.resume, undefined, undefined, invocation.configReplace)
    break
  }
+  case 'dump-config': {
+    const { runDumpConfig } = await import('./dump-config.ts')
+    runDumpConfig(invocation.surface, invocation.defaultOnly, invocation.config)
+    break
+  }
  case 'meta': {
    const { runMeta } = await import('./tui.ts')
    await runMeta()
@@ -0,0 +1,61 @@
+/**
+ * `dsh --dump-config` / `dsh web --dump-config` — print the composed config
+ * tree without booting: the shipped base, the surface overlay, and (unless
+ * `--dump-default-config`) the `--config` or personal overlay, composed
+ * through the include's own patch algorithm so the printed tree is exactly
+ * what that surface would mount. `!!js` expressions print verbatim,
+ * unevaluated — the dump shows composition, not one process's environment.
+ * Launcher-provided boot-context values (session identity, CLI-flag patches)
+ * are per-invocation facts outside the config tree and do not appear.
+ * @module @deepseek-ai/dsh/dump-config
+ */
+
+import { basename, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  loadOverlayPatches,
+  loadPersonalPatches,
+  PERSONAL_CONFIG_FILENAME,
+  renderConfigDump,
+  type ConfigDumpLayer,
+} from '@deepseek-ai/dsh-app-boot'
+import { resolveDshHome } from '@deepseek-ai/dsh-paths'
+
+const NAME = 'dsh'
+
+const BASE_CONFIG = fileURLToPath(new URL('../config/base.cordis.yml', import.meta.url))
+const SURFACE_OVERLAYS = {
+  tui: fileURLToPath(new URL('../config/tui.cordis.yml', import.meta.url)),
+  web: fileURLToPath(new URL('../config/web.cordis.yml', import.meta.url)),
+} as const
+
+/* v8 ignore start -- composition over the unit-tested renderConfigDump; the
+   built-bin e2e drives this path end to end */
+/**
+ * Print one surface's composed config tree to stdout, with a comment
+ * separator naming the file each section of rows comes from (and the layers
+ * that patched it).
+ * @param surface - which surface overlay to compose over the shared base.
+ * @param defaultOnly - stop at the surface overlay (no `--config`/personal layer).
+ * @param config - the `--config` overlay path composed instead of the personal
+ * one, or `undefined` to use `$DSH_HOME/config.yaml`.
+ */
+export function runDumpConfig(surface: 'tui' | 'web', defaultOnly: boolean, config?: string): void {
+  const overlay = SURFACE_OVERLAYS[surface]
+  const layers: ConfigDumpLayer[] = [
+    { label: basename(overlay), patches: loadOverlayPatches(NAME, overlay) },
+  ]
+  if (!defaultOnly) {
+    if (config === undefined) {
+      const personal = loadPersonalPatches(NAME)
+      // The personal file may be absent; the shipped layers still print.
+      if (personal !== undefined) {
+        layers.push({ label: join(resolveDshHome(), PERSONAL_CONFIG_FILENAME), patches: personal })
+      }
+    } else {
+      layers.push({ label: config, patches: loadOverlayPatches(NAME, config) })
+    }
+  }
+  process.stdout.write(renderConfigDump(NAME, BASE_CONFIG, layers))
+}
+/* v8 ignore stop */
@@ -45,6 +45,29 @@ describe('parseDshArgs', () => {
      .toEqual({ mode: 'web', dev: false, trustedHosts: ['harness.internal:3080', 'lab.internal', '10.0.0.9'] })
  })

+  it('routes the dump flags per surface: composed with the user layer, or shipped only', () => {
+    expect(parse(['--dump-config'])).toEqual({ mode: 'dump-config', surface: 'tui', defaultOnly: false })
+    expect(parse(['--dump-config', '--config', 'c.yml']))
+      .toEqual({ mode: 'dump-config', surface: 'tui', defaultOnly: false, config: 'c.yml' })
+    expect(parse(['--dump-default-config'])).toEqual({ mode: 'dump-config', surface: 'tui', defaultOnly: true })
+    expect(parse(['web', '--dump-config'])).toEqual({ mode: 'dump-config', surface: 'web', defaultOnly: false })
+    expect(parse(['web', '--dump-config', '--config', 'w.yml']))
+      .toEqual({ mode: 'dump-config', surface: 'web', defaultOnly: false, config: 'w.yml' })
+    expect(parse(['web', '--dump-default-config'])).toEqual({ mode: 'dump-config', surface: 'web', defaultOnly: true })
+    // The two dump flags contradict each other; boot-only flags alongside a
+    // dump would be silently ignored; the shipped tree takes no user overlay.
+    expect(exitCode(['--dump-config', '--dump-default-config'])).toBe(1)
+    expect(exitCode(['--dump-default-config', '--config', 'c.yml'])).toBe(1)
+    expect(exitCode(['--dump-config', '--resume', 's'])).toBe(1)
+    expect(exitCode(['--dump-config', '-p', 'task'])).toBe(1)
+    expect(exitCode(['--dump-config', '--config-replace', 'tree.yml'])).toBe(1)
+    expect(exitCode(['web', '--dump-config', '--dump-default-config'])).toBe(1)
+    expect(exitCode(['web', '--dump-default-config', '--config', 'w.yml'])).toBe(1)
+    // A leaked dump flag on a subcommand that has none is a mistyped invocation.
+    expect(exitCode(['meta', '--dump-config'])).toBe(1)
+    expect(exitCode(['upgrade', '--dump-config'])).toBe(1)
+  })
+
  it('exits nonzero instead of silently starting fresh or dropping inputs', () => {
    // Empty resume/prompt would be swallowed downstream; --prompt mixed with
    // TUI inputs must not lose them. (Bad host/port are gated by the webserver
@@ -1,8 +1,9 @@
-import { existsSync } from 'node:fs'
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { fileURLToPath } from 'node:url'
 import { execa } from 'execa'
-import { describe, expect, it } from 'vitest'
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'

 /**
 * Published-entry smoke for the `dsh` bin: run the built `lib/bin.js` under
@@ -22,13 +23,20 @@ import { describe, expect, it } from 'vitest'
 const repoRoot = fileURLToPath(new URL('../../../', import.meta.url))
 const dshBin = join(repoRoot, 'apps/cli/lib/bin.js')

-/** Run the built bin with PIPED stdio (stdin closed at EOF); resolve with output + exit code. */
-async function runBuiltBin(): Promise<{ stdout: string; code: number; stderr: string }> {
-  const result = await execa(process.execPath, [dshBin], {
+/**
+ * Run the built bin with PIPED stdio (stdin closed at EOF); resolve with output
+ * + exit code. `env` isolates the Harness home for surfaces that read it.
+ */
+async function runBuiltBin(
+  args: readonly string[] = [],
+  env: Record<string, string> = {},
+): Promise<{ stdout: string; code: number; stderr: string }> {
+  const result = await execa(process.execPath, [dshBin, ...args], {
    input: '',
    timeout: 25_000,
    killSignal: 'SIGKILL',
    reject: false,
+    env,
  })
  if (result.timedOut) {
    throw new Error(`dsh built bin did not exit within 25s. stdout:\n${result.stdout}\nstderr:\n${result.stderr}`)
@@ -45,4 +53,61 @@ describe.skipIf(!existsSync(dshBin))('dsh BUILT bin (node lib/bin.js, no tsx)',
    // The refusal happens before any plugin mounts: stdout stays silent.
    expect(stdout).toBe('')
  }, 30_000)
+
+  describe('dsh --dump-config', () => {
+    let home: string
+    beforeEach(() => { home = mkdtempSync(join(tmpdir(), 'dsh-dump-bin-')) })
+    afterEach(() => { rmSync(home, { recursive: true, force: true }) })
+
+    it('prints the shipped TUI composition without booting or needing a TTY', async () => {
+      const { stdout, code, stderr } = await runBuiltBin(['--dump-default-config'], { DSH_HOME: home })
+      expect(code).toBe(0)
+      expect(stderr).toBe('')
+      // Base rows composed with the TUI overlay's surface values, `!!js`
+      // expressions verbatim (unevaluated), and TUI-only inserted rows present.
+      expect(stdout).toContain("name: '@deepseek-ai/dsh-agent-loop'")
+      expect(stdout).toContain('model: deepseek-v4-pro')
+      expect(stdout).toContain('cwd: !!js process.cwd()')
+      expect(stdout).toContain("name: '@deepseek-ai/dsh-tui'")
+      // Provenance comment separators name each section's source file.
+      expect(stdout).toContain('# == base.cordis.yml')
+      expect(stdout).toContain('# == base.cordis.yml, patched by tui.cordis.yml')
+      expect(stdout).toContain('# == tui.cordis.yml')
+    }, 30_000)
+
+    it('layers the personal overlay in --dump-config and reports an unmatched patch on stderr', async () => {
+      writeFileSync(join(home, 'config.yaml'), [
+        '- id: agent-loop',
+        '  config:',
+        '    agents:',
+        '      - id: main',
+        '        provider: custom-provider',
+        '        model: custom-model',
+        '- id: only-on-web',
+        '  config:',
+        '    value: 1',
+        '',
+      ].join('\n'))
+      const { stdout, code, stderr } = await runBuiltBin(['--dump-config'], { DSH_HOME: home })
+      expect(code).toBe(0)
+      expect(stdout).toContain('provider: custom-provider')
+      expect(stdout).not.toContain('model: deepseek-v4-pro')
+      // The personal layer appears in the patched row's provenance and the
+      // skipped-patch warning carries its label.
+      expect(stdout).toContain(`patched by tui.cordis.yml, ${join(home, 'config.yaml')}`)
+      expect(stderr).toContain('patch: entry "only-on-web" not found')
+
+      // The shipped view ignores the personal overlay entirely.
+      const shipped = await runBuiltBin(['--dump-default-config'], { DSH_HOME: home })
+      expect(shipped.stdout).not.toContain('custom-provider')
+      expect(shipped.stdout).toContain('model: deepseek-v4-pro')
+    }, 30_000)
+
+    it('composes the web overlay for `dsh web --dump-config`', async () => {
+      const { stdout, code } = await runBuiltBin(['web', '--dump-config'], { DSH_HOME: home })
+      expect(code).toBe(0)
+      expect(stdout).toContain("name: '@deepseek-ai/dsh-host-webserver'")
+      expect(stdout).not.toContain("name: '@deepseek-ai/dsh-tui'")
+    }, 30_000)
+  })
 })
@@ -0,0 +1,164 @@
+// @vitest-environment jsdom
+// Assembled search-card snapshot: boots the real built `packages/client/*/lib/
+// client.js` bundles through AppWebEntry's ModuleLoader path against the keyless
+// FixtureApiClient transport (no API key, no model round), opens the fixture
+// session, and pins the search card the `grep` turn (fixture turn 66) renders in
+// the assembled application. The built-boot smoke proves the graph boots but
+// carries no behavior assertions by contract; this is the assembled-output check
+// that a broken SearchRow registration or a dropped card would fail — the
+// per-package suites bench over src and cannot see the bundled wiring.
+//
+// Keyless and deterministic: the fixture is the fake server, so the grep turn's
+// matches, its truncation summary, and its head/tail cap are fixed in the
+// fixture, not harvested from a live model. The recovery-footer arm is a pure
+// derivation over the result view, pinned at every render site by the
+// ui-conversation suite; here the fixture turn exercises the assembled card
+// shape and its cap.
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import { act, cleanup, fireEvent, screen, waitFor, within } from '@testing-library/react'
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import type { WebBootEntry } from '@deepseek-ai/dsh-client-modules/client'
+import { AppWebEntry } from '@deepseek-ai/dsh-client-web'
+
+const EXPECTED = join(process.cwd(), 'apps/web/tests/snapshots/search-card/grep-card.expected.txt')
+const refreshing = process.env.DSH_SNAPSHOT === 'record' || process.env.DSH_SNAPSHOT === 'refresh'
+
+const PLUGINS: readonly (WebBootEntry & { dir: string })[] = [
+  { id: '@deepseek-ai/dsh-client-connection', dir: 'connection', url: '/plugins/connection.js', rev: 'fx', inject: [], immediately: true },
+  { id: '@deepseek-ai/dsh-client-runtime', dir: 'runtime', url: '/plugins/runtime.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-connection'], immediately: true },
+  { id: '@deepseek-ai/dsh-client-ui-theme', dir: 'ui-theme', url: '/plugins/ui-theme.js', rev: 'fx', inject: [], immediately: true },
+  { id: '@deepseek-ai/dsh-client-locale', dir: 'locale', url: '/plugins/locale.js', rev: 'fx', inject: [], immediately: true },
+  { id: '@deepseek-ai/dsh-client-ui-layout', dir: 'ui-layout', url: '/plugins/ui-layout.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-runtime'] },
+  { id: '@deepseek-ai/dsh-client-ui-sidebar', dir: 'ui-sidebar', url: '/plugins/ui-sidebar.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-ui-layout'] },
+  { id: '@deepseek-ai/dsh-client-ui-conversation', dir: 'ui-conversation', url: '/plugins/ui-conversation.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-ui-layout'] },
+  {
+    id: '@deepseek-ai/dsh-client-ui-workspace',
+    dir: 'ui-workspace',
+    url: '/plugins/ui-workspace.js',
+    rev: 'fx',
+    inject: [
+      '@deepseek-ai/dsh-client-runtime',
+      '@deepseek-ai/dsh-client-ui-conversation',
+      '@deepseek-ai/dsh-client-ui-sidebar',
+    ],
+  },
+  { id: '@deepseek-ai/dsh-client-ui-trajectory', dir: 'ui-trajectory', url: '/plugins/ui-trajectory.js', rev: 'fx', inject: ['@deepseek-ai/dsh-client-ui-conversation'] },
+]
+
+const bundles = new Map(PLUGINS.map(plugin => [
+  plugin.url,
+  readFileSync(join(process.cwd(), 'packages/client', plugin.dir, 'lib/client.js'), 'utf8'),
+]))
+
+interface FixtureWindow extends Window {
+  __DSH_BOOT__?: { rev: string; entries: WebBootEntry[] }
+  __ModuleLoader__?: unknown
+}
+
+class ResizeObserverStub {
+  observe(): void {}
+  disconnect(): void {}
+  unobserve(): void {}
+}
+
+const win = window as FixtureWindow
+let unmount: (() => void) | undefined
+
+/** Normalize a rendered search card to a stable text shape: the kind, the banner
+ *  summary, each file header (path + count), each visible match line, the expand
+ *  control label, and the recovery footer. CSS-module class names carry a
+ *  per-build hash in one of two schemes — ui-primitives emits `_<name>_<hash>`
+ *  (name bounded by underscores), ui-conversation emits `<hash>_<name>` (name at
+ *  the end). `hasClass` matches a module class by its logical name under either,
+ *  without matching a longer name that contains it (`line` must not hit
+ *  `lineNumber`). */
+function hasClass(el: Element, name: string): boolean {
+  return [...el.classList].some(cls => cls === name || cls.endsWith(`_${name}`) || cls.startsWith(`_${name}_`) || cls.includes(`_${name}_`))
+}
+
+function cardShape(root: Element): string {
+  const card = root.querySelector('[data-search]')
+  if (card === null) return '<no search card>'
+  const pick = (from: Element, name: string): Element[] =>
+    [...from.querySelectorAll('*')].filter(el => hasClass(el, name))
+  const lines: string[] = [`kind=${card.getAttribute('data-search')}`]
+  const summary = pick(card, 'summary')[0]?.textContent?.trim()
+  if (summary !== undefined && summary !== '') lines.push(`summary=${summary}`)
+  for (const header of pick(card, 'fileHeader')) lines.push(`file=${header.textContent?.trim() ?? ''}`)
+  for (const row of pick(card, 'line')) lines.push(`line=${row.textContent?.trim() ?? ''}`)
+  const expand = pick(card, 'expand')[0]?.textContent?.trim()
+  if (expand !== undefined && expand !== '') lines.push(`expand=${expand}`)
+  const recovery = pick(root, 'searchRecovery')[0]?.textContent?.trim()
+  if (recovery !== undefined && recovery !== '') lines.push(`recovery=${recovery}`)
+  return lines.join('\n')
+}
+
+beforeEach(() => {
+  localStorage.clear()
+  // English pinned before boot so the sidebar's role/text locators stay
+  // deterministic (the built-boot smoke's convention).
+  localStorage.setItem('dsh.locale', 'en')
+  document.title = 'DeepSeek Harness'
+  vi.stubGlobal('ResizeObserver', ResizeObserverStub)
+  vi.stubGlobal('requestAnimationFrame', (callback: FrameRequestCallback) =>
+    setTimeout(() => { callback(0) }, 0) as unknown as number)
+  vi.stubGlobal('cancelAnimationFrame', (id: number) => { clearTimeout(id) })
+})
+
+afterEach(() => {
+  act(() => { unmount?.() })
+  unmount = undefined
+  cleanup()
+  delete win.__DSH_BOOT__
+  delete win.__ModuleLoader__
+  document.body.innerHTML = ''
+  document.head.querySelectorAll('style[data-plugin]').forEach((style) => { style.remove() })
+  document.title = ''
+  history.replaceState(null, '', '/')
+  vi.unstubAllGlobals()
+})
+
+describe('assembled search card', () => {
+  it('renders the grep card, its truncation summary, and its capped head/tail slice from the built bundles', async () => {
+    history.replaceState(null, '', '/?fixture')
+    const root = document.createElement('div')
+    root.id = 'root'
+    document.body.appendChild(root)
+    win.__DSH_BOOT__ = { rev: 'fx', entries: PLUGINS.map(({ dir: _dir, ...plugin }) => plugin) }
+    act(() => {
+      const entry = new AppWebEntry(root, {
+        fetchBundle: (url) => {
+          const code = bundles.get(url)
+          return code === undefined ? Promise.reject(new Error(`missing built bundle ${url}`)) : Promise.resolve(code)
+        },
+        executeBundle: (code) => { (0, eval)(code) },
+      })
+      void entry.run()
+      unmount = () => { entry.dispose() }
+    })
+
+    const tree = await screen.findByRole('tree', { name: 'Sessions' }, { timeout: 10_000 })
+    fireEvent.click(await within(tree).findByText('Fixture 历史会话'))
+    // Wait for chat content to reach the fixture's later turns (the bash sample
+    // is turn 65, the grep card turn 66).
+    await waitFor(() => {
+      expect(document.querySelector('[data-sample="bash-global"]')).not.toBeNull()
+    }, { timeout: 10_000 })
+    // The grep turn's keyed SearchRow renders the card resident: wait for it.
+    await waitFor(() => {
+      const tools = [...document.querySelectorAll('[data-tool]')].map(el => el.getAttribute('data-tool'))
+      expect(tools, `tools present: ${tools.join(', ')}`).toContain('grep')
+    }, { timeout: 10_000 })
+
+    // `data-tool` sits on the summary row; the card and recovery footer are its
+    // siblings inside the SearchRow wrapper, so shape the wrapper (its parent).
+    const grepRow = document.querySelector('[data-tool="grep"]')!.parentElement!
+    const shape = cardShape(grepRow)
+    if (refreshing) {
+      mkdirSync(dirname(EXPECTED), { recursive: true })
+      writeFileSync(EXPECTED, shape)
+    }
+    await expect(shape).toMatchFileSnapshot(EXPECTED)
+  })
+})
@@ -0,0 +1,11 @@
+kind=matches
+summary=显示 9 / 共 42 处匹配 · 3 个文件
+file=packages/client/ui-primitives/src/SearchBlock.tsx3
+file=packages/client/ui-conversation/src/client/toolviews/search-row.tsx4
+line=16: export const DEFAULT_SEARCH_MAX_LINES = 16
+line=138: export function SearchBlock(props: SearchBlockProps) {
+line=141:   const [collapsed, setCollapsed] = useState<ReadonlySet<number>>(() => new Set())
+line=73:   const search = searchCardModel(block)
+line=90:         <SearchBlock {...search.card} maxLines={CHAT_SEARCH_MAX_LINES} className={css.search} />
+line=113:     ctx.slots.register({ name: 'conversation.chat.toolview', key: 'grep' }, SearchRow)
+expand=… 其余 4 行
@@ -138,6 +138,79 @@ const TERMINAL_EXIT_STATUS: Record<string, { exitCode: number } | { signal: stri
  [TERMINAL_OUTPUT_FIXTURE]: { exitCode: 1 },
 }

+/**
+ * Structured grep result for the search sample (turn 66): matches grouped by
+ * file, authored inline because the client-side fixture cannot import the tool
+ * that produces the canonical value. `truncated` with a larger `total` than the
+ * retained match count exercises the search card's capped indicator; the file
+ * with more than CHAT_SEARCH_MAX_LINES rows exercises its head/tail height cap.
+ */
+const SEARCH_MATCHES_FIXTURE: { path: string; matches: { lineNumber: number; line: string }[] }[] = [
+  {
+    path: 'packages/client/ui-primitives/src/SearchBlock.tsx',
+    matches: [
+      { lineNumber: 16, line: 'export const DEFAULT_SEARCH_MAX_LINES = 16' },
+      { lineNumber: 138, line: 'export function SearchBlock(props: SearchBlockProps) {' },
+      { lineNumber: 141, line: '  const [collapsed, setCollapsed] = useState<ReadonlySet<number>>(() => new Set())' },
+    ],
+  },
+  {
+    path: 'packages/client/ui-conversation/src/client/contract/search-card-model.ts',
+    matches: [
+      { lineNumber: 24, line: 'export const CHAT_SEARCH_MAX_LINES = 8' },
+      { lineNumber: 60, line: 'export function searchCardModel(block: ToolCallBlock): SearchCardModel | null {' },
+    ],
+  },
+  {
+    path: 'packages/client/ui-conversation/src/client/toolviews/search-row.tsx',
+    matches: [
+      { lineNumber: 71, line: 'export function SearchRow({ toolName, block }: ToolRowProps) {' },
+      { lineNumber: 73, line: '  const search = searchCardModel(block)' },
+      { lineNumber: 90, line: '        <SearchBlock {...search.card} maxLines={CHAT_SEARCH_MAX_LINES} className={css.search} />' },
+      { lineNumber: 113, line: "    ctx.slots.register({ name: 'conversation.chat.toolview', key: 'grep' }, SearchRow)" },
+    ],
+  },
+]
+
+/**
+ * The model-facing grep render text for the sample — what a UI without a search
+ * card shows, attached as the view's `content`. Mirrors the real grep
+ * presenter's shape (see formatGrepOutput in dsh-tool-fs-search): a
+ * `Found X of Y matches` header, the matches grouped under file headers with
+ * `Line N:` rows, then a spill-recovery footer.
+ */
+const SEARCH_MATCHES_TEXT = [
+  'Found 9 of 42 matches',
+  '',
+  ...SEARCH_MATCHES_FIXTURE.map(file =>
+    [file.path, ...file.matches.map(m => `Line ${m.lineNumber}: ${m.line}`)].join('\n')),
+  '',
+  '(Full grep result stored at: fixture://spill/grep-66. Read it to see every match.)',
+].join('\n')
+
+/**
+ * Structured glob result for the search sample (turn 67): a flat path list,
+ * truncated with a larger `total` so the path card shows its capped indicator.
+ */
+const SEARCH_PATHS_FIXTURE = [
+  'packages/client/ui-primitives/src/SearchBlock.tsx',
+  'packages/client/ui-primitives/src/SearchBlock.module.css',
+  'packages/client/ui-conversation/src/client/contract/search-card-model.ts',
+  'packages/client/ui-conversation/src/client/toolviews/search-row.tsx',
+  'packages/client/ui-conversation/src/client/toolviews/search-row.module.css',
+]
+
+/**
+ * The model-facing glob render text — the newline-joined path list plus a
+ * spill-recovery footer, mirroring the real glob presenter's shape (see
+ * formatGlobOutput in dsh-tool-fs-search).
+ */
+const SEARCH_PATHS_TEXT = [
+  ...SEARCH_PATHS_FIXTURE,
+  '',
+  '(Showing 5 of 23 paths. Full sorted result stored at: fixture://spill/glob-67. Read it to see every path.)',
+].join('\n')
+
 /**
 * Read-card sample for the read turn: a WINDOW past an offset, so the line
 * numbers start above 1 (the card's gutter keeps the file's own numbering) and
@@ -166,7 +239,7 @@ const READ_SAMPLE_TOTAL = 180
 const READ_SAMPLE_TEXT = READ_SAMPLE_SOURCE.map((text, index) => `${READ_SAMPLE_FIRST_LINE + index}: ${text}`).join('\n')

 /**
- * The structured `web_search` result view for fixture turn 67, authored inline
+ * The structured `web_search` result view for the web-search turn, authored inline
 * because this client-side fixture cannot import the web tool that projects it.
 * The sources exercise the citation list's features: a titled source with a
 * snippet and a date, a source with no title (its hostname labels the link) and
@@ -196,7 +269,7 @@ const WEB_SEARCH_RESULT: Omit<Extract<ToolResultView, { card: 'web'; kind: 'sear
  truncated: true,
 }

-/** The `web_fetch` result view for fixture turn 68, authored inline for the same reason. */
+/** The `web_fetch` result view for the web-fetch turn, authored inline for the same reason. */
 const WEB_FETCH_RESULT: Omit<Extract<ToolResultView, { card: 'web'; kind: 'fetch' }>, 'card' | 'kind'> = {
  url: 'https://www.deepseek.com/blog/harness-architecture',
  statusCode: 200,
@@ -419,7 +492,17 @@ function buildAlphaLog(): SessionEvent[] {
  // strip empty and take the todo surfaces' own coverage with it.
  toolTurn(65, 'bash', '{"command":"pnpm run check","cwd":"/tmp/fixture/deep/nested"}', TERMINAL_OUTPUT_FIXTURE)

-  // Turn 66: the read sample — a WINDOW past an offset so the card draws file
+  // Turns 66-67: the search card's two shapes. `grep` emits a `card: 'search'`
+  // `shape: 'matches'` result view (grouped-by-file matches, truncated with a
+  // larger `total`), `glob` emits `shape: 'paths'` (a flat path list, likewise
+  // truncated). Both ride the keyed SearchRow registration under their own
+  // names; the render-site fallback row is covered by the model derivation
+  // tests, since every fixture search tool has a keyed row. Ordered before the
+  // todo turn for the same standing-plan reason the bash turn is.
+  toolTurn(66, 'grep', '{"pattern":"SEARCH_MAX_LINES","path":"packages/client"}', SEARCH_MATCHES_TEXT)
+  toolTurn(67, 'glob', '{"pattern":"**/SearchBlock*","path":"packages/client"}', SEARCH_PATHS_TEXT)
+
+  // Turn 68: the read sample — a WINDOW past an offset so the card draws file
  // line numbers starting above 1 and a "showing N of M" note (the window is
  // shorter than READ_SAMPLE_TOTAL), with a `ts` language hint the shiki path
  // highlights. Named `read`, so it exercises the keyed ReadRow registration.
@@ -430,9 +513,9 @@ function buildAlphaLog(): SessionEvent[] {
  // this fixture. The read render intent is result-side only, so its pending
  // call stays a generic `kind: 'read'` card; presentResult carries the
  // structured window.
-  toolTurn(66, 'read', `{"file_path":${JSON.stringify(READ_SAMPLE_PATH)},"offset":${READ_SAMPLE_FIRST_LINE}}`, READ_SAMPLE_TEXT)
+  toolTurn(68, 'read', `{"file_path":${JSON.stringify(READ_SAMPLE_PATH)},"offset":${READ_SAMPLE_FIRST_LINE}}`, READ_SAMPLE_TEXT)

-  // Turns 67-68: the web render intent — a web_search whose result view carries
+  // Turns 69-70: the web render intent — a web_search whose result view carries
  // structured sources plus an answer (the citation list, one source lacking a
  // title so its hostname labels the link, the capped indicator on), and a
  // web_fetch whose result view carries the fetched URL and its HTTP status.
@@ -441,11 +524,11 @@ function buildAlphaLog(): SessionEvent[] {
  // the real tools so they hit the keyed WebRow registration. Ordered BEFORE
  // the todo turn for the same reason turn 65 is: the standing plan retires at
  // the next turn/start, so a turn after it would empty the dock's plan strip.
-  toolTurn(67, 'web_search', '{"query":"deepseek harness architecture"}', 'Search results for deepseek harness architecture.')
-  toolTurn(68, 'web_fetch', '{"url":"https://www.deepseek.com/blog/harness-architecture"}', '# Harness architecture\n\nEverything is a plugin.')
+  toolTurn(69, 'web_search', '{"query":"deepseek harness architecture"}', 'Search results for deepseek harness architecture.')
+  toolTurn(70, 'web_fetch', '{"url":"https://www.deepseek.com/blog/harness-architecture"}', '# Harness architecture\n\nEverything is a plugin.')

  const todoArgs = JSON.stringify({ todos: fixtureTodos })
-  toolTurn(69, 'todo_write', todoArgs, 'Updated todo list: 1 pending, 1 in progress, 1 completed.')
+  toolTurn(71, 'todo_write', todoArgs, 'Updated todo list: 1 pending, 1 in progress, 1 completed.')
  // The real tool appends the snapshot mid-execution — between tool/call and
  // tool/result — so the fixture reproduces that exact ordering (the last
  // toolTurn events run ... tool/call, tool/result, step/end, turn/end).
@@ -507,6 +590,13 @@ function presentCall(name: string, argsRaw: string): ToolCallView | undefined {
        card: 'diff', title: `Write ${str(args.file_path)}`,
        diffs: [{ path: str(args.file_path), oldText: null, newText: str(args.content) }],
      }
+    // A search call stays a generic card (kind: 'search'): the structured
+    // matches/paths exist only after execute, so the search card is result-time
+    // only (presentResult builds it). This mirrors the real grep/glob presenters.
+    case 'grep':
+      return { card: 'generic', title: `Grep ${str(args.pattern)}`, kind: 'search', rawInput: args }
+    case 'glob':
+      return { card: 'generic', title: `Glob ${str(args.pattern)}`, kind: 'search', rawInput: args }
    // The web tools keep a GENERIC pending card and add the `web` result card
    // only at result time (the contract's result-only web shape); their pending
    // kind matches the result kind so a call and its result read as one category.
@@ -522,6 +612,18 @@ function presentCall(name: string, argsRaw: string): ToolCallView | undefined {
 function presentResult(name: string, argsRaw: string, resultText: string): ToolResultView | undefined {
  const call = presentCall(name, argsRaw)
  if (call === undefined) return undefined
+  // Search is result-time only: the call stays a generic search card, and the
+  // result view carries the structured shape the card renders. The view holds no
+  // result text — a UI without a search card falls back to the raw tool/result
+  // content — so the truncation recovery footer rides that raw content (the
+  // `toolTurn` message text), not the view. `total` exceeds the retained count so
+  // the card shows its capped indicator.
+  if (name === 'grep') {
+    return { card: 'search', shape: 'matches', files: SEARCH_MATCHES_FIXTURE, truncated: true, total: 42 }
+  }
+  if (name === 'glob') {
+    return { card: 'search', shape: 'paths', paths: SEARCH_PATHS_FIXTURE, truncated: true, total: 23 }
+  }
  // The read result is the structured window the tool projects through
  // `presentationMeta`; the fixture authors it inline (it cannot import the
  // tool). Keyed on the name because the read pending call is a generic card,
@@ -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: 90110d420123bf8c7a91cbd52d50b7b06a700230
-README.zh.md: 393fc381dd4a12ceead5dd3fb7a93cafe9d8fbf2
+README.md: 5e918bbf06e163c50e184f500b565eb2436729e0
+README.zh.md: e8ef25b0734e73ff32dc57c12a76adbf6a2fcb6f
@@ -22,6 +22,8 @@ A tool call declaring the `diff` render intent (the `write`/`edit` tools) render

 The chat flow projects consecutive model-retry nodes across retry turns into one stable, muted status row updated to the latest attempt; every retry event remains in the runtime snapshot and session log. Its frontend countdown anchors the scheduled delay to client receipt, avoiding host/browser clock skew, rounds remaining time up to seconds, and has a one-second floor. The latest unresolved retry uses a left-to-right text shimmer. Subsequent turn facts distinguish an attempt that started from one cancelled during backoff, while the Host running bit only controls the live animation; the row then shows a static completed or cancelled label. Normal policy rows show the finite retry maximum; always policy rows show `∞`. Activating the row reveals the latest exact retry delay and failure message. The client runtime removes each failed step's streaming tail before its retry node arrives, while the status remains visible after a later attempt succeeds.

+A `grep`/`glob` call declaring the `search` render intent renders its result inline, at the same render sites, through ui-primitives' `SearchBlock` — grep's matches grouped by file (each a collapsible header of `lineNumber: line` rows), glob's flat path list. `contract/search-card-model.ts` is the single derivation from the snapshot's `resultView`; unlike the terminal card it reads no `callView`, since a search has no matches or paths before `execute`, so a running search shows its summary alone. It yields null — the generic path — for any non-search result view, a `card` or `kind` this client version does not compile, and (because those ride the untrusted wire frame) a known kind whose `files`/`paths` is malformed. The keyed `SearchRow`, registered under both `grep` and `glob` since the derived `kind` decides the shape, carries the card resident below its summary; the render-site fallback keeps it behind the expand control. Both cap at `CHAT_SEARCH_MAX_LINES` (8) against the panel's 16. A capped search drops rows from the card, but the locator to the rest — grep/glob's `Full … stored at …` footer — lives only in the result text, so the derivation surfaces that as a recovery footer below the card when (and only when) the result was truncated; a settled call with no card at all (an errored search, a nested `run_code` sub-dispatch, a legacy generic result) falls back to its flattened result text so nothing is lost behind a bare summary ([decision](../../../.agents/notes/implemented/feature/2026-07-30-web-search-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: '<tool>', 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 (`<done>/<total> 已完成 · <active item>` 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 `"<done>/<total> tasks · <n> 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.
@@ -20,6 +20,8 @@

 聊天流会将跨重试轮次连续出现的模型重试节点投影为一个稳定的弱化状态行，并用最新一次尝试更新该行；每个重试事件仍保留在运行时快照与会话日志中。前端倒计时以客户端收到事件的时刻为计划延迟的起点，避免 Host 与浏览器的时钟偏差；剩余时间向上取整到秒，且下限为 1 秒。最近一次尚未完成的重试会显示从左到右的文字渐变动画。后续轮次事实用于区分已开始的尝试与在退避期间取消的尝试，Host 的 running 位只控制实时动画；随后该行会显示静态的已完成或已取消标签。normal 策略行显示有限重试上限；always 策略行显示 `∞`。激活该行会显示最近一次重试的精确延迟和失败消息。客户端运行时会在相应重试节点到达前移除每个失败步骤的流式输出尾部；后续某次尝试成功后，该状态仍保持可见。

+声明 `search` 渲染意图的 `grep`／`glob` 调用，会在同样的渲染点上通过 ui-primitives 的 `SearchBlock` 内联渲染其结果——grep 的匹配按文件分组（每个是一个可折叠的头，下辖 `lineNumber: line` 行），glob 是扁平路径列表。`contract/search-card-model.ts` 是从快照的 `resultView` 推导的唯一位置；与终端卡片不同，它不读 `callView`，因为搜索在 `execute` 前没有匹配或路径，所以运行中的搜索只显示摘要。对任何非搜索的结果视图、当前客户端版本无法编译的 `card` 或 `kind`、以及（因为这些都与不可信的 wire 帧同行）一个 `files`／`paths` 格式错误的已知 kind，它都返回 null，落回通用路径。键控的 `SearchRow` 因推导出的 `kind` 决定形态而同时注册在 `grep` 与 `glob` 下，把卡片常驻在摘要行下方；渲染点兜底行则把它保持在展开控件之后。两者上限都是 `CHAT_SEARCH_MAX_LINES`（8），面板为 16。被截断的搜索会从卡片里丢掉一些行，但通往其余部分的定位符——grep/glob 的 `Full … stored at …` 脚注——只存在于结果文本里，因此推导在（且仅在）结果被截断时把它作为恢复脚注画在卡片下方；一个完全没有卡片的已结算调用（出错的搜索、嵌套 `run_code` 子派发、旧日志的 generic 结果）则回退到其压平后的结果文本，从而不让任何内容丢失在一个光秃秃的摘要之后（[决策](../../../.agents/notes/implemented/feature/2026-07-30-web-search-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: '<tool>', 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 原语下拉，普通安全预设会立即经输入栏注入的 `command` 回调提交 `/permission <preset>`，而 `danger-full-access` 在界面中显示为 `Full access`，选择后先打开页面内的 Modal 风险确认。用户勾选确认项前启用按钮始终不可用；取消、Escape、关闭按钮与点击遮罩都不会提交命令。
@@ -20,6 +20,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 { searchToolview } from './toolviews/search-row.tsx'
 import { readToolview } from './toolviews/read-row.tsx'
 import { fileMutationToolview } from './toolviews/file-mutation-row.tsx'
 import { webToolview } from './toolviews/web-row.tsx'
@@ -321,6 +322,10 @@ export function apply(ctx: Context): void {
  // (ToolRow-matching Bash · {description} chrome; scoped badge in child sessions).
  ctx.plugin(bashToolviewSample)

+  // The grep/glob search row rides the same seam: one component registered
+  // under both tool names, since both declare the same search render intent.
+  ctx.plugin(searchToolview)
+
  // The read row rides the same seam (a product registration, not a sample):
  // Read · {path} chrome with the file's read card resident below it.
  ctx.plugin(readToolview)
@@ -10,6 +10,7 @@ import {
  IconThinkOutline14, ReadBlock, WebBlock,
 } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { ChatViewSlotProps, ToolRowOwnerProps } from '../contract/slots.ts'
+import { searchCardModel } from '../contract/search-card-model.ts'
 import { CHAT_READ_MAX_LINES, readCardModel } from '../contract/read-card-model.ts'
 import { diffCardModel } from '../contract/diff-card-model.ts'
 import { terminalCardModel, terminalFailed } from '../contract/terminal-card-model.ts'
@@ -38,6 +39,7 @@ export interface GenericToolCardProps extends ToolRowOwnerProps {
 export function GenericToolCard({ toolName, block, cwd, openFile, inspect, t }: GenericToolCardProps) {
  const model = toolRowModel(toolName, block, cwd)
  const terminal = terminalCardModel(block, cwd)
+  const search = searchCardModel(block)
  const read = readCardModel(block, cwd)
  const diff = diffCardModel(block)
  const web = webCardModel(block)
@@ -55,8 +57,9 @@ export function GenericToolCard({ toolName, block, cwd, openFile, inspect, t }:
      icon={VARIANT_ICONS[model.variant]}
      title={model.title}
      // A terminal presenter's description is the contract's above-card text, so
-      // it outranks the args-derived summary here exactly as it does in BashRow.
-      summary={terminal?.description ?? model.summary}
+      // it outranks the args-derived summary here exactly as it does in BashRow;
+      // a search result view's replacement title outranks it the same way.
+      summary={terminal?.description ?? search?.title ?? model.summary}
      // Single-file tools never expose an args body — the path link is the only
      // args interaction. A diff card is not an args body: a write/edit row is
      // single-file AND carries a diff, so the card expands under the path link.
@@ -64,6 +67,7 @@ export function GenericToolCard({ toolName, block, cwd, openFile, inspect, t }:
      output={model.output}
      errorSummary={model.errorSummary}
      terminal={terminal}
+      search={search}
      diff={diff}
      state={state}
      filePath={model.filePath}
@@ -246,17 +246,29 @@
  color: var(--dsw-alias-state-error-primary);
 }

-/* 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 search card's grouped matches or path
+   list through SearchBlock. All 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. */
 .codeBody,
-.terminalBody {
+.terminalBody,
+.searchBody {
  margin: 4px 0 4px 4px;
 }

+/* The recovery footer for a capped search: the result text (its `Full … stored
+   at …` locator) below the card in the muted tone, since the card holds only the
+   retained rows. Same column indent as the card body. */
+.searchRecovery {
+  margin: 4px 0 4px 4px;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  font: var(--dsw-font-xs-13);
+  color: var(--dsw-alias-label-tertiary);
+}
+
 /* A write/edit diff renders through DiffBlock; like the terminal card it draws
   its own surface, so only the row indentation is this file's concern. */
 .diffBody {
@@ -3,23 +3,25 @@
 // separator dot + FILL-truncated summary, drawn through the shared
 // DisclosureRow chrome with the whole row as the expand toggle (click /
 // Enter / Space, icon→chevron hover preview). The collapsed row is always
-// one line; every row with body, output, or terminal material is expandable;
-// the summary stays inline while open, except Think, whose body opens with
-// the same first line and would repeat it.
+// one line; every row with body, output, terminal, or search material is
+// expandable; the summary stays inline while open, except Think, whose body
+// opens with the same first line and would repeat it.
 // The expanded body — an IN/OUT gutter-labeled card (figma 1249:35657) for
-// text input/output, the run_code program through CodeBlock, or a terminal
-// card's command output through TerminalBlock — lives in a max-height scroll
-// container so a long payload scrolls internally instead of taking over the
-// message flow; Think's prose is the exception and flows uncapped like
-// message text. Expand state is component-local view state. File-tool
-// summaries are path links that open through the host (stopPropagation keeps
-// the two gestures independent); an error row's collapsed summary is the
+// text input/output, the run_code program through CodeBlock, a terminal
+// card's command output through TerminalBlock, or a search card's grouped
+// matches / path list through SearchBlock (capped at CHAT_SEARCH_MAX_LINES) —
+// lives in a max-height scroll container so a long payload scrolls internally
+// instead of taking over the message flow; Think's prose is the exception and
+// flows uncapped like message text. Expand state is component-local view state.
+// File-tool summaries are path links that open through the host (stopPropagation
+// keeps the two gestures independent); an error row's collapsed summary is the
 // failure's first line in the error color.

 import { useState, type MouseEvent, type ReactNode } from 'react'
 import clsx from 'clsx'
-import { CodeBlock, DiffBlock, StateDot, TerminalBlock } from '@deepseek-ai/dsh-client-ui-primitives'
+import { CodeBlock, DiffBlock, SearchBlock, StateDot, TerminalBlock } from '@deepseek-ai/dsh-client-ui-primitives'
 import type { TranslateNS } from '@deepseek-ai/dsh-client-ui-slots'
+import { CHAT_SEARCH_MAX_LINES, type SearchCardModel } from '../contract/search-card-model.ts'
 import { CHAT_DIFF_MAX_LINES, type DiffCardModel } from '../contract/diff-card-model.ts'
 import { terminalBlockLabels, type TerminalCardModel } from '../contract/terminal-card-model.ts'
 import type { ToolRowState, ToolRowVariant } from '../contract/tool-call-model.ts'
@@ -49,10 +51,17 @@ export interface ToolRowProps {
   * expandable.
   */
  terminal?: TerminalCardModel | null | undefined
+  /**
+   * Search-card material for a call whose render intent is a search card
+   * (derived by `searchCardModel`); it replaces the text body when present.
+   * Null or absent leaves the text body. A call carries at most one card kind,
+   * so `terminal`, `search`, and `diff` are never both present on the same row.
+   */
+  search?: SearchCardModel | null | undefined
  /**
   * Diff-card material for a call whose render intent is a diff card (derived by
   * `diffCardModel`); it replaces the text body when present, the same way
-   * `terminal` does. A call carries at most one card intent, so the two are
+   * `terminal` does. A call carries at most one card intent, so the cards are
   * never both set.
   */
  diff?: DiffCardModel | null | undefined
@@ -103,6 +112,7 @@ export function ToolRow({
  output,
  errorSummary,
  terminal,
+  search,
  diff,
  state,
  filePath,
@@ -111,9 +121,12 @@ export function ToolRow({
 }: ToolRowProps) {
  const [expanded, setExpanded] = useState(false)
  const terminalBody = terminal ?? null
+  const searchBody = search ?? null
  const diffBody = diff ?? null
  const outputText = output ?? null
-  const expandable = body !== null || outputText !== null || terminalBody !== null || diffBody !== null
+  // A search or diff card replaces the text body; a call carries at most one
+  // card kind, so terminal, search, and diff are never both present on a row.
+  const expandable = body !== null || outputText !== null || terminalBody !== null || searchBody !== null || diffBody !== null
  const open = expanded && expandable
  // An error row's collapsed summary IS the failure: the first error line in
  // the error color outranks both the args summary and a terminal description.
@@ -185,40 +198,51 @@ export function ToolRow({
                className={css.terminalBody}
              />
            )
-            : diffBody !== null
-              ? <DiffBlock {...diffBody.card} maxLines={CHAT_DIFF_MAX_LINES} className={css.diffBody} />
-              : isThink
-                ? <div className={css.thinkBody}>{body}</div>
-                : (
-                  <>
-                    {variant === 'code' && body !== null && (
-                      <div className={css.bodyScroll}>
-                        <CodeBlock code={body} lang="typescript" copyLabel={t('copy')} copiedLabel={t('copied')} className={css.codeBody} />
-                      </div>
-                    )}
-                    {(cardBody !== null || outputText !== null) && (
-                      <div className={css.ioCard}>
-                        {cardBody !== null && (
-                          <div className={css.ioSection}>
-                            <span className={css.ioLabel}>IN</span>
-                            <span className={css.ioText}>{cardBody}</span>
-                          </div>
-                        )}
-                        {cardBody !== null && outputText !== null && (
-                          <span className={css.ioDivider} aria-hidden />
-                        )}
-                        {outputText !== null && (
-                          <div className={css.ioSection}>
-                            <span className={css.ioLabel}>OUT</span>
-                            <span className={css.ioText} data-error={state === 'error' || undefined}>
-                              {outputText}
-                            </span>
-                          </div>
-                        )}
-                      </div>
-                    )}
-                  </>
-                )}
+            : searchBody !== null
+              ? (
+                <>
+                  <SearchBlock {...searchBody.card} maxLines={CHAT_SEARCH_MAX_LINES} className={css.searchBody} />
+                  {/* A capped search's recovery locator lives only in the result
+                      text; show it below the card so the dropped rows survive. */}
+                  {searchBody.recovery !== undefined && (
+                    <div className={css.searchRecovery}>{searchBody.recovery}</div>
+                  )}
+                </>
+              )
+              : diffBody !== null
+                ? <DiffBlock {...diffBody.card} maxLines={CHAT_DIFF_MAX_LINES} className={css.diffBody} />
+                : isThink
+                  ? <div className={css.thinkBody}>{body}</div>
+                  : (
+                    <>
+                      {variant === 'code' && body !== null && (
+                        <div className={css.bodyScroll}>
+                          <CodeBlock code={body} lang="typescript" copyLabel={t('copy')} copiedLabel={t('copied')} className={css.codeBody} />
+                        </div>
+                      )}
+                      {(cardBody !== null || outputText !== null) && (
+                        <div className={css.ioCard}>
+                          {cardBody !== null && (
+                            <div className={css.ioSection}>
+                              <span className={css.ioLabel}>IN</span>
+                              <span className={css.ioText}>{cardBody}</span>
+                            </div>
+                          )}
+                          {cardBody !== null && outputText !== null && (
+                            <span className={css.ioDivider} aria-hidden />
+                          )}
+                          {outputText !== null && (
+                            <div className={css.ioSection}>
+                              <span className={css.ioLabel}>OUT</span>
+                              <span className={css.ioText} data-error={state === 'error' || undefined}>
+                                {outputText}
+                              </span>
+                            </div>
+                          )}
+                        </div>
+                      )}
+                    </>
+                  )}
          {inspect !== undefined && (
            <button
              type="button"
@@ -0,0 +1,159 @@
+/**
+ * Pure derivation of the search-card props from a frozen call slice: the
+ * `card:'search'` render intent the `grep` and `glob` tools declare arrives on
+ * the snapshot as `resultView`, and this is the one place that turns it into
+ * what {@link SearchBlock} draws. Both conversation render sites (the chat tool
+ * row's resident body and the details panel's Output section) call this, so the
+ * grouped matches or the path list they show are derived once.
+ *
+ * The search card is result-time only: a search call has no matches or paths
+ * before `execute`, so its pending state stays a `GenericCallView`
+ * ({@link module:@deepseek-ai/dsh-tools/src/presentation}). This derivation
+ * therefore reads only `resultView` and returns null for a still-running call,
+ * unlike the terminal card whose call view carries the command before
+ * execution.
+ *
+ * A capped result also carries a recovery locator (grep/glob's `Full … stored
+ * at …` footer) in the raw `tool/result` content, not in the structured
+ * matches/paths the view carries. Since both render sites replace that raw
+ * result with the card, this derivation surfaces the block's own result text as
+ * {@link SearchCardModel.recovery} so the one path to the dropped rows is not
+ * lost.
+ * @module
+ */
+import type { SearchBlockProps, SearchFileGroup } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { ToolCallBlock } from './tool-call-model.ts'
+
+/**
+ * Distributive `Omit`: a plain `Omit<A | B, K>` keeps only the keys common to
+ * both members, which would drop the `files`/`paths` discriminated fields.
+ * Distributing over the naked type parameter `T` preserves each shape.
+ */
+type DistributiveOmit<T, K extends keyof T> = T extends unknown ? Omit<T, K> : never
+
+/** The {@link SearchBlockProps} union minus each render site's own fields. */
+type SearchBlockModelProps = DistributiveOmit<SearchBlockProps, 'maxLines' | 'className'>
+
+/**
+ * Result rows the chat row's resident search body 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. A design constant of this UI's row geometry, not a
+ * deployment choice, so it is fixed here rather than a plugin Config field.
+ */
+export const CHAT_SEARCH_MAX_LINES = 8
+
+/**
+ * The {@link SearchBlock} props this derivation owns. Held as a nested object
+ * (`card`) so a render site spreads exactly the primitive's own surface and can
+ * never leak a neighbouring field into it. `maxLines`/`className` belong to each
+ * render site.
+ */
+export interface SearchCardModel {
+  /**
+   * The props {@link SearchBlock} draws, minus each render site's own
+   * `maxLines`/`className`.
+   */
+  card: SearchBlockModelProps
+  /**
+   * The result view's replacement title, which the presentation contract lets a
+   * search tool set at settle time. Absent when the presenter supplied none; a
+   * row then keeps its args-derived summary.
+   */
+  title: string | undefined
+  /**
+   * The raw `tool/result` text, flattened, surfaced only when the search was
+   * capped. The card renders the retained matches or paths, but the recovery
+   * locator a capped result carries — grep/glob's `Full … stored at: <locator>`
+   * footer, the one way to reach the rows the cap dropped — lives only in the raw
+   * result text, which the card replaces. A UI that shows the card would
+   * otherwise lose it. Absent when the result was not capped (the card holds
+   * every result) or the block carries no text.
+   */
+  recovery: string | undefined
+}
+
+/**
+ * Whether every file group in a matches view is structurally valid: the wire
+ * frame carries `shape` and `card` as strings the host schema checks, but not the
+ * grouped shape, so a version mismatch or loose producer could deliver
+ * `shape: 'matches'` with a missing or malformed `files`. Rendering that would
+ * crash {@link SearchBlock} at `.reduce`/`.map`; an invalid shape falls to the
+ * generic path instead.
+ * @param files - the candidate `files` field off the untrusted result view.
+ * @returns whether `files` is a valid {@link SearchFileGroup} array.
+ */
+function isValidFiles(files: unknown): files is SearchFileGroup[] {
+  return Array.isArray(files) && files.every(file =>
+    typeof file === 'object' && file !== null
+    && typeof (file as { path?: unknown }).path === 'string'
+    && Array.isArray((file as { matches?: unknown }).matches)
+    && (file as { matches: unknown[] }).matches.every(match =>
+      typeof match === 'object' && match !== null
+      && typeof (match as { lineNumber?: unknown }).lineNumber === 'number'
+      && typeof (match as { line?: unknown }).line === 'string'))
+}
+
+/**
+ * Flatten a settled tool result's content blocks to their text, joined by
+ * newlines. The search view carries no result text — a UI without a card falls
+ * back to the raw `tool/result` content — so the truncation recovery footer is
+ * read from the block's own content here. Non-text blocks (a search result
+ * carries none) are skipped.
+ * @param content - the result node's content blocks.
+ * @returns the joined text, or undefined when empty.
+ */
+function flattenContent(content: readonly { type: string; text?: string }[]): string | undefined {
+  const text = content
+    .filter((block): block is { type: 'text'; text: string } => block.type === 'text' && typeof block.text === 'string')
+    .map(block => block.text)
+    .join('\n')
+  return text === '' ? undefined : text
+}
+
+/**
+ * Derive the search-card props for a tool call, or null when this call is not a
+ * search card and belongs on the generic path.
+ *
+ * Only the result side matters: the search card carries no call-time state, so
+ * a still-running call (no result view) is null, as is a settled call whose
+ * result view is not a search 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, a `card: 'search'` view whose `shape` is neither
+ * `matches` nor `paths` (equally untrusted wire data), and a generic result a
+ * `grep`/`glob` failure or nested `run_code` dispatch produces (its text keeps
+ * the generic path).
+ * @param block - RunningToolCall or ToolResultNode off the snapshot caches.
+ * @returns the search-card props, or null for the generic path.
+ */
+export function searchCardModel(block: ToolCallBlock): SearchCardModel | null {
+  // Running: no result view exists yet, and a search card is result-only.
+  if (!('kind' in block)) return null
+  const result = block.resultView?.card === 'search' ? block.resultView : null
+  if (result === null) return null
+  const common = { truncated: result.truncated, total: result.total }
+  // The recovery footer only matters when the tool capped the result: an
+  // uncapped card holds every match/path, so the raw text adds nothing the card
+  // does not already show. When capped, the raw result's `Full … stored at …`
+  // locator is the only path to the dropped rows, so surface it.
+  const recovery = result.truncated ? flattenContent(block.content) : undefined
+  if (result.shape === 'matches') {
+    // `files` rides the untrusted wire frame: the host schema checks `card`/`shape`
+    // strings but not the grouped shape, so validate it before SearchBlock, which
+    // would crash on a missing/malformed `files`. An invalid shape falls to generic.
+    if (!isValidFiles(result.files)) return null
+    return { title: result.title, recovery, card: { kind: 'matches', files: result.files, ...common } }
+  }
+  // `shape` rides the same untrusted wire frame as `card`, so a version mismatch
+  // or a loose protocol producer could deliver a `card: 'search'` subtype this
+  // client does not compile. Guard the paths shape explicitly: an unknown shape
+  // falls to the generic path rather than being rendered as a paths card, which
+  // would leave SearchBlock calling `.length`/`.map` on an absent `paths`.
+  // oxlint-disable-next-line typescript/no-unnecessary-condition -- shape is wire data; the compiled union cannot prove this exhaustive.
+  if (result.shape !== 'paths') return null
+  // `paths` is likewise unchecked by the wire schema; a known shape with a
+  // missing/malformed array would crash the paths card at `.map`.
+  if (!Array.isArray(result.paths) || !result.paths.every((path): path is string => typeof path === 'string')) return null
+  return { title: result.title, recovery, card: { kind: 'paths', paths: result.paths, ...common } }
+}
@@ -0,0 +1,45 @@
+// Shared toolview-row helpers for the keyed rows whose card is resident below a
+// summary (SearchRow, FileMutationRow): the visually hidden run-state label and
+// the flattened settled-result text for the fallback arm a card cannot render.
+// Both are pure functions of a frozen call slice — no chat-domain imports — so a
+// row stays a thin ToolRowProps consumer.
+
+import type { ToolRowProps } from './slots.ts'
+import type { ToolRowState } from './tool-call-model.ts'
+
+/**
+ * Visually hidden run-state label for a row's leading `StateDot` (which is
+ * `aria-hidden`), so assistive technology still announces the state. Returns
+ * null for the settled-ok state, which needs no spoken label.
+ * @param state - the row's run state.
+ * @returns the label, or null when none is needed.
+ */
+export function rowStateStatus(state: ToolRowState): string | null {
+  switch (state) {
+    case 'running': return '运行中'
+    case 'error': return '失败'
+    case 'stopped': return '已停止'
+    default: return null
+  }
+}
+
+/**
+ * A settled result's text, flattened from its content blocks, for the fallback
+ * arm a keyed row shows when its card cannot render the result — an errored call
+ * (the tool emits no result view on error) or a settled call with no card view
+ * (a nested `run_code` sub-dispatch, a legacy generic result). The keyed row owns
+ * the render slot, so without this the model-facing text would have nowhere to
+ * go. Falls back to the error name/code when the result carries no text block.
+ * @param block - the frozen call slice.
+ * @returns the result text, or null for a running call or an empty result.
+ */
+export function rowResultText(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
+}
@@ -101,13 +101,24 @@
  font: var(--dsw-font-xs-13);
 }

-/* 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. */
+/* A card body (terminal, search, 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 card-specific value. */
 .cardBody {
  margin: 0;
 }

+/* The recovery footer for a capped search: the result text (its `Full … stored
+   at …` locator) below the card in the muted tone, since the card holds only the
+   retained rows. */
+.searchRecovery {
+  margin: 6px 0 0;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  color: var(--dsw-alias-label-tertiary);
+  font: var(--dsw-font-xs-13);
+}
+
 /* The read and web cards sit directly under their section label, same as the
   terminal card: drop the primitive's standalone vertical margin. */
 .read,
@@ -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, DiffBlock, ReadBlock, TerminalBlock, WebBlock } from '@deepseek-ai/dsh-client-ui-primitives'
+import { CodeBlock, DiffBlock, ReadBlock, SearchBlock, TerminalBlock, WebBlock } 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 { searchCardModel } from '../contract/search-card-model.ts'
 import { readCardModel } from '../contract/read-card-model.ts'
 import { diffCardModel } from '../contract/diff-card-model.ts'
 import { terminalBlockLabels, terminalCardModel } from '../contract/terminal-card-model.ts'
@@ -130,13 +131,15 @@ 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. A read-card call
- * renders through the shared ReadBlock at that same full height, so the whole
- * returned window is line-numbered and highlighted. A diff-card call — a
- * write/edit's applied change — renders through the shared DiffBlock at the same
- * full height. A web-card call — a `web_search`/`web_fetch` result — renders
- * through WebBlock at its own full source-list allowance. Every other call, and
- * a running call with no card yet, keeps the flattened text form.
+ * its alignment and scrolls sideways instead of folding. A search-card call —
+ * a `grep`/`glob` result view — renders through the shared SearchBlock at the
+ * same full height allowance, with a capped search's recovery footer below it.
+ * A read-card call renders through the shared ReadBlock at that same full height,
+ * so the whole returned window is line-numbered and highlighted. A diff-card
+ * call — a write/edit's applied change — renders through the shared DiffBlock at
+ * the same full height. A web-card call — a `web_search`/`web_fetch` result —
+ * renders through WebBlock at its own full source-list allowance. Every other
+ * call, and a running call with no 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.
 * @param props.t - the panel's locale seat, passed down as a plain prop.
@@ -156,6 +159,19 @@ function OutputBody({ material, cwd, t }: { material: CallMaterial; cwd: string
      </>
    )
  }
+  const search = searchCardModel(material.block)
+  if (search !== null) {
+    return (
+      <>
+        <SearchBlock {...search.card} className={css.cardBody} />
+        {/* A capped search's recovery locator lives only in the result text;
+            show it below the card so the dropped rows stay reachable. */}
+        {search.recovery !== undefined && (
+          <div className={css.searchRecovery}>{search.recovery}</div>
+        )}
+      </>
+    )
+  }
  const read = readCardModel(material.block, cwd)
  // The panel takes the primitive's own default cap, not the row's tighter one:
  // it is the single-call reading surface, so the whole window is available.
@@ -18,6 +18,7 @@ import { DiffBlock, IconEditOutline16, StateDot } from '@deepseek-ai/dsh-client-
 import type { ToolRowProps } from '../contract/slots.ts'
 import { CHAT_DIFF_MAX_LINES, diffCardModel } from '../contract/diff-card-model.ts'
 import { toolRowModel, type ToolRowState } from '../contract/tool-call-model.ts'
+import { rowResultText, rowStateStatus } from '../contract/toolview-status.ts'
 import css from './file-mutation-row.module.css'

 function leadingFor(state: ToolRowState) {
@@ -29,37 +30,6 @@ function leadingFor(state: ToolRowState) {
  }
 }

-/** 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
-  }
-}
-
-/**
- * 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
@@ -70,11 +40,11 @@ function errorText(block: ToolRowProps['block']): string | null {
 export function FileMutationRow({ toolName, block, cwd, openFile }: ToolRowProps) {
  const model = toolRowModel(toolName, block, cwd)
  const diff = diffCardModel(block)
-  const status = stateStatus(model.state)
+  const status = rowStateStatus(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
+  const failure = diff === null && model.state === 'error' ? rowResultText(block) : null
  return (
    <div className={css.card}>
      <div className={css.root} data-variant={model.variant} data-state={model.state}>
@@ -0,0 +1,117 @@
+/* Search toolview: same geometry/tokens as ToolRow and BashRow (figma
+   Search · summary), plus the search card the row stacks resident under its
+   summary line. */
+
+/* Summary line over the search 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. */
+.search {
+  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 / BashRow. */
+.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-search-row-sweep 2.6s ease-out infinite;
+  pointer-events: none;
+}
+
+@keyframes dsh-search-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);
+}
+
+.visuallyHidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  overflow: hidden;
+  clip: rect(0 0 0 0);
+  white-space: nowrap;
+}
+
+/* The result text for an errored search, indented to the card's own column and
+   in the error tone, standing in for the search 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);
+}
+
+/* The recovery footer for a capped search: the model-facing result text (its
+   `Full … stored at …` locator) shown below the card in the muted tone, since
+   the card holds only the retained rows. Same column indent as the card body. */
+.recovery {
+  margin: 4px 0 4px 22px;
+  white-space: pre-wrap;
+  overflow-wrap: anywhere;
+  font: var(--dsw-font-xs-13);
+  color: var(--dsw-alias-label-tertiary);
+}
@@ -0,0 +1,96 @@
+// Search toolview registrant: the keyed toolview hole (ctx.slots.register +
+// ToolRowProps only — never imports the chat domain). One SearchRow component
+// registered under both `grep` and `glob`, since both tools declare the same
+// `card: 'search'` render intent and render as one visual object; the row reads
+// the `kind` discriminant off the derived model to draw grouped matches or a
+// path list. Product chrome matches ToolRow / BashRow (Search · {summary}).
+//
+// A search call declares its render intent result-time only, so this row's
+// search card is resident below the summary rather than expand-gated: the row
+// itself has no expand control, and the card's own copy, per-file collapse, and
+// head/tail expand are the row's only interactions. CHAT_SEARCH_MAX_LINES is
+// passed as `maxLines` — the chat flow's tighter cap over the block's own
+// default of 16 — so a large result stays bounded in the message flow.
+
+import type { Context } from 'cordis'
+import { IconSearchOutline16, SearchBlock, StateDot } from '@deepseek-ai/dsh-client-ui-primitives'
+import type { ToolRowProps } from '../contract/slots.ts'
+import { CHAT_SEARCH_MAX_LINES, searchCardModel } from '../contract/search-card-model.ts'
+import { toolRowModel, type ToolRowState } from '../contract/tool-call-model.ts'
+import { rowResultText, rowStateStatus } from '../contract/toolview-status.ts'
+import css from './search-row.module.css'
+
+/** Leading-slot glyph substitution: the search icon yields to the terminal
+ *  state semantic (error = red, interrupted = amber). Running keeps the icon —
+ *  the row sweep carries the in-flight signal. */
+function leadingFor(state: ToolRowState) {
+  switch (state) {
+    case 'error': return <StateDot state="error" />
+    case 'stopped': return <StateDot state="warning" />
+    default: return <IconSearchOutline16 size={14} />
+  }
+}
+
+/**
+ * Search row: icon + Search · {summary} in the shared ToolRow chrome, with the
+ * completed search's card resident below it, and — when the result was capped —
+ * the recovery footer below the card. The summary row is not a details-panel
+ * control, so the card's copy, per-file collapse, and expand controls are the
+ * row's only interactions. Registered under both `grep` and `glob`; the derived
+ * model's `kind` decides the card shape.
+ */
+export function SearchRow({ toolName, block }: ToolRowProps) {
+  const model = toolRowModel(toolName, block)
+  const search = searchCardModel(block)
+  const status = rowStateStatus(model.state)
+  // A settled call with no search card — an errored search (grep/glob emit no
+  // result view on error), a successful nested run_code sub-dispatch, or a
+  // legacy generic result — has its model-facing text nowhere else to go, since
+  // the keyed SearchRow owns this render slot. Surface it as the fallback body.
+  // A running call ('kind' absent) has no result to flatten; rowResultText
+  // returns null for it, so the arm stays closed until settle.
+  const settled = 'kind' in block
+  const fallback = search === null && settled ? rowResultText(block) : null
+  return (
+    <div className={css.card}>
+      <div className={css.root} data-variant="search" data-tool={toolName} data-state={model.state}>
+        <span className={css.leading}>{leadingFor(model.state)}</span>
+        {status !== null && <span className={css.visuallyHidden}>{status}</span>}
+        <span className={css.title}>{model.title}</span>
+        <span className={css.sep} aria-hidden />
+        {/* The result view's replacement title outranks the args-derived
+            summary, matching the terminal card's description precedence. */}
+        <span className={css.summary}>{search?.title ?? model.summary}</span>
+      </div>
+      {search !== null && (
+        <SearchBlock {...search.card} maxLines={CHAT_SEARCH_MAX_LINES} className={css.search} />
+      )}
+      {/* A capped search drops rows from the card; its recovery locator (the
+          `Full … stored at …` footer) lives only in the result text, so show it
+          below the card so the one path to the dropped rows survives. */}
+      {search?.recovery !== undefined && <div className={css.recovery}>{search.recovery}</div>}
+      {fallback !== null && <div className={css.failure}>{fallback}</div>}
+    </div>
+  )
+}
+
+/**
+ * The search toolview 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.
+ * The one component registers under both keys, since `grep` and `glob` are the
+ * same visual object discriminated only by the result view's `kind`.
+ */
+export const searchToolview = {
+  name: 'search-toolview',
+  inject: ['slots', 'conversation'],
+  /**
+   * Register the search row into the chat view's keyed toolview hole under both
+   * the `grep` and `glob` tool names.
+   * @param ctx - registrant context (disposal rides ctx.effect inside slots.register).
+   */
+  apply(ctx: Context): void {
+    ctx.slots.register({ name: 'conversation.chat.toolview', key: 'grep' }, SearchRow)
+    ctx.slots.register({ name: 'conversation.chat.toolview', key: 'glob' }, SearchRow)
+  },
+}
@@ -84,14 +84,15 @@ describe('apply wiring', () => {
    await b.runtime.dispose()
  })

-  it('mounts the bash sample, the read row, the file-mutation rows, the web rows, and the product rows as keyed entries through the load-order seam', async () => {
+  it('mounts the bash sample, the search rows, the read row, the file-mutation rows, the web rows, and the product rows as keyed entries through the load-order seam', async () => {
    const b = await bench()
    // Every 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; the
-    // web rows register one component under both web tool names.
+    // one search row registers under both grep and glob; the file-mutation
+    // registrant claims both write and edit for the diff card; the web rows
+    // register one component under both web tool names.
    const entries = b.slots.entries('conversation.chat.toolview')
-    expect(entries.map(e => e.options.key)).toEqual(['bash', 'read', 'edit', 'write', 'web_search', 'web_fetch', 'todo_write', 'ask_user_question'])
+    expect(entries.map(e => e.options.key)).toEqual(['bash', 'grep', 'glob', 'read', 'edit', 'write', 'web_search', 'web_fetch', 'todo_write', 'ask_user_question'])
    // 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()
@@ -0,0 +1,409 @@
+// @vitest-environment jsdom
+// The search render intent on the web side: the pure searchCardModel derivation
+// over resultView, and the conversation render sites that consume it — the chat
+// tool row (GenericToolCard's expand-gated body and SearchRow's resident card)
+// and the details panel's Output section. The keyed registration under both grep
+// and glob is pinned here too.
+
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { cleanup, fireEvent, render } from '@testing-library/react'
+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 { ToolResultView } from '@deepseek-ai/dsh-client-connection/client'
+import type { SelectionTarget, ToolRowProps } from '@deepseek-ai/dsh-client-ui-conversation/client'
+import { makeTranslate } from '@deepseek-ai/dsh-client-test-runtime'
+import { zh as commonZh } from '@deepseek-ai/dsh-client-locale/src/locales/zh.ts'
+import { CHAT_SEARCH_MAX_LINES, searchCardModel } from '../src/client/contract/search-card-model.ts'
+import { zh } from '../src/client/locales.ts'
+import { createChatStore } from '../src/client/stores.ts'
+import { GenericToolCard, type GenericToolCardProps } from '../src/client/chat/GenericToolCard.tsx'
+import { DetailsPanel } from '../src/client/skeleton/DetailsPanel.tsx'
+import { SearchRow, searchToolview } from '../src/client/toolviews/search-row.tsx'
+
+afterEach(cleanup)
+
+/** Conversation-locale translate stub for the render sites' `t` seat. */
+const t: GenericToolCardProps['t'] = makeTranslate(zh, commonZh)
+
+/** The rendered search card's kind attribute, so a render site cannot silently drop it. */
+function searchKindOf(container: HTMLElement): string | null {
+  return container.querySelector('[data-search]')?.getAttribute('data-search') ?? null
+}
+
+/** The rendered result rows of the search card, one string per visible row. */
+function searchRows(container: HTMLElement): string[] {
+  return [...container.querySelectorAll('[data-search] [class^="_line_"]')].map(row => row.textContent ?? '')
+}
+
+const SID = 's1' as SessionId
+
+const GREP_ARGS = '{"pattern":"foo","path":"src"}'
+const GLOB_ARGS = '{"pattern":"**/*.ts","path":"src"}'
+
+/** A grep result view: matches grouped by file. */
+const resultMatches = (over?: Partial<Extract<ToolResultView, { card: 'search'; shape: 'matches' }>>): ToolResultView => ({
+  card: 'search', shape: 'matches',
+  files: [
+    { path: 'a.ts', matches: [{ lineNumber: 12, line: 'const foo = 1' }, { lineNumber: 40, line: 'return foo' }] },
+    { path: 'b.ts', matches: [{ lineNumber: 7, line: 'foo()' }] },
+  ],
+  truncated: false, total: 3, ...over,
+})
+
+/** A glob result view: a flat path list. */
+const resultPaths = (over?: Partial<Extract<ToolResultView, { card: 'search'; shape: 'paths' }>>): ToolResultView => ({
+  card: 'search', shape: 'paths', paths: ['src/a.ts', 'src/b.ts'], truncated: false, total: 2, ...over,
+})
+
+const runningGrep = (over?: Partial<RunningToolCall>): RunningToolCall => ({
+  callId: 'c1', name: 'grep', argsRaw: GREP_ARGS,
+  turn: 1, step: 1, time: 1_000, callView: { card: 'generic', title: 'Grep foo', kind: 'search' }, ...over,
+})
+
+const settledGrep = (over?: Partial<ToolResultNode>): ToolResultNode => ({
+  kind: 'tool-result', seq: 10, time: 2_000, callId: 'c1',
+  call: { name: 'grep', argsRaw: GREP_ARGS },
+  callTime: 1_000,
+  content: [{ type: 'text', text: 'a.ts\n  Line 12: const foo = 1' }], isError: false,
+  callView: { card: 'generic', title: 'Grep foo', kind: 'search' }, resultView: resultMatches(), ...over,
+})
+
+const settledGlob = (over?: Partial<ToolResultNode>): ToolResultNode => ({
+  kind: 'tool-result', seq: 11, time: 2_000, callId: 'c2',
+  call: { name: 'glob', argsRaw: GLOB_ARGS },
+  callTime: 1_000,
+  content: [{ type: 'text', text: 'src/a.ts\nsrc/b.ts' }], isError: false,
+  callView: { card: 'generic', title: 'Glob **/*.ts', kind: 'search' }, resultView: resultPaths(), ...over,
+})
+
+describe('searchCardModel', () => {
+  it('derives a matches card from the grep result view', () => {
+    expect(searchCardModel(settledGrep())).toEqual({
+      title: undefined,
+      recovery: undefined,
+      card: {
+        kind: 'matches',
+        files: [
+          { path: 'a.ts', matches: [{ lineNumber: 12, line: 'const foo = 1' }, { lineNumber: 40, line: 'return foo' }] },
+          { path: 'b.ts', matches: [{ lineNumber: 7, line: 'foo()' }] },
+        ],
+        truncated: false, total: 3,
+      },
+    })
+  })
+
+  it('derives a paths card from the glob result view, carrying the truncation signal', () => {
+    // Empty block content isolates the truncation signal from the recovery arm.
+    expect(searchCardModel(settledGlob({ content: [], resultView: resultPaths({ truncated: true, total: 20 }) }))).toEqual({
+      title: undefined,
+      recovery: undefined,
+      card: { kind: 'paths', paths: ['src/a.ts', 'src/b.ts'], truncated: true, total: 20 },
+    })
+  })
+
+  it('carries the result view\'s replacement title when the presenter sets one', () => {
+    expect(searchCardModel(settledGrep({ resultView: resultMatches({ title: '3 matches' }) }))?.title).toBe('3 matches')
+    // Without one it is absent, so the row keeps its args-derived summary.
+    expect(searchCardModel(settledGrep())?.title).toBeUndefined()
+  })
+
+  it('returns null for every non-search call: running, no views, generic, terminal, unknown cards', () => {
+    // A search card is result-time only: a running call has no result view yet.
+    expect(searchCardModel(runningGrep())).toBeNull()
+    expect(searchCardModel(settledGrep({ callView: null, resultView: null }))).toBeNull()
+    // A generic result settles a search call as a generic card (grep/glob failure
+    // or a nested run_code dispatch), which keeps the generic path.
+    expect(searchCardModel(settledGrep({ resultView: { card: 'generic' } }))).toBeNull()
+    // A terminal result view is a different card entirely.
+    expect(searchCardModel(settledGrep({ resultView: { card: 'terminal', output: 'x' } }))).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' } as unknown as ToolResultView
+    expect(searchCardModel(settledGrep({ resultView: future }))).toBeNull()
+  })
+
+  it('returns null for a card:search view whose shape this version does not compile', () => {
+    // `shape` rides the same untrusted wire frame as `card`; a subtype this client
+    // does not know must fall to the generic path, never render as a paths card
+    // that would crash SearchBlock on an absent `paths`.
+    const futureShape = {
+      card: 'search', shape: 'future', truncated: false, total: 0,
+    } as unknown as ToolResultView
+    expect(searchCardModel(settledGrep({ resultView: futureShape }))).toBeNull()
+  })
+
+  it('returns null for a known shape whose structured shape is missing or malformed', () => {
+    // The host wire schema checks the `card`/`shape` strings but not the grouped
+    // shape, so a version mismatch could deliver shape:'matches' with no `files`
+    // (or shape:'paths' with no `paths`). Rendering that crashes SearchBlock at
+    // `.reduce`/`.map`; the derivation drops to the generic path instead.
+    const noFiles = { card: 'search', shape: 'matches', truncated: false, total: 0 } as unknown as ToolResultView
+    expect(searchCardModel(settledGrep({ resultView: noFiles }))).toBeNull()
+    const badFile = {
+      card: 'search', shape: 'matches', truncated: false, total: 1,
+      files: [{ path: 'a.ts', matches: [{ lineNumber: 'x', line: 1 }] }],
+    } as unknown as ToolResultView
+    expect(searchCardModel(settledGrep({ resultView: badFile }))).toBeNull()
+    const noPaths = { card: 'search', shape: 'paths', truncated: false, total: 0 } as unknown as ToolResultView
+    expect(searchCardModel(settledGlob({ resultView: noPaths }))).toBeNull()
+    const badPaths = {
+      card: 'search', shape: 'paths', truncated: false, total: 1, paths: [42],
+    } as unknown as ToolResultView
+    expect(searchCardModel(settledGlob({ resultView: badPaths }))).toBeNull()
+  })
+
+  it('surfaces the recovery text only when the result was capped', () => {
+    const recovery = 'a.ts\n  12: const foo = 1\n\n(Full grep result stored at: spill://grep-1. Read it to see every match.)'
+    // The recovery locator lives in the raw tool/result content (the view carries
+    // no text), surfaced only when the card capped the result.
+    const capped = searchCardModel(settledGrep({
+      content: [{ type: 'text', text: recovery }],
+      resultView: resultMatches({ truncated: true, total: 42 }),
+    }))
+    expect(capped?.recovery).toBe(recovery)
+    // Not capped: the card holds every match, so the raw content adds nothing and
+    // is dropped.
+    const whole = searchCardModel(settledGrep({
+      content: [{ type: 'text', text: recovery }],
+      resultView: resultMatches({ truncated: false }),
+    }))
+    expect(whole?.recovery).toBeUndefined()
+    // Capped but the block carries no text: nothing to surface.
+    const noText = searchCardModel(settledGrep({ content: [], resultView: resultMatches({ truncated: true, total: 42 }) }))
+    expect(noText?.recovery).toBeUndefined()
+  })
+})
+
+describe('chat row search body (GenericToolCard fallback)', () => {
+  const ownerProps = (block: RunningToolCall | ToolResultNode, toolName: string): GenericToolCardProps => ({
+    callId: 'c1', toolName, block, openFile: vi.fn(), t,
+  })
+  /** The whole summary row is the expand toggle (ToolRow's unified interaction). */
+  const toggleRow = (view: { container: HTMLElement }) => {
+    fireEvent.click(view.container.querySelector('[data-expandable]')!)
+  }
+
+  it('the expanded body is the grouped matches, capped tighter than the panel', () => {
+    expect(CHAT_SEARCH_MAX_LINES).toBeLessThan(16)
+    const view = render(<GenericToolCard {...ownerProps(settledGrep(), 'grep')} />)
+    // Collapsed: the one-line summary row only, no card.
+    expect(view.queryByText(/const foo = 1/)).toBeNull()
+    toggleRow(view)
+    expect(searchRows(view.container)).toContain('12: const foo = 1')
+    expect(view.getByText('a.ts')).toBeTruthy()
+    expect(searchKindOf(view.container)).toBe('matches')
+    // The args JSON body the generic path would have shown is gone.
+    expect(view.queryByText(/"pattern"/)).toBeNull()
+  })
+
+  it('the glob fallback expands to the flat path card', () => {
+    const view = render(<GenericToolCard {...ownerProps(settledGlob(), 'glob')} />)
+    toggleRow(view)
+    expect(view.getByText('src/a.ts')).toBeTruthy()
+    expect(searchKindOf(view.container)).toBe('paths')
+  })
+
+  it('a non-search result keeps the args-JSON text body', () => {
+    const view = render(<GenericToolCard {...ownerProps(settledGrep({
+      resultView: { card: 'generic' },
+    }), 'grep')} />)
+    toggleRow(view)
+    expect(view.getByText(/"pattern"/)).toBeTruthy()
+    expect(searchKindOf(view.container)).toBeNull()
+  })
+
+  it('the expanded body shows the recovery footer below a capped card', () => {
+    const recovery = 'a.ts\n  12: const foo = 1\n\n(Full grep result stored at: spill://grep-1. Read it to see every match.)'
+    const view = render(<GenericToolCard {...ownerProps(settledGrep({
+      content: [{ type: 'text', text: recovery }],
+      resultView: resultMatches({ truncated: true, total: 42 }),
+    }), 'grep')} />)
+    toggleRow(view)
+    expect(searchKindOf(view.container)).toBe('matches')
+    expect(view.getByText(/Full grep result stored at: spill:\/\/grep-1/)).toBeTruthy()
+  })
+})
+
+describe('SearchRow keyed card', () => {
+  const rowProps = (block: RunningToolCall | ToolResultNode, toolName: string): ToolRowProps => ({
+    callId: 'c1', toolName, block, openFile: vi.fn(), sessionId: SID,
+  } as unknown as ToolRowProps)
+
+  it('renders the grep card resident under the summary row, without an expand gesture', () => {
+    const view = render(<SearchRow {...rowProps(settledGrep(), 'grep')} />)
+    expect(view.getByText('Search')).toBeTruthy()
+    expect(searchRows(view.container)).toContain('12: const foo = 1')
+    expect(searchKindOf(view.container)).toBe('matches')
+    // The card's controls are the row's only interactions.
+    expect(view.getByText('复制')).toBeTruthy()
+  })
+
+  it('renders the glob path card resident', () => {
+    const view = render(<SearchRow {...rowProps(settledGlob(), 'glob')} />)
+    expect(view.getByText('src/a.ts')).toBeTruthy()
+    expect(searchKindOf(view.container)).toBe('paths')
+  })
+
+  it('agrees with the summary row about the run state', () => {
+    const runningView = render(<SearchRow {...rowProps(runningGrep(), 'grep')} />)
+    expect(runningView.container.querySelector('[data-variant="search"]')?.getAttribute('data-state')).toBe('running')
+    // No result view yet, so no resident card.
+    expect(searchKindOf(runningView.container)).toBeNull()
+    cleanup()
+    const errorView = render(<SearchRow {...rowProps(settledGrep({
+      isError: true, resultView: { card: 'generic' },
+    }), 'grep')} />)
+    expect(errorView.container.querySelector('[data-variant="search"]')?.getAttribute('data-state')).toBe('error')
+  })
+
+  it('surfaces the result text when an errored search has no card', () => {
+    // grep/glob return no presentResult on error → no card; the row shows the
+    // model-facing error text instead of a bare red dot.
+    const view = render(<SearchRow {...rowProps(settledGrep({
+      isError: true, resultView: null,
+      content: [{ type: 'text', text: 'grep: invalid regular expression' }],
+    }), 'grep')} />)
+    expect(searchKindOf(view.container)).toBeNull()
+    expect(view.getByText('grep: invalid regular expression')).toBeTruthy()
+  })
+
+  it('surfaces the result text for a settled non-error call with no card', () => {
+    // A successful nested run_code sub-dispatch (backend computes no
+    // presentationMeta, so resultView is null) or a legacy generic result settles
+    // with search === null and state ok. The keyed SearchRow owns the slot, so
+    // without the widened arm the content would be lost behind a bare summary.
+    const view = render(<SearchRow {...rowProps(settledGrep({
+      isError: false, resultView: null,
+      content: [{ type: 'text', text: 'nested run_code output line' }],
+    }), 'grep')} />)
+    expect(view.container.querySelector('[data-variant="search"]')?.getAttribute('data-state')).toBe('ok')
+    expect(searchKindOf(view.container)).toBeNull()
+    expect(view.getByText('nested run_code output line')).toBeTruthy()
+  })
+
+  it('renders the recovery footer below the card when the search was capped', () => {
+    const recovery = 'a.ts\n  12: const foo = 1\n\n(Full grep result stored at: spill://grep-1. Read it to see every match.)'
+    const view = render(<SearchRow {...rowProps(settledGrep({
+      content: [{ type: 'text', text: recovery }],
+      resultView: resultMatches({ truncated: true, total: 42 }),
+    }), 'grep')} />)
+    expect(searchKindOf(view.container)).toBe('matches')
+    expect(view.getByText(/Full grep result stored at: spill:\/\/grep-1/)).toBeTruthy()
+  })
+
+  it('shows no recovery footer for an uncapped search', () => {
+    const view = render(<SearchRow {...rowProps(settledGrep(), 'grep')} />)
+    expect(view.container.textContent).not.toMatch(/stored at/)
+  })
+
+  it('falls back to the error name/code when an errored result has no text block', () => {
+    const view = render(<SearchRow {...rowProps(settledGrep({
+      isError: true, resultView: null, content: [],
+      error: { name: 'ToolError', code: 'timeout' },
+    }), 'grep')} />)
+    expect(view.getByText('ToolError: timeout')).toBeTruthy()
+  })
+
+  it('shows the result view\'s replacement title instead of the args summary', () => {
+    const view = render(<SearchRow {...rowProps(settledGrep({
+      resultView: resultMatches({ title: '3 matches in 2 files' }),
+    }), 'grep')} />)
+    expect(view.getByText('3 matches in 2 files')).toBeTruthy()
+  })
+
+  it('keeps the args-derived summary when the result view has no title', () => {
+    const view = render(<SearchRow {...rowProps(settledGrep(), 'grep')} />)
+    expect(view.getByText('foo')).toBeTruthy()
+  })
+
+  it('registers the one row component under both grep and glob keys', () => {
+    const registered: { key: unknown; component: unknown }[] = []
+    const ctx = {
+      slots: {
+        register: (options: { name: string; key: string }, component: unknown) => {
+          registered.push({ key: options.key, component })
+        },
+      },
+    } as never
+    searchToolview.apply(ctx)
+    expect(registered.map(r => r.key)).toEqual(['grep', 'glob'])
+    // One component, two keys.
+    expect(registered[0]!.component).toBe(SearchRow)
+    expect(registered[1]!.component).toBe(SearchRow)
+    expect(searchToolview.inject).toEqual(['slots', 'conversation'])
+  })
+})
+
+describe('DetailsPanel Output section (search)', () => {
+  function mount(snapshot: ConversationSnapshot, selection: SelectionTarget | null) {
+    localStorage.clear()
+    const chat = createChatStore().create()
+    if (selection !== null) chat.actions.select(selection)
+    const sessions = createSnapshotStore<SessionListState>({ ids: [], byId: {}, current: undefined, phase: 'ready' })
+    const workspaces = createSnapshotStore<WorkspaceListState>({
+      items: [], archivedSessionIds: [], state: 'idle', phase: 'ready', error: null,
+      baselinesReady: true, recentWorkspaceId: undefined,
+    })
+    return render(
+      <DetailsPanel
+        sessionId={SID}
+        useSession={bindSnapshotSelector({ getSnapshot: () => 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()}
+        t={t}
+      />,
+    )
+  }
+
+  function snapshot(over: Partial<ConversationSnapshot> = {}): 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 grepTarget: SelectionTarget = { turnSeq: 10, callId: 'c1', toolName: 'grep' }
+  const globTarget: SelectionTarget = { turnSeq: 11, callId: 'c2', toolName: 'glob' }
+
+  it('renders the grep matches card at full height, keeping the JSON Input section', () => {
+    const view = mount(snapshot({ nodes: [settledGrep()] }), grepTarget)
+    expect(view.getByText(/"pattern"/)).toBeTruthy()
+    expect(searchRows(view.container)).toContain('12: const foo = 1')
+    expect(searchKindOf(view.container)).toBe('matches')
+  })
+
+  it('renders the glob path card', () => {
+    const view = mount(snapshot({ nodes: [settledGlob()] }), globTarget)
+    expect(view.getByText('src/a.ts')).toBeTruthy()
+    expect(searchKindOf(view.container)).toBe('paths')
+  })
+
+  it('renders the recovery footer below the card for a capped search', () => {
+    const recovery = 'src/a.ts\nsrc/b.ts\n\n(Showing 2 of 23 paths. Full sorted result stored at: spill://glob-7.)'
+    const view = mount(snapshot({
+      nodes: [settledGlob({ content: [{ type: 'text', text: recovery }], resultView: resultPaths({ truncated: true, total: 23 }) })],
+    }), globTarget)
+    expect(searchKindOf(view.container)).toBe('paths')
+    expect(view.getByText(/Full sorted result stored at: spill:\/\/glob-7/)).toBeTruthy()
+  })
+
+  it('a non-search result keeps the flattened pre form', () => {
+    const view = mount(snapshot({
+      nodes: [settledGrep({ callView: null, resultView: null })],
+    }), grepTarget)
+    expect(searchKindOf(view.container)).toBeNull()
+    const output = view.getByText('输出').closest('section')
+    expect(output?.querySelector('pre')?.textContent).toContain('const foo = 1')
+  })
+})
@@ -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: 58be01d56a85c66a144df3f8054840961e987403
-README.zh.md: 2efbec77e64d664553e93b5a8f8dcd2ec7fce49e
+README.md: 6430a789c15634538a38d6581df50a489522db55
+README.zh.md: 78249612cce3148fcececded40c529682450460a
@@ -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), TerminalBlock, DiffBlock, and WebBlock. 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, SearchBlock, DiffBlock, and WebBlock. 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).

+## Search results
+
+`SearchBlock` renders a completed search, one component for both kinds (discriminated by `kind`). A `matches` (grep) shows each file as a bold path header with its `lineNumber: line` rows, the per-file group collapsible; a `paths` (glob) shows a flat path list. Both flatten to one row list the height cap slices head/tail over (default 16, the TerminalBlock split arithmetic), and neither soft-wraps — a long match line or path scrolls horizontally instead of folding. The banner summary folds the pre-cap total in when the tool capped the result (`显示 X / 共 N 处匹配 · K 个文件` for grep, `显示 X / 共 N 个路径` for glob), so the card never presents a capped result as complete; a copy control writes the whole structured result regardless of the cap or which groups are collapsed. Geometry mirrors CodeBlock/TerminalBlock. Rationale: [the web search card note](../../../.agents/notes/implemented/feature/2026-07-30-web-search-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).
@@ -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、DiffBlock，以及 WebBlock。契约：api-contracts v3 §8。
+纯 React 原子组件（零 cordis）：StateDot、ic_ds_* 图标、Button/Pill/Menu/Modal/Input、markdown 家族（MessageText/MarkdownText/JsonBlock）、只读 JsonTree 检查器、`useAnchoredMaxHeight` hook（把底部锚定的浮层高度收敛到锚点上方的视口空间，并在 resize、scroll 与调用方提供的依赖变化时重新测量）、TerminalBlock、SearchBlock、DiffBlock，以及 WebBlock。契约：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)。

+## 搜索结果
+
+`SearchBlock` 渲染一次已完成的搜索,一个组件绘制两种 kind(由 `kind` 判别)。`matches`(grep)把每个文件渲染为粗体路径头加其 `lineNumber: line` 行,每个文件组可折叠;`paths`(glob)渲染扁平路径列表。两者都摊平成一个行列表,由高度上限做头/尾切片(默认 16,与 TerminalBlock 相同的切分算法),且都不软换行——长匹配行或路径横向滚动而非折行。当工具截断结果时,banner 摘要把截断前总数折入(grep 为 `显示 X / 共 N 处匹配 · K 个文件`,glob 为 `显示 X / 共 N 个路径`),使卡片绝不把截断结果呈现为完整;复制控件写入完整结构化结果,无论是否触及上限或哪些组被折叠。几何镜像 CodeBlock/TerminalBlock。原理:[Web 搜索卡片笔记](../../../.agents/notes/implemented/feature/2026-07-30-web-search-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)。
@@ -0,0 +1,120 @@
+/* Geometry mirrors CodeBlock and TerminalBlock (12px radius, code-block
+   surface + banner row, markdown code-block font) so a search card reads as one
+   family with them. The deliberate divergence they share: the result rows keep
+   `white-space: pre` and scroll horizontally, because folding a long match line
+   or path destroys the alignment a reader scans by. */
+
+.block {
+  --dsl-search-radius: 12px;
+  --dsl-search-line-height: 22px;
+
+  position: relative;
+  margin: 16px 0;
+  color: var(--dsw-alias-label-primary);
+  background: var(--dsw-alias-markdown-code-block);
+  border-radius: var(--dsl-search-radius);
+}
+
+/* The banner: result summary on the left, the copy control holding its
+   intrinsic width on the right. */
+.header {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+  padding: 9px 14px;
+  background: var(--dsw-alias-markdown-code-block-banner);
+  border-top-left-radius: var(--dsl-search-radius);
+  border-top-right-radius: var(--dsl-search-radius);
+}
+
+.summary {
+  flex: 1;
+  min-width: 0;
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  font: var(--dsw-font-xs-13);
+  color: var(--dsw-alias-label-secondary);
+}
+
+.copyButton {
+  flex: none;
+  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: 8px 14px 12px 0;
+  font: var(--dsw-font-markdown-code-block);
+  overflow-x: auto;
+  overflow-y: hidden;
+}
+
+/* No wrapping: a match line or a path keeps its content on one row and scrolls
+   sideways instead of folding. */
+.line {
+  min-height: var(--dsl-search-line-height);
+  padding-left: 14px;
+  white-space: pre;
+}
+
+/* The 1-based line number ahead of a grep match line, dimmed so the match text
+   stays the salient content. */
+.lineNumber {
+  color: var(--dsw-alias-label-tertiary);
+}
+
+/* A file group's header: a bold path label plus its match count, the whole row
+   the collapse control. */
+.fileHeader {
+  display: flex;
+  align-items: baseline;
+  gap: 8px;
+  width: 100%;
+  min-height: var(--dsl-search-line-height);
+  padding: 0 14px;
+  border: none;
+  background-color: transparent;
+  cursor: pointer;
+  font: inherit;
+  text-align: left;
+}
+
+.filePath {
+  min-width: 0;
+  font-weight: 600;
+  color: var(--dsw-alias-label-primary);
+  white-space: pre;
+}
+
+.fileCount {
+  flex: none;
+  color: var(--dsw-alias-label-tertiary);
+}
+
+.expand {
+  display: block;
+  width: 100%;
+  padding: 0 14px;
+  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);
+}
+
+.empty {
+  padding: 12px 14px;
+  font: var(--dsw-font-markdown-code-block);
+  color: var(--dsw-alias-label-tertiary);
+}
@@ -0,0 +1,277 @@
+// SearchBlock: the search surface for a completed content or path search — a
+// banner (result summary that folds the pre-cap total in when the tool capped
+// the result, plus a copy control), then either grep matches grouped by file
+// (each file a bold
+// path header with its `lineNumber: line` rows, the group collapsible) or a
+// flat glob path list. Both shapes flatten to one list of rows the height cap
+// slices head/tail over, and neither soft-wraps: a long match line or path
+// scrolls horizontally instead of folding. Geometry mirrors CodeBlock and
+// TerminalBlock so a search card reads as one family with them.
+
+import { useCallback, useState, type ReactNode } from 'react'
+import clsx from 'clsx'
+import { headTailCap } from './head-tail-cap.ts'
+import { useCopyFeedback } from './use-copy-feedback.ts'
+import css from './SearchBlock.module.css'
+
+/**
+ * Result rows shown before the height cap collapses the middle. Matches
+ * {@link DEFAULT_TERMINAL_MAX_LINES} so a search card and a terminal card cut a
+ * long result at the same place.
+ */
+export const DEFAULT_SEARCH_MAX_LINES = 16
+
+/** One matched line inside a {@link SearchFileGroup}: its 1-based line number and text. */
+export interface SearchBlockLineMatch {
+  /** 1-based line number of the match within its file. */
+  lineNumber: number
+  /** The matched line text, as the tool surfaced it. */
+  line: string
+}
+
+/** One file's grouped matches, in first-seen file order. */
+export interface SearchFileGroup {
+  /** The file the matches belong to (the display path). */
+  path: string
+  /** The file's matched lines, in output order. */
+  matches: SearchBlockLineMatch[]
+}
+
+/** Fields both search shapes carry (the render site positions; this component draws). */
+interface SearchBlockCommon {
+  /**
+   * Whether the tool capped the inline result: the shape carries only the
+   * retained results, not every result the search found. The banner summary
+   * folds the pre-cap `total` in (`显示 X / 共 N …`) so the card never presents a
+   * capped result as complete.
+   */
+  truncated: boolean
+  /** Total results the search found before capping (equals the retained count when not `truncated`). */
+  total: number
+  /** Height cap in rows before the middle collapses (default {@link DEFAULT_SEARCH_MAX_LINES}). */
+  maxLines?: number | undefined
+  /** Extra class merged onto the wrapper. */
+  className?: string | undefined
+}
+
+/** Props for the grouped-matches (`grep`) shape. */
+export interface SearchMatchesBlockProps extends SearchBlockCommon {
+  kind: 'matches'
+  /** Matched lines grouped by file, in first-seen file order. */
+  files: SearchFileGroup[]
+}
+
+/** Props for the flat-path (`glob`) shape. */
+export interface SearchPathsBlockProps extends SearchBlockCommon {
+  kind: 'paths'
+  /** The discovered paths, in the tool's result order (the retained page when `truncated`). */
+  paths: string[]
+}
+
+/** {@link SearchBlock} props: one card, two `kind`-discriminated shapes. */
+export type SearchBlockProps = SearchMatchesBlockProps | SearchPathsBlockProps
+
+/**
+ * One flattened render row. A matches card produces a `file` header row per
+ * group followed by a `match` row per retained line while the group is
+ * expanded; a paths card produces one `path` row per path. The height cap
+ * counts these rows uniformly, so a file header costs one row exactly as a
+ * match line or a path does.
+ */
+type SearchRow =
+  | { type: 'file'; path: string; count: number; index: number; collapsed: boolean }
+  | { type: 'match'; lineNumber: number; line: string; key: string; fileIndex: number }
+  | { type: 'path'; path: string }
+
+/**
+ * The plain-text form the copy control writes: the whole structured result
+ * regardless of the height cap or which groups are collapsed, so the clipboard
+ * carries the result rather than what the card happens to be showing.
+ * @param props - the card's props.
+ * @returns the copyable text, or the empty string for an empty result.
+ */
+function copyText(props: SearchBlockProps): string {
+  if (props.kind === 'paths') return props.paths.join('\n')
+  return props.files
+    .map(file => [file.path, ...file.matches.map(m => `${m.lineNumber}: ${m.line}`)].join('\n'))
+    .join('\n\n')
+}
+
+/**
+ * Number of retained results the card holds: the matched-line count across all
+ * files for a matches card, the path count for a paths card. This is the count
+ * the banner summary reports against `total` when the result was capped.
+ * @param props - the card's props.
+ * @returns the retained result count.
+ */
+function shownCount(props: SearchBlockProps): number {
+  return props.kind === 'paths'
+    ? props.paths.length
+    : props.files.reduce((sum, file) => sum + file.matches.length, 0)
+}
+
+/**
+ * The banner summary. When the search was capped it reads `显示 X / 共 N …` so
+ * the retained count and the pre-cap total sit in one clause (mirroring the read
+ * card's `显示 X / Y 行`); when it was not capped it is a plain count of what the
+ * card holds. The unit — `处匹配 · K 个文件` for grep, `个路径` for glob — trails
+ * the count either way.
+ * @param props - the card's props.
+ * @param shown - the retained result count from {@link shownCount}.
+ * @param truncated - whether the search was capped.
+ * @param total - the pre-cap total the truncation clause reports.
+ * @returns the summary text.
+ */
+function summaryText(props: SearchBlockProps, shown: number, truncated: boolean, total: number): string {
+  const count = truncated ? `显示 ${shown} / 共 ${total}` : `${shown}`
+  return props.kind === 'paths'
+    ? `${count} 个路径`
+    : `${count} 处匹配 · ${props.files.length} 个文件`
+}
+
+/**
+ * Flatten a card's shape into its render rows, dropping a collapsed file
+ * group's match rows.
+ * @param props - the card's props.
+ * @param collapsed - the set of collapsed file-group indices (matches only).
+ * @returns the flattened rows in output order.
+ */
+function toRows(props: SearchBlockProps, collapsed: ReadonlySet<number>): SearchRow[] {
+  if (props.kind === 'paths') return props.paths.map((path): SearchRow => ({ type: 'path', path }))
+  const rows: SearchRow[] = []
+  props.files.forEach((file, index) => {
+    const isCollapsed = collapsed.has(index)
+    rows.push({ type: 'file', path: file.path, count: file.matches.length, index, collapsed: isCollapsed })
+    if (isCollapsed) return
+    for (const match of file.matches) {
+      rows.push({ type: 'match', lineNumber: match.lineNumber, line: match.line, key: `${index}:${match.lineNumber}`, fileIndex: index })
+    }
+  })
+  return rows
+}
+
+/**
+ * A stable React key for a flattened render row: the group-scoped match key, a
+ * file-index-scoped header key, or the path itself. Rows of different types
+ * never collide, since each key carries its type prefix or the group index.
+ * @param row - the flattened row.
+ * @returns the key.
+ */
+function rowKey(row: SearchRow): string {
+  switch (row.type) {
+    case 'match': return `match:${row.key}`
+    case 'file': return `file:${row.index}`
+    case 'path': return `path:${row.path}`
+  }
+}
+
+/**
+ * Render a completed search as a grouped-matches or flat-path card.
+ * @param props - see {@link SearchBlockProps}.
+ * @returns the search block element.
+ */
+export function SearchBlock(props: SearchBlockProps) {
+  const { truncated, total, maxLines = DEFAULT_SEARCH_MAX_LINES, className } = props
+  const [expanded, setExpanded] = useState(false)
+  const [collapsed, setCollapsed] = useState<ReadonlySet<number>>(() => new Set())
+
+  // `props` is a fresh object each render, so memoizing on it never hits; the
+  // flatten is cheap, so it runs inline keyed on the collapse set instead.
+  const rows = toRows(props, collapsed)
+  const shown = shownCount(props)
+  const empty = rows.length === 0
+  const { copied, onCopy } = useCopyFeedback(copyText(props))
+
+  const onToggle = useCallback(() => { setExpanded(value => !value) }, [])
+
+  const toggleFile = useCallback((index: number) => {
+    setCollapsed((prev) => {
+      const next = new Set(prev)
+      if (next.has(index)) next.delete(index)
+      else next.add(index)
+      return next
+    })
+  }, [])
+
+  const { hidden, capped, headLines, tailLines } = headTailCap(rows.length, maxLines, expanded)
+  const head = capped ? rows.slice(0, headLines) : rows
+  const naturalTail = capped ? rows.slice(rows.length - tailLines) : []
+  // When the tail slice begins inside a file's matches, its own header sits
+  // above the cut and is not shown, so those rows could not be attributed to a
+  // file. Restore the owning header at the top of the tail — unless the head
+  // slice already carries it (a single large file), where it would duplicate.
+  const tailLead = naturalTail[0]
+  const tailHeader = tailLead?.type === 'match'
+    && !head.some(row => row.type === 'file' && row.index === tailLead.fileIndex)
+    ? rows.find((row): row is Extract<SearchRow, { type: 'file' }> =>
+      row.type === 'file' && row.index === tailLead.fileIndex)
+    : undefined
+  // The restored header is itself a row. Left extra it would push the card to
+  // maxLines + 1 and overstate `hidden` by one, so it consumes a tail slot: drop
+  // the tail's first row (the match whose header this is) for it. Visible rows
+  // hold at maxLines and `hidden` stays exact; the dropped match joins the
+  // hidden middle.
+  const tail = tailHeader === undefined ? naturalTail : naturalTail.slice(1)
+
+  const renderRow = (row: SearchRow): ReactNode => {
+    if (row.type === 'path') return <div className={css.line}>{row.path}</div>
+    if (row.type === 'match') {
+      return (
+        <div className={css.line}>
+          <span className={css.lineNumber}>{row.lineNumber}: </span>
+          {row.line}
+        </div>
+      )
+    }
+    return (
+      <button
+        type="button"
+        className={css.fileHeader}
+        aria-expanded={!row.collapsed}
+        onClick={() => { toggleFile(row.index) }}
+      >
+        <span className={css.filePath}>{row.path}</span>
+        <span className={css.fileCount}>{row.count}</span>
+      </button>
+    )
+  }
+
+  return (
+    <div className={clsx(css.block, className)} data-search={props.kind}>
+      <div className={css.header}>
+        <span className={css.summary}>{summaryText(props, shown, truncated, total)}</span>
+        {!empty && (
+          <button type="button" className={css.copyButton} onClick={onCopy}>
+            {copied ? '复制成功' : '复制'}
+          </button>
+        )}
+      </div>
+      {empty
+        ? <div className={css.empty}>无结果</div>
+        : (
+          <div className={css.body}>
+            {head.map(row => (
+              <div key={rowKey(row)}>{renderRow(row)}</div>
+            ))}
+            {hidden > 0 && (
+              <button
+                type="button"
+                className={css.expand}
+                aria-expanded={expanded}
+                aria-label={expanded ? '收起结果' : `展开其余 ${hidden} 行结果`}
+                onClick={onToggle}
+              >
+                {expanded ? '收起' : `… 其余 ${hidden} 行`}
+              </button>
+            )}
+            {tailHeader !== undefined && (
+              <div key={`tailHeader:${rowKey(tailHeader)}`}>{renderRow(tailHeader)}</div>
+            )}
+            {tail.map(row => (
+              <div key={rowKey(row)}>{renderRow(row)}</div>
+            ))}
+          </div>
+        )}
+    </div>
+  )
+}
@@ -8,7 +8,8 @@
 import { useCallback, useMemo, useState } from 'react'
 import clsx from 'clsx'
 import { parseAnsiLines, type AnsiLine } from './ansi.ts'
-import { writeClipboard } from './clipboard.ts'
+import { headTailCap } from './head-tail-cap.ts'
+import { useCopyFeedback } from './use-copy-feedback.ts'
 import { Pill } from './Pill.tsx'
 import { StateDot, type StateDotState } from './StateDot.tsx'
 import css from './TerminalBlock.module.css'
@@ -202,18 +203,9 @@ export function TerminalBlock({
    return terminated ? parsed.slice(0, -1) : parsed
  }, [text])
  const [expanded, setExpanded] = useState(false)
-  const [copied, setCopied] = useState(false)
-
-  const onCopy = useCallback(() => {
-    if (copied) return
-    // The raw output, never the rendered tree: the prompt line and the status
-    // pill are chrome the user did not run.
-    void writeClipboard(text).then((ok) => {
-      if (!ok) return
-      setCopied(true)
-      window.setTimeout(() => { setCopied(false) }, 1000)
-    })
-  }, [copied, text])
+  // The raw output, never the rendered tree: the prompt line and the status pill
+  // are chrome the user did not run.
+  const { copied, onCopy } = useCopyFeedback(text)

  const onToggle = useCallback(() => { setExpanded(value => !value) }, [])

@@ -232,12 +224,7 @@ export function TerminalBlock({
  // the raw text drew an output box of blank rows plus a copy control for
  // invisible bytes, and hid the placeholder that belongs there.
  const empty = lines.every(line => line.every(span => span.text.trim() === ''))
-  const hidden = lines.length - maxLines
-  const capped = hidden > 0 && !expanded
-  // Same split arithmetic as the TUI transcript's collapsed tool card, so a
-  // command's head and tail slices agree between the two front ends.
-  const headLines = Math.ceil(maxLines / 2)
-  const tailLines = maxLines - headLines
+  const { hidden, capped, headLines, tailLines } = headTailCap(lines.length, maxLines, expanded)

  return (
    <div className={clsx(css.block, className)} data-terminal="" data-running={running ? '' : undefined}>
@@ -0,0 +1,33 @@
+// Head/tail height-cap arithmetic shared by the block primitives (TerminalBlock,
+// SearchBlock) and matching the TUI transcript's collapsed tool card, so a long
+// result's head and tail slices agree across every surface. The split is
+// `ceil(maxLines / 2)` head rows and the remainder as tail rows; a result within
+// the cap shows every row and hides none.
+
+/** The head/tail split metrics for a capped list. */
+export interface HeadTailCap {
+  /** Rows beyond the cap (list length − maxLines); ≤ 0 means nothing is hidden. */
+  hidden: number
+  /** Whether the list is over the cap and not expanded, so it shows a head/tail slice. */
+  capped: boolean
+  /** Head-slice row count: `ceil(maxLines / 2)`. */
+  headLines: number
+  /** Tail-slice row count: the remainder after the head. */
+  tailLines: number
+}
+
+/**
+ * Compute the head/tail cap metrics for a list of `total` rows against `maxLines`,
+ * given whether the surface is expanded. Pure arithmetic; the caller slices its
+ * own rows with `headLines`/`tailLines` so a block can layer its own concerns
+ * (SearchBlock restores a tail file header) on top.
+ * @param total - the list's row count.
+ * @param maxLines - the collapsed-height cap in rows.
+ * @param expanded - whether the surface is expanded (uncaps the list).
+ * @returns the split metrics.
+ */
+export function headTailCap(total: number, maxLines: number, expanded: boolean): HeadTailCap {
+  const hidden = total - maxLines
+  const headLines = Math.ceil(maxLines / 2)
+  return { hidden, capped: hidden > 0 && !expanded, headLines, tailLines: maxLines - headLines }
+}
@@ -24,6 +24,10 @@ export { JsonTree } from './JsonTree.tsx'
 export type { JsonTreeProps, JsonTreeLabels } from './JsonTree.tsx'
 export { TerminalBlock, DEFAULT_TERMINAL_MAX_LINES } from './TerminalBlock.tsx'
 export type { TerminalBlockProps, TerminalBlockLabels } from './TerminalBlock.tsx'
+export { SearchBlock, DEFAULT_SEARCH_MAX_LINES } from './SearchBlock.tsx'
+export type {
+  SearchBlockProps, SearchMatchesBlockProps, SearchPathsBlockProps, SearchFileGroup, SearchBlockLineMatch,
+} from './SearchBlock.tsx'
 export { ReadBlock, DEFAULT_READ_MAX_LINES } from './ReadBlock.tsx'
 export type { ReadBlockProps, ReadBlockLine } from './ReadBlock.tsx'
 export { DiffBlock, DEFAULT_DIFF_MAX_LINES } from './DiffBlock.tsx'
@@ -0,0 +1,37 @@
+// The copy-to-clipboard-with-feedback hook shared by the block primitives
+// (TerminalBlock, SearchBlock): write the given text, and on success flip a
+// transient `copied` flag that the caller renders as a "复制成功" label for one
+// second. A refused write leaves the flag untouched, so the control never claims
+// a copy the host declined.
+
+import { useCallback, useState } from 'react'
+import { writeClipboard } from './clipboard.ts'
+
+/** How long the `copied` flag stays true after a successful write, in ms. */
+const COPIED_FEEDBACK_MS = 1000
+
+/** The copy-feedback hook's return: the transient flag and the copy handler. */
+export interface CopyFeedback {
+  /** True for {@link COPIED_FEEDBACK_MS} after a successful write; render the success label off it. */
+  copied: boolean
+  /** Copy the hook's text; no-op while `copied` is still true, silent on a refused write. */
+  onCopy: () => void
+}
+
+/**
+ * Copy `text` to the clipboard with one-second success feedback.
+ * @param text - the text to write on copy.
+ * @returns the `copied` flag and the `onCopy` handler.
+ */
+export function useCopyFeedback(text: string): CopyFeedback {
+  const [copied, setCopied] = useState(false)
+  const onCopy = useCallback(() => {
+    if (copied) return
+    void writeClipboard(text).then((ok) => {
+      if (!ok) return
+      setCopied(true)
+      window.setTimeout(() => { setCopied(false) }, COPIED_FEEDBACK_MS)
+    })
+  }, [copied, text])
+  return { copied, onCopy }
+}
@@ -0,0 +1,214 @@
+// @vitest-environment jsdom
+// SearchBlock: both kinds (grouped grep matches and a flat glob path list), the
+// folded truncation summary, the empty arm, per-file collapse/expand, the
+// head/tail height cap and its expand control, the tail slice restoring its
+// owning file header, and the copy control writing the whole structured
+// result on both the accepted and refused clipboard paths.
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, fireEvent, render, screen } from '@testing-library/react'
+import { DEFAULT_SEARCH_MAX_LINES, SearchBlock } from '../src/index.ts'
+import type { SearchFileGroup } from '../src/index.ts'
+
+afterEach(cleanup)
+
+beforeEach(() => {
+  vi.useRealTimers()
+})
+
+/** The rendered result rows, one string per visible row (CSS-module class prefix). */
+function lines(container: HTMLElement): string[] {
+  return [...container.querySelectorAll('[class^="_line_"]')].map(row => row.textContent ?? '')
+}
+
+/** The file-group header rows, one string per header (path + count concatenated). */
+function fileHeaders(container: HTMLElement): string[] {
+  return [...container.querySelectorAll('[class^="_fileHeader_"]')].map(row => row.textContent ?? '')
+}
+
+/** `count` numbered match lines under one file, without a terminating newline. */
+function group(path: string, count: number, from = 1): SearchFileGroup {
+  return {
+    path,
+    matches: Array.from({ length: count }, (_v, i) => ({ lineNumber: from + i, line: `hit ${from + i}` })),
+  }
+}
+
+describe('SearchBlock matches kind', () => {
+  it('renders each file as a header group with its matched lines', () => {
+    const view = render(<SearchBlock kind="matches" truncated={false} total={3} files={[
+      { path: 'a.ts', matches: [{ lineNumber: 12, line: 'const a = 1' }, { lineNumber: 40, line: 'return a' }] },
+      { path: 'b.ts', matches: [{ lineNumber: 7, line: 'const b = 2' }] },
+    ]} />)
+    expect(fileHeaders(view.container)).toEqual(['a.ts2', 'b.ts1'])
+    expect(lines(view.container)).toEqual(['12: const a = 1', '40: return a', '7: const b = 2'])
+    // The summary counts matches and files, with no folded pre-cap total below the cap.
+    expect(view.getByText('3 处匹配 · 2 个文件')).toBeTruthy()
+    expect(view.queryByText(/显示|共/u)).toBeNull()
+  })
+
+  it('collapses and re-expands a single file group without touching the others', () => {
+    const view = render(<SearchBlock kind="matches" truncated={false} total={3} files={[
+      { path: 'a.ts', matches: [{ lineNumber: 1, line: 'x' }] },
+      { path: 'b.ts', matches: [{ lineNumber: 2, line: 'y' }] },
+    ]} />)
+    const [headerA] = view.container.querySelectorAll('[class^="_fileHeader_"]')
+    expect(headerA!.getAttribute('aria-expanded')).toBe('true')
+    fireEvent.click(headerA!)
+    // a.ts collapsed: its match row is gone, b.ts's stays.
+    expect(headerA!.getAttribute('aria-expanded')).toBe('false')
+    expect(lines(view.container)).toEqual(['2: y'])
+    fireEvent.click(headerA!)
+    expect(lines(view.container)).toEqual(['1: x', '2: y'])
+  })
+
+  it('folds the pre-cap total into the summary when truncated', () => {
+    const view = render(<SearchBlock kind="matches" truncated total={99} files={[group('a.ts', 2)]} />)
+    expect(view.getByText('显示 2 / 共 99 处匹配 · 1 个文件')).toBeTruthy()
+  })
+})
+
+describe('SearchBlock paths kind', () => {
+  it('renders a flat path list with a path-count summary', () => {
+    const view = render(<SearchBlock kind="paths" truncated={false} total={2} paths={['src/a.ts', 'src/b.ts']} />)
+    expect(lines(view.container)).toEqual(['src/a.ts', 'src/b.ts'])
+    expect(view.getByText('2 个路径')).toBeTruthy()
+    // No file-group headers in the paths shape.
+    expect(fileHeaders(view.container)).toEqual([])
+  })
+
+  it('folds the pre-cap total into the paths summary when truncated', () => {
+    const view = render(<SearchBlock kind="paths" truncated total={50} paths={['a', 'b']} />)
+    expect(view.getByText('显示 2 / 共 50 个路径')).toBeTruthy()
+  })
+})
+
+describe('SearchBlock empty arm', () => {
+  it('shows the placeholder and no copy control for an empty matches result', () => {
+    const view = render(<SearchBlock kind="matches" truncated={false} total={0} files={[]} />)
+    expect(view.getByText('无结果')).toBeTruthy()
+    expect(view.queryByText('复制')).toBeNull()
+    expect(view.getByText('0 处匹配 · 0 个文件')).toBeTruthy()
+  })
+
+  it('shows the placeholder for an empty paths result', () => {
+    const view = render(<SearchBlock kind="paths" truncated={false} total={0} paths={[]} />)
+    expect(view.getByText('无结果')).toBeTruthy()
+    expect(view.queryByText('复制')).toBeNull()
+  })
+})
+
+describe('SearchBlock height cap', () => {
+  it('renders every row and no expand control under the cap', () => {
+    const view = render(<SearchBlock kind="paths" truncated={false} total={4}
+      paths={['a', 'b', 'c', 'd']} maxLines={4} />)
+    expect(lines(view.container)).toHaveLength(4)
+    expect(view.container.querySelector('[aria-label^="展开"]')).toBeNull()
+  })
+
+  it('slices head and tail over the cap and expands on click', () => {
+    const paths = Array.from({ length: 10 }, (_v, i) => `p${i + 1}`)
+    const view = render(<SearchBlock kind="paths" truncated={false} total={10} paths={paths} maxLines={4} />)
+    // maxLines 4: head = ceil(4/2) = 2, tail = 2, 6 hidden.
+    expect(lines(view.container)).toEqual(['p1', 'p2', 'p9', 'p10'])
+    const toggle = view.getByRole('button', { name: '展开其余 6 行结果' })
+    expect(toggle.textContent).toBe('… 其余 6 行')
+    fireEvent.click(toggle)
+    expect(lines(view.container)).toHaveLength(10)
+    const collapse = view.getByRole('button', { name: '收起结果' })
+    expect(collapse.textContent).toBe('收起')
+    fireEvent.click(collapse)
+    expect(lines(view.container)).toEqual(['p1', 'p2', 'p9', 'p10'])
+  })
+
+  it('counts a file header as one capped row alongside its matches', () => {
+    // One file with 10 matches → 11 rows (header + 10). Cap 4: head 2, tail 2.
+    const view = render(<SearchBlock kind="matches" truncated={false} total={10}
+      files={[group('a.ts', 10)]} maxLines={4} />)
+    // Head takes the header then the first match; tail takes the last two matches.
+    expect(lines(view.container)).toEqual(['1: hit 1', '9: hit 9', '10: hit 10'])
+    expect(fileHeaders(view.container)).toEqual(['a.ts10'])
+    expect(view.getByRole('button', { name: '展开其余 7 行结果' })).toBeTruthy()
+  })
+
+  it('renders the head slice alone when the cap leaves no tail', () => {
+    const view = render(<SearchBlock kind="paths" truncated={false} total={5}
+      paths={['a', 'b', 'c', 'd', 'e']} maxLines={1} />)
+    expect(lines(view.container)).toEqual(['a'])
+    expect(view.getByRole('button', { name: '展开其余 4 行结果' })).toBeTruthy()
+  })
+
+  it('restores the owning file header above a tail slice that begins mid-file', () => {
+    // Two files of 10 matches each → 22 rows. Cap 8: head 4 (a.ts header + 3
+    // matches), tail 4. The tail begins mid-b.ts, so its header is restored —
+    // and, being a row itself, it consumes one tail slot rather than pushing the
+    // card to 9 rows: the tail keeps its last 3 matches, total visible = 8.
+    const view = render(<SearchBlock kind="matches" truncated={false} total={20} maxLines={8} files={[
+      group('a.ts', 10), group('b.ts', 10, 11),
+    ]} />)
+    expect(fileHeaders(view.container)).toEqual(['a.ts10', 'b.ts10'])
+    expect(lines(view.container)).toEqual([
+      '1: hit 1', '2: hit 2', '3: hit 3',
+      '18: hit 18', '19: hit 19', '20: hit 20',
+    ])
+    // Visible rows hold at maxLines (2 headers + 6 matches = 8), so the hidden
+    // count stays exact: 22 − 8 = 14.
+    expect(view.getByRole('button', { name: '展开其余 14 行结果' })).toBeTruthy()
+  })
+
+  it('caps at the documented default when maxLines is absent', () => {
+    const paths = Array.from({ length: DEFAULT_SEARCH_MAX_LINES + 1 }, (_v, i) => `p${i}`)
+    const view = render(<SearchBlock kind="paths" truncated={false} total={paths.length} paths={paths} />)
+    expect(lines(view.container)).toHaveLength(DEFAULT_SEARCH_MAX_LINES)
+    expect(view.getByRole('button', { name: '展开其余 1 行结果' })).toBeTruthy()
+  })
+})
+
+describe('SearchBlock copy', () => {
+  it('copies the whole structured matches result, not the collapsed or capped view', async () => {
+    vi.useFakeTimers()
+    const writeText = vi.fn().mockResolvedValue(undefined)
+    Object.defineProperty(navigator, 'clipboard', { configurable: true, value: { writeText } })
+    const view = render(<SearchBlock kind="matches" truncated total={9} maxLines={2} files={[
+      { path: 'a.ts', matches: [{ lineNumber: 1, line: 'x' }, { lineNumber: 2, line: 'y' }] },
+      { path: 'b.ts', matches: [{ lineNumber: 3, line: 'z' }] },
+    ]} />)
+    // Collapse a group and leave the cap in place: the clipboard still gets it all.
+    fireEvent.click(view.container.querySelector('[class^="_fileHeader_"]')!)
+    fireEvent.click(screen.getByRole('button', { name: '复制' }))
+    expect(writeText).toHaveBeenCalledWith('a.ts\n1: x\n2: y\n\nb.ts\n3: z')
+    await act(async () => { await Promise.resolve() })
+    expect(screen.getByRole('button', { name: '复制成功' })).toBeTruthy()
+    // A second click while the ok label shows is a no-op.
+    fireEvent.click(screen.getByRole('button', { name: '复制成功' }))
+    expect(writeText).toHaveBeenCalledTimes(1)
+    await vi.advanceTimersByTimeAsync(1000)
+    expect(screen.getByRole('button', { name: '复制' })).toBeTruthy()
+  })
+
+  it('copies the newline-joined path list for the paths shape', async () => {
+    const writeText = vi.fn().mockResolvedValue(undefined)
+    Object.defineProperty(navigator, 'clipboard', { configurable: true, value: { writeText } })
+    render(<SearchBlock kind="paths" truncated={false} total={2} paths={['src/a.ts', 'src/b.ts']} />)
+    fireEvent.click(screen.getByRole('button', { name: '复制' }))
+    expect(writeText).toHaveBeenCalledWith('src/a.ts\nsrc/b.ts')
+    expect(await screen.findByRole('button', { name: '复制成功' })).toBeTruthy()
+  })
+
+  it('does not claim success when the host refuses the write', async () => {
+    Object.defineProperty(navigator, 'clipboard', {
+      configurable: true, value: { writeText: vi.fn().mockRejectedValue(new Error('denied')) },
+    })
+    render(<SearchBlock kind="paths" truncated={false} total={1} paths={['a']} />)
+    fireEvent.click(screen.getByRole('button', { name: '复制' }))
+    await act(async () => { await Promise.resolve() })
+    expect(screen.getByRole('button', { name: '复制' })).toBeTruthy()
+    expect(screen.queryByRole('button', { name: '复制成功' })).toBeNull()
+  })
+
+  it('merges className onto the wrapper and tags the wrapper with the kind', () => {
+    const view = render(<SearchBlock kind="paths" truncated={false} total={0} paths={[]} className="x" />)
+    expect(view.container.firstElementChild?.classList.contains('x')).toBe(true)
+    expect(view.container.firstElementChild?.getAttribute('data-search')).toBe('paths')
+  })
+})
@@ -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/ui/app-boot/README.md
-README.md: 54f754842d9a6673ed6791b94656139f0f1be6a3
-README.zh.md: dd56084812e8241f0db24601ce2baeba51252d42
+README.md: 51bc5082512632dd493956b96c605aff47dc872e
+README.zh.md: 644d3a3613a9516cb02881fac8ba7531bffa81eb
@@ -14,6 +14,7 @@ Shared boot glue for the app bins ([`dsh`](../../../apps/cli/README.md), [`dsh-c
 | `loadPersonalPatches(binName, dir?)` | Parse the optional `config.yaml` in the Harness home (default [`resolveDshHome()`](../../util/paths/README.md): `$DSH_HOME`, else `~/.dsh`) — a top-level YAML array of include `PatchOptions` (id-targeted config overrides, `insert` lists, `!!js` allowed); absent file → `undefined`, an unreadable/unparsable/non-array file throws |
 | `loadOverlayPatches(binName, file)` | Parse a required patch-list file with the same shape as personal config; read or parse failures throw a labelled error |
 | `boot(binName, absoluteConfigPath, patches?, prepare?)` | Create the root context, install Loader, run optional host preparation before config-tree entries mount (`prepare` may use Loader and provide launcher-owned context slots such as [`MAIN_SESSION_ID_KEY`](../tui/README.md)), then mount and await the include tree, assert entries loaded and activated, and return the root context |
+| `renderConfigDump(binName, absoluteConfigPath, layers, warn?)` | Compose the base config and labeled overlay layers offline — the include's own parser and patch algorithm (`entryListSchema`/`applyEntryPatches`), so the result equals what `boot()` mounts — and render YAML with `!!js` expressions verbatim; each run of same-provenance rows is preceded by a `# ==` comment naming the contributing file and the layers that patched it, keeping the output one loadable document; a patch matching no row goes to `warn` with its layer label (default: one stderr line), read/parse/shape failures throw |
 | `addHarnessSourceSection(ctx, sourceRoot)` | Add a global `harness:source` prompt section (ordered just after the harness identity, before the persona) telling the agent the on-disk path to its own source checkout; a no-op returning `undefined` when the booted tree has no `systemPrompt` service. The section is registered against that service's fiber, so a dev HMR reload of the system prompt drops it until the next boot |
 | `HARNESS_SOURCE_SECTION` | The `'harness:source'` section name `addHarnessSourceSection` registers under |

@@ -14,6 +14,7 @@
 | `loadPersonalPatches(binName, dir?)` | 解析 Harness home 中可选的 `config.yaml`（默认使用 [`resolveDshHome()`](../../util/paths/README.md)：先取 `$DSH_HOME`，否则取 `~/.dsh`）：其顶层是一个 YAML 数组，内容为 include 的 `PatchOptions`（按 id 定位的配置覆盖、`insert` 列表，允许 `!!js`）；文件不存在时返回 `undefined`，文件不可读、不可解析或内容不是数组时抛出异常 |
 | `loadOverlayPatches(binName, file)` | 解析一份必需的 patch 列表文件，其形状与个人配置相同；读取或解析失败时抛出带标签的错误 |
 | `boot(binName, absoluteConfigPath, patches?, prepare?)` | 创建根上下文并安装 Loader，在配置树条目挂载前执行可选的宿主准备操作（`prepare` 可以使用 Loader，也可以提供由启动器拥有的上下文插槽，例如 [`MAIN_SESSION_ID_KEY`](../tui/README.md)），再挂载并等待 include 树结算，断言所有条目均已加载并激活，最后返回根上下文 |
+| `renderConfigDump(binName, absoluteConfigPath, layers, warn?)` | 离线合成基础配置与带标签的覆盖层——使用 include 自己的解析器和补丁算法（`entryListSchema`/`applyEntryPatches`），因此结果与 `boot()` 挂载的内容一致——并渲染为 YAML，`!!js` 表达式原样保留；每段来源相同的连续行之前都有一条 `# ==` 注释，标明贡献该段的文件以及修补过它的层，输出仍是一份可加载的文档；未匹配到行的补丁连同其层标签交给 `warn`（默认：一行 stderr），读取／解析／形状失败则抛出 |
 | `addHarnessSourceSection(ctx, sourceRoot)` | 添加全局 `harness:source` 提示词段落（顺序紧随 harness 身份、位于 persona 之前），告知 agent（智能体）自身源代码 checkout 的磁盘路径；如果已启动树没有此项服务，则不执行操作并返回 `undefined`。这里的服务是 `systemPrompt`；该段落注册到它的 fiber，因此开发环境 HMR（热模块替换）重新加载系统提示词后，它会消失直至下次启动 |
 | `HARNESS_SOURCE_SECTION` | `'harness:source'` 段落名称，供 `addHarnessSourceSection` 注册使用 |

@@ -12,7 +12,7 @@ import { basename, dirname, join, resolve } from 'node:path'
 import * as yaml from 'js-yaml'
 import { Context, type FiberState } from 'cordis'
 import Loader from '@cordisjs/plugin-loader'
-import Include, { type PatchOptions } from '@cordisjs/plugin-include'
+import Include, { applyEntryPatches, entryListSchema, type PatchOptions } from '@cordisjs/plugin-include'
 import { resolveDshHome } from '@deepseek-ai/dsh-paths'
 // Side-effect type import: resolves `ctx.get('systemPrompt')` to the service.
 import type {} from '@deepseek-ai/dsh-system-prompt'
@@ -60,16 +60,12 @@ export function loadEnv(
 /** File inside the Harness home holding the personal loader overlay patches. */
 export const PERSONAL_CONFIG_FILENAME = 'config.yaml'

-// The include's YAML dialect: `!!js` scalars become expression nodes the
-// Loader interpolates against each entry's context at mount time. Personal
-// patches are parsed with the same schema so they may reference `process.env`.
-// Load-only: this schema never dumps, so no `predicate`/`represent`.
-const jsExprType = new yaml.Type('tag:yaml.org,2002:js', {
-  kind: 'scalar',
-  resolve: data => typeof data === 'string',
-  construct: data => ({ __jsExpr: String(data) }),
-})
-const personalPatchesSchema = yaml.JSON_SCHEMA.extend(jsExprType)
+// The include's YAML dialect (`!!js` scalars become expression nodes the
+// Loader interpolates against each entry's context at mount time), imported
+// from the include itself so patch parsing and config dumping can never drift
+// from what the include mounts. Personal patches share it so they may
+// reference `process.env`.
+const personalPatchesSchema = entryListSchema

 /**
 * Load the optional personal overlay patches (`config.yaml` under the Harness
@@ -149,6 +145,141 @@ function parsePatchList(
  return parsed as PatchOptions[]
 }

+/** One overlay patch list with the label provenance comments print for it. */
+export interface ConfigDumpLayer {
+  /** Source name shown in provenance comments (a file basename or path). */
+  label: string
+  /** The layer's patches, from {@link loadOverlayPatches} / {@link loadPersonalPatches}. */
+  patches: PatchOptions[]
+}
+
+/**
+ * Compose the effective entry list exactly as `boot()` would mount it: parse
+ * the base config file with the include's entry-list dialect, apply every
+ * layer's patches as ONE flattened list through the include's own patch
+ * algorithm (`applyEntryPatches`) — the same single call `boot()` makes, so
+ * even patch-visibility corner cases (a later layer targeting a group child a
+ * plain config replacement introduced, which the single-pass id index never
+ * sees) compose identically — then render the result as YAML in the same
+ * dialect (`!!js` expressions print verbatim, unevaluated).
+ *
+ * Every run of rows with the same provenance is preceded by a `# ==` comment
+ * naming the file that contributed the rows and any layers that patched them,
+ * so the output stays a loadable YAML document while showing which section
+ * comes from which file. Provenance is derived from single-call prefix
+ * snapshots (base + layers 1..k), diffed positionally: the patch algorithm
+ * only rewrites rows in place or appends, so a top-level index identifies one
+ * row across snapshots, and a layer whose addition changes the row (config
+ * replacement, disable, group insert) is listed as having patched it.
+ *
+ * A patch that matches no row is reported through `warn` with its layer
+ * label, mirroring the Loader's boot-time warning. Earlier layers' patches
+ * see an identical preceding state in every snapshot that includes them, so
+ * each snapshot's warning list extends the previous one and the new tail
+ * belongs to the added layer.
+ * @param binName - the diagnostic prefix on read/parse errors.
+ * @param absoluteConfigPath - the base config file `boot()` would include.
+ * @param layers - overlay layers in application order (later wins).
+ * @param warn - sink for skipped-patch diagnostics; defaults to stderr.
+ * @returns the composed entry list rendered as a YAML document with
+ * provenance comment separators.
+ */
+export function renderConfigDump(
+  binName: string,
+  absoluteConfigPath: string,
+  layers: ConfigDumpLayer[],
+  warn: (line: string) => void = line => void process.stderr.write(`${line}\n`),
+): string {
+  let content: string
+  try {
+    content = readFileSync(absoluteConfigPath, 'utf8')
+  } catch (error) {
+    throw new Error(`${binName}: failed to read config ${absoluteConfigPath}: ${String(error)}`)
+  }
+  let parsed: unknown
+  try {
+    parsed = yaml.load(content, { schema: entryListSchema })
+  } catch (error) {
+    throw new Error(`${binName}: failed to parse config ${absoluteConfigPath}: ${String(error)}`)
+  }
+  if (!Array.isArray(parsed)) {
+    throw new Error(`${binName}: config ${absoluteConfigPath} must be a top-level YAML array of entries`)
+  }
+  const baseLabel = basename(absoluteConfigPath)
+  // The YAML boundary yields untyped rows; the include validates entry shape
+  // at mount, and the dump prints whatever the file holds, so `EntryOptions`
+  // here is structural trust in the same file `boot()` would include.
+  const base = parsed as Parameters<typeof applyEntryPatches>[0]
+  // snapshot_k = ONE application of layers 1..k flattened — boot's exact call
+  // shape for that prefix. snapshot_N is therefore the mounted composition.
+  // The patches are cloned per call: applyEntryPatches detaches the entry
+  // list but pushes `insert` rows by reference from the patch list, so
+  // sharing patch objects across snapshot calls would leak a later
+  // snapshot's mutations into an earlier one's result.
+  const snapshot = (count: number, warnings: string[]): ReturnType<typeof applyEntryPatches> => {
+    const flattened = structuredClone(layers.slice(0, count).flatMap(layer => layer.patches))
+    return applyEntryPatches(base, flattened, (message: string, ...args: unknown[]) => {
+      // The include logs through cordis's printf-style logger (`%C` = code); a
+      // dump has no logger, so substitute inline for a plain line.
+      let index = 0
+      warnings.push(message.replace(/%C/g, () => JSON.stringify(args[index++])))
+    })
+  }
+  let previous = base
+  let previousWarnings: string[] = []
+  const provenance: { origin: string; patchedBy: string[] }[] = base.map(() => ({ origin: baseLabel, patchedBy: [] }))
+  let composed = base
+  for (let count = 1; count <= layers.length; count += 1) {
+    const layer = layers[count - 1]
+    /* v8 ignore next -- count iterates 1..length, so the slot exists */
+    if (layer === undefined) continue
+    const warnings: string[] = []
+    composed = snapshot(count, warnings)
+    for (const line of warnings.slice(previousWarnings.length)) {
+      warn(`${binName}: [${layer.label}] ${line}`)
+    }
+    const before = previous.map(entry => JSON.stringify(entry))
+    for (let index = 0; index < composed.length; index += 1) {
+      if (index >= before.length) provenance.push({ origin: layer.label, patchedBy: [] })
+      else if (JSON.stringify(composed[index]) !== before[index]) provenance[index]?.patchedBy.push(layer.label)
+    }
+    previous = composed
+    previousWarnings = warnings
+  }
+  return groupedDump(composed, provenance)
+}
+
+/** Render the composed rows grouped under one provenance comment per contiguous run. */
+function groupedDump(
+  composed: readonly unknown[],
+  provenance: readonly { origin: string; patchedBy: string[] }[],
+): string {
+  const lines: string[] = []
+  let currentLabel: string | undefined
+  let group: unknown[] = []
+  const flush = (): void => {
+    if (currentLabel === undefined || group.length === 0) return
+    lines.push(`# == ${currentLabel}`)
+    lines.push(yaml.dump(group, { schema: entryListSchema, noRefs: true }).trimEnd())
+    group = []
+  }
+  for (let index = 0; index < composed.length; index += 1) {
+    const record = provenance[index]
+    /* v8 ignore next -- provenance is index-aligned with composed by construction */
+    if (record === undefined) continue
+    const label = record.patchedBy.length === 0
+      ? record.origin
+      : `${record.origin}, patched by ${record.patchedBy.join(', ')}`
+    if (label !== currentLabel) {
+      flush()
+      currentLabel = label
+    }
+    group.push(composed[index])
+  }
+  flush()
+  return lines.join('\n') + '\n'
+}
+
 /**
 * The slice of `process` {@link installFailLoud} needs — injectable so tests
 * exercise the handler without registering on (or exiting) the real process.
@@ -0,0 +1,187 @@
+/**
+ * `renderConfigDump` behavior: the offline composition must equal what
+ * `boot()` mounts (same parser, same patch algorithm), print `!!js`
+ * expressions verbatim, separate provenance runs with comment lines while
+ * staying one loadable YAML document, and report skipped patches through
+ * `warn` instead of failing — mirroring the Loader's boot-time warning for a
+ * shared overlay whose row exists only on another surface.
+ */
+
+import { mkdtempSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { describe, expect, it, vi } from 'vitest'
+import * as yaml from 'js-yaml'
+import { entryListSchema } from '@cordisjs/plugin-include'
+import { loadOverlayPatches, renderConfigDump } from '../src/index.ts'
+
+const NAME = 'dsh-test-bin'
+
+const tmp = (): string => mkdtempSync(join(tmpdir(), 'dsh-config-dump-'))
+
+function writeBase(dir: string): string {
+  const base = join(dir, 'base.yml')
+  writeFileSync(base, [
+    '- id: shared',
+    '  name: ./noop.mjs',
+    '  config:',
+    '    value: base',
+    '    key: !!js process.env.DSH_DUMP_SPEC',
+    '- id: untouched',
+    '  name: ./noop.mjs',
+    '',
+  ].join('\n'))
+  return base
+}
+
+describe('renderConfigDump', () => {
+  it('composes overlay layers in order, prints !!js verbatim, and labels each section with its provenance', () => {
+    const dir = tmp()
+    const base = writeBase(dir)
+    const surface = join(dir, 'surface.yml')
+    writeFileSync(surface, [
+      '- id: shared',
+      '  config:',
+      '    value: surface',
+      '    key: !!js process.env.DSH_DUMP_SPEC',
+      '- insert:',
+      '    - id: surface-extra',
+      '      name: ./noop.mjs',
+      '',
+    ].join('\n'))
+    const personal = join(dir, 'personal.yml')
+    writeFileSync(personal, [
+      '- id: surface-extra',
+      '  config:',
+      '    value: personal',
+      '',
+    ].join('\n'))
+
+    const dump = renderConfigDump(NAME, base, [
+      { label: 'surface.yml', patches: loadOverlayPatches(NAME, surface) },
+      { label: 'personal.yml', patches: loadOverlayPatches(NAME, personal) },
+    ], () => {})
+    // Comments do not break loadability: the dump parses as one document
+    // equal to what boot() would mount.
+    const parsed = yaml.load(dump, { schema: entryListSchema }) as {
+      id: string
+      config?: Record<string, unknown>
+    }[]
+    expect(parsed).toEqual([
+      {
+        id: 'shared',
+        name: './noop.mjs',
+        config: { value: 'surface', key: { __jsExpr: 'process.env.DSH_DUMP_SPEC' } },
+      },
+      { id: 'untouched', name: './noop.mjs' },
+      { id: 'surface-extra', name: './noop.mjs', config: { value: 'personal' } },
+    ])
+    // Unevaluated: the expression text round-trips as a !!js scalar.
+    expect(dump).toContain('!!js process.env.DSH_DUMP_SPEC')
+    // Provenance separators: origin file, plus every layer that changed the
+    // row; an inserted row carries the inserting layer as its origin.
+    expect(dump).toContain('# == base.yml, patched by surface.yml')
+    expect(dump).toContain('# == base.yml\n- id: untouched')
+    expect(dump).toContain('# == surface.yml, patched by personal.yml\n- id: surface-extra')
+    expect(dump.indexOf('# == base.yml, patched by surface.yml')).toBeLessThan(dump.indexOf('# == base.yml\n- id: untouched'))
+  })
+
+  it('groups contiguous same-provenance rows under one separator', () => {
+    const dir = tmp()
+    const base = join(dir, 'base.yml')
+    writeFileSync(base, [
+      '- id: a',
+      '  name: ./noop.mjs',
+      '- id: b',
+      '  name: ./noop.mjs',
+      '',
+    ].join('\n'))
+    const dump = renderConfigDump(NAME, base, [], () => {})
+    expect(dump.match(/# == base\.yml/g)).toHaveLength(1)
+    expect(dump).toContain('# == base.yml\n- id: a')
+  })
+
+  it('composes all layers as one flattened patch list, exactly like boot()', () => {
+    // boot() flattens every layer into ONE applyEntryPatches call, whose id
+    // index sees inserted rows but NOT children introduced by a plain group
+    // `config` replacement. A per-layer composition would rebuild the index
+    // between layers and let the second layer patch that child — a tree the
+    // real boot never mounts. Pin the single-call semantics: the child patch
+    // is skipped (with the layer-labeled warning), matching boot.
+    const dir = tmp()
+    const base = join(dir, 'base.yml')
+    writeFileSync(base, [
+      '- id: g',
+      '  name: ./group.mjs',
+      '  group: true',
+      '  config: []',
+      '',
+    ].join('\n'))
+    const warnings: string[] = []
+    const dump = renderConfigDump(NAME, base, [
+      {
+        label: 'a.yml',
+        patches: [{ id: 'g', config: [{ id: 'child', name: './noop.mjs', config: { v: 1 } }] }],
+      },
+      { label: 'b.yml', patches: [{ id: 'child', config: { v: 2 } }] },
+    ], line => void warnings.push(line))
+    expect(warnings).toEqual([`${NAME}: [b.yml] patch: entry "child" not found`])
+    const parsed = yaml.load(dump, { schema: entryListSchema }) as {
+      config?: { config?: { v?: number } }[]
+    }[]
+    expect(parsed[0]?.config?.[0]?.config?.v).toBe(1)
+    // The skipped layer did not change the row, so it is not in provenance.
+    expect(dump).toContain('# == base.yml, patched by a.yml\n- id: g')
+    expect(dump).not.toContain('b.yml\n- id: g')
+  })
+
+  it('reports a patch whose target row is absent through warn with its layer label and keeps composing', () => {
+    const dir = tmp()
+    const base = writeBase(dir)
+    const overlay = join(dir, 'overlay.yml')
+    writeFileSync(overlay, [
+      '- id: only-on-another-surface',
+      '  config:',
+      '    value: ignored',
+      '- id: shared',
+      '  config:',
+      '    value: patched',
+      '',
+    ].join('\n'))
+    const warnings: string[] = []
+    const dump = renderConfigDump(
+      NAME, base,
+      [{ label: 'overlay.yml', patches: loadOverlayPatches(NAME, overlay) }],
+      line => void warnings.push(line),
+    )
+    expect(warnings).toEqual([`${NAME}: [overlay.yml] patch: entry "only-on-another-surface" not found`])
+    const parsed = yaml.load(dump, { schema: entryListSchema }) as { config?: { value?: string } }[]
+    expect(parsed[0]?.config?.value).toBe('patched')
+  })
+
+  it('defaults its warn sink to one stderr line per skipped patch', () => {
+    const dir = tmp()
+    const base = writeBase(dir)
+    const write = vi.spyOn(process.stderr, 'write').mockReturnValue(true)
+    try {
+      renderConfigDump(NAME, base, [{ label: 'x.yml', patches: [{ id: 'absent', config: {} }] }])
+      expect(write).toHaveBeenCalledWith(`${NAME}: [x.yml] patch: entry "absent" not found\n`)
+    } finally {
+      write.mockRestore()
+    }
+  })
+
+  it('fails loud on a missing, unparsable, or non-array base config', () => {
+    const dir = tmp()
+    expect(() => renderConfigDump(NAME, join(dir, 'absent.yml'), [], () => {}))
+      .toThrow(new RegExp(`^${NAME}: failed to read config `))
+    const invalid = join(dir, 'invalid.yml')
+    writeFileSync(invalid, 'invalid: [unclosed\n')
+    expect(() => renderConfigDump(NAME, invalid, [], () => {}))
+      .toThrow(new RegExp(`^${NAME}: failed to parse config `))
+    const scalar = join(dir, 'scalar.yml')
+    writeFileSync(scalar, 'id: not-a-list\n')
+    expect(() => renderConfigDump(NAME, scalar, [], () => {}))
+      .toThrow('must be a top-level YAML array of entries')
+  })
+})
@@ -39,6 +39,7 @@ Keep this log exhaustive — every divergence from upstream must be listed.
 7. **`cordis/src/*.ts` JSDoc enrichment**: added `@param`/`@returns` tags and contract documentation (disposal semantics, waterfall veto, bail conditions, error cases) across the public plugin-author surface — `Context` (class, statics, and the `Context` interface properties incl. `root`), `EventsService`, `Fiber`, `RegistryService`, `ReflectService`, `Service`, `LoggerService` and their `declare module './context.ts'` overloads. Comment-only; no code changes. Motivation: the website API-reference generator renders these docs and hard-errors on undocumented members. Retire this entry when the enrichment is upstreamed to the fork.
 8. **`include/src/index.ts` hot-reload hardening**: `refresh()` awaits the full read-and-update and catches failures (logging a warning and keeping the last good entry tree) instead of rethrowing — upstream's throw escaped `@cordisjs/plugin-hmr`'s async watcher callback as an unhandled rejection, so one bad `cordis.yml` edit killed a live app. `read()` rejects a non-array parse result (an empty or mid-write truncated file parses to `undefined`, which upstream later crashed on) and commits `content`/`data` only on success, so reverting an edit to the exact last good content reads as "unchanged". `refresh()` and the `internal/update` listener re-apply `config.patches` before `root.update()`, matching initial load; upstream applied patches only in `[Service.init]`, so any config hot-reload silently reverted overlay-patched entries and removed inserted ones. `applyPatches` deep-copies via `structuredClone` instead of mutating the cached parse (repeated application converges; removing a patch reverts), and the veto-style `internal/update` listener persists the incoming config itself (`Fiber.update` only assigns behind `next()`), so later re-reads use the new patches. `[Service.init]` falls back to `initial` only on `ENOENT`; an existing-but-invalid file fails loud with its real parse error instead of "config file not found" (or a silent overwrite). `applyPatches` also indexes each `insert`ed entry as it is added, so a later patch in the same list can configure or disable a row an earlier patch inserted; upstream built the id index once before the patch loop, leaving inserted rows silently unpatchable. That matters because `dsh` composes one shared base (`apps/cli/config/base.cordis.yml`) with a surface overlay, an optional `--config` overlay, and the personal `~/.dsh/config.yaml` as sibling patch lists at one include level — patches never cross an include boundary, so surface-only rows would otherwise be unreachable from user config. Covered by `packages/ui/app-boot/tests/config-reload.spec.ts`.
 9. **Vendored Node-compatible TypeScript**: marked erased imports explicitly across `cordis`, `loader`, `include`, `hmr`, and `schemastery` so Node's native TypeScript transform does not request types as runtime exports. Schemastery's source uses an ESM default export and its package declares `type: module`; its built ESM/CJS entries retain explicit `.mjs`/`.cjs` extensions.
+10. **`include/src/index.ts` patch-semantics export**: extracted the private `applyPatches` body into the exported pure function `applyEntryPatches(data, patches, warn)` (the method delegates to it) and exported the `!!js` YAML dialect as `entryListSchema`, so `dsh --dump-config` composes and prints exactly what the include would mount without booting a tree. Behavior-preserving for mounting; the extraction exists because config tooling must never reimplement (and drift from) the patch algorithm.

 ## Sync procedure

@@ -13,7 +13,15 @@ const JsExpr = new yaml.Type('tag:yaml.org,2002:js', {
  represent: (data) => data['__jsExpr'],
 })

-const schema = yaml.JSON_SCHEMA.extend(JsExpr)
+/**
+ * The entry-list YAML dialect: `!!js` scalars round-trip as expression nodes
+ * the Loader evaluates at entry activation. Exported so config tooling
+ * (`dsh --dump-config`) parses and prints exactly the dialect this include
+ * mounts.
+ */
+export const entryListSchema = yaml.JSON_SCHEMA.extend(JsExpr)
+
+const schema = entryListSchema

 const writable: Record<string, string> = {
  '.json': 'application/json',
@@ -23,6 +31,92 @@ const writable: Record<string, string> = {

 const supported = new Set(Object.keys(writable))

+/**
+ * Apply patch lists to an entry list — THE patch semantics of this include,
+ * shared by mounting (`applyPatches`) and offline config tooling
+ * (`dsh --dump-config`) so a dump can never drift from what boots. The input
+ * is never mutated: patching shared entry objects would bake earlier patch
+ * values into the cached parse, so repeated application (config hot-reloads)
+ * could never revert a removed or changed patch. Inserted entries are indexed
+ * as they are added, so a later patch in the same list can target a row an
+ * earlier patch inserted. A patch that matches nothing warns and is skipped.
+ * @param data - the parsed entry list (JSON-safe plain data).
+ * @param patches - the patch list to apply, in order.
+ * @param warn - sink for skipped-patch diagnostics (printf-style, `%C` = code).
+ * @returns a detached entry list with every applicable patch applied.
+ */
+export function applyEntryPatches(
+  data: EntryOptions[],
+  patches: PatchOptions[] | undefined,
+  warn: (message: string, ...args: any[]) => void,
+): EntryOptions[] {
+  if (!patches?.length) return [...data]
+  data = structuredClone(data)
+
+  const entryMap = new Map<string, EntryOptions>()
+  const buildMap = (entries: EntryOptions[]) => {
+    for (const entry of entries) {
+      if (entry.id) entryMap.set(entry.id, entry)
+      if (entry.group && Array.isArray(entry.config)) {
+        buildMap(entry.config)
+      }
+    }
+  }
+  buildMap(data)
+
+  for (const patch of patches) {
+    const { id, insert, name, ...overrides } = patch
+
+    if (insert) {
+      if (id) {
+        const target = entryMap.get(id)
+        if (!target) {
+          warn('patch insert: entry %C not found', id)
+          continue
+        }
+        if (!target.group) {
+          warn('patch insert: entry %C is not a group', id)
+          continue
+        }
+        if (!Array.isArray(target.config)) target.config = []
+        target.config.push(...insert)
+      } else {
+        data.push(...insert)
+      }
+      // Index what this patch added so a LATER patch in the same list can
+      // target it. Patch lists compose one layer per source (surface overlay,
+      // then `--config`, then the user's), and a layer must be able to
+      // configure or disable a row an earlier layer inserted; without this,
+      // inserted rows were silently unpatchable.
+      buildMap(insert)
+      continue
+    }
+
+    if (!id) {
+      warn('patch: id is required for non-insert patches')
+      continue
+    }
+
+    const target = entryMap.get(id)
+    if (!target) {
+      warn('patch: entry %C not found', id)
+      continue
+    }
+
+    if (name && name !== target.name) {
+      warn('patch: name mismatch for %C (expected %C, got %C), skipping', id, target.name, name)
+      continue
+    }
+
+    for (const [key, value] of Object.entries(overrides)) {
+      if (key === 'id') continue
+      target[key] = value
+    }
+  }
+
+  return data
+}
+
 /** Runtime patch applied to entries loaded from an included config file. */
 export interface PatchOptions {
  id?: string
@@ -125,79 +219,9 @@ export class Include extends EntryTree {
  }

  private applyPatches(data: EntryOptions[], patches = this.config.patches): EntryOptions[] {
-    // Always detach from the cached parse: patching shared entry objects would
-    // bake earlier patch values into `this.data`, so repeated application
-    // (config hot-reloads) could never revert a removed or changed patch. The
-    // supported extensions guarantee JSON-safe plain data, so `structuredClone`
-    // cannot throw here.
-    if (!patches?.length) return [...data]
-    data = structuredClone(data)
-
-    const entryMap = new Map<string, EntryOptions>()
-    const buildMap = (entries: EntryOptions[]) => {
-      for (const entry of entries) {
-        if (entry.id) entryMap.set(entry.id, entry)
-        if (entry.group && Array.isArray(entry.config)) {
-          buildMap(entry.config)
-        }
-      }
-    }
-    buildMap(data)
-
-    for (const patch of patches) {
-      const { id, insert, name, ...overrides } = patch
-
-      if (insert) {
-        if (id) {
-          const target = entryMap.get(id)
-          if (!target) {
-            this.ctx.root.logger?.('loader').warn('patch insert: entry %C not found', id)
-            continue
-          }
-          if (!target.group) {
-            this.ctx.root.logger?.('loader').warn('patch insert: entry %C is not a group', id)
-            continue
-          }
-          if (!Array.isArray(target.config)) target.config = []
-          target.config.push(...insert)
-        } else {
-          data.push(...insert)
-        }
-        // Index what this patch added so a LATER patch in the same list can
-        // target it. Patch lists compose one layer per source (surface overlay,
-        // then `--config`, then the user's), and a layer must be able to
-        // configure or disable a row an earlier layer inserted; without this,
-        // inserted rows were silently unpatchable.
-        buildMap(insert)
-        continue
-      }
-
-      if (!id) {
-        this.ctx.root.logger?.('loader').warn('patch: id is required for non-insert patches')
-        continue
-      }
-
-      const target = entryMap.get(id)
-      if (!target) {
-        this.ctx.root.logger?.('loader').warn('patch: entry %C not found', id)
-        continue
-      }
-
-      if (name && name !== target.name) {
-        this.ctx.root.logger?.('loader').warn(
-          'patch: name mismatch for %C (expected %C, got %C), skipping',
-          id, target.name, name,
-        )
-        continue
-      }
-
-      for (const [key, value] of Object.entries(overrides)) {
-        if (key === 'id') continue
-        target[key] = value
-      }
-    }
-
-    return data
+    return applyEntryPatches(data, patches, (message, ...args) => {
+      this.ctx.root.logger?.('loader').warn(message, ...args)
+    })
  }

  async* [Service.init]() {