dsh-plugin-dev-kb 1.8.0 → 1.8.1

package/kb/extra/upgrade-guide/v0.2.2-rc.2/deepseek-files-timeout/guide.zh.md

@@ -0,0 +1,15 @@
+---
+kind: upgrade-guide
+description: "为上传较慢的 DeepSeek 网关保留较长的图片上传时限。"
+---
+# DeepSeek 图片上传时限
+
+[English](guide.md) | 中文
+
+## 变更
+
+`filesApiTimeoutMs` 的默认值从 60,000 毫秒缩短到 20,000 毫秒。上传超时后，下一次需要上传图片的请求直接使用内联图片。连续超时会使跳过的请求次数翻倍，上传成功后清零。
+
+## 迁移
+
+如果网关需要原先的时限，在当前配置的 `cordis.patch.yml` 中为 DeepSeek 提供方设置 `filesApiTimeoutMs: 60000`。已显式设置的值继续生效。运行 `dsh --profile <profile> --dump-config`，检查提供方条目中的值。

package/kb/extra/upgrade-guide/v0.2.2-rc.2/experimental-tool-error-codes/guide.md

@@ -0,0 +1,28 @@
+---
+kind: upgrade-guide
+description: "Experimental and hook plugin tool failures record error codes, NativeError, OarFailure, and StagehandDrainError become HarnessError subclasses, and browser cleanup rejects with BrowserSessionError."
+---
+
+# Experimental plugin failures carry error codes
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Tool failures from the CUA, browser-use, Cua Driver, worktree, Ralph, terminal, OAR subagent, Liveshare, Claude Code and Codex hook, and claude-code-mods plugins now record `error: { name, code }` on `tool/result`; previously most of these results had no `error`. The [package READMEs](../../../../packages/experimental/README.md) list each class and code.
+
+Code that handles these failures in-process sees these changes:
+
+- `NativeError` from `@deepseek-ai/dsh-cua` and `OarFailure` from `@deepseek-ai/dsh-experimental-subagent-oar` now extend `HarnessError` from `@deepseek-ai/dsh-error`. `NativeError` keeps its name, codes, and `CODE: message` text. `OarFailure` drops its `stage` and `category` fields; the same summary stays in `message`, and `code` names the stage. Cancellation before an OAR run starts rejects with a `DOMException` named `AbortError` instead of an `OarFailure`.
+- `StagehandDrainError` from `@deepseek-ai/dsh-experimental-browser-use-stagehand-native` now extends `StagehandError` and has the code `STAGEHAND_CLEANUP_FAILED`.
+- `SessionResources.dispose()` from `@deepseek-ai/dsh-experimental-browser-use-runtime` rejects with `BrowserSessionError` (`BROWSER_CLEANUP_FAILED`) whose `cause` is the `AggregateError` it previously threw; `instanceof AggregateError` no longer matches.
+- Liveshare guard functions return `{ reason, info }` instead of a reason string.
+- Argument failures that now throw `ToolArgsError` show `invalid arguments: ` before the message the model sees, and a CUA screenshot request for a model without image input shows `MODEL_DOES_NOT_SUPPORT_IMAGES: ` before its message.
+
+## Migration
+
+1. If analytics or retry rules read `tool/result` `error`, add the new names and codes from the package READMEs. Earlier Session logs keep results without `error`.
+2. Replace `instanceof AggregateError` checks on `SessionResources.dispose()` rejections with `instanceof BrowserSessionError` and read the individual failures from `error.cause.errors`.
+3. Replace reads of `OarFailure.stage` or `category` with `error.code`.
+4. If code catches `HarnessError` before `NativeError`, `OarFailure`, or `StagehandDrainError`, move the specific check first where the handling differs.
+5. Confirm with `pnpm run typecheck` and your own failure-path tests.

package/kb/extra/upgrade-guide/v0.2.2-rc.2/experimental-tool-error-codes/guide.zh.md

@@ -0,0 +1,28 @@
+---
+kind: upgrade-guide
+description: "Experimental 与 hook 插件的工具失败带上错误 code，NativeError、OarFailure 与 StagehandDrainError 改为 HarnessError 子类，浏览器清理失败改为以 BrowserSessionError 拒绝。"
+---
+
+# Experimental 插件的失败带上错误 code
+
+[English](guide.md) | 中文
+
+## 变更
+
+CUA、browser-use、Cua Driver、worktree、Ralph、终端、OAR 子 agent、Liveshare、Claude Code 与 Codex hook，以及 claude-code-mods 插件的工具失败现在会在 `tool/result` 上记录 `error: { name, code }`；此前这些结果大多没有 `error`。各[包 README](../../../../packages/experimental/README.zh.md) 列出了每个类和 code。
+
+在进程内处理这些失败的代码会看到以下变化：
+
+- `@deepseek-ai/dsh-cua` 的 `NativeError` 与 `@deepseek-ai/dsh-experimental-subagent-oar` 的 `OarFailure` 现在继承 `@deepseek-ai/dsh-error` 的 `HarnessError`。`NativeError` 的 name、code 与 `CODE: message` 文本不变。`OarFailure` 去掉了 `stage` 与 `category` 字段；同样的摘要保留在 `message` 中，`code` 标明阶段。OAR 运行开始前的取消改为以 name 为 `AbortError` 的 `DOMException` 拒绝，不再是 `OarFailure`。
+- `@deepseek-ai/dsh-experimental-browser-use-stagehand-native` 的 `StagehandDrainError` 现在继承 `StagehandError`，code 为 `STAGEHAND_CLEANUP_FAILED`。
+- `@deepseek-ai/dsh-experimental-browser-use-runtime` 的 `SessionResources.dispose()` 改为以 `BrowserSessionError`（`BROWSER_CLEANUP_FAILED`）拒绝，其 `cause` 是此前直接抛出的 `AggregateError`；`instanceof AggregateError` 不再成立。
+- Liveshare 的 guard 函数改为返回 `{ reason, info }`，不再返回原因字符串。
+- 改为抛出 `ToolArgsError` 的参数失败，模型看到的 message 前多了 `invalid arguments: `；为不支持图片输入的模型请求 CUA 截图时，message 前多了 `MODEL_DOES_NOT_SUPPORT_IMAGES: `。
+
+## 迁移
+
+1. 如果分析或重试规则读取 `tool/result` 的 `error`，按包 README 补充新的 name 与 code。较早的 Session 日志中这些结果仍没有 `error`。
+2. 把对 `SessionResources.dispose()` 拒绝值的 `instanceof AggregateError` 检查改为 `instanceof BrowserSessionError`，并从 `error.cause.errors` 读取各个失败。
+3. 把读取 `OarFailure.stage` 或 `category` 的代码改为读取 `error.code`。
+4. 如果代码在 `NativeError`、`OarFailure` 或 `StagehandDrainError` 之前捕获 `HarnessError`，在处理方式不同的地方把具体类的检查移到前面。
+5. 用 `pnpm run typecheck` 和自己的失败路径测试确认迁移完成。

package/kb/extra/upgrade-guide/v0.2.2-rc.2/package-export-cleanup/guide.md

@@ -0,0 +1,36 @@
+---
+kind: upgrade-guide
+description: Update removed package subpaths; retained identity constructors remain available.
+---
+
+# Update removed package subpath imports
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Upgrading from v0.2.2-rc.2 removes the seven package subpaths below. Existing identity-only string constructors remain available at retained entrypoints; their implementations and branded type definitions are preserved. The `/types` entries re-export those types without runtime values. Persisted strings, Session formats, validation and ID generation do not change.
+
+| Removed subpath | Type import or supported replacement |
+|---|---|
+| `@deepseek-ai/dsh-commands/brand` | `@deepseek-ai/dsh-commands/types` |
+| `@deepseek-ai/dsh-browser-use/brand` | `@deepseek-ai/dsh-browser-use/types` |
+| `@deepseek-ai/dsh-computer-use/brand` | `@deepseek-ai/dsh-computer-use/types` |
+| `@deepseek-ai/dsh-jobs/brand` | `@deepseek-ai/dsh-jobs/types` |
+| `@deepseek-ai/dsh-llm/brand` | `@deepseek-ai/dsh-llm/types` |
+| `@deepseek-ai/dsh-tools/presentation` | Type imports from `@deepseek-ai/dsh-tools` |
+| `@deepseek-ai/dsh-file-reference-local/search` | The `fileReferences` service; no replacement public search helper |
+
+## Migration
+
+1. Move identifier type imports from the five `/brand` paths to the corresponding `/types` entries, using `import type`. These entries do not replace runtime constructor imports.
+2. For existing constructor calls from the removed paths, commands, jobs and LLM callers can import the retained constructor from the package root. Browser/computer provider-name constructors were not root exports; use `brandString<ProviderName>(value)` with the type from `/types`. Add `@deepseek-ai/dsh-brand` as a direct dependency when importing its runtime helper. Keep validation and UUID/counter generation where they already occur.
+
+   ```ts
+   import { brandString } from '@deepseek-ai/dsh-brand'
+   import type { BrowserUseProviderName } from '@deepseek-ai/dsh-browser-use/types'
+
+   const providerName = brandString<BrowserUseProviderName>('my-browser-provider')
+   ```
+
+3. Compile and run your plugin/SDK tests, then load plain-JavaScript fixtures under Node. Check for `ERR_PACKAGE_PATH_NOT_EXPORTED` and missing named-export errors; TypeScript checking alone does not cover `.mjs` consumers.

package/kb/extra/upgrade-guide/v0.2.2-rc.2/package-export-cleanup/guide.zh.md

@@ -0,0 +1,36 @@
+---
+kind: upgrade-guide
+description: 更新已移除的包子路径；保留入口上的标识符构造函数仍可用。
+---
+
+# 更新已移除的包子路径导入
+
+[English](guide.md) | 中文
+
+## 变更
+
+从 v0.2.2-rc.2 升级会移除下列七个包子路径。既有字符串恒等构造函数在保留的入口上仍然可用，其实现和品牌类型定义均保留。`/types` 入口仅再导出这些类型，不导出运行时值。持久化字符串、Session 格式、校验和 ID 生成行为不变。
+
+| 已移除子路径 | 类型导入或受支持的替代方式 |
+|---|---|
+| `@deepseek-ai/dsh-commands/brand` | `@deepseek-ai/dsh-commands/types` |
+| `@deepseek-ai/dsh-browser-use/brand` | `@deepseek-ai/dsh-browser-use/types` |
+| `@deepseek-ai/dsh-computer-use/brand` | `@deepseek-ai/dsh-computer-use/types` |
+| `@deepseek-ai/dsh-jobs/brand` | `@deepseek-ai/dsh-jobs/types` |
+| `@deepseek-ai/dsh-llm/brand` | `@deepseek-ai/dsh-llm/types` |
+| `@deepseek-ai/dsh-tools/presentation` | 从 `@deepseek-ai/dsh-tools` 导入类型 |
+| `@deepseek-ai/dsh-file-reference-local/search` | 使用 `fileReferences` 服务；没有替代的公开搜索辅助值 |
+
+## 迁移
+
+1. 将标识符类型导入从五个 `/brand` 路径移至对应 `/types` 入口，并使用 `import type`。这些入口不能替代运行时构造函数导入。
+2. 对原来从已移除路径调用构造函数的代码，commands、jobs 和 LLM 调用方可以改从包根入口导入保留的构造函数。Browser/computer provider-name 构造函数原本不是根出口，应使用 `brandString<ProviderName>(value)` 并从 `/types` 导入类型。导入这个运行时辅助函数时，应将 `@deepseek-ai/dsh-brand` 加为直接依赖。保留原有位置上的校验和 UUID/计数器生成操作。
+
+   ```ts
+   import { brandString } from '@deepseek-ai/dsh-brand'
+   import type { BrowserUseProviderName } from '@deepseek-ai/dsh-browser-use/types'
+
+   const providerName = brandString<BrowserUseProviderName>('my-browser-provider')
+   ```
+
+3. 编译并运行插件/SDK 测试，再用 Node 加载纯 JavaScript fixture。检查是否出现 `ERR_PACKAGE_PATH_NOT_EXPORTED` 或缺少具名出口错误；仅靠 TypeScript 检查覆盖不到 `.mjs` 消费者。

package/kb/extra/upgrade-guide/v0.2.2-rc.2/python-ptc-removal/guide.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "Python PTC runtime packages, external providers, SDK renderers and Python-specific binding APIs are removed; migrate to TypeScript PTC."
+---
+
+# Python PTC removal
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-experimental-ptc-runtime-python` is no longer published or included in this repository. Custom compositions that select it must migrate to [`@deepseek-ai/dsh-ptc-runtime-node`](../../../../packages/ptc-runtime/ptc-runtime-node/README.md). Shipped profiles already select the Node provider. `dsh-tool-executor-ptc` also removes support for external `PtcRuntime` providers reporting `language: 'python'`: prompt assembly or execution through the selected executor, or creation of a `/run-code` tool with a non-TypeScript provider, fails with `ToolContextUnavailableError` / `TOOL_CONTEXT_UNAVAILABLE`. The package no longer exports `jsonSchemaToPy` or `renderToolsSdkPy`.
+
+## Migration
+
+1. In the `cordis.yml` or profile patch that selects the Python provider, replace that row's `name` with `@deepseek-ai/dsh-ptc-runtime-node`. Remove its Python runtime `config`; configure Node limits separately when needed. Node also requires `fs` and `subprocess` alongside `sandbox` and `sandboxPolicy`. Reuse the existing providers; for a local composition missing them, mount `@deepseek-ai/dsh-fs-local` and `@deepseek-ai/dsh-subprocess-local` in the same execution world.
+2. Replace any external Python PTC provider and remove imports of `jsonSchemaToPy` and `renderToolsSdkPy`. Use the TypeScript `renderToolsSdk` API where SDK rendering is needed. `dsh-ptc-runtime` replaces `PORTABLE_RESERVED_WORDS` with `RESERVED_BINDING_WORDS` and removes `DUNDER_MEMBER`; remove Python-specific binding-name checks.
+3. Rewrite Python `run_code` programs as TypeScript. For fresh execution per call, set `config.executionMode: per-call`; see the [Node runtime configuration](../../../../packages/ptc-runtime/ptc-runtime-node/README.md).
+4. Re-enable `workflow-ptc`, `tool-workflow`, and any previously enabled `tool-ralph` rows that were disabled solely for the Python provider, if those workflows are still wanted.
+5. Run the affected profile with `--dump-config` and confirm its PTC runtime row selects `@deepseek-ai/dsh-ptc-runtime-node` with no Python provider row remaining. Run a PTC task and confirm that its TypeScript program completes.
+
+The Harness Python client in `python/sdk`, its packaged runtime wheel, and Python environments used by other tools are unaffected. Existing Session logs retain their recorded output.

package/kb/extra/upgrade-guide/v0.2.2-rc.2/python-ptc-removal/guide.zh.md

@@ -0,0 +1,22 @@
+---
+kind: upgrade-guide
+description: "Python PTC 运行时包、外部提供方、SDK 渲染器和 Python 专属绑定 API 均已移除，须迁移到 TypeScript PTC。"
+---
+
+# 移除 Python PTC
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-experimental-ptc-runtime-python` 不再发布，也不再包含于本仓库。选择该包的自定义组合必须迁移到 [`@deepseek-ai/dsh-ptc-runtime-node`](../../../../packages/ptc-runtime/ptc-runtime-node/README.zh.md)。已发布 profile 已经选择 Node 提供方。`dsh-tool-executor-ptc` 也移除了对报告 `language: 'python'` 的外部 `PtcRuntime` 提供方的支持：通过已选中的执行器组装提示词、执行程序，或使用非 TypeScript 提供方创建 `/run-code` 工具，会以 `ToolContextUnavailableError` / `TOOL_CONTEXT_UNAVAILABLE` 失败。该包不再导出 `jsonSchemaToPy` 或 `renderToolsSdkPy`。
+
+## 迁移
+
+1. 在选择 Python 提供方的 `cordis.yml` 或 profile patch 中，将对应行的 `name` 替换为 `@deepseek-ai/dsh-ptc-runtime-node`。移除该行的 Python 运行时 `config`；如有需要，单独配置 Node 限制。除了 `sandbox` 和 `sandboxPolicy`，Node 还需要 `fs` 与 `subprocess`。复用已有提供方；本地组合若缺少它们，在同一执行环境中挂载 `@deepseek-ai/dsh-fs-local` 与 `@deepseek-ai/dsh-subprocess-local`。
+2. 替换任何外部 Python PTC 提供方，移除 `jsonSchemaToPy` 与 `renderToolsSdkPy` 导入。需要渲染 SDK 时使用 TypeScript 的 `renderToolsSdk` API。`dsh-ptc-runtime` 将 `PORTABLE_RESERVED_WORDS` 替换为 `RESERVED_BINDING_WORDS`，并移除 `DUNDER_MEMBER`；删除 Python 专属的绑定命名检查。
+3. 将 Python `run_code` 程序改写为 TypeScript。如需每次调用都使用全新执行环境，设置 `config.executionMode: per-call`；参见 [Node 运行时配置](../../../../packages/ptc-runtime/ptc-runtime-node/README.zh.md)。
+4. 如果仍需使用相关工作流，重新启用仅因 Python 提供方而禁用的 `workflow-ptc`、`tool-workflow`，以及此前启用过的 `tool-ralph` 行。
+5. 为受影响的 profile 添加 `--dump-config` 并运行，确认其 PTC 运行时行选择 `@deepseek-ai/dsh-ptc-runtime-node`，且不再保留 Python 提供方行。运行一个 PTC 任务并确认其 TypeScript 程序完成。
+
+`python/sdk` 中的 Harness Python 客户端、其打包运行时 wheel，以及其他工具使用的 Python 环境均不受影响。已有 Session 日志保留其记录的输出。

package/kb/extra/upgrade-guide/v0.2.2-rc.2/session-status-package/guide.md

@@ -0,0 +1,31 @@
+---
+kind: upgrade-guide
+description: "Session status types and the useSessionStatus hook move to @deepseek-ai/dsh-client-ui-session-status/client, ctx.uiSession.sessionStatus becomes an injected service, and completion reminders follow Host reading records."
+---
+
+# Session status moves to `@deepseek-ai/dsh-client-ui-session-status` and completion reminders follow Host reading records
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-client-ui-session/client` no longer exports `SessionStatus`, `SessionStatusSnapshot`, or `UseSessionStatus`, and ui-session no longer declares or provides the `useSessionStatus` root hook. Both now belong to the Client plugin [`@deepseek-ai/dsh-client-ui-session-status`](../../../../packages/client/ui-session-status/README.md), one Web bundle row with a Host reading service and the Client table. A Client composition that loads ui-session without ui-session-status has no status table and no `useSessionStatus` hook.
+
+`ctx.uiSession.sessionStatus` is now the separate `uiSession.sessionStatus` service. Reading it through `ctx.uiSession.sessionStatus.getSnapshot()` and `subscribe()` keeps its form, but a plugin that reads it without injecting `'uiSession.sessionStatus'` fails with `cannot get property "uiSession.sessionStatus" without inject`. Components of a plugin without that injection fail with `useSessionStatus is not a function` after the table unloads. `ctx.uiSession` now has the type `UiSessionService`, which extends the unchanged `UiSession` class with members such as `sessionStatus`; a value annotated as `UiSession` does not show `sessionStatus`.
+
+Pending interactions stay in ui-session: `ctx.uiSession.registerPendingInteraction(precedence)`, `SessionPendingInteractionBase`, `SessionPendingInteractionMap`, `SessionPendingInteraction`, and `PendingInteractionPublisher` keep their names, behavior, and `@deepseek-ai/dsh-client-ui-session/client` export. Extensions of `SessionPendingInteractionMap` keep targeting that module. ui-session additionally exposes the read-only `ctx.uiSession.pendingInteractions` source.
+
+`completionUnread` follows Host-memory reading records shared by every Client and changes through Host completions, explicit marks, and visible main-view acknowledgement; only a main-view switch, including a reload, clears a manual mark. The open viewed Session hides its unacknowledged turn; earlier history reads as read. The required `completionFailed` field marks an unread Session whose latest turn failed. The new `mark(sessionId, unread)` rejects until `readingReady` reports the Host baseline.
+
+This affects Client plugins and tests that import the three status types, construct `SessionStatus` values, render components that read `useSessionStatus`, or read `ctx.uiSession.sessionStatus`.
+
+## Migration
+
+1. Import `SessionStatus`, `SessionStatusSnapshot`, and `UseSessionStatus` from `@deepseek-ai/dsh-client-ui-session-status/client`. A package that only imports these types, for example in tests, declares `@deepseek-ai/dsh-client-ui-session-status` in `devDependencies` and its TypeScript project references.
+2. A package whose components call `useSessionStatus` also lists the package in `dsh.client.inject`, adds `import type {} from '@deepseek-ai/dsh-client-ui-session-status/client'` when it imports none of the types, and adds `'uiSession.sessionStatus'` to the Cordis `inject` of the plugin that registers them.
+3. Each plugin that reads `ctx.uiSession.sessionStatus` adds `'uiSession.sessionStatus'` to `inject`; one that needs only the effective pending request may subscribe to `ctx.uiSession.pendingInteractions` instead.
+4. Where code passes `ctx.uiSession` through a parameter or field annotated as `UiSession` and then reads `sessionStatus`, annotate it as `UiSessionService` from `@deepseek-ai/dsh-client-ui-session/client`.
+5. Leave `registerPendingInteraction` calls and `declare module '@deepseek-ai/dsh-client-ui-session/client'` augmentations of `SessionPendingInteractionMap` unchanged.
+6. Add `completionFailed` to `SessionStatus` values in tests and fixtures, and script Host reading records to drive `completionUnread`.
+7. A custom composition that loads `@deepseek-ai/dsh-client-ui-session` also loads `@deepseek-ai/dsh-client-ui-session-status` as a plugin row, so its Host reading service and `useSessionStatus` are available.
+8. Confirm that the plugin type-checks, that a Session row still shows its running or waiting indicator, and that a Session finishing outside the main view shows an unread reminder.

package/kb/extra/upgrade-guide/v0.2.2-rc.2/session-status-package/guide.zh.md

@@ -0,0 +1,31 @@
+---
+kind: upgrade-guide
+description: "会话状态类型与 useSessionStatus hook 移到 @deepseek-ai/dsh-client-ui-session-status/client，ctx.uiSession.sessionStatus 改为需要注入的服务，完成提醒改为跟随宿主阅读记录。"
+---
+
+# 会话状态移到 `@deepseek-ai/dsh-client-ui-session-status`，完成提醒改由宿主阅读记录提供
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-client-ui-session/client` 不再导出 `SessionStatus`、`SessionStatusSnapshot` 或 `UseSessionStatus`，ui-session 也不再声明或提供根 hook `useSessionStatus`。它们现在属于 Client 插件 [`@deepseek-ai/dsh-client-ui-session-status`](../../../../packages/client/ui-session-status/README.zh.md)，即 Web bundle 中同时提供宿主阅读服务和前端状态表的一行。只加载 ui-session、不加载 ui-session-status 的 Client 组合没有状态表，也没有 `useSessionStatus` hook。
+
+`ctx.uiSession.sessionStatus` 现在是独立的 `uiSession.sessionStatus` 服务。通过 `ctx.uiSession.sessionStatus.getSnapshot()` 和 `subscribe()` 读取的写法不变，但未注入 `'uiSession.sessionStatus'` 就读取它的插件会报错 `cannot get property "uiSession.sessionStatus" without inject`。未注入该服务的插件，其组件会在状态表卸载后报错 `useSessionStatus is not a function`。`ctx.uiSession` 的类型改为 `UiSessionService`，它在不变的 `UiSession` class 之上加入 `sessionStatus` 等成员；标注为 `UiSession` 的值看不到 `sessionStatus`。
+
+待交互仍归 ui-session：`ctx.uiSession.registerPendingInteraction(precedence)`、`SessionPendingInteractionBase`、`SessionPendingInteractionMap`、`SessionPendingInteraction` 和 `PendingInteractionPublisher` 的名称、行为以及从 `@deepseek-ai/dsh-client-ui-session/client` 的导出都不变。扩展 `SessionPendingInteractionMap` 的声明继续指向该模块。ui-session 另外提供只读的 `ctx.uiSession.pendingInteractions` 数据源。
+
+`completionUnread` 跟随宿主内存中、由所有前端共享的阅读记录，因宿主完成轮次、主动标记和可见主视图的确认而变化；只有主视图切换到该会话（包括刷新后恢复）会自动清除手动标记。正在查看且已打开的会话不显示尚未确认的轮次；宿主启动前已有的历史按已读处理。新增的必填字段 `completionFailed` 标记最近一轮失败的未读会话。新增的 `mark(sessionId, unread)` 在 `readingReady` 报告取得宿主基线之前会拒绝。
+
+受影响的是导入这三个状态类型、构造 `SessionStatus` 值、渲染读取 `useSessionStatus` 的组件，或读取 `ctx.uiSession.sessionStatus` 的 Client 插件和测试。
+
+## 迁移
+
+1. 从 `@deepseek-ai/dsh-client-ui-session-status/client` 导入 `SessionStatus`、`SessionStatusSnapshot` 和 `UseSessionStatus`。只导入这些类型（例如只在测试中导入）的包，在 `devDependencies` 和 TypeScript 项目引用中声明 `@deepseek-ai/dsh-client-ui-session-status`。
+2. 组件调用 `useSessionStatus` 的包，另外在 `dsh.client.inject` 中列出该包；不导入任何上述类型时加入 `import type {} from '@deepseek-ai/dsh-client-ui-session-status/client'`；并在注册这些组件的插件的 Cordis `inject` 中加入 `'uiSession.sessionStatus'`。
+3. 每个读取 `ctx.uiSession.sessionStatus` 的插件把 `'uiSession.sessionStatus'` 加入 `inject`；只需要生效待交互请求的插件，可以改为订阅 `ctx.uiSession.pendingInteractions`。
+4. 代码把 `ctx.uiSession` 传给标注为 `UiSession` 的参数或字段、之后又读取 `sessionStatus` 时，把标注改为 `@deepseek-ai/dsh-client-ui-session/client` 的 `UiSessionService`。
+5. `registerPendingInteraction` 调用和对 `SessionPendingInteractionMap` 的 `declare module '@deepseek-ai/dsh-client-ui-session/client'` 扩展保持不变。
+6. 在测试和 fixture 的 `SessionStatus` 值中加入 `completionFailed`，并编排宿主阅读记录来驱动 `completionUnread`。
+7. 加载 `@deepseek-ai/dsh-client-ui-session` 的自定义组合同时以插件行加载 `@deepseek-ai/dsh-client-ui-session-status`，使其宿主阅读服务和 `useSessionStatus` 可用。
+8. 确认插件通过类型检查、会话行仍显示运行或等待标记，并且在主视图之外结束的会话显示未读提醒。

package/kb/extra/upgrade-guide/v0.2.2-rc.2/shared-search-filter/guide.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "ui-primitives no longer exports rankByName, and popupSelect commands no longer accept searchMode."
+---
+
+# Shared search filter replaces rankByName and searchMode
+
+English | [中文](guide.zh.md)
+
+## Change
+
+`@deepseek-ai/dsh-client-ui-primitives` exported `rankByName(items, query)`, which ranked items by an ordered subsequence of `name` or `label`. It is removed. `@deepseek-ai/dsh-client-ui-commands` accepted `searchMode: 'substring' | 'fuzzy-label'` on a `popupSelect` command spec and exported the `PopupSearchMode` type; both are removed. Every popup now filters its options one way: labels match fuzzily and details match as substrings, ranked within each group. The shared search is [`TextSearchIndex`](../../../../packages/util/text-search/README.md) in `@deepseek-ai/dsh-util-text-search`. Plugin authors who import `rankByName`, or who set `searchMode` or import `PopupSearchMode`, are affected.
+
+## Migration
+
+1. Replace `rankByName(items, query)` with a `TextSearchIndex` imported from `@deepseek-ai/dsh-util-text-search`: build `new TextSearchIndex(items, item => ({ fuzzy: [item.name, item.label] }))` when the list changes, and call `index.search(query)` per query. Add that package to the plugin's `devDependencies` for a Client plugin or `dependencies` for a Host plugin. Put descriptions or other long text in `substring`, and pass every language of a `LocalizedText` through `localizedValues`.
+2. Delete `searchMode` from each `popupSelect` spec and remove any `PopupSearchMode` import.
+3. Confirm the plugin typechecks, and that typing part of an option label in its popup still finds that option.

package/kb/extra/upgrade-guide/v0.2.2-rc.2/shared-search-filter/guide.zh.md

@@ -0,0 +1,18 @@
+---
+kind: upgrade-guide
+description: "ui-primitives 不再导出 rankByName，popupSelect 命令不再接受 searchMode。"
+---
+
+# 共享搜索过滤器取代 rankByName 和 searchMode
+
+[English](guide.md) | 中文
+
+## 变更
+
+`@deepseek-ai/dsh-client-ui-primitives` 曾导出 `rankByName(items, query)`，它按 `name` 或 `label` 的有序子序列对条目排序。该函数已移除。`@deepseek-ai/dsh-client-ui-commands` 曾在 `popupSelect` 命令规格上接受 `searchMode: 'substring' | 'fuzzy-label'`，并导出 `PopupSearchMode` 类型；两者均已移除。现在每个弹窗都用同一种方式过滤选项：标签模糊匹配，详情按子串匹配，选项在各自分组内排序。共享搜索是 `@deepseek-ai/dsh-util-text-search` 中的 [`TextSearchIndex`](../../../../packages/util/text-search/README.zh.md)。受影响的是导入 `rankByName`、设置 `searchMode` 或导入 `PopupSearchMode` 的插件作者。
+
+## 迁移
+
+1. 把 `rankByName(items, query)` 替换为从 `@deepseek-ai/dsh-util-text-search` 导入的 `TextSearchIndex`：列表变化时构建 `new TextSearchIndex(items, item => ({ fuzzy: [item.name, item.label] }))`，每次查询时调用 `index.search(query)`。把该包加入插件的依赖：Client 插件加入 `devDependencies`，Host 插件加入 `dependencies`。把描述或其他长文本放进 `substring`，并通过 `localizedValues` 传入 `LocalizedText` 的所有语言。
+2. 从每个 `popupSelect` 规格中删除 `searchMode`，并移除所有 `PopupSearchMode` 导入。
+3. 确认插件通过类型检查，并确认在其弹窗中键入选项标签的一部分仍能找到该选项。

package/kb/extra/upgrade-guide/v0.2.2-rc.2/shell-fs-tool-error-codes/guide.md

@@ -0,0 +1,30 @@
+---
+kind: upgrade-guide
+description: "bash and pwsh report unadvertised sandbox_permissions and run_in_background as ToolArgsError, JOB_BACKGROUND_DISABLED is removed, and read_image reports MODEL_DOES_NOT_SUPPORT_IMAGES instead of IMAGE_UNSUPPORTED_MODEL."
+---
+
+# Shell and read_image failures use consolidated error codes
+
+English | [中文](guide.zh.md)
+
+## Change
+
+Three `tool/result` error identities recorded by v0.2.2-rc.2 change:
+
+| Failure | v0.2.2-rc.2 | Now |
+| --- | --- | --- |
+| `bash` or `pwsh` receives `sandbox_permissions` and `justification` in a composition without a sandboxing executor | `SandboxEscalationError` / `SANDBOX_ESCALATION_UNAVAILABLE` | `ToolArgsError` / `INVALID_ARGS` |
+| `bash` or `pwsh` receives `run_in_background: true` with `enableRunInBackground: false` | `JobError` / `JOB_BACKGROUND_DISABLED` | `ToolArgsError` / `INVALID_ARGS` |
+| `read_image` runs on a model route without image input | `ImageInputError` / `IMAGE_UNSUPPORTED_MODEL` | `ImageInputError` / `MODEL_DOES_NOT_SUPPORT_IMAGES` |
+
+In both shell cases the schema does not advertise the rejected argument, so the model's fix is to drop it. When only one of `sandbox_permissions` and `justification` reaches `bash`, `pwsh`, `write`, `edit`, or `apply_patch` without a sandboxing backend, the call previously failed the pairing check with `SandboxEscalationError` / `SANDBOX_ESCALATION_INVALID_ARGUMENT`; it now reports `INVALID_ARGS` as well. These calls are rejected before any approval request.
+
+The shell messages now start with `invalid arguments: `, and the escalation message names both fields: `invalid arguments: sandbox_permissions and justification are not available in this composition (no sandboxing executor to escalate)`. `SANDBOX_ESCALATION_UNAVAILABLE` keeps its meaning for compositions that have a sandboxing executor but no approval service, calling Agent, or approval channel.
+
+`JOB_BACKGROUND_DISABLED` is removed from `JOB_ERROR_CODES` and the `JobErrorCode` type in `@deepseek-ai/dsh-jobs`. `ImageInputErrorCode` in `@deepseek-ai/dsh-tool-fs` replaces `IMAGE_UNSUPPORTED_MODEL` with `MODEL_DOES_NOT_SUPPORT_IMAGES`, the value subagent attachments and Session attachment rejections already use.
+
+## Migration
+
+1. In analytics or retry rules that read `tool/result` `error`, treat v0.2.2-rc.2 `JOB_BACKGROUND_DISABLED` results as `INVALID_ARGS` and `IMAGE_UNSUPPORTED_MODEL` as `MODEL_DOES_NOT_SUPPORT_IMAGES`. For `SANDBOX_ESCALATION_UNAVAILABLE`, `error` alone does not identify the shell case: treat a v0.2.2-rc.2 `bash` or `pwsh` result as `INVALID_ARGS` only when its message contains `no sandboxing executor to escalate`, and keep every other `SANDBOX_ESCALATION_UNAVAILABLE` result unchanged. Session logs keep the values they were written with.
+2. Replace TypeScript references to `'JOB_BACKGROUND_DISABLED'` or `'IMAGE_UNSUPPORTED_MODEL'`; `pnpm run typecheck` reports any that remain.
+3. Update text matchers that expect the earlier shell messages, which had no `invalid arguments: ` prefix and named only `sandbox_permissions`.

package/kb/extra/upgrade-guide/v0.2.2-rc.2/shell-fs-tool-error-codes/guide.zh.md

@@ -0,0 +1,30 @@
+---
+kind: upgrade-guide
+description: "bash 与 pwsh 把 schema 未公开的 sandbox_permissions 与 run_in_background 报为 ToolArgsError，删除 JOB_BACKGROUND_DISABLED，read_image 改报 MODEL_DOES_NOT_SUPPORT_IMAGES 而非 IMAGE_UNSUPPORTED_MODEL。"
+---
+
+# Shell 与 read_image 的失败改用统一的错误 code
+
+[English](guide.md) | 中文
+
+## 变更
+
+v0.2.2-rc.2 记录的三种 `tool/result` 错误标识发生变化：
+
+| 失败 | v0.2.2-rc.2 | 现在 |
+| --- | --- | --- |
+| 在没有沙箱执行器的组合中，`bash` 或 `pwsh` 收到 `sandbox_permissions` 与 `justification` | `SandboxEscalationError` / `SANDBOX_ESCALATION_UNAVAILABLE` | `ToolArgsError` / `INVALID_ARGS` |
+| `enableRunInBackground: false` 时，`bash` 或 `pwsh` 收到 `run_in_background: true` | `JobError` / `JOB_BACKGROUND_DISABLED` | `ToolArgsError` / `INVALID_ARGS` |
+| `read_image` 运行在不支持图像输入的模型路由上 | `ImageInputError` / `IMAGE_UNSUPPORTED_MODEL` | `ImageInputError` / `MODEL_DOES_NOT_SUPPORT_IMAGES` |
+
+两个 shell 情形中，被拒绝的参数都没有出现在 schema 里，模型的修正办法是去掉它。在没有沙箱后端时，若 `bash`、`pwsh`、`write`、`edit` 或 `apply_patch` 只收到 `sandbox_permissions` 与 `justification` 之一，此前会在配对校验中以 `SandboxEscalationError` / `SANDBOX_ESCALATION_INVALID_ARGUMENT` 失败；现在同样报 `INVALID_ARGS`。这些调用会在任何审批请求之前被拒绝。
+
+shell 消息现在以 `invalid arguments: ` 开头，升权消息同时点名两个字段：`invalid arguments: sandbox_permissions and justification are not available in this composition (no sandboxing executor to escalate)`。对于有沙箱执行器、但缺少审批服务、调用方 Agent 或审批通道的组合，`SANDBOX_ESCALATION_UNAVAILABLE` 的含义不变。
+
+`@deepseek-ai/dsh-jobs` 的 `JOB_ERROR_CODES` 与 `JobErrorCode` 类型删除了 `JOB_BACKGROUND_DISABLED`。`@deepseek-ai/dsh-tool-fs` 的 `ImageInputErrorCode` 用 `MODEL_DOES_NOT_SUPPORT_IMAGES` 替换 `IMAGE_UNSUPPORTED_MODEL`，子 agent 附件与 Session 附件拒绝已在使用这个值。
+
+## 迁移
+
+1. 读取 `tool/result` `error` 的统计或重试规则中，把 v0.2.2-rc.2 的 `JOB_BACKGROUND_DISABLED` 结果视为 `INVALID_ARGS`，把 `IMAGE_UNSUPPORTED_MODEL` 视为 `MODEL_DOES_NOT_SUPPORT_IMAGES`。仅凭 `error` 无法从 `SANDBOX_ESCALATION_UNAVAILABLE` 中分出 shell 情形：只有 v0.2.2-rc.2 的 `bash` 或 `pwsh` 结果的消息含 `no sandboxing executor to escalate` 时，才视为 `INVALID_ARGS`；其余 `SANDBOX_ESCALATION_UNAVAILABLE` 结果保持原义。Session 日志保留写入时的值。
+2. 替换 TypeScript 中对 `'JOB_BACKGROUND_DISABLED'` 或 `'IMAGE_UNSUPPORTED_MODEL'` 的引用；`pnpm run typecheck` 会报出剩余的引用。
+3. 更新那些期望旧 shell 消息的文本匹配：旧消息没有 `invalid arguments: ` 前缀，且只点名 `sandbox_permissions`。

package/kb/extra/web-styling.md

@@ -1,57 +1,57 @@
-# Web UI style reference
-
-English | [中文](web-styling.zh.md)
-
-This reference defines styling ownership and component rules for browser client packages. The current token values live in [`packages/client/ui-theme/src/styles/`](../packages/client/ui-theme/src/styles/); this document does not duplicate that generated-by-source inventory.
-
-## Ownership
-
-[`ui-theme`](../packages/client/ui-theme/README.md) owns the `--dsw-*` static scale, semantic aliases, typography, motion, gradients, shadows, scrollbar styles, and light/dark preference. [`ui-layout`](../packages/client/ui-layout/README.md) applies the resolved theme snapshot to the document. Feature packages consume semantic aliases and do not define another global theme.
-
-Global style sheets belong in `ui-theme/src/styles/`. Component styles live beside their component as CSS Modules. A component may define a local custom property when its value is part of that component's layout or presentation contract; shared colors, typography, elevation, and motion belong to the theme package.
-
-<a id="component-rules"></a>
-## Component rules
-
-- Reuse the control before restyling one: the [ui-primitives component catalog](../packages/client/ui-primitives/README.md#component-catalog) is the only channel that crosses feature packages, and a deliberate visual difference belongs in a prop there rather than in a second copy ([reference](../packages/client/ui-primitives/README.md)).
-- Use CSS Modules and `clsx`; do not add a component library or Tailwind.
-- Use `--dsw-alias-*` semantic tokens in feature components. Do not copy static palette values or write literal colors there.
-- Keep theme selectors out of feature component CSS. Light/dark overrides belong to the theme owner.
-- Pair font sizes with line heights and use the theme typography variables when an existing role matches.
-- Keep source text, terminal output, and diff lines unwrapped when their component contract requires column preservation; use the shared scrollbar styles rather than component-specific scrollbar selectors.
-- Put presentation in CSS. Inline React styles may pass component-local custom-property values but must not encode theme branches.
-- A relative `url()` in a plugin stylesheet points to a file in the package's `src/client/assets/`, and the build rewrites it to the [package asset](../packages/client/AGENTS.md#dependency-declaration) URL. `data:`, `#fragment`, `/`-rooted, scheme, and empty `url('')` references stay unchanged, a relative file reference with a fragment or query fails the build, and stylesheets from dependencies are not rewritten.
-- Put `:hover` selectors under `@media (hover: hover)`, independently of viewport width. Keep selected, expanded, pressed, and keyboard-focus styles outside that condition. Without hover, actions remain visible or accessible through an explicit control; pointer handlers ignore touch when opening hover-only previews. Preserve keyboard focus visibility and reduced-motion behavior.
-- Rounded corners inherit the global superellipse smoothing from ui-theme's `corner-shape.css` on supporting engines. Pair `corner-shape: round` with every full-round `border-radius` (`50%`, `100%`, or a pill radius) so circles and capsules keep circular arcs; the ui-theme corner-shape spec enforces the pairing.
-- Elevated surfaces (menus, popovers, modals, panels, floating buttons, the composer) set `border: 0` and take `box-shadow: var(--dsw-elevation-panel)`, `var(--dsw-elevation-prominent)`, or the composer's `var(--dsw-elevation-soft)` (larger blur at lower alpha): the 0.5px hairline stroke is the first shadow layer, and `--dsw-elevation-stroke-color` rebinds or suppresses it per surface or state. Never pair a `--dsw-alias-border-*` border with an lv/elevation shadow — the ui-theme elevation spec rejects the pairing; state-colored borders (warn panels) stay real borders.
-- Existing and new dropdown, context, submenu, and selection menus use `Menu` or wrap custom content in `MenuSurface`. The material is the theme-owned `--dsw-menu-surface-fill` plus `--dsw-menu-backdrop-filter`; feature and platform CSS must not override either. The ui-theme menu spec rejects unwrapped menu/listbox renderers, material overrides, and token redefinitions. The schedule-owned `TaskMenu` and `ClockPicker` retain their existing containers and material as explicit exceptions ([owner](../packages/client/ui-schedule/README.md)).
-- Modal backdrops, including settings and confirmation dialogs, retain their translucent dark mask without blur. The theme sets `--dsw-mask-blur` to `none`; Desktop-owned modal overlays also leave the parent page unfiltered.
-- Floating panels preserve horizontal anchor alignment when neither vertical side fits. Try vertical window bounds before a fallback that also clears horizontal anchoring; every candidate reserves the window edge and frame margins.
-
-- Menu background filtering stays on an isolated layer so nested menus and fixed overlays retain their positioning and backdrop. On macOS, `MenuSurface` adds an opaque backing behind page content only within each menu’s bounds, allowing Chromium to blur content over native vibrancy; CSS anchors follow placement and size, and unmounting removes the backing. Overlays without this backing use `--dsw-specific-menu`, whose theme-owned macOS fill is 94% opaque to keep underlying text from bleeding through. Other elevated surfaces using that fill pair it with the same filter on their own isolated background when they contain fixed overlays.
-- Flat borders and separators that use a neutral `--dsw-alias-border-*` token draw at `0.5px` — buttons, inputs, cards, row dividers, and separators drawn as filled boxes (menu separators, the conversation header seam, markdown `hr`, vertical rails) share the hairline weight, which Chromium paints as one device pixel. Dashed affordances and state-colored borders keep 1px; spinner ring tracks keep their width through the spec's explicit allowlist. The ui-theme elevation spec rejects wider neutral solid borders.
-- Clickable artifact links (markdown anchors, prose file mentions, web source and fetch links, produced-file chips, workflow member links) color through `--dsw-alias-link` at `font-weight: 500`, with no underline at rest and a dotted 3px-offset underline on hover/focus. Compact Thinking Markdown keeps tertiary text color and a resting dotted underline ([compact presentation](../packages/client/ui-primitives/README.md#rendering-agent-output)). Text-leading anchors also lead with the ui-primitives `LinkIconMedium` category glyph riding `currentColor`, which for a well-known external host is that site's own mark instead of the globe; workflow member links and image-only anchors carry no glyph, and tool-row file links keep their grey dotted affordance.
-
-<a id="input-capabilities"></a>
-## Input capabilities
-
-`pointer` and `hover` describe the primary pointing device chosen by the browser; `any-hover` considers every available pointing device. None detects a physical keyboard.
-
-- Use `(pointer: coarse)` for presentation that depends on pointing accuracy, such as touch-sized controls and text fields.
-- Keep CSS hover effects under `(hover: hover)` so a touch-first layout remains usable without hover.
-- JavaScript hover previews use `(any-hover: hover)` when accepting mouse entry and ignore touch entry. A secondary mouse can therefore open a preview even when the touchscreen remains the primary pointer. Enabling all CSS hover styles through `any-hover` would also enable them for touch-generated `:hover` states.
-
-On a mixed-input device, a mouse preview can appear while the primary-pointer CSS hover style stays inactive. Keyboard focus and shortcut hints follow actual keyboard interaction independently of these capability queries; [Menu and input modality](../packages/client/ui-primitives/README.md#input-modality) define the shared behavior.
-
-<a id="corner-radii-and-settings-cards"></a>
-## Corner radii and settings cards
-
-The [DSH unified corner-radius standard](ui-radius.md) defines the radius scale, component size mapping, circle and capsule exceptions, nested hover geometry, and settings-card fills and strokes.
-
-## Review the assembled design
-
-Use the [UI review baseline](ui-design-review-cases.md#review-baseline) to combine these material and typography rules with radius, responsive behavior, feedback and artwork guidance across the [entire page or modal](ui-design-review-cases.md#whole-interface-review). Compare all regions and same-role elements within that unit; individually compliant components can still form doubled edges, inconsistent grouping or clipped focus indicators. This document and the theme remain the styling owners.
-
-## Changing the system
-
-Add or change a shared token in the owning `ui-theme` sheet, then consume its semantic alias from feature packages. Update the owning package reference when a public styling contract changes. Visual behavior follows the [testing policy](testing.md); the [archived styling-system Agent Note](../.agents/notes/archived/process/2026-07-19-web-styling-system.md) records framework rationale.
+# Web UI style reference
+
+English | [中文](web-styling.zh.md)
+
+This reference defines styling ownership and component rules for browser client packages. The current token values live in [`packages/client/ui-theme/src/styles/`](../packages/client/ui-theme/src/styles/); this document does not duplicate that generated-by-source inventory.
+
+## Ownership
+
+[`ui-theme`](../packages/client/ui-theme/README.md) owns the `--dsw-*` static scale, semantic aliases, typography, motion, gradients, shadows, scrollbar styles, and light/dark preference. [`ui-layout`](../packages/client/ui-layout/README.md) applies the resolved theme snapshot to the document. Feature packages consume semantic aliases and do not define another global theme.
+
+Global style sheets belong in `ui-theme/src/styles/`. Component styles live beside their component as CSS Modules. A component may define a local custom property when its value is part of that component's layout or presentation contract; shared colors, typography, elevation, and motion belong to the theme package.
+
+<a id="component-rules"></a>
+## Component rules
+
+- Reuse the control before restyling one: the [ui-primitives component catalog](../packages/client/ui-primitives/README.md#component-catalog) is the only channel that crosses feature packages, and a deliberate visual difference belongs in a prop there rather than in a second copy ([reference](../packages/client/ui-primitives/README.md)).
+- Use CSS Modules and `clsx`; do not add a component library or Tailwind.
+- Use `--dsw-alias-*` semantic tokens in feature components. Do not copy static palette values or write literal colors there. The ui-theme color-token spec rejects static palette references and hex, color-function, `white`, and `black` literals in feature stylesheets and static palette references in feature scripts; `box-shadow` values, mask properties, alpha-0 literals, and its listed artwork and pre-theme files are exempt.
+- Keep theme selectors out of feature component CSS. Light/dark overrides belong to the theme owner.
+- Pair font sizes with line heights and use the theme typography variables when an existing role matches.
+- Keep source text, terminal output, and diff lines unwrapped when their component contract requires column preservation; use the shared scrollbar styles rather than component-specific scrollbar selectors.
+- Put presentation in CSS. Inline React styles may pass component-local custom-property values but must not encode theme branches.
+- A relative `url()` in a plugin stylesheet points to a file in the package's `src/client/assets/`, and the build rewrites it to the [package asset](../packages/client/AGENTS.md#dependency-declaration) URL. `data:`, `#fragment`, `/`-rooted, scheme, and empty `url('')` references stay unchanged, a relative file reference with a fragment or query fails the build, and stylesheets from dependencies are not rewritten.
+- Put `:hover` selectors under `@media (hover: hover)`, independently of viewport width. Keep selected, expanded, pressed, and keyboard-focus styles outside that condition. Without hover, actions remain visible or accessible through an explicit control; pointer handlers ignore touch when opening hover-only previews. Preserve keyboard focus visibility and reduced-motion behavior.
+- Rounded corners inherit the global superellipse smoothing from ui-theme's `corner-shape.css` on supporting engines. Pair `corner-shape: round` with every full-round `border-radius` (`50%`, `100%`, or a pill radius) so circles and capsules keep circular arcs; the ui-theme corner-shape spec enforces the pairing.
+- Elevated surfaces (menus, popovers, modals, panels, floating buttons, the composer) set `border: 0` and take `box-shadow: var(--dsw-elevation-panel)`, `var(--dsw-elevation-prominent)`, or the composer's `var(--dsw-elevation-soft)` (larger blur at lower alpha): the 0.5px hairline stroke is the first shadow layer, and `--dsw-elevation-stroke-color` rebinds or suppresses it per surface or state. Never pair a `--dsw-alias-border-*` border with an lv/elevation shadow — the ui-theme elevation spec rejects the pairing; state-colored borders (warn panels) stay real borders.
+- Existing and new dropdown, context, submenu, and selection menus use `Menu` or wrap custom content in `MenuSurface`. The material is the theme-owned `--dsw-menu-surface-fill` plus `--dsw-menu-backdrop-filter`; feature and platform CSS must not override either. The ui-theme menu spec rejects unwrapped menu/listbox renderers, material overrides, and token redefinitions. The schedule-owned `TaskMenu` and `ClockPicker` retain their existing containers and material as explicit exceptions ([owner](../packages/client/ui-schedule/README.md)).
+- Modal backdrops, including settings and confirmation dialogs, retain their translucent dark mask without blur. The theme sets `--dsw-mask-blur` to `none`; Desktop-owned modal overlays also leave the parent page unfiltered.
+- Floating panels preserve horizontal anchor alignment when neither vertical side fits. Try vertical window bounds before a fallback that also clears horizontal anchoring; every candidate reserves the window edge and frame margins.
+
+- Menu background filtering stays on an isolated layer so nested menus and fixed overlays retain their positioning and backdrop. On macOS, `MenuSurface` adds an opaque backing behind page content only within each menu’s bounds, allowing Chromium to blur content over native vibrancy; CSS anchors follow placement and size, and unmounting removes the backing. Overlays without this backing use `--dsw-specific-menu`, whose theme-owned macOS fill is 94% opaque to keep underlying text from bleeding through. Other elevated surfaces using that fill pair it with the same filter on their own isolated background when they contain fixed overlays.
+- Flat borders and separators that use a neutral `--dsw-alias-border-*` token draw at `0.5px` — buttons, inputs, cards, row dividers, and separators drawn as filled boxes (menu separators, the conversation header seam, markdown `hr`, vertical rails) share the hairline weight, which Chromium paints as one device pixel. Dashed affordances and state-colored borders keep 1px; spinner ring tracks keep their width through the spec's explicit allowlist. The ui-theme elevation spec rejects wider neutral solid borders.
+- Clickable artifact links (markdown anchors, prose file mentions, web source and fetch links, produced-file chips, workflow member links) color through `--dsw-alias-link` at `font-weight: 500`, with no underline at rest and a dotted 3px-offset underline on hover/focus. Compact Thinking Markdown keeps tertiary text color and a resting dotted underline ([compact presentation](../packages/client/ui-primitives/README.md#rendering-agent-output)). Text-leading anchors also lead with the ui-primitives `LinkIconMedium` category glyph riding `currentColor`, which for a well-known external host is that site's own mark instead of the globe; workflow member links and image-only anchors carry no glyph, and tool-row file links keep their grey dotted affordance.
+
+<a id="input-capabilities"></a>
+## Input capabilities
+
+`pointer` and `hover` describe the primary pointing device chosen by the browser; `any-hover` considers every available pointing device. None detects a physical keyboard.
+
+- Use `(pointer: coarse)` for presentation that depends on pointing accuracy, such as touch-sized controls and text fields.
+- Keep CSS hover effects under `(hover: hover)` so a touch-first layout remains usable without hover.
+- JavaScript hover previews use `(any-hover: hover)` when accepting mouse entry and ignore touch entry. A secondary mouse can therefore open a preview even when the touchscreen remains the primary pointer. Enabling all CSS hover styles through `any-hover` would also enable them for touch-generated `:hover` states.
+
+On a mixed-input device, a mouse preview can appear while the primary-pointer CSS hover style stays inactive. Keyboard focus and shortcut hints follow actual keyboard interaction independently of these capability queries; [Menu and input modality](../packages/client/ui-primitives/README.md#input-modality) define the shared behavior.
+
+<a id="corner-radii-and-settings-cards"></a>
+## Corner radii and settings cards
+
+The [DSH unified corner-radius standard](ui-radius.md) defines the radius scale, component size mapping, circle and capsule exceptions, nested hover geometry, and settings-card fills and strokes.
+
+## Review the assembled design
+
+Use the [UI review baseline](ui-design-review-cases.md#review-baseline) to combine these material and typography rules with radius, responsive behavior, feedback and artwork guidance across the [entire page or modal](ui-design-review-cases.md#whole-interface-review). Compare all regions and same-role elements within that unit; individually compliant components can still form doubled edges, inconsistent grouping or clipped focus indicators. This document and the theme remain the styling owners.
+
+## Changing the system
+
+Add or change a shared token in the owning `ui-theme` sheet, then consume its semantic alias from feature packages. Update the owning package reference when a public styling contract changes. Visual behavior follows the [testing policy](testing.md); the [archived styling-system Agent Note](../.agents/notes/archived/process/2026-07-19-web-styling-system.md) records framework rationale.