diff --git a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml
index 1d7c7a29bb..3f8444bcfa 100644
--- a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.i18n.yaml
@@ -24,8 +24,8 @@
en: ec3703b7e7c6b23d
zh: 325755e6e90092da
/agent-note-web-capability-seam-stable-tools-over-multiple-providers/fetch-request-and-result-schema:
- en: f734fdc57a6546c9
- zh: 027c28cbc584a8c2
+ en: 6dba3b9a51c28b6d
+ zh: 58a93f6ba2d269ea
/agent-note-web-capability-seam-stable-tools-over-multiple-providers/tool-consumer-behavior:
en: 62127883453dd79c
zh: 01503a8177a0ddab
@@ -55,19 +55,16 @@
zh: 64032ea6ab61b836
/agent-note-web-capability-seam-stable-tools-over-multiple-providers/alternatives-considered/mirror-claude-code-s-url-prompt-webfetch-shape:
en: 56a080de39e96056
- zh: ae4d070aa7657503
-/agent-note-web-capability-seam-stable-tools-over-multiple-providers/alternatives-considered/validate-dns-and-then-call-an-ordinary-fetch:
- en: aa6c1e7e6374a875
- zh: 045c8af6cd44c3e1
-/agent-note-web-capability-seam-stable-tools-over-multiple-providers/alternatives-considered/block-private-looking-hostname-strings-without-pinning-resolved-addresses:
- en: 3d906f3056733479
- zh: d652723eb5372007
+ zh: 937336a73de70518
+/agent-note-web-capability-seam-stable-tools-over-multiple-providers/alternatives-considered/restrict-fetch-to-public-addresses:
+ en: af3014c0de7ff66f
+ zh: 509040c9183327fe
/agent-note-web-capability-seam-stable-tools-over-multiple-providers/alternatives-considered/require-per-call-approval-before-public-fetches:
- en: f8d1fc8e9c9659cf
- zh: da5792520e35cba0
+ en: 3ea94ffb142d144a
+ zh: 89645f68412f6769
/agent-note-web-capability-seam-stable-tools-over-multiple-providers/consequences:
- en: 12fd20ba54818215
- zh: c1ca000b13666701
+ en: 9774448fd6b21c41
+ zh: 8411c590ad70d5c4
/agent-note-web-capability-seam-stable-tools-over-multiple-providers/deferred-work:
en: 48b7b8e7310cd56b
zh: d406cd6a8a649e58
diff --git a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md
index 135447cb15..91e212ad9f 100644
--- a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md
+++ b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.md
@@ -202,7 +202,7 @@ Full page retrieval remains the job of `web_fetch(url)`. Search snippets are dis
## Fetch request and result schema
-The `web_fetch` implementation is an anonymous public HTTP(S) fetch provider, `http`. It fetches bytes from a concrete URL, resolves and pins public destinations, applies the transport hygiene below, decodes textual content, and returns only the minimal model-useful result: final URL, status code, body, and truncation. It carries no browser cookies, editor credentials, git credentials, internal auth tokens, or implicit access to private services.
+The `web_fetch` implementation is an anonymous HTTP(S) fetch provider, `http`. It fetches bytes from a concrete URL, applies the transport hygiene below, decodes textual content, and returns only the minimal model-useful result: final URL, status code, body, and truncation. It carries no browser cookies, editor credentials, git credentials, or internal auth tokens. It does not restrict destination addresses.
The seam request stays smaller than OpenCode's model-facing tool:
@@ -238,14 +238,12 @@ The provider owns safe resource retrieval: URL validation, HTTP transport, redir
The fetch provider's resource controls:
- Only `http:` and `https:` URLs are accepted; credentials in URLs are rejected.
-- A literal address or the complete result of one hostname lookup must contain only globally reachable unicast IPv4 or IPv6 destinations. IPv6 resolution also discovers the active DNS64 prefix and rejects NAT64 addresses that translate to non-public IPv4. Loopback, private, link-local, carrier-grade NAT, multicast, reserved, transition, translation, and private IPv4-mapped IPv6 addresses are rejected.
-- The request retains that validated address set in an Undici lookup callback instead of resolving the hostname again. The original hostname remains the HTTP Host and TLS SNI value, while DNS rebinding cannot replace the connection destination after validation.
- Maximum URL length, response byte cap, decoded body character cap, timeout, and redirect hop cap are enforced.
- Abort signals propagate through network fetches and expensive decoding.
-- Only same-origin redirects are followed automatically; each followed hop performs a fresh public-address lookup and pins its own connection. A cross-origin redirect fails with `WEB_REDIRECT_BLOCKED`, requiring a fresh tool call and fresh public-address validation. (Claude Code's WebFetch uses this same model — it does not auto-follow a cross-host redirect; it returns the redirect target to the model for a fresh call.)
+- Only same-origin redirects are followed automatically; each followed hop repeats URL validation. A cross-origin redirect fails with `WEB_REDIRECT_BLOCKED`, requiring a fresh tool call. (Claude Code's WebFetch uses this same model — it does not auto-follow a cross-host redirect; it returns the redirect target to the model for a fresh call.)
- Requests carry an explicit product user agent rather than silently impersonating a browser.
-The provider rejects an entire DNS answer set when any address is not public instead of silently filtering the unsafe members. This fail-closed rule prevents connection-family selection or fallback from reaching an address that did not satisfy the public-network policy.
+Requests use the process-wide dispatcher, so the installed outbound proxy policy and the system resolver decide the connection. Loopback, private-network, and cloud metadata destinations are reachable.
## Tool consumer behavior
@@ -313,17 +311,13 @@ Rejected for the first version. Those providers often return extracted or summar
Rejected for the seam. `prompt` turns fetch into LLM summarization and couples public-web retrieval to a model provider. The harness seam should fetch and decode deterministically; `dsh-tool-web` can later offer summaries as a presentation mode without making `ctx.web` depend on `ctx.llm`.
-### Validate DNS and then call an ordinary fetch
+### Restrict fetch to public addresses
-Rejected because an ordinary fetch resolves the hostname again when it opens the connection. An attacker can return a public address during validation and a private address during the second lookup. Passing the validated answer set through the connection's lookup callback closes that rebinding interval while preserving hostname-based HTTP and TLS behavior.
-
-### Block private-looking hostname strings without pinning resolved addresses
-
-Rejected because hostname syntax does not establish the connection destination: an arbitrary public-looking name can resolve to loopback, a private range, or a cloud metadata address. Address classification belongs after resolution, and every address available to connection fallback must pass it.
+Rejected. Resolving each hostname, rejecting any non-public answer, and pinning the connection to the validated set does not confine the model, which reaches the same networks through mounted shell tools, and it refuses every page on hosts whose DNS answers with non-public addresses, such as TUN-mode proxies with fake-IP DNS. Deployments that must keep the model away from private destinations need network confinement, a `tools/pre-execute` policy, or no fetch tool.
### Require per-call approval before public fetches
-Rejected for the shipped presets. Public-address validation blocks SSRF destinations, while per-call confirmation would interrupt ordinary browsing without controlling public data egress reliably: a model can reach the same public network through mounted shell tools. Deployments that require a dedicated confirmation step can add a `tools/pre-execute` policy or disable `web_fetch`.
+Rejected for the shipped presets. Per-call confirmation would interrupt ordinary browsing without controlling data egress reliably: a model can reach the same networks through mounted shell tools. Deployments that require a dedicated confirmation step can add a `tools/pre-execute` policy or disable `web_fetch`.
## Consequences
@@ -335,7 +329,7 @@ Rejected for the shipped presets. Public-address validation blocks SSRF destinat
**Provider state can change after startup.** A tool can be visible in the request assembled at step start and lose its provider before execution. The execution path resolves again and fails with a structured error.
-**Fetch is a network boundary, not just a read-only tool.** Public-address validation and connection pinning prevent `web_fetch` from reaching non-public destinations, but a model can still disclose data through a public URL and fetched text remains untrusted model input. The shipped `cordis`, `code`, and `standard` presets expose `web_fetch` in every sandbox and approval mode without per-call confirmation.
+**Fetch is a network boundary, not just a read-only tool.** `web_fetch` reaches any destination the host can, including loopback and private-network services, a model can disclose data through a URL, and fetched text remains untrusted model input. The shipped `cordis`, `code`, and `standard` presets expose `web_fetch` in every sandbox and approval mode without per-call confirmation.
**Large web content can damage context quality.** Providers enforce byte/character caps and report `truncated`; `tool-web` formats bounded model output with clear continuation or follow-up guidance.
diff --git a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md
index 736b50ebb3..27b7777f23 100644
--- a/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md
+++ b/.agents/notes/implemented/architecture/2026-06-24-web-capability-seam.zh.md
@@ -202,7 +202,7 @@ Exa 搜索将提供方扁平 `results[]` 的每一项映射为 `WebSearchSource`
## Fetch 请求与结果 schema
-`web_fetch` 的实现是一个匿名公开 HTTP(S) fetch 提供方 `http`。它从具体 URL 获取字节，解析并固定公开目的地址，应用下述传输卫生措施，解码文本内容，并仅返回最小的模型可用结果：最终 URL、状态码、正文和截断标志。它不携带浏览器 cookie、编辑器凭证、git 凭证、内部认证令牌，也不隐式访问私有服务。
+`web_fetch` 的实现是一个匿名 HTTP(S) fetch 提供方 `http`。它从具体 URL 获取字节，应用下述传输卫生措施，解码文本内容，并仅返回最小的模型可用结果：最终 URL、状态码、正文和截断标志。它不携带浏览器 cookie、编辑器凭证、git 凭证或内部认证令牌。它不限制目的地址。
seam 请求比 OpenCode 的面向模型工具更小：
@@ -238,14 +238,12 @@ export type WebFetchBody =
fetch 提供方的资源控制：
- 仅接受 `http:` 和 `https:` URL；拒绝 URL 中的凭证。
-- 字面 IP 地址或 hostname 一次解析得到的完整结果只能包含全球可达的单播 IPv4 或 IPv6 目的地址。IPv6 解析还会发现当前 DNS64 前缀，并拒绝转换到非公开 IPv4 的 NAT64 地址。loopback、私有、link-local、运营商级 NAT、多播、保留、过渡、转换和映射到私有 IPv4 的 IPv6 地址都会被拒绝。
-- 请求通过 Undici lookup 回调保留这一组已验证地址，不会再次解析 hostname。原 hostname 仍作为 HTTP Host 与 TLS SNI 值，而 DNS rebinding 无法在验证后替换连接目的地址。
- 强制执行最大 URL 长度、响应字节上限、解码正文字符上限、超时和重定向跳数上限。
- Abort 信号传播到网络获取和高开销解码。
-- 仅自动跟随同源重定向；每个跟随的跳转都会重新解析公开地址，并把自己的连接固定到解析结果。跨源重定向以 `WEB_REDIRECT_BLOCKED` 失败，要求一次新的工具调用和新的公开地址校验。（Claude Code 的 WebFetch 使用同样的模型——它不自动跟随跨主机重定向，而是将重定向目标返回给模型以发起新调用。）
+- 仅自动跟随同源重定向；每个跟随的跳转都会重复 URL 校验。跨源重定向以 `WEB_REDIRECT_BLOCKED` 失败，要求一次新的工具调用。（Claude Code 的 WebFetch 使用同样的模型——它不自动跟随跨主机重定向，而是将重定向目标返回给模型以发起新调用。）
- 请求携带显式的产品 User-Agent，而非静默伪装浏览器。
-只要 DNS 完整解析结果中存在任一非公开地址，提供方就会拒绝整个结果，而不是静默过滤不安全成员。该 fail-closed 规则可防止连接的地址族选择或回退触及未满足公开网络策略的地址。
+请求使用进程级 dispatcher，因此由已安装的出站代理策略与系统解析器决定连接。loopback、内网与云 metadata 目的地址都可访问。
## 工具消费方行为
@@ -313,17 +311,14 @@ fetch 提供方的资源控制：
在 seam 层面否决。`prompt` 将 fetch 变成 LLM 摘要，并将公开 web 获取耦合到模型提供方。harness seam 应当确定性地获取和解码；`dsh-tool-web` 日后可以将摘要作为展示模式提供，而无需让 `ctx.web` 依赖 `ctx.llm`。
-### 验证 DNS 后调用普通 fetch
+` key remains. Readers accept both leg
There is no new draft service, storage key, general task framework, or Session creation entry point. SlotRenderer, Host Session logs, command execution, and file-discovery RPCs are unchanged. `InputActions` remains the shared input-action entry; components receive no separate content-initialization callback.
-The call parameters are `startSession(workspaceId?: WorkspaceId, options?: StartSessionOptions)`, `requestDraftInitialization(binding: SessionBinding, options: DraftInitializationOptions)`, `SessionInputShell.requestDraftInitialization(options)`, and the internal `SessionInputShell.setDraft(input: string | DraftSnapshot)`. `StartSessionOptions` aliases `DraftInitializationOptions`, whose fields are `prompt?: string` and `clearPreviousDraft?: boolean`. A shallow copy captures these values before asynchronous creation, and the result addresses only the retained target binding. Initialization distinguishes applied, preserved, and submission-blocked outcomes. Refusal does not clear first; superseded navigation does not write a draft.
+The call parameters are `startSession(workspaceId?: WorkspaceId, options?: StartSessionOptions)`, `requestDraftInitialization(binding: SessionBinding, options: DraftInitializationOptions)`, `SessionInputShell.requestDraftInitialization(options)`, and the internal `SessionInputShell.setDraft(input: string | DraftSnapshot)`. `StartSessionOptions` extends `DraftInitializationOptions`, whose fields are `prompt?: string`, `whenDraftExists?: 'replace' | 'append' | 'keep'`, and `clearPreviousDraft?: boolean`. A shallow copy captures these values before asynchronous creation, and the result addresses only the retained target binding. Initialization distinguishes applied, preserved, and submission-blocked outcomes. Refusal does not clear first; superseded navigation does not write a draft.
### Data flow
diff --git a/.agents/notes/implemented/architecture/2026-09-30-structured-draft-initialization.zh.md b/.agents/notes/implemented/architecture/2026-09-30-structured-draft-initialization.zh.md
index 07c185a969..12d4e4731a 100644
--- a/.agents/notes/implemented/architecture/2026-09-30-structured-draft-initialization.zh.md
+++ b/.agents/notes/implemented/architecture/2026-09-30-structured-draft-initialization.zh.md
@@ -12,7 +12,7 @@ Status: implemented
保留现有 `SessionInputShell`、`DraftEditorRuntime`、Conversation store 和 Session 引用生命周期。普通文字与结构化草稿统一经过输入模型导入；初始导入在 `InputHub.shellFor()` 返回对象前完成，不由 React effect 恢复文字。已存在的输入对象不重新恢复。React 只挂载同一编辑器，并绑定现有持久化回调。
-`startSession(workspaceId?, options?)` 的第二参数保留 `prompt` 与 `clearPreviousDraft`。`prompt` 仅接受字符串；结构化草稿只用于内部恢复和工作区携带。无选项时维持原流程。不清空时保留已有内容，空稿才采用 prompt；显式清空作用于目标 Session 的文字文档，不删除附件，也不修改其他 Session。预填不自动发送、执行命令或改变 `blank`。
+`startSession(workspaceId?, options?)` 的第二参数包含 `prompt`、`whenDraftExists` 与 `clearPreviousDraft`。`prompt` 仅接受字符串；结构化草稿只用于内部恢复和工作区携带。无选项时维持原流程。空稿直接采用 prompt。目标已有文字或附件时由 `whenDraftExists` 决定：`keep`（默认）保留原稿，`replace` 用 prompt 替换目标 Session 的文字文档、无 prompt 时清空，`append` 在原有文字与引用之后另起段落追加 prompt。三者都不删除附件，也不修改其他 Session。只有未传 `whenDraftExists` 时，`clearPreviousDraft: true` 才等同 `replace`。预填不自动发送、执行命令或改变 `blank`。
### 数据模型
@@ -41,7 +41,7 @@ Status: implemented
不新增草稿服务、存储 key、通用任务框架或另一套 Session 创建入口；不改 SlotRenderer、Host Session 日志、命令执行和文件发现 RPC。`InputActions` 保留统一输入操作入口，组件不单独注入另一条内容初始化回调。
-调用参数依次为 `startSession(workspaceId?: WorkspaceId, options?: StartSessionOptions)`、`requestDraftInitialization(binding: SessionBinding, options: DraftInitializationOptions)`、`SessionInputShell.requestDraftInitialization(options)`，以及内部的 `SessionInputShell.setDraft(input: string | DraftSnapshot)`。`StartSessionOptions` 直接引用 `DraftInitializationOptions`，字段为 `prompt?: string` 和 `clearPreviousDraft?: boolean`；进入异步创建前浅拷贝这些值，结果只作用于最终保留的 binding。初始化结果区分已应用、保留原稿和提交期间拒绝；拒绝不先清空，导航被后续操作取消时不写稿。
+调用参数依次为 `startSession(workspaceId?: WorkspaceId, options?: StartSessionOptions)`、`requestDraftInitialization(binding: SessionBinding, options: DraftInitializationOptions)`、`SessionInputShell.requestDraftInitialization(options)`，以及内部的 `SessionInputShell.setDraft(input: string | DraftSnapshot)`。`StartSessionOptions` 扩展 `DraftInitializationOptions`，字段为 `prompt?: string`、`whenDraftExists?: 'replace' | 'append' | 'keep'` 和 `clearPreviousDraft?: boolean`；进入异步创建前浅拷贝这些值，结果只作用于最终保留的 binding。初始化结果区分已应用、保留原稿和提交期间拒绝；拒绝不先清空，导航被后续操作取消时不写稿。
### 数据流
diff --git a/.agents/notes/implemented/architecture/2026-10-12-peer-principal-and-remote-access.i18n.yaml b/.agents/notes/implemented/architecture/2026-10-12-peer-principal-and-remote-access.i18n.yaml
index fbf95020c0..9378bc4f0b 100644
--- a/.agents/notes/implemented/architecture/2026-10-12-peer-principal-and-remote-access.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-10-12-peer-principal-and-remote-access.i18n.yaml
@@ -54,8 +54,8 @@
en: 7865e159528e2d30
zh: 1399d54632f4d926
/agent-note-peer-principals-and-method-level-remote-access-control/decision/method-level-access-control/access-snapshot-stream:
- en: 41d7ac1faf2448d7
- zh: 6d523895a9abae68
+ en: a928a63e8c36177c
+ zh: c943c1fdc8c4bb45
/agent-note-peer-principals-and-method-level-remote-access-control/decision/method-level-access-control/client-face:
en: 7be28cd7e19e5377
zh: 30b5aee957271d6c
@@ -81,8 +81,8 @@
en: 89452c3c3f042e75
zh: 9bcad00a60c65303
/agent-note-peer-principals-and-method-level-remote-access-control/consequences/verification:
- en: 048067eb02e6bf8a
- zh: 12508b59f6b206b8
+ en: 2279a8c153cc5b89
+ zh: 63c0b6462722f0a3
/agent-note-peer-principals-and-method-level-remote-access-control/consequences/costs-and-limits:
en: 1e254cec680b1a37
zh: 06a31e057ba965aa
diff --git a/.agents/notes/implemented/architecture/2026-10-12-peer-principal-and-remote-access.md b/.agents/notes/implemented/architecture/2026-10-12-peer-principal-and-remote-access.md
index 324606f3ab..c9894ae409 100644
--- a/.agents/notes/implemented/architecture/2026-10-12-peer-principal-and-remote-access.md
+++ b/.agents/notes/implemented/architecture/2026-10-12-peer-principal-and-remote-access.md
@@ -446,7 +446,7 @@ export const REMOTE_ACCESS_SNAPSHOT_KEY = '__DSH_REMOTE_ACCESS__'
| Behavior | Detail |
|---|---|
-| First snapshot | `snapshotFor(principal)` computes a page's opening baseline. remote-access adds the global `REMOTE_ACCESS_SNAPSHOT_KEY`, set to the owner baseline `{ type: 'baseline', owner: true }`, to every index the webServer renders, through `webserver/index-inject`. A business package that renders a non-owner page (such as liveshare on the owner Host) places an assignment of that global to `snapshotFor(principal)` after every index injection row; the later assignment wins, and the Client reads the global when it mounts |
+| First snapshot | `snapshotFor(principal)` computes a page's opening baseline. The webServer renders each index for the Peer the page speaks for, and `webserver/index-inject` passes that Peer to listeners; remote-access adds the global `REMOTE_ACCESS_SNAPSHOT_KEY`, set to `snapshotFor(peer.principal)`, to every index, so the owner's page receives the owner baseline `{ type: 'baseline', owner: true }` and a page rendered for a non-owner Peer (such as a liveshare viewer page on the owner Host) receives that principal's grants. The Client reads the global when it mounts |
| Subscription | Each Peer subscribes to one access snapshot stream, whose baseline replaces the injected one |
| Computation | All bindings of the policy for the principal's kind are merged by equal resource; each resource's `actions` are the endpoint actions of those bindings' roles that the same decision as a call allows (one resource, without args, conditions called without args); only a resource with at least one allowed endpoint action gets a grant. Decisions and snapshots share one source: for the same principal, action, and resource (without arguments), the snapshot answer equals `decide()` |
| Endpoint actions only | `event:` actions do not enter the snapshot; the frontend decides entry visibility from endpoint actions only |
@@ -638,7 +638,7 @@ The review rule's home is the "`@Remote` marks capability methods" section of [R
| Resource resolution | A default field (top-level or first object argument) yields its resource; a lookup parameter that declares that kind as its `resource` yields its wire identity; a Context method gets its Session resource from the Agent Context identity in args without activating the Agent, and may declare other resources through `resources`; a `resources` reader overrides its kind, an array yields several resources, and `undefined` none; with nothing the call is `[global]`; a throw, an empty array, or a value that is not a non-empty string (including a Context identity) is invalid, refused by the Gateway with `resource-invalid` without asking `decide()`; a Context that declares no `resource` resolves by the ordinary rules; resources and `args` read the validated arguments, so an undeclared nested field changes no resource and no condition sees it, and a JSON argument failing validation returns `gateway/input-invalid` before the access check | Gateway host spec (gateway-access) |
| Resource registry | `typert.resources` registers one default field per kind, rejects a second registration and `global`, and withdraws the registration with its fiber; a configured lookup resolver keeps the provider's `resource`; a Host Context adapter keeps its `resource` | typert-registry spec |
| Forwarded events | A non-owner `$events` stream receives an event, whole, only when `event:` is granted on its resources; an event that declares no resources is decided on `global`; an event whose reader returns `undefined` does not reach non-owners, and `decide()` is not asked; the owner receives all | Gateway host spec (gateway-access) |
-| First snapshot | `snapshotFor()` returns the owner baseline or the principal's grants; remote-access injects the owner baseline into every rendered index; the Client starts from the injected baseline and rejects a malformed one | remote-access host and client specs |
+| First snapshot | `snapshotFor()` returns the owner baseline or the principal's grants; remote-access injects the snapshot of the Peer each index speaks for; the Client starts from the injected baseline and rejects a malformed one | remote-access host and client specs |
| Type inference | The parameter types of `resources` readers are inferred from the method; lookup positions have wire types; a missing property, more parameters than the method has, and a `global` key fail compilation; a binding whose resource kind differs from its role's fails compilation | typert-protocol spec, remote-access spec (type tests) |
| List filtering | `session/list`, `session/search`, `session/control`, and `workspace/follow` return non-owners only items for which `allows()` is true; `workspace/follow` sends a `replace` increment when a delivered Workspace loses visibility, and the Workspace reappears once access returns; owner results are unchanged | session-controller / workspace-controller host spec |
| Access snapshots | The allowed set in a snapshot equals the Host decision for the same principal, action, and resource without arguments; it contains endpoint actions only; a resource with no allowed action gets no grant, and one whose allowed set becomes empty is removed; `invalidate()` and policy registration or removal push increments; a wait that a change ends leaves no abort listener behind; unloading the service ends every open snapshot stream; the owner receives only `{ owner: true }` | remote-access host spec |
diff --git a/.agents/notes/implemented/architecture/2026-10-12-peer-principal-and-remote-access.zh.md b/.agents/notes/implemented/architecture/2026-10-12-peer-principal-and-remote-access.zh.md
index afbd49de7f..ed124e8159 100644
--- a/.agents/notes/implemented/architecture/2026-10-12-peer-principal-and-remote-access.zh.md
+++ b/.agents/notes/implemented/architecture/2026-10-12-peer-principal-and-remote-access.zh.md
@@ -446,7 +446,7 @@ export const REMOTE_ACCESS_SNAPSHOT_KEY = '__DSH_REMOTE_ACCESS__'
| 行为 | 说明 |
|---|---|
-| 首份快照 | `snapshotFor(principal)` 计算页面打开时的 baseline。remote-access 经 `webserver/index-inject` 为 webServer 渲染的每个 index 加入全局变量 `REMOTE_ACCESS_SNAPSHOT_KEY`，值为 owner baseline `{ type: 'baseline', owner: true }`。渲染非 owner 页面的业务包（例如 owner Host 上的 liveshare）在所有 index 注入行之后放置一条把该全局变量赋值为 `snapshotFor(principal)` 的语句；后写的赋值生效，Client 在挂载时读取该全局变量 |
+| 首份快照 | `snapshotFor(principal)` 计算页面打开时的 baseline。webServer 按页面所代表的 Peer 渲染 index，`webserver/index-inject` 把该 Peer 传给监听方；remote-access 为每个 index 加入全局变量 `REMOTE_ACCESS_SNAPSHOT_KEY`，值为 `snapshotFor(peer.principal)`，owner 页面因此得到 owner baseline `{ type: 'baseline', owner: true }`，为非 owner Peer 渲染的页面（例如 owner Host 上的 liveshare 读者页）得到该 principal 的 grant。Client 在挂载时读取该全局变量 |
| 订阅 | 每个 Peer 订阅一条访问快照流，其 baseline 取代注入的快照 |
| 计算 | 取该 principal kind 的 policy 的全部 binding，按资源相等归并；每个资源的 `actions` 为这些 binding 的 role 中、经与调用相同的判定（单个资源、不带 args，condition 以无 args 调用）放行的端点 action；只为至少放行一个端点 action 的资源给出 grant。判定与快照同源：同一 principal、action 与资源（不带参数）上，快照答案与 `decide()` 一致 |
| 只含端点 action | `event:` action 不进入快照；前端只据端点 action 决定入口显隐 |
@@ -638,7 +638,7 @@ GlobalStandardProps.useWorkspaceAccess: (workspaceId: WorkspaceId, action: Remot
| 资源解析 | 默认字段（顶层或首个对象参数）得到对应资源；声明了该种类 `resource` 的 lookup 参数得到其 wire 身份；Context 方法从 args 中的 Agent Context 身份得到其 session 资源且不激活 Agent，另可经 `resources` 声明其他资源；`resources` 读取函数覆盖该种类，数组为多个资源，`undefined` 为无；都没有为 `[global]`；抛错、空数组或非非空字符串（含 Context 身份）为非法，Gateway 以 `resource-invalid` 拒绝且不询问 `decide()`；未声明 `resource` 的 Context 按普通规则解析；资源与 `args` 读取校验后的参数，未声明的嵌套字段不改变资源、condition 也读不到它，JSON 参数校验失败在访问检查前返回 `gateway/input-invalid` | Gateway host spec（gateway-access） |
| 资源注册表 | `typert.resources` 每个种类登记一个默认字段，拒绝重复登记与 `global`，并随 fiber 撤回；配置的 lookup resolver 保留 provider 的 `resource`；Host Context adapter 保留其 `resource` | typert-registry spec |
| 转发事件 | 非 owner 的 `$events` 流只在 `event:` 于其资源上被授权时整条收到事件；未声明资源的事件按 `global` 判定；读取函数返回 `undefined` 的事件不送达非 owner，且不询问 `decide()`；owner 全部收到 | Gateway host spec（gateway-access） |
-| 首份快照 | `snapshotFor()` 返回 owner baseline 或该 principal 的 grant；remote-access 为渲染的每个 index 注入 owner baseline；Client 从注入的 baseline 起步并拒绝格式错误的快照 | remote-access host 与 client spec |
+| 首份快照 | `snapshotFor()` 返回 owner baseline 或该 principal 的 grant；remote-access 为每个 index 注入其所代表 Peer 的快照；Client 从注入的 baseline 起步并拒绝格式错误的快照 | remote-access host 与 client spec |
| 类型推断 | `resources` 读取函数的参数类型从方法推断；lookup 位为 wire 类型；访问不存在的属性、参数多于方法参数与 `global` 键编译失败；binding 的资源种类与 role 不符编译失败 | typert-protocol spec、remote-access spec（类型测试） |
| 列表过滤 | `session/list`、`session/search`、`session/control`、`workspace/follow` 对非 owner 只返回 `allows()` 为 true 的项；已下发工作区失去可见性时 `workspace/follow` 发送 `replace` 增量帧，访问恢复后该工作区重新出现；owner 结果不变 | session-controller / workspace-controller host spec |
| 访问快照 | 快照中的允许集合与 Host 对同一 principal、action、资源（不带参数）的判定一致；只含端点 action；没有放行 action 的资源不出 grant，放行集合变空时推送 `remove`；`invalidate()` 与 policy 注册、撤回后推送增量；被变化结束的等待不残留 abort 监听器；卸载服务即结束所有打开的快照流；owner 只收 `{ owner: true }` | remote-access host spec |
diff --git a/.agents/notes/implemented/architecture/2026-10-13-cua-hover-routes-and-coordinates.i18n.yaml b/.agents/notes/implemented/architecture/2026-10-13-cua-hover-routes-and-coordinates.i18n.yaml
index 62f41f9e6f..85cccf7afa 100644
--- a/.agents/notes/implemented/architecture/2026-10-13-cua-hover-routes-and-coordinates.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-10-13-cua-hover-routes-and-coordinates.i18n.yaml
@@ -9,8 +9,8 @@
en: f96bf1ebc0719fb0
zh: e9a1144f0e76572d
/agent-note-background-hover-and-screenshot-coordinates/decision:
- en: 0cdd295d5f1872ed
- zh: fe03ec9f7df94a4a
+ en: 0f45528ea6c5988c
+ zh: 9bde9df417ddb1ce
/agent-note-background-hover-and-screenshot-coordinates/alternatives-considered:
en: 5fc4beaf79761c50
zh: 4948333b0020be28
diff --git a/.agents/notes/implemented/architecture/2026-10-13-cua-hover-routes-and-coordinates.md b/.agents/notes/implemented/architecture/2026-10-13-cua-hover-routes-and-coordinates.md
index e43121c8c8..d81d964f8a 100644
--- a/.agents/notes/implemented/architecture/2026-10-13-cua-hover-routes-and-coordinates.md
+++ b/.agents/notes/implemented/architecture/2026-10-13-cua-hover-routes-and-coordinates.md
@@ -12,7 +12,7 @@ Hover-only controls can sometimes be revealed without moving the user's pointer.
Native hover first uses a same-window element or ancestor advertising both `AXShowAlternateUI` and `AXShowDefaultUI`. Entering its revealed descendants preserves the parent UI; leaving restores it. An unavailable route falls back to the real system pointer. An AX action failure propagates because received effects may be uncertain. The result records the route and whether the system pointer moved. System movement requires the selected foreground app and AppKit's mouse hit test, which excludes input-transparent overlays. No route grants [cross-call ownership](2026-10-13-cua-continuous-hover.md).
-Model-facing coordinate input defaults to pixels in the returned screenshot. `relative: true` accepts integer thousandths from 0 to 1000 for click, hover, scroll and drag; it does not apply to AX indices. The Host owns the mapping to native window points. An application-wide observation refreshes its inventory; a scoped observation preserves other windows' image mappings. Window resizing invalidates the old image, while movement preserves local coordinates. Relative endpoints remain inside the window and do not depend on screenshot resolution.
+Model-facing coordinate input defaults to pixels in the returned screenshot. `relative: true` accepts integer thousandths from 0 to 999 for click, hover, scroll and drag; it does not apply to AX indices. The Host owns the mapping to native window points. An application-wide observation refreshes its inventory; a scoped observation preserves other windows' image mappings. Window resizing invalidates the old image, while movement preserves local coordinates. Relative endpoints remain inside the window and do not depend on screenshot resolution.
`LlmAdapter.imageRequestTarget` exposes the same dimensions and byte target used by image serialization. DeepSeek and pi-ai share their existing projection functions with this method. Other adapters preserve normalized images unless they declare resizing. Screenshot bytes returned to programs match the request image; its durable source is admitted and stored once. The native PNG metadata is checked against decoded source dimensions before any input mapping is published.
diff --git a/.agents/notes/implemented/architecture/2026-10-13-cua-hover-routes-and-coordinates.zh.md b/.agents/notes/implemented/architecture/2026-10-13-cua-hover-routes-and-coordinates.zh.md
index 51beb3967f..2ef7ac9e44 100644
--- a/.agents/notes/implemented/architecture/2026-10-13-cua-hover-routes-and-coordinates.zh.md
+++ b/.agents/notes/implemented/architecture/2026-10-13-cua-hover-routes-and-coordinates.zh.md
@@ -12,7 +12,7 @@ Status: implemented
原生悬停优先寻找同一窗口内同时声明 `AXShowAlternateUI` 和 `AXShowDefaultUI` 的元素或祖先。进入其展开区域的子控件时保持父控件展开，离开后恢复。没有可用路径时回退到真实系统鼠标。AX 动作失败直接返回，因为已产生的效果可能不确定。结果记录实际路径及是否移动系统鼠标。系统移动要求所选应用处于前台，并使用 AppKit 的鼠标命中查询排除不接收输入的覆盖窗口。所有路径都遵守[跨调用不分配所有权](2026-10-13-cua-continuous-hover.zh.md)的决定。
-面向模型的坐标默认使用返回截图中的像素。click、hover、scroll 和 drag 传入 `relative: true` 时接受 0～1000 的千分比整数，不适用于 AX 索引。Host 负责换算原生窗口 point。应用级观察刷新窗口清单，单窗口观察保留其他窗口的图片映射。窗口尺寸变化使旧图片失效，移动窗口保留局部坐标。相对坐标的端点保持在窗口内，不随截图分辨率改变。
+面向模型的坐标默认使用返回截图中的像素。click、hover、scroll 和 drag 传入 `relative: true` 时接受 0～999 的千分比整数，不适用于 AX 索引。Host 负责换算原生窗口 point。应用级观察刷新窗口清单，单窗口观察保留其他窗口的图片映射。窗口尺寸变化使旧图片失效，移动窗口保留局部坐标。相对坐标的端点保持在窗口内，不随截图分辨率改变。
`LlmAdapter.imageRequestTarget` 提供与图片序列化相同的尺寸和字节目标。DeepSeek 和 pi-ai 在该方法中复用已有投影函数。其他适配器除非声明缩放，否则保留归一化图片。返回程序的截图字节与模型请求图片一致，持久原图只接入并保存一次。发布输入映射前，原生 PNG 元数据必须与解码后的原图尺寸一致。
diff --git a/.agents/notes/implemented/architecture/2026-10-14-plugin-entry-customization.i18n.yaml b/.agents/notes/implemented/architecture/2026-10-14-plugin-entry-customization.i18n.yaml
new file mode 100644
index 0000000000..1c14701120
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-10-14-plugin-entry-customization.i18n.yaml
@@ -0,0 +1,37 @@
+# Bilingual-pair consistency record for 2026-10-14-plugin-entry-customization.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-10-14-plugin-entry-customization.md
+/agent-note-plugin-entry-customization-region-owned-pins-and-more-menus:
+ en: 2fdf5b95d5603955
+ zh: bfdc61e7db5f5f5b
+/agent-note-plugin-entry-customization-region-owned-pins-and-more-menus/problem:
+ en: 896876f139383cba
+ zh: 42a4aae7e5885780
+/agent-note-plugin-entry-customization-region-owned-pins-and-more-menus/decision:
+ en: a6cfc29cb9caa83c
+ zh: 21bbeb6a7ab20018
+/agent-note-plugin-entry-customization-region-owned-pins-and-more-menus/decision/user-visible-behavior:
+ en: f1456281aa937626
+ zh: 6fef46b8d72ddd2b
+/agent-note-plugin-entry-customization-region-owned-pins-and-more-menus/decision/structure-and-ownership:
+ en: d6a2816ca55b1c38
+ zh: 53217016f1595755
+/agent-note-plugin-entry-customization-region-owned-pins-and-more-menus/decision/package-changes-relative-to-release-dsh-0-2-1:
+ en: 18ed81fee1ca7d41
+ zh: fc298457e54b6488
+/agent-note-plugin-entry-customization-region-owned-pins-and-more-menus/decision/actions-slots-and-menu-content:
+ en: c87e2fdd911714b5
+ zh: 074426fdc7abafa9
+/agent-note-plugin-entry-customization-region-owned-pins-and-more-menus/decision/the-three-regions:
+ en: 770c6150e84742ba
+ zh: 1d619388c8f38646
+/agent-note-plugin-entry-customization-region-owned-pins-and-more-menus/alternatives-considered:
+ en: 79355028387c4094
+ zh: 5b518166e4803ebe
+/agent-note-plugin-entry-customization-region-owned-pins-and-more-menus/verification:
+ en: 9c6a9ec155bbbfaa
+ zh: 8bd6e7afc8c43d21
+/agent-note-plugin-entry-customization-region-owned-pins-and-more-menus/consequences:
+ en: a2459a3316f3ee60
+ zh: 713b51329995fe46
diff --git a/.agents/notes/implemented/architecture/2026-10-14-plugin-entry-customization.md b/.agents/notes/implemented/architecture/2026-10-14-plugin-entry-customization.md
new file mode 100644
index 0000000000..58e5929ff5
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-10-14-plugin-entry-customization.md
@@ -0,0 +1,136 @@
+# Agent Note: Plugin entry customization: region-owned pins and More menus
+
+Status: implemented
+
+English | [中文](2026-10-14-plugin-entry-customization.zh.md)
+
+## Problem
+
+The `release/dsh-0.2.1` Web app shows plugin entries in three regions: the left sidebar's panel buttons (`sidebar.panellist`), the Conversation header's View tabs (`conversation.view`), and the right sidebar guide's tool cards (guide entries from the right-sidebar tab registry). Each region shows every entry in registration order, so users cannot hide entries they rarely use, and every installed plugin makes the regions more crowded. Users also cannot browse more plugins or start creating a plugin from these positions.
+
+The feature ships in `release/dsh-0.2.1` and is later merged back to master with the release, so it changes as little as possible relative to the release: no changes to the slot framework (`ui-slots`, `ui-renderer`), no new Cordis service, `ui-layout` unchanged, and client plugin packages share only types ([Client package export rules](../../../../packages/client/AGENTS.md)). Persisted data must be readable without migration by a later slot-level store for manual order and pin state.
+
+## Decision
+
+Each region keeps and persists its own list of unpinned entries and filters its own entry buttons with it. Each region draws its own More button, opens a menu with the shared `Menu` component, and renders its actions slot inside that menu. The default-loaded plugin package `ui-entry-customization` registers the same menu-content component into the three actions slots: the entry list with pin buttons, Browse other plugins, and Create your plugin. This follows the Plugins page's Add plugin menu, where the page draws the button and menu and `ui-agent-preset` adds Create plugin through `plugins.add.actions`. Entries cannot be reordered.
+
+### User-visible behavior
+
+- The left sidebar, the Conversation header, and the right sidebar guide each have a More button. Its menu lists the region's customizable entries. Selecting an entry name opens the entry; its pin button shows or hides the entry in the region; the bottom of the menu has Browse other plugins (opens the Plugins main list) and Create your plugin (opens a new or reused blank Session with the Creator preset and fills in the region's prompt without sending it).
+- Entries appear in registration order, as in the release; they cannot be reordered.
+- Default entries always show and never appear in the menu: Plugins in the left sidebar, Chat in the Conversation header, and Files in the right sidebar.
+- Pin state survives page reloads and is shared by every Session.
+- Hiding the selected entry does not navigate away from its content; the left-sidebar row or View tab of the selected entry stays visible, as the current item, until another entry is selected.
+- The left-sidebar `` and the Conversation header tab bar keep their release visibility conditions: `` shows while any panel is registered, and the tab bar shows while more than one View is registered. Both conditions count registered entries, not entries left visible by pin state. With only Chat registered the tab bar stays hidden; with other Views registered, the tab bar and its More button stay visible even when every other View is hidden, so users can pin them again.
+- While an actions slot has no registrations, for example when `ui-entry-customization` is not loaded, its region shows no More button.
+
+### Structure and ownership
+
+```text
+ui-sidebar / ui-conversation / ui-sidebar-right (each region)
+ apply: the region's unpinned list (createSnapshotStore + persist) and setPinned
+ whether the actions slot has registrations (entriesOfSlot + subscribe)
+ root component: draws only fixed or pinned entries
+ while the actions slot has registrations, draws the region's More button and Menu:
+
+ renderSlot('.actions', { entries, onOpen, onPinnedChange, onDismiss })
+
+
+ui-entry-customization (default-loaded)
+ registers one menu-content component into each actions slot (id 'entry-customization')
+ content: non-fixed entries with pin buttons, Browse other plugins, Create your plugin; keeps no state
+```
+
+Dependency direction: the three regions do not depend on the plugin package and only add uses of `client-store` and `ui-primitives` they already depend on. `ui-entry-customization` depends on the three regions (slot types) and on `ui-plugin-manager` and `ui-workspace` (service types), and calls `ctx.pluginNavigation` and `ctx.uiWorkspace` at runtime. No package gains a new runtime value import from another package.
+
+### Package changes relative to release/dsh-0.2.1
+
+| Package | Change |
+|---|---|
+| `ui-sidebar` | Adds `sidebar.panellist.actions`; apply adds the unpinned list, `setPinned`, and the actions-slot registration state; `SidebarRoot` filters entries and draws the More button and menu at the end of ``; expanded panel rows use a 2px gap instead of 4px |
+| `ui-conversation` | Adds `conversation.session.header.views.actions`; apply adds the same three parts; the Session header filters View tabs and draws the More button and menu inside the tab bar after the tablist; View tabs use a 32px gap instead of 36px, with 20px before More |
+| `ui-sidebar-right` | Adds `sidebar.right.tab.guide.actions`; apply adds the same three parts; the guide filters cards and draws the More card and menu after the cards; the guide registration declares the `sidebarRight` locale namespace |
+| `ui-entry-customization` (new package) | Registers the menu-content component into the three actions slots; owns the `entryCustomization` locale namespace; keeps no state |
+| `ui-plugin-manager` | Adds `openList()` to `pluginNavigation`: selects the Installed tab of the Plugins main list without opening a dialog or changing the current Session |
+| `ui-primitives` | Adds `minWidthFromAnchor` to `Menu` so the right-sidebar menu is never narrower than its card; adds `IconAppsAddOutlineRegular` / `IconAppsAddOutlineMedium` (`compact` for card size), shared by the left-sidebar and right-sidebar buttons |
+| `@deepseek-ai/dsh-web-app` | Loads `ui-entry-customization` by default |
+
+### Actions slots and menu content
+
+The three actions slots are root-scoped list slots declared by their regions and rendered inside the region's More menu. Other plugins may register menu items into them; items follow their registration `order`. Each region declares the owner props in its own contract (`SidebarPanelActionsOwnerProps`, `ConversationViewActionsOwnerProps`, `SidebarRightGuideActionsOwnerProps`) with the same fields; the left sidebar's type is:
+
+```ts
+interface SidebarPanelActionsOwnerProps {
+ /** The region's customizable entries in registration order; fixed entries are excluded. */
+ readonly entries: readonly { readonly id: string; readonly label: string; readonly pinned: boolean }[]
+ /** Open an entry without changing its pin state. */
+ readonly onOpen: (id: string) => void
+ /** Show (true) or hide (false) an entry. */
+ readonly onPinnedChange: (id: string, pinned: boolean) => void
+ /** Close the More menu. */
+ readonly onDismiss: () => void
+}
+```
+
+The `ui-entry-customization` menu-content component renders those fields: one row per entry (`EntryPickerRow`, whose name and pin button are separately focusable). Selecting the name calls `onDismiss` and then `onOpen`; the pin button calls `onPinnedChange`. Browse other plugins and Create your plugin follow and call `onDismiss` before acting. Each registration receives its region (used only to choose pin copy and the Creator prompt) and the two footer actions through its registration `inject`. Browse other plugins calls `ctx.pluginNavigation.openList()`; Create your plugin calls `ctx.uiWorkspace.startSession(undefined, { agentPreset: 'cordis', prompt, whenDraftExists: 'append' })` with the region's localized prompt. The call does not go through `ui-agent-preset`, so the preset chip plays no introduction animation. When no Creator preset exists, Session creation fails, Workspace shows its creation-failure notice, and no draft is created.
+
+The region decides its More button's styling, accessible name ("More", "More conversation views", and "More tools", from the regions' `panels.more`, `session.moreViews`, and `tab.guide.more` copy), Tooltip, and the menu's placement and width. Every menu uses the `ui-primitives` `Menu` component.
+
+### The three regions
+
+| | Left sidebar (`ui-sidebar`) | Conversation header (`ui-conversation`) | Right sidebar guide (`ui-sidebar-right`) |
+|---|---|---|---|
+| Entry source | Existing `panels` (from `sidebar.panellist`) | Existing View list (from `conversation.view`; Trajectory is removed while developer tools are off) | Existing tab registry `guide()` |
+| Entry id | Panel id | View id | `kind:entryId` |
+| Fixed | `plugins` | `chat` | Entries of kind `files` |
+| localStorage key | `dsh.slot.manual-order.sidebar.panellist.v1` | `dsh.slot.manual-order.conversation.view.v1` | `dsh.slot.manual-order.sidebar.right.tab.guide.list.v1` |
+| Actions slot | `sidebar.panellist.actions` | `conversation.session.header.views.actions` | `sidebar.right.tab.guide.actions` |
+| More button | Panel-button styling; shows its label when expanded and a Tooltip when collapsed | Small header button with a Tooltip | Card styling; the menu is at least as wide as the card and aligned to its end |
+| `onOpen` | `selectPanel(id)` | The Session's `selectView(id)` | Finds the entry by id, then `openTab(kind, { replaceTab: true })` |
+
+Each region defines its fixed entry in a module constant. The unpinned list is created in apply with client-store's `createSnapshotStore(…, { persist })`, is independent of Sessions, and stores `{ "unpinned": string[] }`. It reaches the region's root component through the inject `hooks.entryPins`; `setPinned` is an inject callback and ignores the fixed entry. Reads accept only an array of strings and treat any other value as an empty list, so corrupted localStorage content cannot break rendering. Ids that are no longer registered stay in `unpinned`, so an entry registered again stays hidden. Whether the actions slot has registrations reaches the root component through `hooks.entryActions`.
+
+Every localStorage key has the form `dsh.slot.manual-order..v1`, named after the list slot that holds the entries rather than after the region package: the left sidebar and the Conversation header use the existing `sidebar.panellist` and `conversation.view`. The right-sidebar guide entries come from the tab registry and have no list slot in the release, so their key uses the name reserved for one, `sidebar.right.tab.guide.list`. A later slot-level store for the manual order and pin state of a list slot reads these keys and ids directly; saved `unpinned` values need no migration, and fields added later default to empty lists when absent from saved values.
+
+Right-sidebar ids use `kind` instead of `providerId`: when an extension takes over a kind, `providerId` changes while `kind` stays the same, so persisted pin state remains valid after the takeover.
+
+## Alternatives considered
+
+**Keep pin state in a Cordis service (provided by `ui-layout` or the plugin).** A region must read pin state while drawing its own buttons, and a slot only passes data from the region to the plugin, so plugin-held state needs a new public service. A `ui-layout` service would hold state unrelated to layout; a plugin-provided service would require each region to handle the service appearing and disappearing. Region-held state needs only a few lines.
+
+**One pin service per region.** Adds three public services with different signatures, while pin state is used only by its region and that region's menu.
+
+**Add `useSlotEntries` / `useManualOrderedListSlot` to the slot framework.** Requires changing `ui-slots` and `ui-renderer`, makes `ui-renderer` hold user preferences and read and write localStorage, and requires the right sidebar to mirror its guide entries into an internal list slot. Without reordering, each region's pin logic is a few lines, which does not justify changing the framework in a release.
+
+**Drag reordering in the left sidebar.** Only the left sidebar would use it, so the three regions would behave differently; this version does not support reordering.
+
+**Make the popover a Component Factory with the More button as a local slot.** The callers are the three regions and the implementation is the plugin. Declaring the Factory in the plugin package creates a dependency cycle, because the plugin's dependencies `ui-plugin-manager` and `ui-workspace` depend on the regions. Declaring it in `ui-layout` cannot name the plugin's locale namespace, so the declaration would be split across two packages and completed through declaration merging.
+
+**Let the plugin draw the whole More control (button and menu) from region data.** The plugin would copy the three regions' button styles, because CSS Modules cannot be reused across packages, and would need layout state from each region. Button styling carries region-specific behavior and belongs to the region.
+
+**Let the plugin render the region entries.** Left-sidebar icons and right-sidebar cards depend on their regions' child slots, and the plugin cannot reach the region's `renderSlot`; React nodes also cannot be passed as props.
+
+**Stop applying pin state while the plugin is not loaded.** The only benefit is that entries hidden before the plugin was disabled or failed to load would still show. That case requires explicitly disabling a default-loaded plugin; the limitation is accepted and documented in the README.
+
+**Show the tab bar based on entries left visible by pin state.** With other Views registered, hiding all of them would remove the tab bar together with its More button, and users could not pin them again.
+
+**Publish `agentPresetNavigation`, or have `ui-agent-preset` react to `startSession` calls that carry `agentPreset` and play the introduction animation.** The first adds a service only to forward to `startSession`; the second changes the `ui-workspace` and `ui-agent-preset` interfaces, and the introduction animation is not essential to this feature.
+
+**Name localStorage keys after region packages.** A later slot-level store keyed by list slot would have to migrate saved data.
+
+## Verification
+
+- Unit tests for the three regions cover: entry buttons show only fixed or pinned entries; `setPinned` ignores the fixed entry; `setPinned` writes and persists to the region's key; corrupted localStorage content reads as an empty list; ids that are no longer registered are kept; More shows while the actions slot has registrations and passes `entries` without fixed entries and the callbacks, and is absent without registrations; the Conversation header tab bar stays hidden with only Chat and stays visible after every other View is hidden; right-sidebar ids are `kind:entryId`.
+- Unit tests for the menu-content component cover: opening an entry, toggling a pin, an empty list showing only the footer actions, the arguments of Browse other plugins and Create your plugin, and removal of the three registrations when the plugin is released.
+- The Web e2e `entry-customization.e2e.ts` exercises the left sidebar through the real Web composition: More shows by default, hiding a panel removes its button, the panel still opens from the menu, it stays hidden after a reload, and pinning it again restores the button. Recorded-session Web goldens cover the Conversation header and right-sidebar More buttons; `changed-files-turn.e2e.ts` and `document-preview.e2e.ts` assert that the compact header has no tab bar with only Chat.
+- Every changed source file has 100% per-file coverage.
+
+## Consequences
+
+- If a user hides entries and the plugin is later explicitly disabled or fails to load, the hidden entries stay hidden with no menu to restore them; re-enabling the plugin or clearing the region's localStorage key restores them.
+- localStorage is isolated by protocol, host, and port, so pin state is not shared after changing the Web port or between Web and Desktop.
+- client-store's persist does not validate restored values, so each region validates on read; the validation and the owner props type exist once per region.
+- The actions slots sit inside the More menus, so other plugins can add menu items but cannot place arbitrary controls beside the entries.
+- The right-sidebar key reserves `sidebar.right.tab.guide.list`; a later list slot for guide entries must use that name for saved pin state to carry over.
+- When an extension takes over a kind and uses different guide entry ids, existing pin state does not match the new entries.
+- With the plugin loaded by default, Web goldens that record the left navigation, the Conversation header tab bar, or the right sidebar guide include a More button.
diff --git a/.agents/notes/implemented/architecture/2026-10-14-plugin-entry-customization.zh.md b/.agents/notes/implemented/architecture/2026-10-14-plugin-entry-customization.zh.md
new file mode 100644
index 0000000000..c653292a62
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-10-14-plugin-entry-customization.zh.md
@@ -0,0 +1,136 @@
+# Agent Note: 插件入口自定义：区域自管的 Pin 与“更多”菜单
+
+Status: implemented
+
+[English](2026-10-14-plugin-entry-customization.md) | 中文
+
+## 问题
+
+`release/dsh-0.2.1` 的 Web 应用在三个区域显示插件入口：左侧栏的面板按钮（`sidebar.panellist`）、会话头部的 View 标签（`conversation.view`）和右侧栏起始页的工具卡片（右侧栏 tab 注册表的 guide 入口）。三处都按注册顺序显示全部入口，用户不能收起不常用的入口，插件越多三处越挤；用户也不能在这些位置直接浏览更多插件或开始创建插件。
+
+该功能随 `release/dsh-0.2.1` 发布，之后随 release 合回 master，因此相对 release 的改动要尽量少：不修改 slot 框架（`ui-slots`、`ui-renderer`），不新增 Cordis 服务，`ui-layout` 保持不变，client 插件包之间只共享类型（[Client 包导出规则](../../../../packages/client/AGENTS.md)）。持久化的数据要能被以后在 slot 层统一保存手动顺序与 Pin 状态的实现直接沿用。
+
+## 决策
+
+三个区域各自保存本区域被收起入口的列表并持久化，用它过滤自己的入口按钮；各自画自己的“更多”按钮，用共用的 `Menu` 组件弹出菜单，菜单里渲染本区域的 actions slot。默认加载的插件包 `ui-entry-customization` 往三个 actions slot 注册同一个菜单内容组件：入口列表与 Pin 按钮、“浏览更多插件”和“创建你的插件”。做法与插件页的“添加插件”菜单一致：页面画按钮和菜单，`ui-agent-preset` 通过 `plugins.add.actions` 往菜单里加“创建插件”。不提供排序。
+
+### 用户可见行为
+
+- 左侧栏、会话头部、右侧栏起始页各有一个“更多”按钮，打开后的菜单列出该区域可自定义的入口。点入口名称打开它；点 Pin 让它在区域里显示或收起；底部有“浏览更多插件”（打开插件页主列表）和“创建你的插件”（用 Creator 预设新开或复用空白会话，填入该区域对应的提示语，不发送）。
+- 入口按注册顺序显示，与 release 一致；不提供排序。
+- 默认绑定的入口始终显示，不进入菜单：左侧栏的插件管理、会话头部的 Chat、右侧栏的文件。
+- Pin 状态在刷新页面后保留，所有会话共用。
+- 收起当前选中的入口不会切走当前内容；左侧栏行或 View 标签在选中其他入口之前保持显示，并标为当前项。
+- 左侧栏 `` 与会话头部标签条的显示条件与 release 一致：`` 在有已注册面板时显示，标签条在注册的 View 多于一个时显示。条件按已注册的入口计算，不按 Pin 后可见的入口计算，因此只有 Chat 时不显示标签条；有其他 View 时即使全部收起，标签条和其中的“更多”仍然显示，用户可以重新固定。
+- actions slot 没有注册项时（例如 `ui-entry-customization` 未加载），区域不显示“更多”。
+
+### 结构与职责
+
+```text
+ui-sidebar / ui-conversation / ui-sidebar-right (each region)
+ apply: the region's unpinned list (createSnapshotStore + persist) and setPinned
+ whether the actions slot has registrations (entriesOfSlot + subscribe)
+ root component: draws only fixed or pinned entries
+ while the actions slot has registrations, draws the region's More button and Menu:
+
+ renderSlot('.actions', { entries, onOpen, onPinnedChange, onDismiss })
+
+
+ui-entry-customization (default-loaded)
+ registers one menu-content component into each actions slot (id 'entry-customization')
+ content: non-fixed entries with pin buttons, Browse other plugins, Create your plugin; keeps no state
+```
+
+依赖方向：三个区域不依赖插件包，只增加 `client-store` 与 `ui-primitives` 的既有用法；`ui-entry-customization` 依赖三个区域（slot 类型）、`ui-plugin-manager` 与 `ui-workspace`（服务类型），运行时通过 `ctx.pluginNavigation` 与 `ctx.uiWorkspace` 调用。各包之间不新增运行时值导入。
+
+### 各包改动（相对 release/dsh-0.2.1）
+
+| 包 | 改动 |
+|---|---|
+| `ui-sidebar` | 新增 `sidebar.panellist.actions`；apply 中新增 unpinned 列表、`setPinned` 和 actions slot 注册状态；`SidebarRoot` 过滤入口，并在 `` 末尾画“更多”按钮与菜单；展开态面板行间距由 4px 改为 2px |
+| `ui-conversation` | 新增 `conversation.session.header.views.actions`；apply 中新增同样三项；会话头部过滤 View 标签，并在标签条内、tablist 之后画“更多”按钮与菜单；View 标签间距由 36px 改为 32px，与“更多”间隔 20px |
+| `ui-sidebar-right` | 新增 `sidebar.right.tab.guide.actions`；apply 中新增同样三项；起始页过滤卡片，并在卡片之后画“更多”卡片与菜单；guide 注册声明 `sidebarRight` 文案命名空间 |
+| `ui-entry-customization`（新包） | 往三个 actions slot 注册菜单内容组件；`entryCustomization` 文案命名空间；不保存状态 |
+| `ui-plugin-manager` | `pluginNavigation` 增加 `openList()`：切到插件页主列表的“已安装”标签，不打开对话框，不改变当前会话 |
+| `ui-primitives` | `Menu` 增加 `minWidthFromAnchor`，让右侧栏菜单不窄于卡片；新增 `IconAppsAddOutlineRegular` / `IconAppsAddOutlineMedium`（`compact` 用于卡片尺寸），供左侧栏和右侧栏的按钮共用 |
+| `@deepseek-ai/dsh-web-app` | 默认加载 `ui-entry-customization` |
+
+### actions slot 与菜单内容
+
+三个 actions slot 都是 root 级 list slot，由各区域声明，渲染在本区域的“更多”菜单里，其他插件也可以往里注册菜单项，排列顺序按注册项的 `order`。owner props 由各区域在自己的 contract 中声明（`SidebarPanelActionsOwnerProps`、`ConversationViewActionsOwnerProps`、`SidebarRightGuideActionsOwnerProps`），三处字段相同，以左侧栏为例：
+
+```ts
+interface SidebarPanelActionsOwnerProps {
+ /** The region's customizable entries in registration order; fixed entries are excluded. */
+ readonly entries: readonly { readonly id: string; readonly label: string; readonly pinned: boolean }[]
+ /** Open an entry without changing its pin state. */
+ readonly onOpen: (id: string) => void
+ /** Show (true) or hide (false) an entry. */
+ readonly onPinnedChange: (id: string, pinned: boolean) => void
+ /** Close the More menu. */
+ readonly onDismiss: () => void
+}
+```
+
+`ui-entry-customization` 的菜单内容组件按上述字段渲染：每个入口一行（`EntryPickerRow`，名称与 Pin 按钮各自可聚焦），点名称先 `onDismiss` 再 `onOpen`，点 Pin 调 `onPinnedChange`；其后是“浏览更多插件”和“创建你的插件”，先 `onDismiss` 再执行。每个注册项通过 registration `inject` 得到所属区域（只用于选择 Pin 提示与创建提示语）和两个底部操作：“浏览更多插件”调用 `ctx.pluginNavigation.openList()`；“创建你的插件”调用 `ctx.uiWorkspace.startSession(undefined, { agentPreset: 'cordis', prompt, whenDraftExists: 'append' })`，`prompt` 按区域取本地化文案。该调用不经过 `ui-agent-preset`，预设标签不播放介绍动画；Creator 预设不存在时会话创建失败，Workspace 显示创建失败提示，不产生草稿。
+
+“更多”按钮的样式、无障碍名称（“更多”“更多会话视图”“更多工具”，分别来自各区域的 `panels.more`、`session.moreViews`、`tab.guide.more` 文案）、Tooltip、菜单的弹出方向与宽度都由区域决定；菜单外框统一使用 `ui-primitives` 的 `Menu`。
+
+### 三个区域
+
+| | 左侧栏（`ui-sidebar`） | 会话头部（`ui-conversation`） | 右侧栏起始页（`ui-sidebar-right`） |
+|---|---|---|---|
+| 入口来源 | 现有的 `panels`（来自 `sidebar.panellist`） | 现有的 View 列表（来自 `conversation.view`，未开启开发者工具时去掉 Trajectory） | 现有的 tab 注册表 `guide()` |
+| 入口 id | 面板 id | View id | `kind:入口id` |
+| fixed | `plugins` | `chat` | kind 为 `files` 的入口 |
+| localStorage 键 | `dsh.slot.manual-order.sidebar.panellist.v1` | `dsh.slot.manual-order.conversation.view.v1` | `dsh.slot.manual-order.sidebar.right.tab.guide.list.v1` |
+| actions slot | `sidebar.panellist.actions` | `conversation.session.header.views.actions` | `sidebar.right.tab.guide.actions` |
+| “更多”按钮 | 与面板按钮同样式；展开时显示文字，收起时显示 Tooltip | 头部样式的小按钮，带 Tooltip | 卡片样式，菜单不窄于卡片并右对齐 |
+| `onOpen` | `selectPanel(id)` | 本会话的 `selectView(id)` | 按 id 找到入口后 `openTab(kind, { replaceTab: true })` |
+
+每个区域用一个模块常量定义 fixed。unpinned 列表在 apply 中用 client-store 的 `createSnapshotStore(…, { persist })` 创建，与会话无关，值为 `{ "unpinned": string[] }`，经 inject 的 `hooks.entryPins` 交给区域根组件，`setPinned` 作为 inject 回调，对 fixed 入口不生效。读取时只接受字符串数组，其他值按空列表处理，避免损坏的 localStorage 内容影响渲染。`unpinned` 中已不存在的 id 保留，同一入口重新注册后保持收起。actions slot 是否有注册项经 `hooks.entryActions` 交给根组件。
+
+localStorage 键统一为 `dsh.slot.manual-order..v1`，按入口所在的 list slot 命名，不按区域包命名：左侧栏与会话头部使用现有的 `sidebar.panellist`、`conversation.view`；右侧栏的 guide 入口来自 tab 注册表，release 中还没有对应的 list slot，键名使用为它预留的 `sidebar.right.tab.guide.list`。以后在 slot 层统一保存同一 list slot 的手动顺序与 Pin 状态时，直接沿用这些键和 id，已保存的 `unpinned` 不需要迁移；新增的字段在旧值中缺失时按空列表处理。
+
+右侧栏 id 使用 `kind` 而不是 `providerId`：扩展接管某个 kind 时 `providerId` 会改变，`kind` 不变，持久化的 Pin 状态在接管后仍然有效。
+
+## 考虑过的替代方案
+
+**由一个 Cordis 服务保存 Pin 状态（在 `ui-layout` 或插件中提供）。** 区域画自己的按钮时要读到 Pin 状态，而 slot 只能把数据从区域传给插件；由插件保存就必须新增公开服务。放在 `ui-layout` 会让布局服务承担与布局无关的状态；由插件提供时，区域还要处理服务时有时无。区域自己保存只需几行。
+
+**三个区域各提供一个 Pin 服务。** 新增三个形态不同的公开服务，而 Pin 状态只被所在区域和它的菜单使用。
+
+**在 slot 框架中提供 `useSlotEntries` / `useManualOrderedListSlot`。** 需要修改 `ui-slots` 与 `ui-renderer`，让 `ui-renderer` 持有用户偏好并读写 localStorage，右侧栏还要在内部同步成 list slot；不提供排序时，各区域的 Pin 逻辑只有几行，不值得为 release 修改框架。
+
+**左侧栏拖动排序。** 只有左侧栏使用，三个区域的交互不一致；本版本不提供排序。
+
+**把弹出框做成 Component Factory，“更多”按钮作为局部 slot。** 调用方是三个区域，实现方是插件：Factory 声明放在插件包会形成依赖环（插件依赖的 `ui-plugin-manager`、`ui-workspace` 依赖区域），放在 `ui-layout` 又引用不到插件的文案命名空间，只能把声明拆在两个包里用声明合并补齐。
+
+**插件画整个“更多”（按钮与菜单），区域只提供数据。** 插件要复制三个区域的按钮样式（CSS Module 不能跨包复用），并从区域取得布局状态；按钮样式带有区域的业务特点，应留在各自的区域。
+
+**由插件渲染区域入口。** 左侧栏图标和右侧栏卡片依赖各自的子 slot，插件拿不到区域的 `renderSlot`；ReactNode 也不能作为 props 传递。
+
+**插件未加载时停止应用 Pin 状态。** 唯一收益是插件在用户收起入口后被禁用或加载失败时，入口仍能显示；该情形需要显式禁用默认加载的插件，接受这一限制并在 README 中说明。
+
+**按 Pin 后可见的入口数决定标签条是否显示。** 有其他 View 时全部收起后，标签条和其中的“更多”一起消失，用户无法重新固定。
+
+**公开 `agentPresetNavigation`，或让 `ui-agent-preset` 响应带 `agentPreset` 的 `startSession` 并播放介绍动画。** 前者只为转调 `startSession` 新增服务；后者要修改 `ui-workspace` 与 `ui-agent-preset` 的接口，介绍动画不是本功能的必要部分。
+
+**按区域包命名 localStorage 键。** 以后在 slot 层按 list slot 统一保存时需要迁移已保存的数据。
+
+## 验证
+
+- 三个区域的单元测试覆盖：入口按钮只显示 fixed 或未收起的入口；对 fixed 入口调用 `setPinned` 不生效；`setPinned` 写入并持久化到对应键；localStorage 内容损坏时按空列表处理；已不存在的 id 被保留；actions slot 有注册项时显示“更多”并传入不含 fixed 入口的 `entries` 与回调，没有注册项时不显示；会话头部标签条在只有 Chat 时不显示，有其他 View 时全部收起后仍然显示；右侧栏 id 为 `kind:入口id`。
+- 菜单内容组件的单元测试覆盖：入口打开、Pin 切换、空列表时只有底部操作、浏览更多插件与创建插件的调用参数，以及三个注册项在插件释放后移除。
+- Web e2e `entry-customization.e2e.ts` 通过真实 Web 组合验证左侧栏：默认显示“更多”，收起后面板按钮消失，仍可从菜单打开，刷新后保持收起，重新固定后恢复。会话头部与右侧栏的“更多”由录制会话的 Web golden 覆盖；`changed-files-turn.e2e.ts` 与 `document-preview.e2e.ts` 断言只有 Chat 时紧凑头部没有标签条。
+- 改动的源文件逐文件覆盖率 100%。
+
+## 后果
+
+- 用户收起入口后，若插件被显式禁用或加载失败，被收起的入口保持隐藏且没有菜单可以恢复；恢复方式是重新启用插件或清除对应 localStorage 键。
+- localStorage 按协议、主机和端口隔离，更换 Web 端口或在 Web 与 Desktop 之间切换时 Pin 状态不共享。
+- client-store 的 persist 读回时不校验格式，三个区域各自在读取处校验；校验逻辑与 owner props 类型在三处各有一份。
+- actions slot 位于“更多”菜单内，其他插件只能往里加菜单项，不能在入口旁放置任意控件。
+- 右侧栏的键名预留了 `sidebar.right.tab.guide.list`；以后为 guide 入口新增 list slot 时必须使用这个名称，已保存的 Pin 状态才能沿用。
+- 扩展接管某个 kind 且使用不同的 guide 入口 id 时，原有 Pin 状态无法对应到新入口。
+- 插件默认加载后，录有左侧导航、会话头部标签条或右侧栏起始页的 Web golden 都会出现“更多”按钮。
diff --git a/.agents/notes/implemented/architecture/2026-10-17-agent-controller-message-delivery.i18n.yaml b/.agents/notes/implemented/architecture/2026-10-17-agent-controller-message-delivery.i18n.yaml
deleted file mode 100644
index 9714a56a7e..0000000000
--- a/.agents/notes/implemented/architecture/2026-10-17-agent-controller-message-delivery.i18n.yaml
+++ /dev/null
@@ -1,19 +0,0 @@
-# Bilingual-pair consistency record for 2026-10-17-agent-controller-message-delivery.md (docs/i18n/README.md): per heading
-# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
-# After editing either side, bring the other along and re-record with:
-# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-10-17-agent-controller-message-delivery.md
-/agent-note-delivering-messages-from-outside-an-agent-through-the-agent-controller:
- en: 9105f8148e107f43
- zh: a160e87bb0605da4
-/agent-note-delivering-messages-from-outside-an-agent-through-the-agent-controller/problem:
- en: 5071232d9743096c
- zh: b553a626538b3466
-/agent-note-delivering-messages-from-outside-an-agent-through-the-agent-controller/decision:
- en: 1b61d351c4d2bdf1
- zh: d6f8180b30d97b34
-/agent-note-delivering-messages-from-outside-an-agent-through-the-agent-controller/alternatives-considered:
- en: acc465cfe02b624c
- zh: db1d06574f647130
-/agent-note-delivering-messages-from-outside-an-agent-through-the-agent-controller/consequences:
- en: 9d8486586d044709
- zh: 24c7249421fd2541
diff --git a/.agents/notes/implemented/architecture/2026-10-17-agent-controller-message-delivery.md b/.agents/notes/implemented/architecture/2026-10-17-agent-controller-message-delivery.md
deleted file mode 100644
index 6d1c10ad9f..0000000000
--- a/.agents/notes/implemented/architecture/2026-10-17-agent-controller-message-delivery.md
+++ /dev/null
@@ -1,51 +0,0 @@
-# Agent Note: Delivering messages from outside an Agent through the Agent controller
-
-Status: implemented
-
-English | [中文](2026-10-17-agent-controller-message-delivery.zh.md)
-
-## Problem
-
-Plugins need to decide, with Host context, whether a message someone sends may enter a Session now. The experimental forge panel must create a requested worktree before the first message reaches the Agent, and must stop a message after the Session's worktree was removed. The Host had no point for that decision. `session/prompt` appended a prompt to the Agent inbox synchronously, and the only seam every sender passes, `agent/pre-step`, runs after the inbox accepted the message and the client already showed it as sent. A pre-step rejection ends the turn without returning the message to its sender, and a queued message reaches pre-step only when its turn starts. A gate in the Web composer, tried first, had no Host context and was bypassed by every other client.
-
-## Decision
-
-The core package `dsh-agent-controller` owns how a message from outside an Agent enters its inbox. The base bundle mounts it as `ctx.agentController`, so every base-backed profile can deliver through it; `dsh-agent` and `agent-loop` keep their inbox methods unchanged.
-
-| Part | Contract |
-|---|---|
-| Entry | `ctx.agentController.deliver(agent, { mode, source, signal, prepare, beforeInsert })` prepares the content, builds the message, asks the `agent-controller/admission` waterfall for an `AdmissionDecision`, checks the sender's cancellation and that the Agent is still registered, calls `beforeInsert`, then `followup()` or `steer()`, and resolves with the message id once the message is in the inbox |
-| Sender work | `prepare` turns the sender's content into durable message content inside the Agent's delivery order; the optional `beforeInsert` runs synchronously immediately before the append, for bookkeeping that must precede the Agent's wake |
-| Listeners | Run in registration order with Agent scope filtering and receive the Agent, the message, and a signal that aborts when the sender cancels or the controller stops; return the decision of `next()` to admit, await before `next()` to hold, and return `{ kind: 'reject', reason, message, presented }` to refuse without asking later listeners; throw only when the check itself fails |
-| Delivery mode | Stays with the sender; listeners do not see it, because no admission policy depends on it |
-| Order | Messages to one Agent are prepared, decided, and appended one at a time in arrival order; a sender that cancels before the append is not admitted and stops waiting at once, even behind a held message; disposing the controller stops every message that has not entered an inbox and finishes once those deliveries settled |
-| Failures | A rejection raises `AgentAdmissionRejected`, a `HarnessError` with code `AGENT_ADMISSION_REJECTED`, with its reason and `presented`; senders recognize it by that code rather than its class and import only types from this package; a thrown listener error raises it with `agent-controller/admission-failed`, and an Agent that left the registry with `agent-controller/agent-gone`; errors from `prepare`, `beforeInsert`, `followup()`, and `steer()` pass through; no listener runs after the message entered the inbox |
-
-Only senders that deliver work on someone's behalf call `deliver()`. Messages the Agent's own machinery produces, such as job results, goal rounds, plan transitions, and question answers, keep `followup()`, `steer()`, and `inject()`: they belong to work that was already admitted. A listener must not wait for a person when the message source is unattended, such as a schedule or a webhook; it passes or refuses such a message.
-
-`presented` tells an interactive client that the refusing plugin explains the refusal in its own interface, so the client adds no generic notice.
-
-The Web Session Remote adopts the controller first. `session/prompt` resolves or resumes the Agent, acknowledges a repeated `requestId` itself, and delivers with a `prepare` that checks image input against the Session model, resolves upload receipts, and stores attachments, and a `beforeInsert` that binds the receipts to the request. It maps a refusal to `session/prompt-rejected` with `reason` and `presented`. The call stays open while a listener holds the message, and the client's cancellation stops it. The SDK server, ACP, headless runs, schedules, webhooks, and subagent prompts move to `deliver()` in later changes, each mapping a refusal to its own protocol. Until they do, a plugin that must cover them keeps an `agent/pre-step` check.
-
-Request deduplication stays in the Session Remote. It reads the Session history synchronously, and the [synchronous-read decision](2026-09-09-deprecate-synchronous-session-event-reads.md) prohibits copying such a read into new production code; the controller can take over deduplication once a projection records accepted request ids.
-
-The Web client keeps its existing echo: Enter clears the composer and shows the message at once, and a refusal reaches the client as an ordinary prompt failure, which retires the echo and restores the draft unless new text was typed meanwhile.
-
-## Alternatives considered
-
-- **An admission stage in `dsh-agent`.** `ctx.agents.admit()` with an `agent/admission` event reaches every sender as well, but it adds a delivery concern and a new extension point to the Agent core, whose contract the loop implements. A package composed in the base bundle reaches the same senders without changing that contract.
-- **A Session Remote event, or a layer inside the Session Controller.** It fits the Web path, but the Session Controller is composed only in the Web profile, so ACP, SDK, and headless senders could never reach it.
-- **`agent/pre-step`.** It covers every sender, but it runs after the inbox accepted the message and the client showed it as sent, a refusal drops the message instead of returning it, and a queued message is checked only when its turn starts.
-- **Gated, asynchronous `followup()` and `steer()`.** Every internal sender would pass listeners meant for outside input, and their callers rely on synchronous enqueueing.
-- **A composer gate in the Web client.** It has no Host context, and other clients and `ctx.conversation.send` bypass it.
-- **Appending in the innermost step, with refusals thrown.** Listeners could act once `next()` returned with the message already in the inbox, but that capability, which no listener uses, cost three special cases: a listener failure after the append could only be logged, the inbox's own refusal had to be told apart from a listener failure, and a refusal thrown from another module copy of the error class needed a structural check. A returned decision keeps the stage a pure decision, as `agent/pre-step` is; a plugin that reacts to admitted messages listens to `agent/inbox/inserted`.
-
-The liveshare proposal in PR #3854 also introduced an admission hook, for caller identity. [Peer principals](2026-10-12-peer-principal-and-remote-access.md) replaced it; this stage decides whether the Agent can take a message now, independent of who sent it.
-
-## Consequences
-
-- A listener that holds one message keeps later messages to the same Agent waiting; other Agents proceed.
-- While a listener holds a Web prompt, the client already shows its echo; a refusal then retires the echo and returns the draft.
-- `prepare` stores attachments before the decision, so a refused prompt can leave a stored attachment unreferenced.
-- Image prompts deliver inside the Session Remote's image admission chain, so a model switch waits while a listener holds an image prompt.
-- Until every outside sender adopts `deliver()`, the stage is not a complete enforcement point.
diff --git a/.agents/notes/implemented/architecture/2026-10-17-agent-controller-message-delivery.zh.md b/.agents/notes/implemented/architecture/2026-10-17-agent-controller-message-delivery.zh.md
deleted file mode 100644
index 5f5d247f7b..0000000000
--- a/.agents/notes/implemented/architecture/2026-10-17-agent-controller-message-delivery.zh.md
+++ /dev/null
@@ -1,51 +0,0 @@
-# Agent Note：经 Agent 控制器投递来自 Agent 外部的消息
-
-Status: implemented
-
-[English](2026-10-17-agent-controller-message-delivery.md) | 中文
-
-## 问题
-
-插件需要借助 Host 侧的上下文，判断别人发来的一条消息现在能否进入 Session。实验性的 forge 面板必须在第一条消息到达 Agent 之前建好所请求的工作树，并在 Session 的工作树被删除后拦下消息。Host 此前没有做这个判断的位置：`session/prompt` 同步地把提示词追加进 Agent 收件箱，而所有发送方都会经过的唯一扩展点 `agent/pre-step` 运行在收件箱接受消息、客户端已显示为已发送之后。pre-step 拒绝会结束本轮，却不会把消息退回给发送方；排队的消息也要等到它的轮次开始才会到达 pre-step。最初尝试的 Web 输入框闸门拿不到 Host 上下文，其他客户端也都会绕过它。
-
-## 决策
-
-core 包 `dsh-agent-controller` 负责来自 Agent 外部的消息如何进入其收件箱。base 组合包把它挂载为 `ctx.agentController`，因此每个基于 base 的 profile 都能经它投递；`dsh-agent` 与 `agent-loop` 的收件箱方法保持不变。
-
-| 部分 | 约定 |
-|---|---|
-| 入口 | `ctx.agentController.deliver(agent, { mode, source, signal, prepare, beforeInsert })` 准备内容、构造消息、向 `agent-controller/admission` waterfall 要一个 `AdmissionDecision`，检查发送方是否取消、Agent 是否仍在注册表中，调用 `beforeInsert`，再调用 `followup()` 或 `steer()`，消息进入收件箱后返回消息 id |
-| 发送方的工作 | `prepare` 在该 Agent 的投递顺序内把发送方的内容转成持久的消息内容；可选的 `beforeInsert` 紧挨在放入之前同步运行，用于必须先于 Agent 唤醒完成的登记 |
-| 监听器 | 按注册顺序运行，按 Agent 作用域过滤，拿到 Agent、消息和一个在发送方取消或控制器停止时中止的信号；返回 `next()` 的决定即放行，在 `next()` 前 await 即暂留，返回 `{ kind: 'reject', reason, message, presented }` 即拒绝且不再询问后面的监听器；只在检查本身执行失败时抛出异常 |
-| 投递方式 | 留在发送方，监听器看不到，因为目前没有按投递方式区分的准入策略 |
-| 顺序 | 同一个 Agent 的消息按到达顺序逐条准备、决定并放入；在放入之前取消的发送方不会被接纳，并立即结束等待，即使排在被暂留的消息之后；销毁控制器会停止所有尚未进入收件箱的消息，并在这些投递结束后才完成 |
-| 失败 | 拒绝时抛出带其 reason 与 `presented` 的 `AgentAdmissionRejected`，它是 code 为 `AGENT_ADMISSION_REJECTED` 的 `HarnessError`；发送方按这个 code 而不是按类识别拒绝，对本包只导入类型；监听器抛出异常时 reason 为 `agent-controller/admission-failed`，Agent 离开注册表时为 `agent-controller/agent-gone`；`prepare`、`beforeInsert`、`followup()` 与 `steer()` 的错误原样抛出；消息进入收件箱之后不再有监听器运行 |
-
-只有代表他人送来工作的发送方调用 `deliver()`。Agent 自身机制产生的消息，例如后台任务结果、goal 轮次、plan 切换和问题答复，继续使用 `followup()`、`steer()` 与 `inject()`：它们属于已经接纳的工作。消息来源无人值守时（例如定时任务或 webhook），监听器不得等待人来处理，只能放行或拒绝。
-
-`presented` 告诉交互式客户端，拒绝它的插件会在自己的界面里给出说明，客户端因此不再追加通用提示。
-
-Web Session Remote 首先接入控制器。`session/prompt` 自己解析或恢复 Agent、确认重复的 `requestId`，再调用投递：`prepare` 按 Session 模型检查图片输入、解析上传凭证并存储附件，`beforeInsert` 把凭证绑定到该请求。它把拒绝映射为带 `reason` 与 `presented` 的 `session/prompt-rejected`。监听器暂留消息期间调用保持未完成，客户端取消会让它停止。SDK 服务端、ACP、headless 运行、定时任务、webhook 与子代理提示词在后续改动中改用 `deliver()`，各自把拒绝映射到自己的协议。在此之前，必须覆盖它们的插件仍保留一个 `agent/pre-step` 检查。
-
-请求去重留在 Session Remote。它同步读取 Session 历史，而[同步读取决策](2026-09-09-deprecate-synchronous-session-event-reads.zh.md)禁止把这类读取复制到新的生产代码；等有投影记录已接收的请求 id 后，控制器才能接管去重。
-
-Web 客户端保留现有的回显方式：Enter 立即清空 composer 并显示消息；拒绝在客户端表现为一次普通的提示词失败，回显撤下，草稿回到 composer，除非期间已经输入了新内容。
-
-## 备选方案
-
-- **在 `dsh-agent` 里加接纳阶段。** `ctx.agents.admit()` 加 `agent/admission` 事件同样能覆盖所有发送方，但它把投递职责和一个新扩展点加进了 Agent 核心，而 Agent 的约定由循环实现。组合在 base 组合包里的独立包能覆盖同样的发送方，又不改变这项约定。
-- **Session Remote 自己的事件，或 Session Controller 内部的一层。** 它适合 Web 路径，但 Session Controller 只在 Web profile 中组合，ACP、SDK 与 headless 发送方永远无法使用它。
-- **`agent/pre-step`。** 它覆盖所有发送方，但运行在收件箱接受消息、客户端显示为已发送之后；拒绝会丢掉消息而不是退回；排队的消息要到轮次开始才会被检查。
-- **让 `followup()` 与 `steer()` 异步并经过闸门。** 每个内部发送方都会经过为外部输入准备的监听器，而它们的调用方依赖同步入队。
-- **Web 客户端的输入框闸门。** 它拿不到 Host 上下文，其他客户端和 `ctx.conversation.send` 都会绕过它。
-- **在最内层步骤放入消息，并以抛出异常表示拒绝。** 监听器能在 `next()` 返回、消息已进入收件箱之后继续执行，但这项没有监听器使用的能力带来三处特殊处理：放入之后的监听器失败只能记录日志；要把收件箱自身的拒绝与监听器失败区分开；另一个模块副本抛出的错误类需要按结构识别。返回决定让这个阶段和 `agent/pre-step` 一样只做决定；需要对已接纳消息作出反应的插件监听 `agent/inbox/inserted`。
-
-PR #3854 中的 liveshare 方案也引入过一个接纳钩子，用于调用方身份。[Peer principals](2026-10-12-peer-principal-and-remote-access.zh.md) 取代了它；本阶段判断 Agent 现在能否接收一条消息，与发送者是谁无关。
-
-## 影响
-
-- 监听器暂留一条消息时，同一 Agent 之后的消息都要等待；其他 Agent 不受影响。
-- 监听器暂留一条 Web 提示词期间，客户端已经显示其回显；随后被拒绝时，回显撤下，草稿回到 composer。
-- `prepare` 在决定之前存储附件，因此被拒绝的提示词可能留下一个无人引用的已存附件。
-- 图片提示词在 Session Remote 的图片接纳链内投递，因此监听器暂留图片提示词期间，切换模型要等待。
-- 在所有外部发送方都改用 `deliver()` 之前，这个阶段还不是完整的强制执行点。
diff --git a/.agents/notes/implemented/architecture/2026-10-19-file-drag-plugin-ownership.i18n.yaml b/.agents/notes/implemented/architecture/2026-10-19-file-drag-plugin-ownership.i18n.yaml
new file mode 100644
index 0000000000..3ebb632746
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-10-19-file-drag-plugin-ownership.i18n.yaml
@@ -0,0 +1,19 @@
+# Bilingual-pair consistency record for 2026-10-19-file-drag-plugin-ownership.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-10-19-file-drag-plugin-ownership.md
+/agent-note-file-drag-ownership-outside-the-application-layout:
+ en: 951575b08912a949
+ zh: f33e8e6bcb9240bd
+/agent-note-file-drag-ownership-outside-the-application-layout/problem:
+ en: 557edc1db9bee8d8
+ zh: 20f47c78c8b0078b
+/agent-note-file-drag-ownership-outside-the-application-layout/decision:
+ en: 1dfea60901d6e6ae
+ zh: e4fc534dbe01b0d5
+/agent-note-file-drag-ownership-outside-the-application-layout/alternatives-considered:
+ en: 571eabab132ce4c1
+ zh: b5f8207015aeb3be
+/agent-note-file-drag-ownership-outside-the-application-layout/consequences:
+ en: 56ebb7c25911fd61
+ zh: 88120d2af74785ef
diff --git a/.agents/notes/implemented/architecture/2026-10-19-file-drag-plugin-ownership.md b/.agents/notes/implemented/architecture/2026-10-19-file-drag-plugin-ownership.md
new file mode 100644
index 0000000000..5d99b5815a
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-10-19-file-drag-plugin-ownership.md
@@ -0,0 +1,25 @@
+# Agent Note: File drag ownership outside the application layout
+
+Status: implemented
+
+English | [中文](2026-10-19-file-drag-plugin-ownership.zh.md)
+
+## Problem
+
+Image dragging spans conversation images, sidebar previews, and composer drop targets. Original files must survive source unmount during a drag, and failures must remain visible after the originating panel closes. An application-root image provider puts feature state in layout and makes independent image entries depend on an undeclared React ancestor.
+
+## Decision
+
+The [file-drag plugin](../../../../packages/client/ui-file-drag/README.md) owns generic file preparation, browser transfer tokens, retained original files, desktop bridge selection, and transient failure feedback. Consumers receive preparation and error callbacks through their slot or Factory injection. The plugin registers its feedback through `shell.overlay`; layout declares the generic slot and has no image dependency. The shared image primitive owns gestures and cancellation. Images are the first consumer, while MIME naming and transport accept other files.
+
+## Alternatives considered
+
+**Root React provider.** It preserves transfer lifetime but adds image-specific assembly to the layout package and hides dependencies from slot registration. Moving the same wrapper into the renderer would move the feature coupling into another generic owner.
+
+**State on each image.** It avoids shared assembly but cannot deliver the retained file after the source unmounts or keep a late failure visible after the panel closes.
+
+**Direct browser File only.** Manual macOS Chrome 154.0.8037.93 drags of PNG and PDF fixtures produced a populated `dataTransfer.files` in trusted `dragstart`, but empty files in trusted same-page and cross-window drops. Finder received filename-only text clippings. These measured failures require the application-local token path; they do not establish behavior in untested browsers or cross-tab delivery. Desktop retains Electron native file dragging.
+
+## Consequences
+
+One plugin lifetime governs transfer state, a native source-node end listener, and drop completion. The source listener remains attached after React unmount. Independent render roots can share a transfer without sharing a React ancestor. Custom compositions must load the service and declare the feedback slot; custom image Factory registrations supply the required callbacks. Application-local browser tokens are accepted only over the composer; native Desktop files retain the full-page drop overlay. Plugin disposal removes feedback and clears retained files. Loader-backed browser scenarios cover source removal and delivery, while focused tests cover local resource authorization and cleanup failures.
diff --git a/.agents/notes/implemented/architecture/2026-10-19-file-drag-plugin-ownership.zh.md b/.agents/notes/implemented/architecture/2026-10-19-file-drag-plugin-ownership.zh.md
new file mode 100644
index 0000000000..0e361717a4
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-10-19-file-drag-plugin-ownership.zh.md
@@ -0,0 +1,25 @@
+# Agent Note: 应用布局之外的文件拖放归属
+
+Status: implemented
+
+[English](2026-10-19-file-drag-plugin-ownership.md) | 中文
+
+## Problem
+
+图片拖放跨越会话图片、侧栏预览和输入框接收区。拖动期间原始文件必须在源组件卸载后继续保留，发起操作的面板关闭后失败提示也必须可见。应用根部的图片 Provider 把功能状态放进布局，并使独立图片入口依赖未声明的 React 祖先组件。
+
+## Decision
+
+[文件拖放插件](../../../../packages/client/ui-file-drag/README.zh.md) 持有通用文件准备、浏览器传递令牌、原始文件、桌面桥接选择和临时失败提示。消费方通过 slot 或 Factory 注入接收准备及错误回调。插件通过 `shell.overlay` 注册提示，布局只声明通用插槽，不依赖图片功能。共享图片原语负责手势与取消。图片是首个调用方，MIME 命名与传输也接受其他文件。
+
+## Alternatives considered
+
+**根部 React Provider。** 它能保留传递生命周期，但会把图片专属组合放进布局包，并对 slot 注册隐藏依赖。把同一个包裹组件移到渲染器，只会把功能耦合转移到另一个通用模块。
+
+**每张图片独立持有状态。** 这能避免共享组合，却不能在源组件卸载后交付保留文件，也不能在面板关闭后继续显示延迟到达的失败提示。
+
+**仅直接传递浏览器 File。** 在 macOS Chrome 154.0.8037.93 中手动拖放 PNG 与 PDF 时，可信 `dragstart` 中 `dataTransfer.files` 有文件，同页与跨窗口的可信 drop 却收到空文件列表。Finder 收到仅含文件名的文本摘录。这些实测失败要求保留应用内令牌路径，但不能据此判定未测试浏览器或跨标签页交付的行为。Desktop 保留 Electron 原生文件拖放。
+
+## Consequences
+
+一个插件生命周期管理传递状态、源节点上的原生结束监听器与投放完成。React 卸载后，监听器仍绑定源节点。独立渲染根可以共享传递，而不共享 React 祖先组件。自定义组合必须加载服务并声明反馈插槽，自定义图片 Factory 注册提供所需回调。应用内浏览器令牌仅在输入框范围接受；Desktop 原生文件保留全页投放遮罩。插件卸载会移除提示并清除保留文件。通过 Loader 启动的浏览器场景覆盖源图移除与交付，定向测试覆盖本地资源授权和清理失败。
diff --git a/.agents/notes/implemented/architecture/2026-10-19-pi-ai-system-reminder-fallback.i18n.yaml b/.agents/notes/implemented/architecture/2026-10-19-pi-ai-system-reminder-fallback.i18n.yaml
new file mode 100644
index 0000000000..3e9350f2b3
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-10-19-pi-ai-system-reminder-fallback.i18n.yaml
@@ -0,0 +1,19 @@
+# Bilingual-pair consistency record for 2026-10-19-pi-ai-system-reminder-fallback.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-10-19-pi-ai-system-reminder-fallback.md
+/agent-note-pi-ai-system-reminder-fallback:
+ en: f43b5c6974289180
+ zh: abc0a86b1d137189
+/agent-note-pi-ai-system-reminder-fallback/problem:
+ en: 5247278483ca4e7a
+ zh: ca711671a43fae76
+/agent-note-pi-ai-system-reminder-fallback/decision:
+ en: 604eb72704c73328
+ zh: 6661d1065f65ecf9
+/agent-note-pi-ai-system-reminder-fallback/alternatives-considered:
+ en: 0e2aaf897587ebb0
+ zh: 0a7f9a9cb7ddffaf
+/agent-note-pi-ai-system-reminder-fallback/consequences:
+ en: 8a0c53289a04c64a
+ zh: 591e602eb2036a1a
diff --git a/.agents/notes/implemented/architecture/2026-10-19-pi-ai-system-reminder-fallback.md b/.agents/notes/implemented/architecture/2026-10-19-pi-ai-system-reminder-fallback.md
new file mode 100644
index 0000000000..458fdb83ca
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-10-19-pi-ai-system-reminder-fallback.md
@@ -0,0 +1,25 @@
+# Agent Note: Pi-ai system reminder fallback
+
+Status: implemented
+
+English | [中文](2026-10-19-pi-ai-system-reminder-fallback.zh.md)
+
+## Problem
+
+Pi-ai concatenates later system messages into the initial prompt for models without native mid-conversation system support. Later system messages supplied to the adapter therefore invalidate the preceding conversation cache prefix.
+
+## Decision
+
+The pi-ai adapter uses the prepared model's existing `supportsMidConvoSystemMessages` capability mapping. It preserves native system messages on capable models and converts each non-empty later system message into a user message wrapped in `` otherwise, before pi-ai receives the context. Leading system text remains in the initial prompt. Message order, repeated updates, and existing text-block concatenation remain intact. Durable messages retain their original roles.
+
+The fallback belongs to the adapter because it depends on the selected protocol capability. Prompt admission remains owned by the agent loop, which consolidates system-prompt updates on routes without native support; this fallback only handles later system messages present in the supplied request.
+
+## Alternatives considered
+
+**Let pi-ai concatenate updates.** Retains system-role priority but changes the initial prompt whenever later system text changes, defeating prefix reuse.
+
+**Advertise native support or send developer messages.** Misstates model capability or relies on another unsupported instruction role. The fallback uses ordinary user messages and does not change capability metadata.
+
+## Consequences
+
+The wrapper does not confer system-role authority, so reminders have user-role priority. Cache hits remain provider-dependent; tool changes and compaction can still invalidate prefixes. Both text-only and attachment-aware conversion apply the same fallback, and wire tests inspect the real pi-ai serializer output.
diff --git a/.agents/notes/implemented/architecture/2026-10-19-pi-ai-system-reminder-fallback.zh.md b/.agents/notes/implemented/architecture/2026-10-19-pi-ai-system-reminder-fallback.zh.md
new file mode 100644
index 0000000000..02e9ca648f
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-10-19-pi-ai-system-reminder-fallback.zh.md
@@ -0,0 +1,25 @@
+# Agent Note: Pi-ai 系统提醒回退
+
+Status: implemented
+
+[English](2026-10-19-pi-ai-system-reminder-fallback.md) | 中文
+
+## 问题
+
+对于不原生支持对话中系统消息的模型，pi-ai 会把后续系统消息拼接进初始提示词。因此，传给适配器的后续系统消息会使此前的对话缓存前缀失效。
+
+## 决策
+
+pi-ai 适配器使用已准备模型的现有 `supportsMidConvoSystemMessages` 能力映射。对于具备该能力的模型，适配器保留原生系统消息；否则，在 pi-ai 接收上下文之前，将每条非空的后续系统消息转换为以 `` 包裹的用户消息。开头的系统文本仍位于初始提示词中。消息顺序、重复更新和现有文本块拼接方式均保持不变。持久消息保留原始角色。
+
+回退由适配器负责，因为它取决于所选协议的能力。提示词纳入仍由 Agent loop 负责，它在不支持原生更新的路由上合并系统提示词更新；此回退仅处理传入请求中已有的后续系统消息。
+
+## 考虑过的替代方案
+
+**让 pi-ai 拼接更新。** 保留系统角色优先级，但后续系统文本每次变化都会改变初始提示词，破坏前缀复用。
+
+**宣称原生支持或发送 developer 消息。** 错报模型能力，或依赖另一种不受支持的指令角色。回退使用普通用户消息，不改变能力元数据。
+
+## 后果
+
+包裹文本不会赋予系统角色权限，因此提醒具有用户角色优先级。缓存命中仍取决于提供方；工具变化和压缩仍可能使前缀失效。纯文本与附件感知转换使用相同的回退，线协议测试检查真实 pi-ai 序列化器的输出。
diff --git a/.agents/notes/implemented/architecture/2026-10-20-new-session-blank-reuse-by-preset.i18n.yaml b/.agents/notes/implemented/architecture/2026-10-20-new-session-blank-reuse-by-preset.i18n.yaml
new file mode 100644
index 0000000000..edba469d43
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-10-20-new-session-blank-reuse-by-preset.i18n.yaml
@@ -0,0 +1,25 @@
+# Bilingual-pair consistency record for 2026-10-20-new-session-blank-reuse-by-preset.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-10-20-new-session-blank-reuse-by-preset.md
+/agent-note-new-session-reuses-a-blank-session-matching-a-requested-preset:
+ en: ff1fe8bacfb05cee
+ zh: b03fa775407f8aa2
+/agent-note-new-session-reuses-a-blank-session-matching-a-requested-preset/problem:
+ en: 5e6529a1ff3c1af5
+ zh: 7d08e27fd9e4ccac
+/agent-note-new-session-reuses-a-blank-session-matching-a-requested-preset/decision:
+ en: a06d2e45382320f0
+ zh: 3eb09fc03c69eced
+/agent-note-new-session-reuses-a-blank-session-matching-a-requested-preset/alternatives-considered:
+ en: 895f9dedbb6d7abf
+ zh: bb882bd3cc962ed3
+/agent-note-new-session-reuses-a-blank-session-matching-a-requested-preset/verification:
+ en: bcfd62fdd75b53c4
+ zh: 040ca441c67030c2
+/agent-note-new-session-reuses-a-blank-session-matching-a-requested-preset/consequences:
+ en: 88d1152b67ab392d
+ zh: 8c95b9fa7c1b2a04
+/agent-note-new-session-reuses-a-blank-session-matching-a-requested-preset/deferred-work:
+ en: a7a8e49adae7b4fc
+ zh: a835f0e39b981fc6
diff --git a/.agents/notes/implemented/architecture/2026-10-20-new-session-blank-reuse-by-preset.md b/.agents/notes/implemented/architecture/2026-10-20-new-session-blank-reuse-by-preset.md
new file mode 100644
index 0000000000..caece494a8
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-10-20-new-session-blank-reuse-by-preset.md
@@ -0,0 +1,51 @@
+# Agent Note: New Session reuses a blank Session, matching a requested preset
+
+Status: implemented
+
+English | [中文](2026-10-20-new-session-blank-reuse-by-preset.zh.md)
+
+## Problem
+
+In 0.2.0-rc.2, New Session (the sidebar button, the Workspace "+" button, and the shortcut, all calling `uiWorkspace.startSession` without options) reused the Workspace's first blank Session. PR #5775, first released in `dsh-v0.2.1-alpha.2`, changed it to create a fresh Session and Agent on every call, so that New Session composes the current preset definition after the user changes one instead of keeping a reused blank's earlier composition ([upgrade guide](../../../../docs/upgrade-guide/v0.2.1-alpha.1/new-session-generations/guide.md)).
+
+A blank Session that is not current is hidden from the Session tree, and New Session is the only way back to it. After that change, a user who types a draft into a blank Session, switches to another Session, and clicks New Session lands in another empty Session; the original draft stays in localStorage under the old Session id, but no control returns to it. 0.2.1-rc.2 therefore loses New Session's unsent drafts.
+
+The Creator entries (`startSession(…, { agentPreset: 'cordis', prompt, clearPreviousDraft: false })`) also reuse the first blank Session and switch it to Creator: an existing ordinary draft stays under Creator mode and the Creator prompt is not filled in, and New Session can likewise take over a Creator blank.
+
+## Decision
+
+Only the Client (`ui-workspace`) changes; the Host is unchanged:
+
+- `startSession` without options takes the reuse path again and follows the same rule as `openWorkspace`, `connectWorkspace`, and `startSession` with options.
+- `createInWorkspace` names the first unstarted, unarchived blank Session that is still a Workspace member. A request that names a preset skips a blank whose listed preset (`projectionValues.agentPreset`) is a different one, while a blank with no listed preset remains eligible; a request without a preset may name any blank, which the Host switches to its default preset. The Host creates a Session when no blank is eligible.
+
+As a result, New Session returns to the original blank Session with its unsent draft, and preset flows such as the Creator entries do not take over a blank that lists another preset, so an ordinary draft is not moved under Creator. No persisted state is added, and the Client does not read the preset roster.
+
+## Alternatives considered
+
+**Revert the PR #5775 change completely, reusing the first blank for every request.** Drafts come back, but preset flows such as the Creator entries take over the blank holding the user's ordinary draft, switch it to Creator, keep the draft there, and cannot fill in their prompt.
+
+**Keep creating a fresh Session and move the abandoned blank's draft into it.** This needs rules for which blank to move from when several exist, how to treat attachments, and whether to archive the old Session, which is more change and state than reusing blanks.
+
+**Let a request without a preset reuse only a blank of the Host default preset.** The Client does not know the default preset and would have to request the `agentPresets.list()` roster.
+
+**Record a persisted source-to-blank-Session map in the Client.** It duplicates the preset each blank already records and must handle stale entries and per-origin isolation.
+
+**Clear the existing draft in place when the preset changes (`clearPreviousDraft: true`).** It deletes a draft the user was writing in the other mode.
+
+**Also change the Host to always call `presets.select` when reusing a loaded blank.** It fully keeps #5775's goal but is outside this Client-only fix; see Deferred work.
+
+## Verification
+
+- `ui-workspace` unit tests: New Session without options returns to the existing blank; a request without a preset reuses any blank, a request with a preset reuses only a blank listing the same preset, and a new Session is created when none matches. `navigation.ts` has 100% per-file coverage.
+- Regression localization: the same unit probe on the PR #5775 commit that made this change and on its parent, plus a browser reproduction on builds of both, confirmed that the draft loss comes from that change.
+
+## Consequences
+
+- New Session no longer guarantees the current preset definition: a reused blank whose Agent is still loaded in the Host with the same preset id keeps its creation-time composition; a blank resumed after a Host restart composes the current definition.
+- New Session may reuse a blank left by a preset flow such as the Creator entries; the Host switches it back to the default preset and its draft stays.
+- The [new-session-blank-reuse](../../../../docs/upgrade-guide/v0.2.1-rc.2/new-session-blank-reuse/guide.md) upgrade guide records the change relative to 0.2.1-rc.2.
+
+## Deferred work
+
+- Host `reuseLive` (`packages/api/session-controller/src/agent.ts`) returns the loaded Agent unchanged when the preset id matches and does not call `presets.select`. `select` decides whether a definition was registered again by comparing `Generation` objects: when they are the same it does nothing; when they differ it recomposes under the same Session id with the current definition and records `agent-preset/selected`; on a started Session it throws `agent-preset/locked`, and the caller creates a new Session instead. Removing the `target === current` early return and always calling `select` keeps drafts while meeting #5775's goal that New Session composes the current definition; it needs a Host test, and updates to the `reuseLive` JSDoc and to the upgrade guide's statement that the current preset definition is no longer guaranteed.
diff --git a/.agents/notes/implemented/architecture/2026-10-20-new-session-blank-reuse-by-preset.zh.md b/.agents/notes/implemented/architecture/2026-10-20-new-session-blank-reuse-by-preset.zh.md
new file mode 100644
index 0000000000..3c85abb713
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-10-20-new-session-blank-reuse-by-preset.zh.md
@@ -0,0 +1,51 @@
+# Agent Note: 新会话复用空白会话，指定预设时按预设匹配
+
+Status: implemented
+
+[English](2026-10-20-new-session-blank-reuse-by-preset.md) | 中文
+
+## 问题
+
+0.2.0-rc.2 中，新会话（左侧栏按钮、工作区“+”和快捷键，均调用不带选项的 `uiWorkspace.startSession`）复用工作区内第一个空白会话。PR #5775（首次发布于 `dsh-v0.2.1-alpha.2`）改为每次新建 Session 与 Agent，目的是在用户修改预设定义后，新会话按当前定义装配，而不是沿用复用空白会话的旧装配（[升级指南](../../../../docs/upgrade-guide/v0.2.1-alpha.1/new-session-generations/guide.zh.md)）。
+
+空白会话不是当前会话时不在 Session 树中显示，返回它的唯一入口是新会话。改为每次新建后，用户在空白会话中写下草稿、切到其他会话再点新会话，会进入另一个空的 Session；原草稿仍按会话 id 保存在 localStorage，但没有界面入口可以回到它。0.2.1-rc.2 因此丢失新会话的未发送草稿。
+
+此外，创造模式入口（`startSession(…, { agentPreset: 'cordis', prompt, clearPreviousDraft: false })`）复用第一个空白会话并把它切换到 Creator：已有普通草稿时，草稿留在 Creator 模式下，Creator 提示语不会填入；反之新会话也可能接管 Creator 的空白会话。
+
+## 决策
+
+只修改前端（`ui-workspace`），Host 不变：
+
+- 不带选项的 `startSession` 重新走复用分支，与 `openWorkspace`、`connectWorkspace` 和带选项的 `startSession` 使用同一规则。
+- `createInWorkspace` 在未开始、未归档、仍属于该工作区的空白会话中选第一个。请求指明预设时，跳过列出的预设（`projectionValues.agentPreset`）为其他值的空白会话，未列出预设的空白会话仍可用；请求未指明预设时任何空白会话都可用，由 Host 切换到默认预设。没有可用的空白会话时由 Host 新建。
+
+结果：新会话回到原来的空白会话，未发送的草稿保留；创造模式等预设流程不会接管列出其他预设的空白会话，用户的普通草稿不会被切到 Creator 下。不新增持久化状态，前端也不读取预设名单。
+
+## 考虑过的替代方案
+
+**完全回退 PR #5775 的这项改动，所有请求都复用第一个空白会话。** 草稿可以回来，但创造模式等预设流程会接管用户普通草稿所在的空白会话，把它切到 Creator，草稿留在 Creator 下，提示语也填不进去。
+
+**保持每次新建，把被丢下的空白会话中的草稿迁移到新会话。** 需要定义多个空白会话时迁移哪一个、附件如何处理、旧会话是否归档，改动和状态都比按预设复用多。
+
+**未指明预设的请求只复用 Host 默认预设的空白会话。** 前端不知道默认预设，需要额外请求 `agentPresets.list()` 名单。
+
+**在前端记录“来源 → 空白会话 id”的映射并持久化。** 与空白会话自身记录的预设重复，需要处理映射过期、按浏览器 origin 隔离等问题。
+
+**预设变化时在原会话上清空草稿（`clearPreviousDraft: true`）。** 会删除用户在另一种模式下写到一半的草稿。
+
+**同时修改 Host，让复用内存中的空白会话时总是调用 `presets.select`。** 能完整保留 #5775 的目的，但不在本次只修前端的范围内，见“推迟工作”。
+
+## 验证
+
+- `ui-workspace` 单元测试：不带选项的新会话回到已有空白会话；未指明预设时复用任何空白会话，指明预设时只复用列出相同预设的空白会话，没有时新建。`navigation.ts` 逐文件覆盖率 100%。
+- 回归定位：在 PR #5775 中做出这项改动的提交及其父提交上运行同一单元探针，以及在两侧构建上用浏览器复现，确认草稿丢失由该改动引入。
+
+## 后果
+
+- 新会话不再保证使用当前预设定义：复用的空白会话若其 Agent 仍在 Host 内存中且预设 id 相同，沿用创建时的装配；Host 重启后恢复的空白会话按当前定义装配。
+- 新会话可能复用创造模式等预设流程留下的空白会话，Host 把它切回默认预设，其中的草稿保留。
+- 升级指南 [new-session-blank-reuse](../../../../docs/upgrade-guide/v0.2.1-rc.2/new-session-blank-reuse/guide.zh.md) 记录相对 0.2.1-rc.2 的行为变化。
+
+## 推迟工作
+
+- Host `reuseLive`（`packages/api/session-controller/src/agent.ts`）在预设 id 相同时直接返回内存中的 Agent，不调用 `presets.select`。`select` 用定义的 `Generation` 对象是否相同判断定义是否重新注册过：相同则不做任何事；不同则在同一会话 id 上按当前定义重新装配并记录 `agent-preset/selected`；会话已开始时抛出 `agent-preset/locked`，调用方改为新建。去掉 `target === current` 的提前返回、改为总是调用 `select`，可以在保留草稿的同时满足 #5775“新会话按当前定义装配”的目的；需要配套 Host 测试，并更新 `reuseLive` 的 JSDoc 和上述升级指南中“不再保证当前预设定义”的说明。
diff --git a/.agents/notes/implemented/architecture/2026-10-21-when-access.i18n.yaml b/.agents/notes/implemented/architecture/2026-10-21-when-access.i18n.yaml
new file mode 100644
index 0000000000..2a74d80a3d
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-10-21-when-access.i18n.yaml
@@ -0,0 +1,28 @@
+# Bilingual-pair consistency record for 2026-10-21-when-access.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-10-21-when-access.md
+/agent-note-whenaccess-registration-that-follows-access:
+ en: 2ef7cfef514c138a
+ zh: 064e3aecbfafcd9c
+/agent-note-whenaccess-registration-that-follows-access/problem:
+ en: 4f88d3ee7868eaa5
+ zh: 72a4ce2dde13bef7
+/agent-note-whenaccess-registration-that-follows-access/decision:
+ en: a15c7c13f167e5ac
+ zh: 63bcc2ef60c2f344
+/agent-note-whenaccess-registration-that-follows-access/decision/whenaccess:
+ en: c168de20989cf9a4
+ zh: bf3b0361beea083d
+/agent-note-whenaccess-registration-that-follows-access/decision/plugin-migration:
+ en: 73577ed282c656f3
+ zh: 2f60a6824218e693
+/agent-note-whenaccess-registration-that-follows-access/alternatives-considered:
+ en: ddc432b693608163
+ zh: 620294d8812b0a31
+/agent-note-whenaccess-registration-that-follows-access/consequences:
+ en: de44fa92c49bc335
+ zh: 34436fe971ab013f
+/agent-note-whenaccess-registration-that-follows-access/related:
+ en: 89073ffbfcff0641
+ zh: 736a180d13a08981
diff --git a/.agents/notes/implemented/architecture/2026-10-21-when-access.md b/.agents/notes/implemented/architecture/2026-10-21-when-access.md
new file mode 100644
index 0000000000..5936accdf5
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-10-21-when-access.md
@@ -0,0 +1,88 @@
+# Agent Note: whenAccess registration that follows access
+
+Status: implemented
+
+English | [中文](2026-10-21-when-access.zh.md)
+
+## Problem
+
+Client plugins need to switch their own registrations on and off with the current Peer's access: sidebar entries, main panels, overlays, and data streams. The existing Client access surface covers only rendering:
+
+| Where | Existing capability | Gap |
+|---|---|---|
+| Components | `useRemoteAccess(action)` (global), `useSessionAccess(sessionId, action)`, `useWorkspaceAccess(workspaceId, action)`, and the Session-scope `useAccess(action)` | Readable only during render; a changed answer re-renders automatically |
+| JS (`apply`, services) | `ctx.remoteAccess.source(kind, id, action)` returns a `HostObservable` | A plugin must read `getSnapshot` and subscribe to changes itself, then register and dispose by hand |
+
+Without a JS entry point, a plugin can only decide its registrations once by identity at `apply`, and they do not follow an access change.
+
+## Decision
+
+### whenAccess
+
+The JS side has a `whenAccess` for each of the three access Hooks, from the package that publishes that Hook:
+
+| Interface | Provider | Matching Hook |
+|---|---|---|
+| `ctx.remoteAccess.whenAccess(action, callback)` | remote-access | `useRemoteAccess(action)` |
+| `ctx.uiSession.whenAccess(sessionId, action, callback)` | ui-session | `useSessionAccess(sessionId, action)` |
+| `ctx.uiWorkspace.whenAccess(workspaceId, action, callback)` | ui-workspace | `useWorkspaceAccess(workspaceId, action)` |
+
+```ts ignore-check
+import type { AccessEffect, RemoteEndpoint } from '@deepseek-ai/dsh-api-remote-access/client'
+
+/** The global-resource member; the Session and Workspace versions take the resource id first. */
+export interface WhenAccess {
+ /**
+ * Keep `callback`'s effects installed while the current Peer may call `action`
+ * on the resource: run it when the answer becomes true, dispose its effects in
+ * reverse order when it becomes false, and run it again on the next true.
+ * @returns disposer for the observation and any installed effects.
+ */
+ whenAccess(action: RemoteEndpoint, callback: () => AccessEffect): () => void
+}
+```
+
+`AccessEffect` is `(() => void) | Iterable<() => void, void, void>`.
+
+| Rule | Content |
+|---|---|
+| Semantics | Same as `ctx.slots.inject`: the callback returns one disposer or an iterable of disposers; an iterable installs as one transaction and disposes in reverse order; the controller belongs to the caller's fiber and disposes when the plugin unloads |
+| Synchronous run | When the answer is already true, the callback runs synchronously; the owner's answer is always true, so registration order matches direct registration |
+| Stream failure | A non-owner's answer turns false and the installed effects dispose |
+| Callback failure | A setup failure at the call throws synchronously; a setup failure on a later grant stops the controller and is rethrown in a microtask |
+| Layering | remote-access knows only `global`; the Session and Workspace versions are built over remote-access's lower-level `whenResourceAccess(kind, id, action, callback)`, as their Hooks are built over `source(kind, id, action)`. Only the package that owns a resource kind calls `source` and `whenResourceAccess`; other plugins use only the access Hooks and `whenAccess` and pass no kind. All four entry points share [`when-allowed.ts`](../../../../packages/api/remote-access/src/client/when-allowed.ts) |
+
+### Plugin migration
+
+| Plugin | Change | Action |
+|---|---|---|
+| ui-schedule | The task catalog source, delete toast overlay, right-sidebar task tab and title, main panel, sidebar entry, turn-tail card, Session-header reminder catalog, and Session row mark and hover list move into `remoteAccess.whenAccess`; the Session-header catalog reads the per-Session `schedule.list`, so its component also decides through the Session-scope `useAccess` whether to render; the task tab type and the turn definition stay registered outside | `schedule/catalog`, `schedule/list` |
+| ui-plugin-manager | Host change subscriptions, refresh toast overlay, main panel (including `pluginNavigation`), and sidebar entry move into `remoteAccess.whenAccess`, and each grant refreshes a list already loaded; the controller and `pluginChanges` stay outside, and `pluginChanges` receives no updates while access is withdrawn. ui-entry-customization and voice-input use `pluginNavigation` optionally: without the service they hide the browse-plugins and open/details buttons and still start | `pluginManager/listBundles` |
+| ui-settings-general | The settings shell `sidebar.settings` and the `settings.open` shortcut move into `remoteAccess.whenAccess` | `settings/describe` |
+| ui-settings-account | The account state stream (including default model initialization), quota notice, settings launcher, account settings section, and `settings.models.sign-in` move into `remoteAccess.whenAccess`. On revocation the stream's disposer synchronously invalidates the account reads this grant started, closes the pending authorization tab, clears the account view, details, picture, and sign-in dialog state, ends this generation's bonus notices, which a frame of that stream begins, and then closes the stream; a frame delivered before the revocation but not yet handled is dropped. The notice controller stays outside and begins again under the next grant; the account section appears once the new stream's first frame arrives | `account/watch` |
+| ui-directory-picker-native | Both directory flows move into `remoteAccess.whenAccess` | `directoryPicker/pick` |
+| ui-message-feedback | The message feedback buttons stay registered and the component decides whether to render through the Session-scope `useAccess`; `messageFeedback/*` requests carry `sessionId`, which the Gateway resolves to that Session through the `session` resource's default field, so they declare nothing. The `/feedback` decoration has no Client check: the decoration registry is global while `sessionFeedback/record` is decided per Session, so without access the dialog still opens and the Host refuses the submission, which the dialog reports with its failure code | `messageFeedback/put` |
+| ui-deliverables, ui-open-in-app | Unchanged: an owner-only HTTP route that cannot be read falls back as before | — |
+
+## Alternatives considered
+
+**Return after an owner check at the start of `apply` (the #6486 approach)**: fixed on identity; does not follow an access change.
+
+**Trim the plugin list per connection**: a plugin cannot reload at once when access changes.
+
+**Declare access in the plugin package manifest**: defines an access-control concept in the package manifest.
+
+**One generic method with a resource parameter, or all three versions on remote-access**: business code would pass a kind, and remote-access would name the Session and Workspace resource kinds.
+
+## Consequences
+
+| Consequence | Note |
+|---|---|
+| Registrations follow access changes | Without a grant, a migrated plugin registers none of the corresponding entries for a non-owner; they appear after a grant and disappear after a revocation; the owner's answer is always true, so its registrations match direct registration |
+| The callback must hand back disposers | An effect registered through the plugin's `ctx` inside the callback also hangs on the plugin fiber; a registration whose disposer is not yielded does not dispose on access loss, only when the plugin unloads |
+| Readers receive all plugin code | Plugins load as before; the Gateway decides each call, and `whenAccess` and the Hooks control the UI |
+| Test stand-ins | [`dsh-client-test-runtime`](../../../../packages/test-support/client-runtime/README.md) replaces remote-access with fixed answers through `StaticRemoteAccess`, `staticAccessPlugin`, and `TestClientOptions.access`, so plugin specs cover the refused path |
+
+## Related
+
+- [Peer, principal, and remote access](2026-10-12-peer-principal-and-remote-access.md): this Note extends its Client access face.
diff --git a/.agents/notes/implemented/architecture/2026-10-21-when-access.zh.md b/.agents/notes/implemented/architecture/2026-10-21-when-access.zh.md
new file mode 100644
index 0000000000..242be55f65
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-10-21-when-access.zh.md
@@ -0,0 +1,88 @@
+# Agent Note: 按访问状态注册的 whenAccess
+
+Status: implemented
+
+[English](2026-10-21-when-access.md) | 中文
+
+## 问题
+
+Client 插件需要按当前 Peer 的访问状态开关自己的注册：侧栏入口、主面板、浮层、数据流。现有 Client 访问面只覆盖渲染：
+
+| 位置 | 现有能力 | 缺口 |
+|---|---|---|
+| 组件 | `useRemoteAccess(action)`（global）、`useSessionAccess(sessionId, action)`、`useWorkspaceAccess(workspaceId, action)`、会话作用域的 `useAccess(action)` | 只能在渲染时读，答案变化时自动重渲染 |
+| JS（`apply`、服务） | `ctx.remoteAccess.source(kind, id, action)` 返回 `HostObservable` | 插件要自己读 `getSnapshot`、订阅变化，再手动注册与撤销 |
+
+没有 JS 侧入口时，插件只能在 `apply` 时按身份一次性决定注册与否，授权变化后注册不跟随。
+
+## 决策
+
+### whenAccess
+
+JS 侧有与三个访问 Hook 一一对应的 `whenAccess`，由各自 Hook 的发布者提供：
+
+| 接口 | 提供者 | 对应 Hook |
+|---|---|---|
+| `ctx.remoteAccess.whenAccess(action, callback)` | remote-access | `useRemoteAccess(action)` |
+| `ctx.uiSession.whenAccess(sessionId, action, callback)` | ui-session | `useSessionAccess(sessionId, action)` |
+| `ctx.uiWorkspace.whenAccess(workspaceId, action, callback)` | ui-workspace | `useWorkspaceAccess(workspaceId, action)` |
+
+```ts ignore-check
+import type { AccessEffect, RemoteEndpoint } from '@deepseek-ai/dsh-api-remote-access/client'
+
+/** The global-resource member; the Session and Workspace versions take the resource id first. */
+export interface WhenAccess {
+ /**
+ * Keep `callback`'s effects installed while the current Peer may call `action`
+ * on the resource: run it when the answer becomes true, dispose its effects in
+ * reverse order when it becomes false, and run it again on the next true.
+ * @returns disposer for the observation and any installed effects.
+ */
+ whenAccess(action: RemoteEndpoint, callback: () => AccessEffect): () => void
+}
+```
+
+`AccessEffect` 为 `(() => void) | Iterable<() => void, void, void>`。
+
+| 规则 | 内容 |
+|---|---|
+| 语义 | 与 `ctx.slots.inject` 相同：回调返回一个 disposer 或一组 disposer；一组时按事务安装、逆序撤销；控制器属于调用方 fiber，插件卸载时撤销 |
+| 同步执行 | 调用时答案为 true 则回调同步执行；owner 的答案恒为 true，注册顺序与直接注册相同 |
+| 快照流失败 | 非 owner 的答案变为 false，已安装的效果撤销 |
+| 回调失败 | 调用时安装失败同步抛出；之后重新授权时安装失败，控制器停止并在微任务中抛出 |
+| 分层 | remote-access 只认识 global；会话版与工作区版经 remote-access 的底层方法 `whenResourceAccess(kind, id, action, callback)` 实现，与它们用 `source(kind, id, action)` 构造 Hook 相同。`source` 与 `whenResourceAccess` 只由拥有该资源种类的包调用，其他插件只用访问 Hook 与 `whenAccess`，不传 kind。四个入口共用 [`when-allowed.ts`](../../../../packages/api/remote-access/src/client/when-allowed.ts) |
+
+### 插件迁移
+
+| 插件 | 改法 | action |
+|---|---|---|
+| ui-schedule | 任务列表数据源、删除提示浮层、右栏任务 tab 与标题、主面板、侧栏入口、turn 尾部卡片、会话头部提醒、会话行标记与悬浮列表包进 `remoteAccess.whenAccess`；会话头部提醒读取按会话判定的 `schedule.list`，组件另在会话作用域里用 `useAccess` 决定是否渲染；任务 tab 类型与 turn 定义的注册留在外面 | `schedule/catalog`、`schedule/list` |
+| ui-plugin-manager | Host 变更订阅、刷新提示浮层、主面板（含 `pluginNavigation`）、侧栏入口包进 `remoteAccess.whenAccess`，每次授权时刷新已加载过的列表；controller 与 `pluginChanges` 留在外面，撤权期间 `pluginChanges` 不更新。依赖 `pluginNavigation` 的 ui-entry-customization 与 voice-input 改为可选使用：服务不在时隐藏「浏览插件」与「打开 / 查看详情」按钮，插件照常启动 | `pluginManager/listBundles` |
+| ui-settings-general | 设置外壳 `sidebar.settings` 与 `settings.open` 快捷键包进 `remoteAccess.whenAccess` | `settings/describe` |
+| ui-settings-account | 账号状态流（含默认模型初始化）、额度提醒、设置启动器、账号设置分区与 `settings.models.sign-in` 包进 `remoteAccess.whenAccess`。撤权时账号流的 disposer 同步作废这一轮发出的账号读取，关闭待授权的浏览器标签页，清空账号视图、详情、头像与登录对话框状态，结束本轮奖励提示（提示由该流的帧开始），再关闭流；撤权前已交付但尚未处理的帧被丢弃。提示控制器留在外面，下次授权时重新开始；账号分区等新流的第一帧到达后才出现 | `account/watch` |
+| ui-directory-picker-native | 两个目录选择流程包进 `remoteAccess.whenAccess` | `directoryPicker/pick` |
+| ui-message-feedback | 消息反馈按钮照常注册，组件在会话作用域里用 `useAccess` 判断是否渲染；`messageFeedback/*` 的请求带 `sessionId`，Gateway 按 `session` 资源的默认字段自动解析为该 Session，无需声明。`/feedback` 装饰不做前端判断：装饰注册表是全局的，而 `sessionFeedback/record` 按会话判定；没有权限时对话框照常打开，提交被 Host 拒绝并显示失败码 | `messageFeedback/put` |
+| ui-deliverables、ui-open-in-app | 不动：owner 专用 HTTP 路由读不到时走已有回退 | — |
+
+## 考虑过的替代方案
+
+**插件 `apply` 开头判断 owner 后 return（#6486 的做法）**：按身份写死，授权变化后不跟随。
+
+**按连接裁剪插件列表**：授权变化后插件无法立即重新加载。
+
+**插件包清单声明访问性**：在包清单上定义访问控制概念。
+
+**一个带资源参数的通用方法，或三个版本都挂在 remote-access 上**：业务代码要传 kind，且 remote-access 会出现会话、工作区的资源种类名。
+
+## 后果
+
+| 后果 | 说明 |
+|---|---|
+| 注册跟随授权变化 | 迁移的插件在非 owner 无授权时不注册相应入口，授予后出现，撤销后消失；owner 的答案恒为 true，注册与直接注册相同 |
+| 回调必须交还 disposer | 回调里经插件 `ctx` 注册的效果也挂在插件 fiber 上；不 yield 其 disposer 的注册在失权时不会撤销，只在插件卸载时撤销 |
+| 读者拿到全部插件代码 | 插件照常加载；访问由 Gateway 逐次判定，界面由 `whenAccess` 与 Hook 控制 |
+| 测试替身 | [`dsh-client-test-runtime`](../../../../packages/test-support/client-runtime/README.zh.md) 的 `StaticRemoteAccess`、`staticAccessPlugin` 与 `TestClientOptions.access` 以固定答案替换 remote-access，供插件测试无权限路径 |
+
+## 相关
+
+- [Peer、principal 与 remote-access](2026-10-12-peer-principal-and-remote-access.zh.md)：本 Note 扩展其 Client 访问面。
diff --git a/.agents/notes/implemented/bug-fix/2026-09-17-multiline-display-dollar-math.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-17-multiline-display-dollar-math.i18n.yaml
new file mode 100644
index 0000000000..e17980cb32
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-17-multiline-display-dollar-math.i18n.yaml
@@ -0,0 +1,22 @@
+# Bilingual-pair consistency record for 2026-09-17-multiline-display-dollar-math.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-09-17-multiline-display-dollar-math.md
+/agent-note-multi-line-display-dollar-math:
+ en: 8f57c77aa43fbd6c
+ zh: ef5192184e4923d5
+/agent-note-multi-line-display-dollar-math/problem:
+ en: e4b73644a982844c
+ zh: 48f86358242d6ccc
+/agent-note-multi-line-display-dollar-math/decision:
+ en: d6b136b1f62285b7
+ zh: aba323bfdb800162
+/agent-note-multi-line-display-dollar-math/alternatives-considered:
+ en: e0833b5674e648e7
+ zh: b0472020b07099b9
+/agent-note-multi-line-display-dollar-math/consequences:
+ en: 70f16597bd640e93
+ zh: 0e0c9005f331e514
+/agent-note-multi-line-display-dollar-math/testing:
+ en: f17a1453df91ce88
+ zh: 4f15be0139e8b694
diff --git a/.agents/notes/implemented/bug-fix/2026-09-17-multiline-display-dollar-math.md b/.agents/notes/implemented/bug-fix/2026-09-17-multiline-display-dollar-math.md
new file mode 100644
index 0000000000..0362895314
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-17-multiline-display-dollar-math.md
@@ -0,0 +1,66 @@
+# Agent Note: Multi-line display-dollar math
+
+Status: implemented
+
+English | [中文](2026-09-17-multiline-display-dollar-math.zh.md)
+
+## Problem
+
+Authors and models write `$$` display math in three shapes. The settled grammar rendered two of them: `$$math$$` on one line, and an opening `$$` alone on its line closed by `$$` alone on its line. The third shape — math on the opening line, a closing `$$` at the end of the last math line — did not:
+
+```markdown
+$$f(x)=x
+\text{continued}$$
+```
+
+`micromark-extension-math` treats text after an opening `$$` as fence meta and accepts a closing fence only on a line whose content is exactly `$$` (after optional whitespace). The [markdown compatibility layer](../../archived/feature/2026-07-23-web-assistant-markdown.md) claimed only the same-line shape, and the settled renderer passes `node.value` to KaTeX while ignoring `node.meta`. The block therefore never closed: it consumed the document text that followed, `value` retained the literal `$$`, KaTeX raised `Can't use function '$' in math mode`, and [katex.tsx](../../../../packages/client/ui-primitives/src/markdown/katex.tsx)'s error arm painted the TeX source plus the swallowed prose in red.
+
+In the session that surfaced this, one chat reply lost lines 22–55 of 55 to a single error span, and six note files lost every line after such a block (up to 500 lines) to one. A second defect shared the mechanism: when a later lone `$$` did close the flow, the opening line had already been assigned to `meta`, so the renderer silently dropped the first line of the formula.
+
+## Decision
+
+[mathCompatibility.ts](../../../../packages/client/ui-primitives/src/markdown/mathCompatibility.ts) gains multi-line display-dollar blocks. Its dollar construct keeps the opening line's text in `mathFlowValue` instead of fence meta and closes at a trailing `$$` on any later content line, so `$$a+b` continued by `c+d$$` becomes one math node.
+
+A `$$` sequence that fails to close ends the candidate: immediately on a later line, and at that line's ending on the opening line (`$$x$$ trailing` fails there). Within the opening line the scan continues, so a later `$$` there still closes (`$$\verb*a$$a$$`). Scanning past either point would consume a later block's closing fence. A solitary `$` is content rather than a failed fence, so a formula that uses one — `$$P = \begin{cases} 1 & \text{if $x>0$} \end{cases}$$` — keeps the block open and closes normally wherever this flow owns the block. A trailing backslash escapes the line ending, not the next line's first character, so the escape run ends at the line ending instead of reaching into the next candidate. An unescaped `%` starts a TeX comment that runs to the line ending, so a `$$` at the end of a later line closes nothing when the comment holds text before it. A `%` whose text before the fence is empty or whitespace (`95%$$`, `95 %$$`) holds no comment text, and a block that opens and closes on one line keeps closing at that line's `$$`, as it did before this flow spanned lines. That state and its gate on the closing check belong to the dollar flow. The characters right after `\verb` or `\verb*` are that command's delimiter rather than a fence, so the delimiter and, when the region is empty, the `$` closing it are content; that tail is cleared at a line ending and after an escaped backslash (`\\verb` is a line break followed by letters), and a comment holds no commands. Otherwise verbatim regions are not parsed, which keeps `\verb`-bearing formulas on the same value path as every other input.
+
+Its paragraph-interruption check declines instead of consuming the line ending, for the dollar construct only. Consuming it there keeps the paragraph open across the line boundary, so the document layer keeps the container and counts the next line lazy for every construct tried afterwards; that made upstream's `mathFlow`, the construct tried after this one, end empty inside a list item. Declining also leaves the interruption decision to that upstream flow, whose own check short-circuits without consuming and claims only the fences it accepts, so a candidate neither construct accepts (`**before` followed by `$$a\$b`) leaves its paragraph intact. The backslash construct has no competing upstream construct and keeps consuming there.
+
+[parse.ts](../../../../packages/client/ui-primitives/src/markdown/parse.ts) registers `mathCompatibility()` after `math()`: micromark dispatches the extension registered last first, so the dollar flow above takes precedence over upstream's `mathFlow` while `math()` still owns inline `$…$`.
+
+## Alternatives considered
+
+**Keep the compatibility layer at same-line `$$…$$`.** The multi-line shape is what GitHub, KaTeX's auto-render, VS Code, and Typora accept, and the form models emit for multi-case formulas; leaving it unparsed means a red error span in place of the formula plus the rest of the document.
+
+**Repair the parsed tree afterwards.** The flow consumes the swallowed text into `mathFlowValue`, where it is indistinguishable from math source; `meta` and `value` cannot be reassembled into the intended block, and the following blocks were never parsed at all.
+
+**Rewrite `$$` fences in the source text before parsing.** The compatibility layer is a grammar extension by design; a text pass would need to locate code spans, fences, and escapes itself, and would change author text rather than parse it.
+
+**Continue the dollar flow after a failed close.** That is what a plain `multiline` flag produces: `$$x$$ trailing\n\n$$y$$` then scans to the second block's `$$` and renders one math node holding both lines' text, where upstream inline math renders `x`, the prose, and `y` separately. Existing behavior for `$$x$$ trailing` already pinned the fallback, so the flow declines the candidate instead. Declining on any `$` rather than a full `$$` sequence also broke formulas that use a solitary `$` inside `\text{}`.
+
+**End the attempt as soon as one line resists parsing.** Declining every failed same-line close swallows nothing but turns `$$a$b` lines into a quadratic scan and drops the solitary-`$` formulas above. The condition is the full `$$` sequence, not the character.
+
+**Claim the paragraph interruption in the check.** Returning success there, as upstream's flow does for the fences it accepts, prevents the lazy bookkeeping that broke the list case, but it also ends the paragraph for candidates that later fail (`**before\n$$a\$b\nafter**` split in two and exposed its `**`). Declining instead lets upstream's own check decide.
+
+**Apply the interruption guard to the backslash construct too.** The guard exists to protect the construct tried after this one; `\[`/`\(` have no second construct, and an unconditional guard dropped their multi-line blocks (`Prose line` followed by `\[`).
+
+## Consequences
+
+The three shapes now produce the same math node, so formulas stop truncating at the opening line and stop swallowing the prose after them. `$$` fence meta is no longer honored: `$$asciimath$$` parses as a formula whose value is `asciimath`, which upstream's flow treats as fence meta and drops. That spelling has no user in this repository, and the renderer never read `meta` anyway.
+
+Six inputs still reach upstream's flow or stay in the surrounding paragraph, because the compatibility flow declines them. Trailing text after a closing `$$` (`$$x$$ trailing`, or a CJK quote mark closing a line of prose) resolves through upstream inline math, as the existing `markdown.client.spec.tsx` case pins — including when a later `$$` block follows. A `$$` sequence the line does not end after declines the block: immediately on a later line, and at that line's ending on the opening line. A `$$` block left open runs to the next lone `$$` or to EOF exactly as it did before this change, because the upstream flow closes at EOF.
+
+The fourth is a multi-line block whose opening line carries a solitary `$` and that must interrupt a paragraph, with no blank line before it. Both flows decline the interruption there — this one by design, upstream because its fence meta stops at the `$` — so the block stays inside the paragraph and renders as inline math or not at all. Separating the block from the paragraph with a blank line makes this flow own it and render the display block.
+
+The fifth follows from the comment gate: a block whose only closing fence sits behind a comment that holds text keeps scanning instead of closing there, so when nothing else closes it the block reaches the upstream flow as the shapes above do. A fence behind a whitespace-only comment closes the block there, which leaves a following lone `$$` as its own empty block where the flow it replaced kept one node.
+
+The sixth is a multi-line block inside a container whose continuation line falls back to the container's indentation. `- Define:` followed by `$$f(x)=x` at the item's indentation and then a de-indented continuation line gives upstream's flow a fence meta and no value, so the reader sees an empty display block and the continuation as prose — the opening line is gone. Keeping the continuation at the same indentation, or moving the block out of the list, renders it normally. Both flow behaviors match the grammar this replaced; only the multi-line blocks this flow owns are new.
+
+One further limitation is not a fallback: the flow reads the six characters before a fence and does not parse verbatim regions, so a fence inside an unterminated region (`\verb|$$`) closes the block there, and a region whose text ends in `\verb` (`\verb**\verb*$$`) has its fence read as that text's delimiter. The six characters before either fence are locally identical, so no rule that reads only that tail separates them.
+
+Repeated unclosed candidates keep linear parser work: an open candidate declines at the next line that starts with a full `$$` it cannot close, rather than scanning each candidate to EOF, which would make 9.6 KB of `$$a$b` lines take ~4 s instead of ~16 ms. KaTeX-level failures in a formula's own source, such as `\arccot`, remain errors by design.
+
+## Testing
+
+`packages/client/ui-primitives/tests/markdown.client.spec.tsx` adds the multi-line case — opening-line math closed on a content line, closed by a lone fence, after a paragraph, inside a list item, and at column zero after a list item — and that case fails without the change. The same file also pins a multi-line formula that uses a solitary `$`, which like the case above renders only with this change. Further cases pin one condition each: a trailing-text candidate ahead of a later block (the flow must decline a full `$$` the line does not end after), a solitary `$` inside a single-line display formula (the flow must not decline on a single `$`), an escaped-dollar candidate that leaves its paragraph intact (the interruption check must not claim the paragraph), an unclosed `\[` candidate that leaves its paragraph intact (the guard must not apply to the backslash construct), a candidate ending in an odd backslash (the escape run must end at the line ending), a closing fence inside a TeX comment, a `%` the fence follows immediately or after whitespace, a second `%` inside an open comment, a `%` inside `\verb|…|`, the delimiter right after `\verb` and `\verb*` together with its empty region, an escaped backslash before `verb`, a verb tail that crosses no line ending, a comment ending in `verb`, a later-line trailing fence whose following prose upstream takes, a failed fence inside a comment, and bounded-work cases for repeated candidates with that backslash, without it, and ending in a verb tail.
+
+The DOM compatibility corpus adds `math-multiline-display` with its `.settled.txt` and `.streaming.txt` fixtures, which also pin that a column-zero `$$` after a list item stays outside the list item. `apps/web/tests/math-rendering.e2e.ts` renders the multi-line shape in the browser lane.
diff --git a/.agents/notes/implemented/bug-fix/2026-09-17-multiline-display-dollar-math.zh.md b/.agents/notes/implemented/bug-fix/2026-09-17-multiline-display-dollar-math.zh.md
new file mode 100644
index 0000000000..ed0ef3f46a
--- /dev/null
+++ b/.agents/notes/implemented/bug-fix/2026-09-17-multiline-display-dollar-math.zh.md
@@ -0,0 +1,66 @@
+# Agent Note: Multi-line display-dollar math
+
+Status: implemented
+
+[English](2026-09-17-multiline-display-dollar-math.md) | 中文
+
+## Problem
+
+作者和模型写 `$$` 行间公式时有三种写法。定稿语法只渲染其中两种：一行内开闭的 `$$math$$`，以及 `$$` 独占一行、由独占一行的 `$$` 闭合。第三种——开围栏同一行就带公式内容，闭合 `$$` 落在最后一行公式行行尾——不渲染：
+
+```markdown
+$$f(x)=x
+\text{continued}$$
+```
+
+`micromark-extension-math` 把开围栏 `$$` 之后的同一行文本当作围栏 meta，并且只接受内容恰为 `$$`（后接可选空白）的行作为闭合围栏。[markdown 兼容层](../../archived/feature/2026-07-23-web-assistant-markdown.md)只认同一行开闭这一种形状，而定稿渲染器把 `node.value` 交给 KaTeX，不读 `node.meta`。于是该块始终不闭合：它吞掉后续正文，`value` 里残留字面 `$$`，KaTeX 抛出 `Can't use function '$' in math mode`，[katex.tsx](../../../../packages/client/ui-primitives/src/markdown/katex.tsx) 的错误分支把 TeX 原文连同被吞掉的正文一起显示为红色。
+
+在暴露该问题的会话中，一条聊天回复 55 行里有 34 行（第 22–55 行）变成同一个错误块，六个笔记文件从出错点起的所有行（最多约 500 行）同样变成一个错误块。同一机制还带出第二个缺陷：当更靠后的独占行 `$$` 恰好闭合了这个流时，开围栏那一行已经归给 `meta`，渲染器于是静默丢掉公式的第一行。
+
+## Decision
+
+[mathCompatibility.ts](../../../../packages/client/ui-primitives/src/markdown/mathCompatibility.ts) 现在支持跨行的显示美元块。dollar 构造把开围栏同一行的文本留在 `mathFlowValue` 里而不是当作围栏 meta，并在后续任意内容行行尾的 `$$` 处闭合，于是 `$$a+b` 接 `c+d$$` 成为一个 math 节点。
+
+闭合失败的 `$$` 序列会结束该候选：出现在后续行时立即结束；出现在开围栏行时在该行行尾结束（`$$x$$ trailing` 即在此放弃）。在开围栏行内扫描继续，因此同一行更靠后的 `$$` 仍能闭合（`$$\verb*a$$a$$`）。越过这两点继续扫描都会吞掉更靠后一个块的闭合围栏。孤立的一个 `$` 属于公式内容而不是失败的围栏，所以凡是本 flow 拥有该块的场合，用到它的公式——`$$P = \begin{cases} 1 & \text{if $x>0$} \end{cases}$$`——保持块打开并正常闭合。行尾反斜杠转义的是换行本身，不是下一行的第一个字符，因此转义状态在换行处结束，不会延续到下一个候选。未转义的 `%` 会开启延续到行尾的 TeX 注释：当注释在围栏之前还有文本时，块后续行行尾的 `$$` 不闭合任何东西；而围栏之前只有空白或什么都没有的 `%`（`95%$$`、`95 %$$`）不含注释文本，且在一行内开闭的块仍在该行的 `$$` 处闭合，与它跨行之前的行为一致。该状态及其对闭合判定的门控属于 dollar flow。`\verb` 或 `\verb*` 之后的那个字符是该命令的分隔符而不是围栏，因此该分隔符、以及区域为空时紧随其后的那个 `$` 都属于内容；这段尾部状态在换行处、以及在被转义的反斜杠之后清空（`\\verb` 是换行加字母，不是该命令），注释里也不识别命令。除此之外不解析原样文本区域，使含 `\verb` 的公式与其它输入走同一条 value 路径。
+
+它的段落打断检查改为「不认领」，且只作用于 dollar 构造。在那里消耗换行会让段落跨行边界保持打开，document 层因此保留容器并把下一行对随后尝试的所有构造计为 lazy；这正是上游 `mathFlow`（本构造之后被尝试的构造）在列表项内以空块结束的原因。不认领同时把打断决定交给上游 flow：它自己的检查不消耗换行就短路返回，并且只认领它接受的围栏，因此两个构造都不接受的候选（`**before` 后接 `$$a\$b`）保持原段落。反斜杠构造没有竞争的上游构造，仍然照旧消耗换行。
+
+[parse.ts](../../../../packages/client/ui-primitives/src/markdown/parse.ts) 把 `mathCompatibility()` 注册在 `math()` 之后：micromark 先派发最后注册的扩展，上面的 dollar flow 因此优先于上游 `mathFlow`，而行内 `$…$` 仍由 `math()` 负责。
+
+## Alternatives considered
+
+**兼容层维持只处理同一行 `$$…$$`。** 多行写法是 GitHub、KaTeX auto-render、VS Code、Typora 都接受的形状，也是模型写多分支公式时实际采用的形状；不解析它意味着公式位置显示为红色错误块，并连带吞掉后文。
+
+**解析后修补语法树。** 被吞掉的正文已经进入 `mathFlowValue`，与数学源码无法区分；`meta` 和 `value` 无法还原成原意的块，而且后面的块根本没有被解析。
+
+**解析前用文本替换改写 `$$` 围栏。** 兼容层的设计就是语法扩展；文本替换需要自己定位代码 span、围栏和转义，而且改的是作者原文而不是解析它。
+
+**闭合失败后继续扫描。** 这正是单纯打开 `multiline` 会得到的行为：`$$x$$ trailing\n\n$$y$$` 会一路扫到第二个块的 `$$`，渲染成一个同时含着两行文本的 math 节点；而上游行内数学会把 `x`、正文和 `y` 分开渲染。`$$x$$ trailing` 的既有行为已经固定了这条回退，因此该构造放弃这个候选。对任意一个 `$`（而不是完整的 `$$` 序列）就放弃，还会破坏在 `\text{}` 内使用单个 `$` 的公式。
+
+**只要有一行解析不下去就结束尝试。** 对每次同一行闭合失败都放弃虽然不再吞文，却会让 `$$a$b` 这类行变成平方级扫描，并丢掉上面那些含单个 `$` 的公式。判据是完整的 `$$` 序列，不是那个字符。
+
+**在检查阶段认领段落打断。** 像上游 flow 那样返回成功可以避免破坏列表用例的 lazy 记账，但也会让最终失败的候选提前结束段落（`**before\n$$a\$b\nafter**` 被拆成两段并暴露 `**`）。改为不认领，把决定交给上游自己的检查。
+
+**把打断守卫也用在反斜杠构造上。** 这个守卫是为了保护随后被尝试的构造；`\[`/`\(` 没有第二个构造，无条件套用会丢掉它们的跨行块（`Prose line` 后接 `\[`）。
+
+## Consequences
+
+三种写法现在产生同一个 math 节点，公式不再在开围栏那一行被截断，也不再吞掉其后的正文。`$$` 围栏 meta 不再生效：`$$asciimath$$` 会解析成 value 为 `asciimath` 的公式，而上游 flow 会把该段当作 fence meta 丢弃。这种写法在本仓库没有使用者，且渲染器本来就从不读 `meta`。
+
+有六种输入仍会走到上游 flow，或留在所属段落里，因为兼容 flow 主动放弃它们。闭合 `$$` 之后还有文本时（`$$x$$ trailing`，或用中文引号收尾的散文行）走上游行内数学，这一点由 `markdown.client.spec.tsx` 中已有用例固定，后面还有别的 `$$` 块时同样如此。「后面不是行尾」的 `$$` 序列会让块放弃：出现在后续行时立即放弃，出现在开围栏行时在该行行尾放弃。未闭合的 `$$` 块仍像本次改动之前那样延伸到下一个独占行 `$$` 或文件结尾，因为上游 flow 在 EOF 处闭合。
+
+第四种是「开围栏行含孤立 `$`、且需要打断段落、前面又没有空行」的多行块。两个 flow 都不认领这次打断——本 flow 出于设计，上游则因为它的围栏 meta 在 `$` 处即停止——该块因此留在段落里，渲染成行内数学或根本不渲染。用空行把块与段落分开，本 flow 就会拥有它并渲染 display。
+
+第五种来自注释门控：当块唯一的闭合围栏位于「带文本的注释」之后时，块继续扫描而不是在那里闭合，若再没有别的围栏闭合它，就会像上面几种一样走到上游 flow。若围栏之前只有空白，则块在该处闭合，此后单独一行的 `$$` 会成为它自己的空块——而被替换掉的语法那时只给出一个节点。
+
+第六种是容器内续行退回容器缩进的多行块。`- Define:` 之后以列表项缩进写 `$$f(x)=x`，再接一行不缩进的续行，上游 flow 会得到有 meta、无 value 的结果：读者看到一个空的 display 块加一行散文，公式首行无声消失。续行保持同样缩进，或把整块移到列表之外，即可正常渲染。这两种 flow 行为都与本次替换掉的语法一致；真正新增的只是「本 flow 拥有的多行块」。
+
+另有一项不属于回退的限制：flow 只读取围栏之前的六个字符、不解析原样文本区域，因此未闭合区域内部的围栏（`\verb|$$`）会在那里闭合块，而内容以文本 `\verb` 结尾的区域（`\verb**\verb*$$`）其围栏会被读成该文本的分隔符。两种情况下围栏前的六个字符在局部完全相同，仅凭这段尾部无法区分。
+
+重复的未闭合候选保持线性解析开销：未闭合的候选会在下一行遇到无法闭合的完整 `$$` 时放弃，而不是把每个候选都扫到 EOF——否则 9.6 KB 的 `$$a$b` 行会花约 4 秒而不是约 16 毫秒。公式自身源码层面的 KaTeX 失败，例如 `\arccot`，仍按设计报错。
+
+## Testing
+
+`packages/client/ui-primitives/tests/markdown.client.spec.tsx` 新增多行用例——开围栏行内容由内容行行尾 `$$` 闭合、由独占行 `$$` 闭合、出现在段落之后、出现在列表项内，以及列表项之后的零缩进围栏——该用例去掉改动即失败。同一文件还固定了「使用单个 `$` 的多行公式」，它与上面的多行用例一样只有本次改动才会渲染成 display。另有一组用例各自对应一个条件：后面还有块时的尾随文本候选（flow 必须放弃「后面不是行尾」的完整 `$$`）、单行显示公式内的单个 `$`（不得因为一个 `$` 就放弃）、保持段落完整性的转义美元候选（打断检查不得认领段落）、保持段落完整性的未闭合 `\[` 候选（守卫不得作用于反斜杠构造）、以奇数个反斜杠结尾的候选（转义状态必须在换行处结束）、TeX 注释内的闭合围栏、紧邻围栏或只隔空白的 `%`、已开启注释内的第二个 `%`、`\verb|…|` 内的 `%`、`\verb` 与 `\verb*` 之后的分隔符及其空区域、`verb` 之前的转义反斜杠、不跨行的 verb 尾部、以 `verb` 结尾的注释、后续行尾随文本围栏（其后正文由上游接管）、注释内失败的围栏，以及带该反斜杠、不带该反斜杠、以 verb 尾部结尾三种重复候选的有界解析开销。
+
+DOM 兼容语料新增 `math-multiline-display` 及其 `.settled.txt`、`.streaming.txt`，同时固定了「列表项之后的零缩进 `$$` 不进入列表项内」。`apps/web/tests/math-rendering.e2e.ts` 在浏览器 lane 渲染多行写法。
diff --git a/.agents/notes/implemented/feature/2026-06-15-ptc.i18n.yaml b/.agents/notes/implemented/feature/2026-06-15-ptc.i18n.yaml
index e3bd9b93f5..9c1ddab7b7 100644
--- a/.agents/notes/implemented/feature/2026-06-15-ptc.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-06-15-ptc.i18n.yaml
@@ -15,8 +15,8 @@
en: da694641e1d009de
zh: 9d7492d39039af66
/agent-note-ptc-mode-the-model-writes-typescript-against-the-tool-registry/decision/the-registry-owns-the-mode:
- en: 091b7bc49b027353
- zh: 42dc77a810202694
+ en: 4cd76a34f4712e1a
+ zh: 303ef72a18644d7c
/agent-note-ptc-mode-the-model-writes-typescript-against-the-tool-registry/decision/the-run-code-tool-and-the-dispatch-bridge:
en: 6a0e2698b082978e
zh: fbb03503520b30e9
diff --git a/.agents/notes/implemented/feature/2026-06-15-ptc.md b/.agents/notes/implemented/feature/2026-06-15-ptc.md
index 97fc5b04db..e99eccd65b 100644
--- a/.agents/notes/implemented/feature/2026-06-15-ptc.md
+++ b/.agents/notes/implemented/feature/2026-06-15-ptc.md
@@ -40,7 +40,7 @@ The [Node execution decision](../architecture/2026-09-11-sandboxed-node-ptc-runt
**SDK prompt section.** In `'ptc'`, the lazy `tools:sdk` section in the tool-guidance order band renders the loaded runtime's language declarations plus fixed usage instructions for the scope's visible capabilities (TypeScript by default; the [language-dispatch note](../../archived/feature/2026-07-31-ptc-language-dispatch.md) added Python and the `ctx.ptcRuntime.language` renderer table). It shares lookup and execution visibility, excludes `run_code`, and sorts tools lexicographically for byte-stable output.
-**Assembly ownership.** `run_code` and `tools:sdk` enter the trusted `system-prompt/assemble` waterfall as normal assembly inputs. A scoped `tools:sdk` section may shadow the global default before dispatch, and a listener may remove or replace either contribution. The waterfall's returned assembly is final, so whoever changes these inputs owns preserving a viable PTC mode protocol when the deployment expects PTC mode to remain usable; no restoration pass overrides deliberate composition.
+**Assembly ownership.** `tools:sdk` enters the trusted `system-prompt/assemble` presentation waterfall as a normal section, while `run_code` stays a provider-owned declaration that the waterfall cannot remove or replace. A scoped `tools:sdk` section may shadow the global default before dispatch, and a listener may remove or replace the section. Whoever changes it owns preserving a viable PTC mode protocol when the deployment expects PTC mode to remain usable; no restoration pass overrides deliberate composition.
**Codegen.** `jsonSchemaToTs()` maps the `defineTool` JSON-Schema subset to TypeScript, carries schema descriptions into JSDoc, and degrades unsupported constructs to `unknown`. The SDK exposes tools as quoted object keys, supporting arbitrary names without aliases or collisions. Typing is advisory because the runtime strips types before execution.
diff --git a/.agents/notes/implemented/feature/2026-06-15-ptc.zh.md b/.agents/notes/implemented/feature/2026-06-15-ptc.zh.md
index 381448d354..71efafa7f2 100644
--- a/.agents/notes/implemented/feature/2026-06-15-ptc.zh.md
+++ b/.agents/notes/implemented/feature/2026-06-15-ptc.zh.md
@@ -40,7 +40,7 @@ Cloudflare 的 [Code Mode](https://blog.cloudflare.com/code-mode/) 提出了一
**SDK 提示词段。** 在 `'ptc'` 下，tool-guidance order band 中的惰性 `tools:sdk` 段为当前 scope 的可见能力渲染所加载运行时语言的声明加固定的使用说明（默认 TypeScript；[语言分发 note](../../archived/feature/2026-07-31-ptc-language-dispatch.md) 加入了 Python 与按 `ctx.ptcRuntime.language` 选择的渲染器表）。它共享查找和执行可见性，排除 `run_code`，并按字典序排列工具以获得字节稳定的输出。
-**组装所有权。** `run_code` 和 `tools:sdk` 作为正常的组装输入进入受信任的 `system-prompt/assemble` waterfall。一个 scoped 的 `tools:sdk` 段可以在分发前遮蔽全局默认值，监听器也可以移除或替换任一贡献。waterfall 返回的组装结果是最终的，因此修改这些输入的人有责任在部署期望 PTC mode 可用时保持协议面的完整性；没有恢复 pass 会覆盖有意的组合。
+**组装所有权。** `tools:sdk` 作为正常段进入受信任的 `system-prompt/assemble` 展示 waterfall，而 `run_code` 仍是提供方持有的声明，waterfall 不能移除或替换它。一个 scoped 的 `tools:sdk` 段可以在分发前遮蔽全局默认值，监听器也可以移除或替换该段。修改它的人有责任在部署期望 PTC mode 可用时保持协议面的完整性；没有恢复 pass 会覆盖有意的组合。
**代码生成。** `jsonSchemaToTs()` 将 `defineTool` 的 JSON Schema 子集映射为 TypeScript，将 schema 描述带入 JSDoc，不支持的构造降级为 `unknown`。SDK 将工具暴露为带引号的对象键，支持任意名称而无需别名或冲突处理。类型是建议性的，因为运行时在执行前会剥离类型。
diff --git a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml
index 639381d125..ca48f70356 100644
--- a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.i18n.yaml
@@ -12,8 +12,8 @@
en: 532bb7268d9b93ce
zh: ad47162233222ab0
/agent-note-parallel-tool-call-execution-by-per-call-safety/scheduling-and-ordering:
- en: 4e85280cc5eb8697
- zh: 8e6b09b1527784fa
+ en: 47010d626ab15117
+ zh: a5b77385d7a3e781
/agent-note-parallel-tool-call-execution-by-per-call-safety/safety-contract:
en: 16c4ee08b65ead23
zh: df80d6e49982615b
@@ -21,11 +21,11 @@
en: e112957ed8a48039
zh: 37d63f9ea4968fb2
/agent-note-parallel-tool-call-execution-by-per-call-safety/verification:
- en: eb5a6aa84980f0ab
- zh: eed2680a160e8ed2
+ en: 224b6838130c113f
+ zh: f3d7eb68ab5932fb
/agent-note-parallel-tool-call-execution-by-per-call-safety/alternatives-considered:
en: 17becc038bb7df7c
zh: 673d9a9bdfa39edf
/agent-note-parallel-tool-call-execution-by-per-call-safety/consequences:
- en: a5508057bc03f4f6
- zh: 96b46c59402474c3
+ en: 20a3e29931e01aa0
+ zh: acbfc61dd710d960
diff --git a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md
index 40adc9f9aa..4eb497b1ff 100644
--- a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md
+++ b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.md
@@ -26,7 +26,7 @@ A tagged mode, rather than a public boolean scheduler API, keeps resource-aware
## Scheduling and ordering
-The loop waits for the complete assistant message, parses every call once, creates a distinct `ToolExecution` for each call, and scans them in model order. Consecutive parallel calls form one group; every exclusive call forms a singleton group and an ordering barrier. Groups execute sequentially. Classification is lazy: the scheduler resolves the next call after each barrier and reclassifies every later call before replenishing a parallel pool. If a registry mutation makes that call exclusive, the current pool drains before the call starts as the next barrier.
+The loop waits for the complete assistant message, parses every call once, creates a distinct `ToolExecution` for each call, and scans them in model order. Consecutive parallel calls form one group; every exclusive call forms a singleton group and an ordering barrier. Groups execute sequentially. Classification is lazy: the scheduler resolves the next call after each barrier and reclassifies every later call before replenishing a parallel pool. Calls resolve through the step's admitted tool set, so replacing or removing a call's registration makes that unstarted call fail as `UNKNOWN_TOOL`; the scheduler classifies it as exclusive, and the current pool drains before it settles as the next barrier.
For example:
@@ -66,7 +66,7 @@ Filesystem read relies on a narrow recorder exception: its synchronous observati
## Verification
-Unit coverage pins fail-closed classification, typed argument validation, grouping, barriers, live reclassification after registry replacement, the rolling cap, distinct execution objects, middleware order, ordered results and context, abort draining, and scheduler-failure quiescence. First-party tests pin each parallel declaration.
+Unit coverage pins fail-closed classification, typed argument validation, grouping, barriers, rejection of unstarted calls after registry replacement, the rolling cap, distinct execution objects, middleware order, ordered results and context, abort draining, and scheduler-failure quiescence. First-party tests pin each parallel declaration.
Snapshot coverage pins the visible multi-call transcript: pending calls may overlap while completed results remain model-ordered. PTC mode coverage pins its serial boundary. No provider-backed e2e is required because scheduling is deterministic loop behavior.
@@ -102,6 +102,6 @@ Ordered commits may hold a fast result behind a slow earlier sibling. This prese
Concurrent external calls can compete for quota or process capacity. Providers own their capacity controls; the loop cap only limits calls from one agent step.
-Tool registration is a scheduling boundary. Registry mutations affect not-yet-started calls because the scheduler reclassifies after each barrier and before every pool replenishment. Already-started calls retain the scheduling decision under which they entered the pool.
+Tool registration is a scheduling boundary. Registry mutations affect not-yet-started calls because the scheduler reclassifies after each barrier and before every pool replenishment. A call runs only the registration its step declared ([conditional tools](../../../../packages/core/tools/README.md)), so a hot reload, MCP reconnect, or skill reload that re-registers a tool mid-step fails that step's unstarted calls of it; the next step declares and runs the new registration. Already-started calls retain the scheduling decision under which they entered the pool.
A terminal scheduler failure reaches step recovery only after live dispatches settle. Recovery reports uncommitted outcomes as unknown, preserving quiescence and the original failure while keeping later model history usable.
diff --git a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md
index 536541370b..dbfa7cd684 100644
--- a/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-10-parallel-tool-call-execution.zh.md
@@ -26,7 +26,7 @@ Status: implemented
## 调度与顺序
-循环会等待完整的 assistant 消息，对每个调用只解析一次，为每个调用创建独立的 `ToolExecution`，再按模型顺序扫描。连续的并行调用组成一组；每个独占调用单独组成一组，并构成顺序屏障。各组按顺序执行。分类采用惰性方式：每经过一个屏障，调度器都会解析下一个调用；补充并行池之前，还会重新分类每个后续调用。如果注册表变更使该调用变为独占，当前池会先完全排空，然后该调用才作为下一个屏障启动。
+循环会等待完整的 assistant 消息，对每个调用只解析一次，为每个调用创建独立的 `ToolExecution`，再按模型顺序扫描。连续的并行调用组成一组；每个独占调用单独组成一组，并构成顺序屏障。各组按顺序执行。分类采用惰性方式：每经过一个屏障，调度器都会解析下一个调用；补充并行池之前，还会重新分类每个后续调用。调用通过本步骤的准入工具集合解析，因此替换或移除某个调用的注册后，该尚未开始的调用会以 `UNKNOWN_TOOL` 失败；调度器把它分类为独占，当前池会先完全排空，然后它才作为下一个屏障结束。
例如：
@@ -66,7 +66,7 @@ Status: implemented
## 验证
-单元测试固定了按安全侧原则进行的分类、类型化参数验证、分组、屏障、注册表替换后的运行时重新分类、滚动上限、独立执行对象、中间件顺序、有序结果与上下文、中止排空，以及调度器故障后的完全停稳。第一方测试固定了每项并行声明。
+单元测试固定了按安全侧原则进行的分类、类型化参数验证、分组、屏障、注册表替换后拒绝尚未开始的调用、滚动上限、独立执行对象、中间件顺序、有序结果与上下文、中止排空，以及调度器故障后的完全停稳。第一方测试固定了每项并行声明。
快照测试固定了可见的多调用 transcript（文本记录）：待处理调用可以重叠执行，已完成结果仍按模型顺序排列。PTC mode 测试固定了其串行边界。此调度属于确定性循环行为，因此无需依赖提供方的 e2e 测试。
@@ -102,6 +102,6 @@ Status: implemented
并发外部调用可能会争用配额或进程容量。提供方负责自身容量控制；循环上限只限制一个 agent 步骤中的调用数量。
-工具注册是调度边界。调度器会在每个屏障之后以及每次补充池之前重新分类，因此注册表变更会影响尚未启动的调用。已启动的调用保留它们进入池时所依据的调度决策。
+工具注册是调度边界。调度器会在每个屏障之后以及每次补充池之前重新分类，因此注册表变更会影响尚未启动的调用。调用只执行其步骤所声明的注册（[条件工具](../../../../packages/core/tools/README.zh.md)），因此在步骤中途重新注册工具的热重载、MCP 重连或 skill 重载会让该步骤里这个工具尚未开始的调用失败；下一个步骤声明并执行新的注册。已启动的调用保留它们进入池时所依据的调度决策。
终态调度器故障只有在运行中的派发结算后才会进入步骤恢复。恢复将未提交的执行结果报告为未知，保留完全停稳与原始失败，同时让后续模型历史保持可用。
diff --git a/.agents/notes/implemented/feature/2026-08-26-generic-file-upload.i18n.yaml b/.agents/notes/implemented/feature/2026-08-26-generic-file-upload.i18n.yaml
index 496d2e8136..98789701f0 100644
--- a/.agents/notes/implemented/feature/2026-08-26-generic-file-upload.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-26-generic-file-upload.i18n.yaml
@@ -9,8 +9,8 @@
en: e7c3b5d7702714fe
zh: 268f162b553b37d1
/agent-note-generic-file-upload/decision:
- en: 31c7ad96c6ab82c8
- zh: 806922fc8fcd1242
+ en: 1769950d73d30dca
+ zh: bf296b920ea9b997
/agent-note-generic-file-upload/alternatives-considered:
en: 23f386b05e4e79ef
zh: 0756c4fa30e8d0eb
@@ -21,5 +21,5 @@
en: 3a50ac370d51cda9
zh: d490f58922f8795b
/agent-note-generic-file-upload/related:
- en: 7579c49eefdb8488
- zh: 68ad384fd9d2f8f9
+ en: 14e8659b89dc08a8
+ zh: dec5baa11f168e91
diff --git a/.agents/notes/implemented/feature/2026-08-26-generic-file-upload.md b/.agents/notes/implemented/feature/2026-08-26-generic-file-upload.md
index f60649a083..133312a83c 100644
--- a/.agents/notes/implemented/feature/2026-08-26-generic-file-upload.md
+++ b/.agents/notes/implemented/feature/2026-08-26-generic-file-upload.md
@@ -14,7 +14,7 @@ The command plane had already established a whole-envelope rule for images: a co
Files and images use separate storage schemes and one ordered message attachment list. Images keep their normalized-attachment pipeline unchanged. Other picked files enter one FIFO background-upload queue and are stored byte-for-byte with no type or size limits, then staged in-process for the same Session. Equal bytes have one canonical object under `DSH_HOME/attachments/v1/file-objects//`; each read-only model-facing path at `DSH_HOME/attachments/v1/files///` is a hard link, so different display names do not duplicate content. The configurable queue defaults to two active transfers. The independent dual-face `file-upload` Cordis package owns transfer and staging. Its Client `fileUpload` service accepts the owning Session identity together with a `Blob`, exact bytes, or a one-shot `ReadableStream`; it uses that identity to assemble the raw route request or invoke the generated Remote directly. Its Host `fileUploads` service owns the streaming route, encoded Remote fallback, command receipt resolver, and receipt tables keyed by the receiving Agent's Session object. Encoded admission and attachment-error recognition go through `ctx.attachments`, whose provider owns byte storage. Session Controller registers the resolver for cold ordinary Agents and consumes receipts during prompt admission; Session objects do not expose file transfer. Served Web pages hand each active body to a dedicated upload Worker: Blob bodies use XMLHttpRequest for total-aware byte progress, while streams transfer ownership and feed Fetch incrementally. Worker-hosted pages transfer the body through their page-owned Fetch carrier to the Host Worker, which reads bounded chunks. The page thread never reads, base64-encodes, or JSON-serializes generic file bytes. The authenticated Host route opts into Connection's streaming request mode, so the bridge dispatches before consuming the body and the local store hashes and writes bounded chunks to a private staging object. Completion atomically publishes the content-addressed object; cancellation or failure removes the staging file. Upload operations and draft state belong to the resident conversation root, so navigation to another Session does not stop the transfer; returning to the original Session shows the same card and progress. Removing the file card skips its queued transfer or aborts its active transfer. The sent message carries a structured `FileBlock` (`{ name, bytes, attachmentId }`) inside `user/message`; no new session event type exists. Request assembly in `LlmRuntime` projects every file block, including nested tool-result occurrences, to one deterministic handle naming the file and its saved read-only path. The handle tells a main agent to include that path when delegating file work and to report when the child's execution environment cannot see it. No provider receives file bytes; the model reads the stored copy with existing file tools on demand.
-Default mode, active Plan Mode, and an active goal share ordinary queue, follow-up, and steer attachment admission. `/goal` create and edit and `/plan` entry accept the same ordered image and file batches; attachment-bearing control subcommands reject before changing state. Command submissions cite completed staged-file receipts, so generic file bytes are not read or copied again. Session Controller resolves every file receipt to a durable reference before `ctx.attachments.admitPromptContent()` receives the complete ordered content list; attachment admission persists images and passes file references unchanged. The Host rejects upload completion after the original Agent is disposed and deduplicates prompt retries already identified by `rpcId`. Prompt receipts remain available through failure recovery, then retire after the accepted queue or history occurrence is observed; command-only receipts remain until Session disposal. Submission echoes register through `beginSubmission` before serialization, carry mixed attachments through `pendingSubmissions`, correlate by `rpcId`, retire once after queue or history observation, and keep drafts on failure. Before submission, the composer presents the ordered batch in one non-wrapping horizontal rail: images use 64 by 64 pixel thumbnails and generic files use 240 by 64 pixel cards with a 16 pixel radius, blue document glyph, filename plus extension and size, and a hover or keyboard removal action. QueueDock uses the same order with compact thumbnails and file cards. After submission, Chat presents the ordered batch in one right-aligned wrapping attachment flow. A lone image retains the large gallery presentation; a message with multiple attachments uses 64 by 64 pixel image tiles and 240 by 64 pixel file cards, so files and images share each row until the available width forces a wrap. Trajectory keeps the user-message preview compact and adds a localized generic-file count. Paperclip, drag, and paste classify by MIME; send waits for every file upload. Continuable subagent composers disable attachment intake, and the Host rejects any file block received for a child session.
+Default mode, active Plan Mode, and an active goal share ordinary queue, follow-up, and steer attachment admission. `/goal` create and edit and `/plan` entry accept the same ordered image and file batches; attachment-bearing control subcommands reject before changing state. Command submissions cite completed staged-file receipts, so generic file bytes are not read or copied again. Session Controller resolves every file receipt to a durable reference before `ctx.attachments.admitPromptContent()` receives the complete ordered content list; attachment admission persists images and passes file references unchanged. The Host rejects upload completion after the original Agent is disposed and deduplicates prompt retries already identified by `rpcId`. Prompt receipts remain available through failure recovery, then retire after the accepted queue or history occurrence is observed; command-only receipts remain until Session disposal. Submission echoes register through `beginSubmission` before serialization, carry mixed attachments through `pendingSubmissions`, correlate by `rpcId`, retire once after queue or history observation, and keep drafts on failure. Before submission, the composer presents the ordered batch in one non-wrapping horizontal rail: images use 64 by 64 pixel thumbnails and generic files use 240 by 64 pixel cards with a 16 pixel radius, blue document glyph, filename plus extension and size, and a hover or keyboard removal action. QueueDock uses the same order with compact thumbnails and file cards. After submission, Chat presents the ordered batch in one right-aligned wrapping attachment flow. A lone image retains the large gallery presentation; a message with multiple attachments uses 64 by 64 pixel image tiles and 240 by 64 pixel file cards, so files and images share each row until the available width forces a wrap. Trajectory keeps the user-message preview compact and adds a localized generic-file count. Paperclip, drag, and paste classify by MIME; send waits for every upload. Continuable subagent composers disable attachment intake, and the Host rejects any file block received for a child session.
## Alternatives considered
@@ -54,3 +54,5 @@ Unit and integration coverage pins verbatim and streamed storage, name sanitizat
The [Trajectory reference](../../../../packages/client/ui-trajectory/README.md) documents ledger counts and inspector attachment layouts.
The [input echo admission reference](../../../../packages/api/session-controller/README.md) owns placement-specific retirement and delayed Inbox suppression for submissions with or without attachments.
+
+The [composer image upload on add](2026-10-21-composer-image-upload-on-add.md) note extends this background-upload queue to the images of an ordinary Session's draft.
diff --git a/.agents/notes/implemented/feature/2026-08-26-generic-file-upload.zh.md b/.agents/notes/implemented/feature/2026-08-26-generic-file-upload.zh.md
index 3d1667d181..dfc48509c5 100644
--- a/.agents/notes/implemented/feature/2026-08-26-generic-file-upload.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-26-generic-file-upload.zh.md
@@ -14,7 +14,7 @@ Status: implemented
文件与图片使用不同存储方案，并进入同一个有序消息附件列表。图片的规范化附件流水线保持不变。其他被选中的文件进入同一个先进先出的后台上传队列，按字节原样保存且不设类型与大小限制，再在本进程内按同一 Session 暂存。相同字节在 `DSH_HOME/attachments/v1/file-objects//` 下只有一个规范对象；每条模型可见的只读路径 `DSH_HOME/attachments/v1/files///` 都是硬链接，因此不同显示名称不会复制内容。该队列可以配置，默认同时运行两项传输。独立的双端 `file-upload` Cordis 包拥有传输与暂存。其 Client `fileUpload` 服务同时接收所属 Session 标识与 `Blob`、精确字节或只能使用一次的 `ReadableStream`；它使用该标识组装原始路由请求，或直接调用生成的 Remote。其 Host `fileUploads` 服务拥有流式路由、编码 Remote 兜底、命令凭证解析器，以及以接收方 Agent 的 Session 对象为键的凭证表。编码准入和附件错误识别通过 `ctx.attachments` 完成，字节存储由附件提供方拥有。Session Controller 注册用于休眠普通 Agent 的解析器，并在 prompt 准入时消费凭证；Session 对象不公开文件传输。普通 Web 页面把每个活动请求体交给专用上传 Worker：Blob 请求体通过 XMLHttpRequest 发送并报告包含总量的字节进度，stream 则转移所有权并增量传入 Fetch。Worker-hosted 页面通过页面自有 Fetch 载体把请求体转交给 Host Worker，后者读取有界分片。页面线程不读取通用文件字节，也不做 base64 编码或 JSON 序列化。经过认证的 Host 路由显式使用 Connection 的流式请求模式，因此 bridge 会在消费请求体前分发，本地存储则把有界分片写入私有暂存对象并同时计算摘要。接收完成后，内容寻址对象以原子方式发布；取消或失败会移除暂存文件。上传任务和草稿状态属于常驻的 conversation 根，因此切到另一条 Session 不会停止传输，返回原 Session 时仍显示同一张文件卡和当前进度。移除文件卡会跳过排队中的传输或中止正在运行的传输。发送的消息在 `user/message` 里携带结构化的 `FileBlock`（`{ name, bytes, attachmentId }`），不新增会话事件类型。`LlmRuntime` 的请求组装把每个文件块，包括嵌套工具结果中的文件块，投影成确定性 handle 文本，指出文件与其只读保存路径。handle 会要求主 agent 委派文件任务时附上该路径，并在子级执行环境看不到路径时明确报告。提供方不会收到文件字节，模型在需要时用现有文件工具读取存储副本。
-默认模式、激活的 Plan Mode 与 active goal 共用普通 queue、follow-up 和 steer 的附件准入。`/goal` create 和 edit 以及 `/plan` 进入接受同一套有序图片与文件批量；携带附件的控制子命令会在状态变更前拒绝。命令提交引用已完成暂存的文件凭证，不会再次读取或复制通用文件字节。Session Controller 先把每个文件凭证解析为持久引用，再由 `ctx.attachments.admitPromptContent()` 接收完整有序内容列表；附件准入会持久化图片，并让文件引用原样通过。原 Agent 已销毁时，Host 会拒绝发布上传完成凭证，并按 `rpcId` 去重已经存在的 prompt 重试。prompt 凭证在失败恢复期间保持可用，已接受的 queue 或历史 occurrence 被观察后才退休；只被命令使用的凭证保留到 Session 销毁。提交回显在序列化前经 `beginSubmission` 注册，通过 `pendingSubmissions` 携带混合附件，以 `rpcId` 关联，在 queue 或历史观察后只退休一次，并在失败时保留草稿。发送前，composer 把有序附件放进同一条不换行的横向附件栏：图片使用 64 乘 64 像素缩略图，通用文件使用 240 乘 64 像素卡片，带 16 像素圆角、蓝色文档图标、文件名加扩展名与大小，以及悬停或键盘操作时可用的移除按钮。QueueDock 使用相同顺序以及紧凑的缩略图和文件卡。发送后，Chat 把有序附件放进同一个右对齐、可换行的附件区域。只有一张图片时保留图片画廊的大图样式；一条消息含有多个附件时，图片使用 64 乘 64 像素缩略图，文件使用 240 乘 64 像素卡片，文件与图片在可用宽度内共用一行，空间不足时再换行。Trajectory 保持紧凑的用户消息预览，并增加本地化的通用文件数量。回形针、拖拽和粘贴按 MIME 分类；发送会等待每个文件上传完成。continuable 子代理 composer 禁用附件入口，Host 会拒绝收到的任何子会话文件块。
+默认模式、激活的 Plan Mode 与 active goal 共用普通 queue、follow-up 和 steer 的附件准入。`/goal` create 和 edit 以及 `/plan` 进入接受同一套有序图片与文件批量；携带附件的控制子命令会在状态变更前拒绝。命令提交引用已完成暂存的文件凭证，不会再次读取或复制通用文件字节。Session Controller 先把每个文件凭证解析为持久引用，再由 `ctx.attachments.admitPromptContent()` 接收完整有序内容列表；附件准入会持久化图片，并让文件引用原样通过。原 Agent 已销毁时，Host 会拒绝发布上传完成凭证，并按 `rpcId` 去重已经存在的 prompt 重试。prompt 凭证在失败恢复期间保持可用，已接受的 queue 或历史 occurrence 被观察后才退休；只被命令使用的凭证保留到 Session 销毁。提交回显在序列化前经 `beginSubmission` 注册，通过 `pendingSubmissions` 携带混合附件，以 `rpcId` 关联，在 queue 或历史观察后只退休一次，并在失败时保留草稿。发送前，composer 把有序附件放进同一条不换行的横向附件栏：图片使用 64 乘 64 像素缩略图，通用文件使用 240 乘 64 像素卡片，带 16 像素圆角、蓝色文档图标、文件名加扩展名与大小，以及悬停或键盘操作时可用的移除按钮。QueueDock 使用相同顺序以及紧凑的缩略图和文件卡。发送后，Chat 把有序附件放进同一个右对齐、可换行的附件区域。只有一张图片时保留图片画廊的大图样式；一条消息含有多个附件时，图片使用 64 乘 64 像素缩略图，文件使用 240 乘 64 像素卡片，文件与图片在可用宽度内共用一行，空间不足时再换行。Trajectory 保持紧凑的用户消息预览，并增加本地化的通用文件数量。回形针、拖拽和粘贴按 MIME 分类；发送会等待每项上传完成。continuable 子代理 composer 禁用附件入口，Host 会拒绝收到的任何子会话文件块。
## 考虑过的替代方案
@@ -54,3 +54,5 @@ Status: implemented
[Trajectory 参考](../../../../packages/client/ui-trajectory/README.zh.md)说明列表计数与详情面板附件布局。
[输入回显入档参考](../../../../packages/api/session-controller/README.zh.md)负责有无附件提交的按展示归属回收和迟到 Inbox 排除。
+
+[输入框在加入时上传图片](2026-10-21-composer-image-upload-on-add.zh.md) 记录把这条后台上传队列扩展到普通 Session 草稿里的图片。
diff --git a/.agents/notes/implemented/feature/2026-08-26-web-rich-text-quotes.i18n.yaml b/.agents/notes/implemented/feature/2026-08-26-web-rich-text-quotes.i18n.yaml
new file mode 100644
index 0000000000..efb7b7a757
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-26-web-rich-text-quotes.i18n.yaml
@@ -0,0 +1,22 @@
+# Bilingual-pair consistency record for 2026-08-26-web-rich-text-quotes.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-26-web-rich-text-quotes.md
+/agent-note-durable-rich-text-quotes-in-the-web-composer:
+ en: 49522a0a81db6981
+ zh: 92e81872377e96e9
+/agent-note-durable-rich-text-quotes-in-the-web-composer/problem:
+ en: 7bd295c086ad9905
+ zh: 704dc665acfaa5ec
+/agent-note-durable-rich-text-quotes-in-the-web-composer/decision:
+ en: d27134e46ab55ea0
+ zh: 3f1da063b661a1b3
+/agent-note-durable-rich-text-quotes-in-the-web-composer/alternatives-considered:
+ en: 1999da9f900c9be3
+ zh: cf6aad990a180851
+/agent-note-durable-rich-text-quotes-in-the-web-composer/verification:
+ en: b320c262d9c08ee4
+ zh: 6047f864213a2b4c
+/agent-note-durable-rich-text-quotes-in-the-web-composer/consequences:
+ en: bb6f4338aad0ec41
+ zh: 93a4396b619492b1
diff --git a/.agents/notes/implemented/feature/2026-08-26-web-rich-text-quotes.md b/.agents/notes/implemented/feature/2026-08-26-web-rich-text-quotes.md
new file mode 100644
index 0000000000..c122d6c671
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-26-web-rich-text-quotes.md
@@ -0,0 +1,37 @@
+# Agent Note: Durable rich-text quotes in the Web composer
+
+Status: implemented
+
+English | [中文](2026-08-26-web-rich-text-quotes.zh.md)
+
+## Problem
+
+Selected transcript excerpts need atomic editing and reload-safe drafts without depending on the availability of their source messages.
+
+## Decision
+
+`ui-conversation` owns an inline `QuoteNode` beside reference nodes in the existing editor runtime. Its clipboard projection is canonical Markdown, while its detect projection is one atomic character. The existing semantic `DraftSnapshot` persists quote text and clipboard-coordinate spans beside references; raw Lexical JSON and runtime node identities remain outside browser storage. Session switching, Workspace transfer, and failed-send restoration use this same snapshot. Quote controls receive runtime-only locale labels.
+
+`ui-chat` accepts one nonblank browser selection within displayed user content, including pending steering and local submission echoes or finalized Assistant text and reasoning. Streaming and interrupted Assistant output, tools, injected context, and Markdown controls are excluded. Selection extraction follows visible line and block breaks and inserts through the current Session input actions.
+
+Text interaction belongs to the shared primitive and the Chat-owned list Slot. Quote registers only gesture admission and insertion. Local absolute placement keeps actions in the content coordinate system; outside presses and Escape close the same area-owned interaction for every consumer. Dismissal and selection clearing are separate operations so a failed insertion preserves the excerpt. Context-menu consumers cancel their originating browser event synchronously; rendering a Slot cannot retroactively cancel it.
+
+The [text-derived blockquote decision](../simplification/2026-10-13-text-derived-message-quotes.md) owns sent-message recognition and presentation. The [UserText evaluator](../architecture/2026-10-10-user-text-json-nodes.md) renders derived quote nodes through the existing matcher registry.
+
+Quotes display a compact single-line preview; clipped excerpts expose the complete text in a shared inline HoverCard. Their text has no source-navigation action. The editable draft alone exposes whole-node removal. Only selected text survives message persistence: no source Session, message, or selection coordinates are retained.
+
+## Alternatives considered
+
+**Persist Lexical JSON or introduce another draft format.** Editor serialization would become a product storage obligation, while a second draft format would duplicate restoration and transfer ownership. The existing semantic snapshot already carries reference spans and extends to quotes.
+
+**Retain source navigation.** Availability checks would require source coordinates, subscriptions, history pagination, focus routing, and failure states. A future navigation feature must define those durable coordinates and target-owned actions before adding them.
+
+**Store UserText nodes or callbacks.** Text nodes are derived presentation, and callbacks are runtime state. Both can change independently of the logged input and semantic draft.
+
+## Verification
+
+Composer tests cover atomic removal and undo, semantic storage round trips, Markdown serialization, and failed-send restoration. UserText tests cover text recognition, literal excerpt rendering, literal references, and credential spelling. The keyless Web scenario exercises selection, clipped previews, draft switching and reload, persistence, and ordinary Markdown submission through the shipped composition.
+
+## Consequences
+
+The draft and Session retain enough data for atomic editing and replay without retaining source-history dependencies. UserText remains a display projection; its JSON nodes never replace authoritative content. Browser-local storage retains unsent selected text under the existing draft policy.
diff --git a/.agents/notes/implemented/feature/2026-08-26-web-rich-text-quotes.zh.md b/.agents/notes/implemented/feature/2026-08-26-web-rich-text-quotes.zh.md
new file mode 100644
index 0000000000..7f324768e1
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-08-26-web-rich-text-quotes.zh.md
@@ -0,0 +1,37 @@
+# Agent Note：Web composer 中的持久富文本 quote
+
+Status: implemented
+
+[English](2026-08-26-web-rich-text-quotes.md) | 中文
+
+## 问题
+
+所选 transcript 摘录需要原子编辑与可跨刷新恢复的草稿，不依赖来源消息的可用性。
+
+## 决策
+
+`ui-conversation` 在现有编辑器 runtime 中于 reference 节点旁拥有行内 `QuoteNode`。其剪贴板投影是规范 Markdown，检测投影则是一个原子字符。现有语义 `DraftSnapshot` 在 reference 旁持久化 quote 文本与剪贴板坐标范围；原始 Lexical JSON 与 runtime 节点身份不进入浏览器存储。Session 切换、Workspace 转移和发送失败恢复使用同一个 snapshot。Quote 控件接收仅用于 runtime 的 locale 标签。
+
+`ui-chat` 接受已展示的用户内容（包括待接纳 steering 和本地发送回显）、或最终完成的 Assistant 文本与 reasoning 中的一个非空浏览器选区。流式及中断的 Assistant 输出、tool、注入上下文和 Markdown 控件被排除。选区提取遵循可见的行与 block 换行，通过当前 Session 的 input actions 插入。
+
+文本交互属于共享基础能力与 Chat 拥有的 list Slot，quote 只注册手势接管与插入操作。本地绝对定位让操作处于内容坐标系；外部按下与 Escape 对所有使用方关闭同一个区域拥有的交互。关闭展示与清除选区是独立操作，因此插入失败时保留摘录。右键菜单使用方同步取消来源浏览器事件；渲染 Slot 无法事后取消事件。
+
+[文本派生 blockquote 决策](../simplification/2026-10-13-text-derived-message-quotes.zh.md)拥有发送后的消息识别与展示。[UserText 计算器](../architecture/2026-10-10-user-text-json-nodes.zh.md)通过现有 matcher registry 渲染派生的 quote 节点。
+
+Quote 显示紧凑的单行预览；截断的摘录通过共享行内 HoverCard 展示完整文本。文本不提供来源导航操作，只有可编辑草稿提供整节点删除。消息持久化只保留所选文本：不保留来源 Session、消息或选区坐标。
+
+## 考虑过的替代方案
+
+**持久化 Lexical JSON 或引入另一套草稿格式。** 编辑器序列化会成为产品存储义务，第二套草稿格式则会重复拥有恢复与转移逻辑。现有语义 snapshot 已携带 reference 范围，也可扩展到 quote。
+
+**保留来源导航。** 可用性检查需要来源坐标、订阅、历史分页、焦点路由和失败状态。未来若添加导航功能，必须先定义其持久坐标与目标拥有的操作。
+
+**存储 UserText 节点或 callback。** 文本节点是派生的展示，callback 是 runtime 状态；二者都可以独立于记录的输入和语义草稿变化。
+
+## 验证
+
+Composer 测试覆盖原子删除与撤销、语义存储往返、Markdown 序列化和发送失败恢复。UserText 测试覆盖文本识别、字面摘录展示、字面 reference 与凭据原文。无密钥 Web 场景通过已发布组合验证选区、截断预览、草稿切换与刷新、持久化和普通 Markdown 提交。
+
+## 后果
+
+草稿与 Session 保留足以支持原子编辑和 replay 的数据，不保留对来源历史的依赖。UserText 仍是展示投影；其 JSON 节点不会替代权威 content。浏览器本地存储按现有草稿策略保留未发送的所选文本。
diff --git a/.agents/notes/implemented/feature/2026-08-28-auto-review.i18n.yaml b/.agents/notes/implemented/feature/2026-08-28-auto-review.i18n.yaml
index 7a93249b1a..f50ce14bc9 100644
--- a/.agents/notes/implemented/feature/2026-08-28-auto-review.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-08-28-auto-review.i18n.yaml
@@ -15,8 +15,8 @@
en: db0a2deb9193a00d
zh: dab5a65b88957464
/agent-note-experimental-auto-review-before-each-tool-call/decision/one-complete-reviewer-request:
- en: 3a07a59b6c5ec26c
- zh: e4f3290dc6d26368
+ en: 7bd9fef90e8639b9
+ zh: e2a096885c9c1e83
/agent-note-experimental-auto-review-before-each-tool-call/decision/result-and-cancellation:
en: 647fe68c52b907e0
zh: 267a739bad44ad65
diff --git a/.agents/notes/implemented/feature/2026-08-28-auto-review.md b/.agents/notes/implemented/feature/2026-08-28-auto-review.md
index 66981180c1..9434c92f41 100644
--- a/.agents/notes/implemented/feature/2026-08-28-auto-review.md
+++ b/.agents/notes/implemented/feature/2026-08-28-auto-review.md
@@ -30,19 +30,20 @@ The reviewer derives authority from existing Session facts. Text with `source.ki
### One complete reviewer request
-The integration uses only the latest `request/header.config` provider/model and the shipped adapter's default reasoning. It neither compares redundant route metadata nor copies the main agent's request. The request has five fixed partitions:
+The integration uses only the latest `request/header.config` provider/model and the shipped adapter's default reasoning. It neither compares redundant route metadata nor copies the main agent's request. The request is a fixed system prompt followed by user messages:
-| Partition | Retained input |
+| Part | Retained input |
| --- | --- |
-| `REVIEW_POLICY` | Fixed classification, source authority, and strict result rules; allow executes immediately with Full access and no later confirmation |
-| `ENVIRONMENT` | Existing Session header `cwd` only |
-| `PROJECT_INSTRUCTIONS` | Visible project instructions with their original sources and constraint role |
-| `FILTERED_HISTORY` | Current compaction surface's sourced user/direct-parent messages, checkpoints, image/attachment facts, and historical call names with logged arguments |
-| `PENDING_ACTION` | Tool name, description, parameter schema, and parsed arguments |
+| System prompt `REVIEW_POLICY` | Fixed classification, source authority, message layout, and strict result rules; allow executes immediately with Full access and no later confirmation |
+| First user message `ENVIRONMENT` | Existing Session header `cwd` only |
+| One user message per retained item | Current compaction surface's sourced user/direct-parent messages, project instructions with the constraint role, checkpoints, image/attachment facts, historical call names with logged arguments, and a `tool-schema` item before the first call that used each reviewed schema, in surface order |
+| Final user message | The pending call with its logged arguments; the latest earlier `tool-schema` item with its mode and name gives the tool description and parameter schema |
-The reviewer builds those two action sections from the Session's complete action history: an authorization is the earlier call the `REVIEW_POLICY` source rules make eligible, and a duplicate or conflicting identity has to be visible anywhere in the log rather than inside a recent window, so neither the Session projections nor a bounded read serves the decision. The read is the deprecated synchronous `snapshotEvents()` under a line-scoped `typescript/no-deprecated` waiver.
+Each item is its own message and keeps the same text in later reviews: the pending call becomes a historical call, and the integration remembers, for each live Session, the schema each reviewed call showed so that it reappears at the same position. A review's messages therefore begin with all messages of the previous review. Providers that cache only at message ends, such as OpenAI implicit breakpoints on GPT-5.6 and later, or at a final marker with lookback, such as Anthropic `cache_control`, reuse the previous review; one growing user message let them reuse only the policy. The schema memory is process-local, so the first review after a restart omits earlier schemas and misses the cache once.
-The main agent's V3 `system/message` nodes, assistant text/reasoning, and tool results are excluded. The current call must belong to the open step recorded by `step/start`; missing step ownership fails closed. It appears only in `PENDING_ACTION`; an unstarted sibling has no historical call fact. Native schema comes from the latest request header. PTC captures a frozen schema at binding construction and passes it through the scheduler into `ToolExecution`; descriptions and parameter schemas never enter start/settle events or the Session/SDK wire. Missing, inconsistent, or ambiguous action facts reject the call without consulting the live registry. An oversized request fails closed without summarization, truncation, another compaction pass, or a small output-token budget.
+The reviewer builds the history and the pending call from the Session's complete action history: an authorization is the earlier call the `REVIEW_POLICY` source rules make eligible, and a duplicate or conflicting identity has to be visible anywhere in the log rather than inside a recent window, so neither the Session projections nor a bounded read serves the decision. The read is the deprecated synchronous `snapshotEvents()` under a line-scoped `typescript/no-deprecated` waiver.
+
+The main agent's V3 `system/message` nodes, assistant text/reasoning, and tool results are excluded. The current call must belong to the open step recorded by `step/start`; missing step ownership fails closed. It appears only as the final message; an unstarted sibling has no historical call fact. Native schema comes from the latest request header. PTC captures a frozen schema at binding construction and passes it through the scheduler into `ToolExecution`; descriptions and parameter schemas never enter start/settle events or the Session/SDK wire. Missing, inconsistent, or ambiguous action facts reject the call without consulting the live registry. An oversized request fails closed without summarization, truncation, another compaction pass, or a small output-token budget.
### Result and cancellation
diff --git a/.agents/notes/implemented/feature/2026-08-28-auto-review.zh.md b/.agents/notes/implemented/feature/2026-08-28-auto-review.zh.md
index a585142928..5ba7a8b39c 100644
--- a/.agents/notes/implemented/feature/2026-08-28-auto-review.zh.md
+++ b/.agents/notes/implemented/feature/2026-08-28-auto-review.zh.md
@@ -30,19 +30,20 @@ Reviewer 从既有 Session 事实派生权威。`source.kind === 'user'` 的文
### 一次完整 reviewer 请求
-Integration 只使用最新 `request/header.config` 的 provider／model 与 shipped adapter 默认 reasoning。它既不比较冗余 route metadata，也不复制主 agent 请求。请求固定包含五个分区：
+Integration 只使用最新 `request/header.config` 的 provider／model 与 shipped adapter 默认 reasoning。它既不比较冗余 route metadata，也不复制主 agent 请求。请求由固定 system prompt 和其后的 user 消息组成：
-| 分区 | 保留输入 |
+| 部分 | 保留输入 |
| --- | --- |
-| `REVIEW_POLICY` | 固定分类、来源权威与严格结果规则；allow 后立即以 Full access 执行，没有后续确认 |
-| `ENVIRONMENT` | 仅既有 Session header `cwd` |
-| `PROJECT_INSTRUCTIONS` | 可见项目指令，保留原始来源并赋予约束角色 |
-| `FILTERED_HISTORY` | 当前 compaction surface 中带来源的用户／直接父级消息、checkpoint、图片／附件事实，以及历史调用名称与日志参数 |
-| `PENDING_ACTION` | 工具名称、描述、参数 schema 与解析后的 arguments |
+| System prompt `REVIEW_POLICY` | 固定分类、来源权威、消息布局与严格结果规则；allow 后立即以 Full access 执行，没有后续确认 |
+| 第一条 user 消息 `ENVIRONMENT` | 仅既有 Session header `cwd` |
+| 每个保留条目一条 user 消息 | 当前 compaction surface 中带来源的用户／直接父级消息、带约束角色的项目指令、checkpoint、图片／附件事实、历史调用名称与日志参数，以及在首次使用某个已审 schema 的调用之前出现的 `tool-schema` 条目，按 surface 顺序排列 |
+| 最后一条 user 消息 | 待审调用及其日志参数；其之前同 mode 与名称的最新 `tool-schema` 条目给出工具描述与参数 schema |
-reviewer 从 Session 的完整动作历史构建这两个动作分节：授权是符合 `REVIEW_POLICY` 来源规则的那个更早调用，而重复或冲突的身份必须在整份日志的任何位置都可见，而不是只在近期窗口内可见，因此 Session 投影与有界读取都无法支撑该判定。这次读取使用已废弃的同步 `snapshotEvents()`，并带有行级 `typescript/no-deprecated` 豁免。
+每个条目各占一条消息，并在后续评审中保持相同文本：待审调用会变成历史调用，integration 为每个存活 Session 记住每次已审调用展示的 schema，使其在同一位置再次出现。因此一次评审的消息以上一次评审的全部消息开头。只在消息结尾缓存的 provider（如 GPT-5.6 及以后的 OpenAI 隐式断点），或在末尾标记处向前回溯的 provider（如 Anthropic `cache_control`），都能复用上一次评审；单条不断增长的 user 消息只能让它们复用策略。Schema 记忆只在进程内，因此重启后的第一次评审会缺少先前的 schema，并有一次缓存未命中。
-主 agent 的 V3 `system/message` 节点、assistant 正文／reasoning 与 tool results 全部排除。当前调用必须属于 `step/start` 记录的开放 step；缺少 step 归属时拒绝执行。该调用只在 `PENDING_ACTION` 出现；尚未开始的 sibling 没有历史调用事实。原生 schema 来自最新 request header。PTC 在 binding 构造时捕获冻结 schema，经由调度器传入 `ToolExecution`；描述与参数 schema 不进入开始／结算事件或 Session／SDK wire。动作事实缺失、不一致或有歧义时拒绝调用，不查询 live registry。超窗请求直接拒绝，不做摘要、截断、额外 compaction 或设置小型输出 token 预算。
+reviewer 从 Session 的完整动作历史构建历史与待审调用：授权是符合 `REVIEW_POLICY` 来源规则的那个更早调用，而重复或冲突的身份必须在整份日志的任何位置都可见，而不是只在近期窗口内可见，因此 Session 投影与有界读取都无法支撑该判定。这次读取使用已废弃的同步 `snapshotEvents()`，并带有行级 `typescript/no-deprecated` 豁免。
+
+主 agent 的 V3 `system/message` 节点、assistant 正文／reasoning 与 tool results 全部排除。当前调用必须属于 `step/start` 记录的开放 step；缺少 step 归属时拒绝执行。该调用只作为最后一条消息出现；尚未开始的 sibling 没有历史调用事实。原生 schema 来自最新 request header。PTC 在 binding 构造时捕获冻结 schema，经由调度器传入 `ToolExecution`；描述与参数 schema 不进入开始／结算事件或 Session／SDK wire。动作事实缺失、不一致或有歧义时拒绝调用，不查询 live registry。超窗请求直接拒绝，不做摘要、截断、额外 compaction 或设置小型输出 token 预算。
### 结果与取消
diff --git a/.agents/notes/implemented/feature/2026-10-13-web-install-icons-and-launch-display.i18n.yaml b/.agents/notes/implemented/feature/2026-10-13-web-install-icons-and-launch-display.i18n.yaml
new file mode 100644
index 0000000000..6b05794b2c
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-10-13-web-install-icons-and-launch-display.i18n.yaml
@@ -0,0 +1,19 @@
+# Bilingual-pair consistency record for 2026-10-13-web-install-icons-and-launch-display.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-10-13-web-install-icons-and-launch-display.md
+/agent-note-web-install-icons-and-launch-display:
+ en: 99458c7724588fd3
+ zh: 1af39a382e1a8b6a
+/agent-note-web-install-icons-and-launch-display/problem:
+ en: 726b732fcaf49153
+ zh: b04aad2d0a65a42d
+/agent-note-web-install-icons-and-launch-display/decision:
+ en: 65c6eb6a3ad5ab30
+ zh: 46ca48685f38269c
+/agent-note-web-install-icons-and-launch-display/alternatives-considered:
+ en: 588d709bd7c8c95b
+ zh: 871b618b86247926
+/agent-note-web-install-icons-and-launch-display/consequences:
+ en: 79695897b5237603
+ zh: b61304c9527e8dfc
diff --git a/.agents/notes/implemented/feature/2026-10-13-web-install-icons-and-launch-display.md b/.agents/notes/implemented/feature/2026-10-13-web-install-icons-and-launch-display.md
new file mode 100644
index 0000000000..69ea6b05ae
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-10-13-web-install-icons-and-launch-display.md
@@ -0,0 +1,41 @@
+# Agent Note: Web install icons and launch display
+
+Status: implemented
+
+English | [中文](2026-10-13-web-install-icons-and-launch-display.zh.md)
+
+## Problem
+
+A launcher masks the icon it puts on the home screen and chooses that icon itself. The install manifest advertised the whale favicon: an SVG mark drawn edge to edge on a transparent canvas, with no tile and no background of its own. Handed to a mask, the mark loses its fins and fills the tile at the wrong proportion. iOS reads no manifest icon at all and had no `apple-touch-icon` to fall back on, so an installed web app showed a generic tile. The manifest also requested `display: "fullscreen"`, which removes both system bars on Android and leaves a chat surface with no clock, battery, or navigation.
+
+## Decision
+
+`apps/web/public/` carries four install icons: a 192px and a 512px `any` raster, a 512px `maskable` raster, and a 180px `apple-touch-icon`. [`render-app-icons.ts`](../../../../apps/web/scripts/render-app-icons.ts) renders all four from the official application tile in `apps/desktop/resources/icon.svg`, and `pnpm --filter @deepseek-ai/dsh-web-frontend run render:app-icons` regenerates the committed files. Each variant preserves the whale's geometry, gradients, opacity, and filters. Rendering first produces a bitmap at no less than the 1024px source extent and four times the output edge, then reduces it with Lanczos3. This separate rasterization retains the original shading while smoothing the small icon's curves. Every variant crops the tile's desktop drop shadow. The maskable variant scales the whale about the tile centre by `MASKABLE_ARTWORK_SCALE` while the tile's gradient keeps its own extent, so the border a mask may crop is still the real tile rather than a flat colour meeting it at a seam.
+
+[`pwa-manifest.e2e.ts`](../../../../apps/web/tests/pwa-manifest.e2e.ts) uses the browser image decoder to measure the committed maskable whale’s ink radius and rejects artwork outside the platform safe zone or smaller than the intended scale. The unscaled tile exceeds that zone and serves as the negative control.
+
+The manifest requests `display: "standalone"`, names `#ffffff` as its `theme_color` and `background_color`, and lists the three rasters. `apps/web/index.html` adds the `apple-touch-icon` link, `mobile-web-app-capable`, and `apple-mobile-web-app-title`. It adds no `theme-color`: `ThemePresenter` owns the single such node and follows the resolved in-application theme, which a static media query cannot. The tab favicons are unchanged.
+
+This supersedes the icon entry and the display mode in the [archived Web install manifest note](../../archived/feature/2026-08-06-web-install-manifest.md); its link to the manifest, product name, compact name, and root identity remain current.
+
+## Alternatives considered
+
+**Keep `favicon.svg` as the only icon.** It leaves iOS, which reads no manifest icon, with a generic tile, and the mark already reaches its own edges, so a launcher's mask crops it. `pwa-manifest.e2e.ts` keeps the unscaled tile’s overflow as its browser-pixel negative control.
+
+**Commit the rasters without a generator.** The tile artwork moves with the desktop application's icon. A hand-exported set drifts silently and records neither the crop nor the safe-zone scale that makes it installable.
+
+**Draw a separate browser mark.** The product has one approved tile. A second mark would need designer approval and would not match the installed desktop application beside it.
+
+**Keep `display: "fullscreen"`.** Hiding both system bars suits an immersive surface, not a conversation the user reads beside the clock and returns to from the app switcher; `fullscreen` also offers no way back to the bars without a swipe.
+
+**Ship a service worker for offline start.** Installation, launch, and reconnect work without one. Offline use is a separate capability with its own cache-invalidation contract, and no current requirement asks for it.
+
+## Consequences
+
+The repository carries four committed rasters, all rendered by one script from `apps/desktop/resources/icon.svg`. Changing the desktop tile means rerunning that script and reviewing the PNG diff. Unit tests inspect committed PNG dimensions without loading the native renderer. Browser tests execute the generator and decode its output and all four built PNGs, checking declared edges, opaque corners, and artwork extents against the source tile with a two-pixel rasterization tolerance. Maskable checks bound its artwork above and below, with the unscaled tile as the safe-zone negative control. Tests also compare fractional coverage along the Apple icon’s curves against direct small-size SVG rendering, which retains the source’s hard pixel edges.
+
+The manifest's `theme_color` is one value and cannot follow the in-application theme, so a user whose theme differs from the system scheme sees that value until `ThemePresenter` writes the synchronized node shortly after boot. The presenter stays the only owner of `meta[name="theme-color"]`: a second static node wins document order and desynchronizes surrounding browser chrome from the rendered palette, which `settings-chrome.e2e.ts` pins.
+
+iOS ignores `background_color` and masks the touch icon with its own rounded rectangle; the tile's own margins keep the whale clear of that mask. Android selects the maskable raster for the home screen and an `any` raster for the install surface. The install icons are not a service worker: an installed Web App still needs the Host reachable.
+
+Real-device installation, launch display, and window mode remain a device check.
diff --git a/.agents/notes/implemented/feature/2026-10-13-web-install-icons-and-launch-display.zh.md b/.agents/notes/implemented/feature/2026-10-13-web-install-icons-and-launch-display.zh.md
new file mode 100644
index 0000000000..dbb77d24dc
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-10-13-web-install-icons-and-launch-display.zh.md
@@ -0,0 +1,41 @@
+# Agent Note: Web 安装图标与启动显示
+
+Status: implemented
+
+[English](2026-10-13-web-install-icons-and-launch-display.md) | 中文
+
+## Problem
+
+启动器会自行选择放到桌面上的图标，并对它套用蒙层。安装 manifest 使用的却是鲸鱼 favicon：一个铺满整张画布、背景透明的 SVG 标记，既没有底板，也没有自己的背景。交给蒙层后，标记会丢掉尾鳍，并且以错误的比例填满图标。iOS 完全不读 manifest 图标，此前又没有 `apple-touch-icon` 可回退，因此安装后的 web app 只显示通用图标。manifest 还请求了 `display: "fullscreen"`，这在 Android 上会同时移除两条系统栏，让一个对话界面失去时钟、电量和导航。
+
+## Decision
+
+`apps/web/public/` 承载四个安装图标：192px 与 512px 的 `any` 位图、512px 的 `maskable` 位图，以及 180px 的 `apple-touch-icon`。[`render-app-icons.ts`](../../../../apps/web/scripts/render-app-icons.ts) 从 `apps/desktop/resources/icon.svg` 的官方应用底板渲染这四个文件，`pnpm --filter @deepseek-ai/dsh-web-frontend run render:app-icons` 重新生成已提交的文件。每个变体都保留鲸鱼的几何路径、渐变、透明度和滤镜。渲染先生成不小于源图 1024px、且边长至少为输出尺寸四倍的位图，再以 Lanczos3 下采样。分开的栅格化步骤在平滑小图标曲线的同时保留原有明暗细节。每个变体都会裁掉底板的桌面投影。maskable 变体围绕底板中心按 `MASKABLE_ARTWORK_SCALE` 缩放鲸鱼，而底板渐变保持自身范围，因此可能被蒙层裁掉的那圈边框仍是真实底板，而不是与其相接的纯色。
+
+[`pwa-manifest.e2e.ts`](../../../../apps/web/tests/pwa-manifest.e2e.ts) 使用浏览器图像解码器测量已提交 maskable 图标的鲸鱼墨迹半径，拒绝越出平台安全区或小于预期比例的图案。未缩放图块超出该安全区，用作反向对照。
+
+manifest 请求 `display: "standalone"`，把 `theme_color` 与 `background_color` 定为 `#ffffff`，并列出三个位图。`apps/web/index.html` 增加 `apple-touch-icon` 链接、`mobile-web-app-capable` 与 `apple-mobile-web-app-title`。它不添加 `theme-color`：该节点由 `ThemePresenter` 独占并跟随解析后的应用内主题，这是静态媒体查询做不到的。标签页 favicon 保持不变。
+
+本决策取代[已归档的 Web 安装 manifest 记录](../../archived/feature/2026-08-06-web-install-manifest.md)中的图标条目与显示模式；其指向 manifest 的链接、产品名、简称与根路径身份仍然有效。
+
+## Alternatives considered
+
+**只保留 `favicon.svg` 作为图标。** 这会让不读 manifest 图标的 iOS 只显示通用图标，而该标记已经抵达自身边界，启动器的蒙层必然裁切它。`pwa-manifest.e2e.ts` 把未缩放图块的越界保留为浏览器像素反向对照。
+
+**不使用生成器，直接提交位图。** 底板素材随桌面应用图标变化。手工导出的图标集会静默漂移，也无法记录使其可安装的裁剪方式与安全区缩放。
+
+**另画一个浏览器专用标记。** 产品只有一个已批准的底板。第二个标记需要设计师批准，并且无法与旁边已安装的桌面应用保持一致。
+
+**保留 `display: "fullscreen"`。** 隐藏两条系统栏适合沉浸式界面，而不适合用户对着时钟阅读、并从应用切换器返回的对话；`fullscreen` 也无法在不滑动的情况下恢复系统栏。
+
+**为离线启动引入 service worker。** 安装、启动与重连都不需要它。离线使用是独立能力，有自己的缓存失效约定，当前没有需求要求它。
+
+## Consequences
+
+仓库携带四张已提交的栅格图，均由同一个脚本从 `apps/desktop/resources/icon.svg` 渲染。桌面图块变化时，需要重新运行该脚本并审查 PNG diff。单元测试直接检查已提交 PNG 的尺寸，不加载原生渲染器。浏览器测试执行生成器，并解码生成结果和全部四张构建后的 PNG，以两个像素的栅格化容差检查声明边长、不透明角落及相对于源图块的图案范围。maskable 检查同时限制图案范围的上界和下界，并以未缩放图块作为安全区反向对照。测试也将 Apple 图标曲线边缘的部分像素覆盖与直接小尺寸渲染的 SVG 对比；后者保留源图的硬像素边缘。
+
+manifest 的 `theme_color` 是单个值，无法跟随应用内主题；因此当用户选择的主题与系统方案不同时，该值会一直生效，直到 `ThemePresenter` 在启动后不久写入同步节点。该 presenter 仍是 `meta[name="theme-color"]` 的唯一所有者：第二个静态节点会在文档顺序上胜出，使周边浏览器界面与已渲染的配色脱节，这一点由 `settings-chrome.e2e.ts` 固定。
+
+iOS 忽略 `background_color`，并用自己的圆角矩形裁切触摸图标；底板自带的留白使鲸鱼避开该蒙层。Android 为桌面选择 maskable 位图，为安装界面选择 `any` 位图。安装图标不是 service worker：安装后的 Web App 仍要求 Host 可达。
+
+真机安装、启动显示与窗口模式仍属设备检查。
diff --git a/.agents/notes/implemented/feature/2026-10-15-deepseek-search-fetch-api.i18n.yaml b/.agents/notes/implemented/feature/2026-10-15-deepseek-search-fetch-api.i18n.yaml
index d928cbf9b4..dea1cb8a9f 100644
--- a/.agents/notes/implemented/feature/2026-10-15-deepseek-search-fetch-api.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-10-15-deepseek-search-fetch-api.i18n.yaml
@@ -18,8 +18,8 @@
en: ad7b3e4fbe528cf2
zh: 8ab8779bfdaaa4fa
/agent-note-direct-deepseek-search-and-fetch-apis/decision/fetch-metadata-and-ownership:
- en: 8051417b08739ed0
- zh: c11d35a346014436
+ en: 7566e400f9ab3a51
+ zh: 118b2e84d0030480
/agent-note-direct-deepseek-search-and-fetch-apis/decision/default-migration:
en: d5a8e36b545f1c04
zh: d741fd0789401c62
diff --git a/.agents/notes/implemented/feature/2026-10-15-deepseek-search-fetch-api.md b/.agents/notes/implemented/feature/2026-10-15-deepseek-search-fetch-api.md
index 5e32e17786..4369faee79 100644
--- a/.agents/notes/implemented/feature/2026-10-15-deepseek-search-fetch-api.md
+++ b/.agents/notes/implemented/feature/2026-10-15-deepseek-search-fetch-api.md
@@ -32,7 +32,7 @@ Direct retrieval emits no auxiliary model-request event because Harness makes no
Fetch sends a URL and returns Markdown without an extra Harness summarization request. The API supplies neither a final redirected URL nor a target HTTP status, and the shared result has no title field. The provider keeps the requested URL, returns the Markdown body, and reports HTTP 200 for a successful response: the Fetch API answers 404 when the URL is unavailable, blocked by site policy, or returns an error, or when no Markdown can be extracted. On 2026-10-16 an unresolvable host returned HTTP 500 instead, so every non-success status is a retrieval failure rather than a specific target diagnosis. The shared fetch result and its consumers stay unchanged.
-The HTTP provider retains its own public-address validation, connection pinning, and resource limits. Selecting DeepSeek delegates page retrieval and target access policy to that service; Harness rejects redirects of the API request and retains cancellation and bounded tool output. The reported HTTP 200 therefore means the service retrieved the page, not that Harness observed the target response. The guide's Fetch 403 means crawler-policy rejection, while 404 means no usable page content.
+The HTTP provider retains its own URL validation and resource limits. Selecting DeepSeek delegates page retrieval and target access policy to that service; Harness rejects redirects of the API request and retains cancellation and bounded tool output. The reported HTTP 200 therefore means the service retrieved the page, not that Harness observed the target response. The guide's Fetch 403 means crawler-policy rejection, while 404 means no usable page content.
### Default migration
diff --git a/.agents/notes/implemented/feature/2026-10-15-deepseek-search-fetch-api.zh.md b/.agents/notes/implemented/feature/2026-10-15-deepseek-search-fetch-api.zh.md
index c974ebd371..0b736cb445 100644
--- a/.agents/notes/implemented/feature/2026-10-15-deepseek-search-fetch-api.zh.md
+++ b/.agents/notes/implemented/feature/2026-10-15-deepseek-search-fetch-api.zh.md
@@ -32,7 +32,7 @@ Status: implemented
Fetch 发送 URL，返回 Markdown，无需 Harness 额外发起摘要请求。API 既不提供重定向后的最终 URL，也不提供目标 HTTP 状态，而共享结果没有标题字段。提供方保留请求 URL，返回 Markdown 正文，并对成功响应报告 HTTP 200：URL 不可用、被站点策略拦截、目标站点返回错误或无法提取 Markdown 时，Fetch API 会返回 404。2026-10-16 无法解析的主机实际返回 HTTP 500，因此任何非成功状态都视为抓取失败，而不是对目标的具体诊断。共享抓取结果及其消费方保持不变。
-HTTP 提供方继续负责自身的公开地址校验、连接固定和资源限制。选择 DeepSeek 会将页面抓取与目标访问策略交给该服务；Harness 拒绝 API 请求重定向，并保留取消与工具输出限额。因此报告的 HTTP 200 表示服务已获取页面，而不是 Harness 观察到了目标响应。指南中的 Fetch 403 表示抓取器策略拒绝，404 则表示没有可用的页面内容。
+HTTP 提供方继续负责自身的 URL 校验和资源限制。选择 DeepSeek 会将页面抓取与目标访问策略交给该服务；Harness 拒绝 API 请求重定向，并保留取消与工具输出限额。因此报告的 HTTP 200 表示服务已获取页面，而不是 Harness 观察到了目标响应。指南中的 Fetch 403 表示抓取器策略拒绝，404 则表示没有可用的页面内容。
### 默认值迁移
diff --git a/.agents/notes/implemented/feature/2026-10-21-composer-image-upload-on-add.i18n.yaml b/.agents/notes/implemented/feature/2026-10-21-composer-image-upload-on-add.i18n.yaml
new file mode 100644
index 0000000000..3d86d265aa
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-10-21-composer-image-upload-on-add.i18n.yaml
@@ -0,0 +1,25 @@
+# Bilingual-pair consistency record for 2026-10-21-composer-image-upload-on-add.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-10-21-composer-image-upload-on-add.md
+/agent-note-composer-image-upload-on-add:
+ en: 996b39b53086b9ac
+ zh: c81fade50ac895ec
+/agent-note-composer-image-upload-on-add/problem:
+ en: b184ade2bd353f50
+ zh: 00b97c91df54b310
+/agent-note-composer-image-upload-on-add/decision:
+ en: eada67e3c3d50f47
+ zh: 5fb4f3a5e774e47e
+/agent-note-composer-image-upload-on-add/alternatives-considered:
+ en: afa82b9bce9015f6
+ zh: d088b92c2cb6c622
+/agent-note-composer-image-upload-on-add/consequences:
+ en: 08d1bcb970beb40e
+ zh: f42db4052618c289
+/agent-note-composer-image-upload-on-add/testing:
+ en: f2d2c59272ffcf70
+ zh: 46c933fd2aeb87ea
+/agent-note-composer-image-upload-on-add/related:
+ en: 6eac98f60c3b99f9
+ zh: c1e318e74f44fbb4
diff --git a/.agents/notes/implemented/feature/2026-10-21-composer-image-upload-on-add.md b/.agents/notes/implemented/feature/2026-10-21-composer-image-upload-on-add.md
new file mode 100644
index 0000000000..ae8c509ac7
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-10-21-composer-image-upload-on-add.md
@@ -0,0 +1,36 @@
+# Agent Note: Composer image upload on add
+
+Status: implemented
+
+English | [中文](2026-10-21-composer-image-upload-on-add.zh.md)
+
+## Problem
+
+The Web composer kept image drafts in the browser and base64-encoded each image into `session/prompt` at send time, so the Host received, validated, normalized, and stored image bytes inside prompt admission. Generic files already uploaded when picked ([generic file upload](2026-08-26-generic-file-upload.md)). An image message therefore carried up to the per-message image byte limit in one RPC body, and its send time grew with image size; a composer that waits for the Host to accept a message before clearing it would hold the draft for that whole transfer.
+
+## Decision
+
+An ordinary Session's composer uploads each image draft as soon as it is added, through the same FIFO background-upload queue, Worker carriers, progress, retry, and cancellation that generic files use. The raw upload route takes a `mediaType` query parameter for an image upload; the Host reads at most the smaller of the deployment's per-image and per-message image byte limits, then validates, normalizes, and stores the image with `ctx.attachments.saveImages` exactly as prompt admission would, and stages the normalized image under a receipt for that Session. The prompt cites the receipt in an ordinary file part, so `session/prompt` keeps its wire types; prompt admission resolves the receipt to the stored image, applies the model's image-input check to the prompt, and counts stored images toward `maxImagesPerMessage` and `maxMessageImageBytes` together with encoded ones, each stored image by the bytes of its upload. Send waits until every image draft has a receipt, and a failed image upload turns its thumbnail into a retry control. Commands accept only file receipts, so command submissions keep encoding images inline. A continuable subagent's composer keeps inline images because the Host stages uploads only for ordinary Sessions; SDK and other wire callers may still send encoded images.
+
+## Alternatives considered
+
+- **A dedicated image-receipt prompt part.** Rejected: the receipt already names what was staged, so a second part kind would widen the `session/prompt` wire union, its generated catalogs, and every consumer that switches on parts without changing what the Host admits.
+- **A separate image upload route or Remote method.** Rejected: one route with an explicit `mediaType` parameter reuses Session addressing, carrier selection, progress, and the failure envelope; the exact-bytes Remote fallback has no image caller.
+- **Upload images but normalize them at send.** Rejected: normalization is the expensive part of image admission, so deferring it would keep the send-time cost this change removes.
+
+## Consequences
+
+- Sending an image message transfers only references, and the normalization cost moves to the moment the image is added.
+- Per-image refusals such as an undecodable or oversized image surface when the image is added: the thumbnail names the refusal instead of offering a retry, and Enter repeats it. The model's image-input check and the per-message image count and byte limits still apply at send.
+- Commands accept only file receipts, so a command submission that carries an image waits for the image upload like a message and then encodes the image inline: the image is stored a second time, and its unused receipt lasts until its Session ends.
+- Removing an image while it uploads cancels the upload, and a cancelled upload receives no receipt; an image whose storage had already begun, or whose upload had finished, stays under `DSH_HOME`, which never deletes attachments. On a remote Host the bytes reach the server as soon as the user adds the image.
+- Staged image receipts share the generic files' in-memory lifetime: a Host restart between adding and sending surfaces `FILE_NOT_STAGED`, and the user adds the image again.
+- Image drafts, like file drafts, are not restored after a page reload or after their Session's client scope is released.
+
+## Testing
+
+Host coverage pins image staging through the raw route, the per-image byte bound that stops reading, unsupported types, subagent refusal, command refusal of image receipts, receipt resolution into the admitted image, the image-input check for an uploaded image, the per-message byte limit across receipts, and withheld receipts for uploads cancelled after their last chunk or during storage. Attachment admission coverage pins stored-image pass-through and the combined image count and byte limits. Client coverage pins image upload start, retry, cancellation, the send gate, receipt citation without re-encoding, inline images for drafts without an upload, the rail's progress, retry, and refusal states, and the Enter explanation of a held send.
+
+## Related
+
+The [generic file upload](2026-08-26-generic-file-upload.md) note owns the background-upload queue, carriers, staging lifetime, and file storage that image uploads reuse.
diff --git a/.agents/notes/implemented/feature/2026-10-21-composer-image-upload-on-add.zh.md b/.agents/notes/implemented/feature/2026-10-21-composer-image-upload-on-add.zh.md
new file mode 100644
index 0000000000..bfa887c85b
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-10-21-composer-image-upload-on-add.zh.md
@@ -0,0 +1,36 @@
+# Agent Note: 输入框在加入时上传图片
+
+Status: implemented
+
+[English](2026-10-21-composer-image-upload-on-add.md) | 中文
+
+## 问题
+
+Web 输入框把图片草稿留在浏览器里，发送时才把每张图片 base64 编码进 `session/prompt`，Host 在 prompt 准入时才接收、校验、规整并存储图片字节。通用文件早已在选中时上传（[通用文件上传](2026-08-26-generic-file-upload.zh.md)）。因此一条图片消息要在一个 RPC 请求体里携带最多达到单条消息图片字节上限的数据，发送耗时随图片大小增长；如果输入框要等 Host 接纳消息后才清空，草稿就要在整个传输期间一直保留。
+
+## 决定
+
+普通 Session 的输入框在图片草稿加入时就上传它，复用通用文件的先进先出后台上传队列、Worker 载体、进度、重试与取消。原始上传路由用 `mediaType` 查询参数表示图片上传；Host 最多读取部署配置的单张图片与单条消息图片字节上限中较小的一个，然后按 prompt 准入的同样方式用 `ctx.attachments.saveImages` 校验、规整并存储图片，再以该 Session 的凭证暂存规整后的图片。prompt 在普通文件部分引用该凭证，因此 `session/prompt` 的线上类型不变；prompt 准入把凭证解析为已存储的图片，对这条 prompt 执行模型的图片输入检查，并把已存储图片与编码图片一起计入 `maxImagesPerMessage` 和 `maxMessageImageBytes`，已存储图片按其上传的字节数计入。发送会等到每个图片草稿都取得凭证；图片上传失败时，缩略图变成重试控件。命令只接受文件凭证，所以命令提交仍以内联方式编码图片。continuable 子代理的输入框继续内联图片，因为 Host 只为普通 Session 暂存上传；SDK 和其他线上调用方仍可发送编码图片。
+
+## 考虑过的替代方案
+
+- **专用的图片凭证 prompt 部分。** 已否决：凭证本身已经指明暂存的内容，新增一种部分类型会扩大 `session/prompt` 线上联合类型、它的生成目录以及每个按部分类型分支的消费方，却不改变 Host 准入的内容。
+- **单独的图片上传路由或 Remote 方法。** 已否决：一条带显式 `mediaType` 参数的路由复用了 Session 寻址、载体选择、进度和失败信封；精确字节的 Remote 兜底没有图片调用方。
+- **加入时上传、发送时再规整。** 已否决：规整是图片准入中开销最大的部分，推迟它会保留这次改动要消除的发送耗时。
+
+## 后果
+
+- 发送图片消息只传引用，规整开销移到图片加入的时刻。
+- 无法解码、超过单张上限等逐张拒绝在图片加入时出现：缩略图说明拒绝原因而不提供重试，按 Enter 也会提示同样的原因。模型的图片输入检查以及单条消息的图片数量与总字节上限仍在发送时执行。
+- 命令只接受文件凭证，所以带图片的命令提交也要像消息一样等图片上传完成，再以内联方式编码图片：同一张图会再存储一次，未被引用的凭证一直留到 Session 结束。
+- 图片上传中移除会取消上传，取消的上传不会取得凭证；已开始存储或已上传完成的图片仍留在 `DSH_HOME` 下，附件存储从不删除。Host 在远端时，用户一加入图片，字节就到达服务器。
+- 暂存的图片凭证与通用文件同样只存在内存里：在加入与发送之间重启 Host 会得到 `FILE_NOT_STAGED`，用户需要重新加入图片。
+- 与文件草稿一样，图片草稿在页面刷新后或其 Session 的客户端作用域释放后不会恢复。
+
+## 测试
+
+Host 侧覆盖经原始路由暂存图片、单张字节上限一超出即停止读取、不支持的类型、子代理拒绝、命令拒绝图片凭证、凭证解析为准入后的图片、已上传图片的图片输入检查、多个凭证合计的单条消息字节上限，以及在最后一个分块之后或存储期间取消的上传不签发凭证。附件准入覆盖已存储图片原样通过，以及合并后的图片数量与总字节上限。客户端覆盖图片上传的开始、重试、取消、发送闸门、发送时引用凭证而不重新编码、没有上传的草稿以内联方式发送图片，附件栏的进度、重试与拒绝状态，以及发送被挡住时按 Enter 的说明。
+
+## 相关记录
+
+[通用文件上传](2026-08-26-generic-file-upload.zh.md) 记录负责图片上传所复用的后台上传队列、载体、暂存生命周期与文件存储。
diff --git a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml
index c1501b5647..c870bf9a78 100644
--- a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.i18n.yaml
@@ -9,8 +9,8 @@
en: 4fb1c27a631b32d3
zh: 9dbe9a4b9aadfca9
/agent-note-serial-cross-platform-ci-reference/decision:
- en: c88f606c0749bd67
- zh: b2038b0d92fd8890
+ en: b78b36281749773b
+ zh: c4ed34782577e5e7
/agent-note-serial-cross-platform-ci-reference/alternatives-considered:
en: 3610152c5c4e93af
zh: f4c09d327716f750
diff --git a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md
index 35fa389802..41b6666d6b 100644
--- a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md
+++ b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.md
@@ -16,7 +16,7 @@ Real-kernel sandbox proofs require specific hosted operating systems and archite
## Decision
-[CI](../../../../.github/workflows/ci.yml) (pull-request-only) and [CI master](../../../../.github/workflows/ci-master.yml) (master-push + workflow_dispatch) give pull-request and master-push events complementary responsibilities. Pull requests run Linux, native Windows, [Node compatibility with self-hosted routing under the Linux variable and trust conditions](../../../../.github/workflows/ci.yml), and Python checks; [platform scheduling](../../../../.github/workflows/ci-master.yml) assigns Wine and three Python runtime carriers to master pushes. On a push to `master`, the active references are `serial / linux (self-hosted standby)` on the in-house `vm-backup` pool and `serial / windows (self-hosted standby)` on the in-house `dsh-win-ci` pool — the hot-standby drills that continuously re-prove the failover targets described in the [failover runbook](2026-07-26-ci-failover-runbook.md). There is no standard-hosted `serial / linux` definition; the standard-hosted `serial / macos` remains disabled under `TODO(hosted-serial-ci)` until its portable capacity can be restored. The current `serial / windows` definition is the in-house `dsh-win-ci` standby. The separate job definitions intentionally keep their short checkout, runtime setup, and immutable install sequences visible instead of hiding operating systems behind a matrix or reusable workflow. `workflow_dispatch` is reserved for runner benchmarks.
+[CI](../../../../.github/workflows/ci.yml), [CI Windows](../../../../.github/workflows/ci-windows.yml), and [CI Python](../../../../.github/workflows/ci-python.yml) (pull-request-only) and [CI master](../../../../.github/workflows/ci-master.yml) (master-push + workflow_dispatch) give pull-request and master-push events complementary responsibilities. Pull requests run Linux, native Windows, [Node compatibility with self-hosted routing under the Linux variable and trust conditions](../../../../.github/workflows/ci.yml), and Python checks; [platform scheduling](../../../../.github/workflows/ci-master.yml) assigns Wine and three Python runtime carriers to master pushes. On a push to `master`, the active references are `serial / linux (self-hosted standby)` on the in-house `vm-backup` pool and `serial / windows (self-hosted standby)` on the in-house `dsh-win-ci` pool — the hot-standby drills that continuously re-prove the failover targets described in the [failover runbook](2026-07-26-ci-failover-runbook.md). There is no standard-hosted `serial / linux` definition; the standard-hosted `serial / macos` remains disabled under `TODO(hosted-serial-ci)` until its portable capacity can be restored. The current `serial / windows` definition is the in-house `dsh-win-ci` standby. The separate job definitions intentionally keep their short checkout, runtime setup, and immutable install sequences visible instead of hiding operating systems behind a matrix or reusable workflow. `workflow_dispatch` is reserved for runner benchmarks.
Each reference job runs `pnpm run check:ci` without any shard selector. `DSH_GATE_CONCURRENCY=1` makes the top-level aggregate execute one ready gate at a time; coverage, snapshot replay, built-bin smoke, and publication validation also receive worker counts of one. The reference jobs may run beside one another, but each host's repository gates are serial and complete. Linux installs bubblewrap before replaying snapshots, and Windows enables Developer Mode before installing the symlinked workspace.
diff --git a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md
index 98ab14a3e1..8a725acc3b 100644
--- a/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md
+++ b/.agents/notes/implemented/process/2026-07-21-serial-cross-platform-ci-reference.zh.md
@@ -16,7 +16,7 @@ Status: implemented
## 决策
-[CI](../../../../.github/workflows/ci.yml)（仅 pull request）与 [CI master](../../../../.github/workflows/ci-master.yml)（master 推送 + `workflow_dispatch`）为拉取请求事件与 master 推送事件赋予互补的职责。拉取请求运行 Linux、原生 Windows、[仅在 Linux 变量与信任条件满足时使用自托管路由的 Node 兼容性](../../../../.github/workflows/ci.yml)与 Python 检查；[平台调度](../../../../.github/workflows/ci-master.yml)将 Wine 与三个 Python 运行时载体分配给 master 推送。向 `master` 推送时，当前启用的参考作业是公司自有 `vm-backup` 池上的 `serial / linux (self-hosted standby)` 和 `dsh-win-ci` 池上的 `serial / windows (self-hosted standby)`——这些热备演练持续验证[故障切换手册](2026-07-26-ci-failover-runbook.zh.md)所描述的切换目标。不存在标准托管的 `serial / linux` 定义；标准托管的 `serial / macos` 仍处于禁用状态，并由 `TODO(hosted-serial-ci)` 标记，直到其可移植容量恢复。当前 `serial / windows` 定义是公司自有 `dsh-win-ci` 池的 standby。各自独立的作业定义有意显式保留简短的代码检出、运行时设置和依赖锁定的安装步骤，而不是用矩阵或可复用工作流隐藏操作系统差异。`workflow_dispatch` 仅用于运行器基准测试。
+[CI](../../../../.github/workflows/ci.yml)、[CI Windows](../../../../.github/workflows/ci-windows.yml) 与 [CI Python](../../../../.github/workflows/ci-python.yml)（仅 pull request）与 [CI master](../../../../.github/workflows/ci-master.yml)（master 推送 + `workflow_dispatch`）为拉取请求事件与 master 推送事件赋予互补的职责。拉取请求运行 Linux、原生 Windows、[仅在 Linux 变量与信任条件满足时使用自托管路由的 Node 兼容性](../../../../.github/workflows/ci.yml)与 Python 检查；[平台调度](../../../../.github/workflows/ci-master.yml)将 Wine 与三个 Python 运行时载体分配给 master 推送。向 `master` 推送时，当前启用的参考作业是公司自有 `vm-backup` 池上的 `serial / linux (self-hosted standby)` 和 `dsh-win-ci` 池上的 `serial / windows (self-hosted standby)`——这些热备演练持续验证[故障切换手册](2026-07-26-ci-failover-runbook.zh.md)所描述的切换目标。不存在标准托管的 `serial / linux` 定义；标准托管的 `serial / macos` 仍处于禁用状态，并由 `TODO(hosted-serial-ci)` 标记，直到其可移植容量恢复。当前 `serial / windows` 定义是公司自有 `dsh-win-ci` 池的 standby。各自独立的作业定义有意显式保留简短的代码检出、运行时设置和依赖锁定的安装步骤，而不是用矩阵或可复用工作流隐藏操作系统差异。`workflow_dispatch` 仅用于运行器基准测试。
每个参考作业均在不设置任何分片选择器的情况下运行 `pnpm run check:ci`。`DSH_GATE_CONCURRENCY=1` 使顶层聚合每次只执行一个已经就绪的门禁；覆盖率、快照回放、built-bin 冒烟测试和发布验证的 worker 数量也设为 1。各参考作业可以彼此并行，但每台主机上的仓库门禁都串行运行且完整执行。Linux 在回放快照前安装 bubblewrap，Windows 则在安装采用符号链接的工作区前启用开发人员模式。
diff --git a/.agents/notes/implemented/process/2026-07-26-ci-failover-runbook.i18n.yaml b/.agents/notes/implemented/process/2026-07-26-ci-failover-runbook.i18n.yaml
index d13a9fab6d..907c19c6e6 100644
--- a/.agents/notes/implemented/process/2026-07-26-ci-failover-runbook.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-26-ci-failover-runbook.i18n.yaml
@@ -6,11 +6,11 @@
en: 677b522817e84e2f
zh: f8518a7033b0fd54
/agent-note-ci-failover-runbook-hosted-pools-in-house-pool/problem:
- en: 3ecedc74cceced3b
- zh: f4708f1887d42c61
+ en: bcdd24f3c39d593c
+ zh: 3e576d09c8c3bfd4
/agent-note-ci-failover-runbook-hosted-pools-in-house-pool/decision:
- en: 4a76615718dbc8f0
- zh: f46b885a11d5dd1d
+ en: fed13ca92e488b69
+ zh: 9e5c9cdc118ab84e
/agent-note-ci-failover-runbook-hosted-pools-in-house-pool/decision/release-rehearsals-share-the-linux-switch:
en: 01e74068e0a96375
zh: aa811861ce30cb47
diff --git a/.agents/notes/implemented/process/2026-07-26-ci-failover-runbook.md b/.agents/notes/implemented/process/2026-07-26-ci-failover-runbook.md
index a4be39a582..8c03479ba2 100644
--- a/.agents/notes/implemented/process/2026-07-26-ci-failover-runbook.md
+++ b/.agents/notes/implemented/process/2026-07-26-ci-failover-runbook.md
@@ -6,11 +6,11 @@ English | [中文](2026-07-26-ci-failover-runbook.zh.md)
## Problem
-The three required Linux worker jobs in [CI](../../../../.github/workflows/ci.yml) (`node 24 / static`, `node 24 / coverage`, `node 24 / snapshots and artifacts`) run on the hosted enterprise 32-core pools; the required verdict job that aggregates them (`all checks passed`) runs on standard `ubuntu-latest`; the [native Windows jobs](2026-08-08-native-windows-pull-request-ci.md) run on the hosted `dsh-windows-2025-16core` larger runner. When the enterprise pools degrade — jobs queue indefinitely or the enterprise labels vanish — every open pull request becomes unmergeable, and the ordinary recovery of merging a fix is itself deadlocked behind the very required checks that cannot run. **Scope: two independent switches, one per platform.** `DSH_CI_FAILOVER_LINUX` recovers an enterprise Linux-pool outage (the three required Linux workers plus the `all checks passed` verdict); `DSH_CI_FAILOVER_WINDOWS` recovers a hosted Windows-pool outage (the native Windows jobs). A Linux-pool outage need not retarget Windows jobs and vice versa. The [Node compatibility jobs](../../../../.github/workflows/ci.yml) also follow the Linux switch with isolated setup; the verdict's `node-24-bench`, `python-sdk`, and `python-runtime` dependencies stay on standard hosted runners; in a broader GitHub-hosted capacity failure that also takes out the standard pools, those dependencies still block `all checks passed`. An outage therefore needs a switch any responder with repository write access can throw without merging anything.
+The three required Linux worker jobs in [CI](../../../../.github/workflows/ci.yml) (`node 24 / static`, `node 24 / coverage`, `node 24 / snapshots and artifacts`) run on the hosted enterprise 32-core pools; the required verdict job that aggregates them (`all checks passed`) runs on standard `ubuntu-latest`; the [native Windows jobs](2026-08-08-native-windows-pull-request-ci.md) in [CI Windows](../../../../.github/workflows/ci-windows.yml) run on the hosted `dsh-windows-2025-16core` larger runner. When the enterprise pools degrade — jobs queue indefinitely or the enterprise labels vanish — every open pull request becomes unmergeable, and the ordinary recovery of merging a fix is itself deadlocked behind the very required checks that cannot run. **Scope: two independent switches, one per platform.** `DSH_CI_FAILOVER_LINUX` recovers an enterprise Linux-pool outage (the three required Linux workers plus the `all checks passed`, `windows checks passed`, and `python checks passed` verdicts); `DSH_CI_FAILOVER_WINDOWS` recovers a hosted Windows-pool outage (the native Windows jobs). A Linux-pool outage need not retarget Windows jobs and vice versa. The [Node compatibility jobs](../../../../.github/workflows/ci.yml) also follow the Linux switch with isolated setup; the verdict's `node-24-bench`, `python-sdk`, and `python-runtime` dependencies stay on standard hosted runners, as does CI Python's `python-runtime`; in a broader GitHub-hosted capacity failure that also takes out the standard pools, those dependencies still block the verdicts that require them. An outage therefore needs a switch any responder with repository write access can throw without merging anything.
## Decision
-The three primary Linux jobs (`node-24`, `node-24-coverage`, `node-24-consumers`), the two `node-compat` matrix entries, and `all-checks-passed` resolve through `DSH_CI_FAILOVER_LINUX`; the native Windows jobs resolve through `DSH_CI_FAILOVER_WINDOWS`. A platform switch does not redirect the other platform. Set to `selfhosted` by a repository writer, the applicable trusted jobs select `vm-backup` or `dsh-win-ci`; the `blacksmith` value routes the participating jobs per the [blacksmith failover leg note](2026-09-09-blacksmith-failover-leg.md); unset or any other value retains the workflow-defined hosted fallbacks. Node compatibility jobs require a same-repository, non-fork head and a non-Dependabot author, use isolated runtime setup, and retain the `ubuntu-latest` fallback under unset and non-special values; the blacksmith branch carries none of those predicates. Under the `selfhosted` value, Linux failover bounds snapshot concurrency and skips hosted package-cache restores. The verdict follows its workers so it does not remain queued on an unavailable hosted pool. Each switch is writer-manageable repository state, not a merge, so it works while checks are red. The `serial / linux (self-hosted standby)` and `serial / windows (self-hosted standby)` lanes re-prove the complete unsharded aggregates on master pushes.
+The three primary Linux jobs (`node-24`, `node-24-coverage`, `node-24-consumers`), the two `node-compat` matrix entries, and the `all-checks-passed`, `windows-checks-passed`, and `python-checks-passed` verdicts resolve through `DSH_CI_FAILOVER_LINUX`; the native Windows jobs resolve through `DSH_CI_FAILOVER_WINDOWS`. A platform switch does not redirect the other platform. Set to `selfhosted` by a repository writer, the applicable trusted jobs select `vm-backup` or `dsh-win-ci`; the `blacksmith` value routes the participating jobs per the [blacksmith failover leg note](2026-09-09-blacksmith-failover-leg.md); unset or any other value retains the workflow-defined hosted fallbacks. Node compatibility jobs require a same-repository, non-fork head and a non-Dependabot author, use isolated runtime setup, and retain the `ubuntu-latest` fallback under unset and non-special values; the blacksmith branch carries none of those predicates. Under the `selfhosted` value, Linux failover bounds snapshot concurrency and skips hosted package-cache restores. The three verdict jobs follow the Linux switch so they do not remain queued on an unavailable hosted pool. Each switch is writer-manageable repository state, not a merge, so it works while checks are red. The `serial / linux (self-hosted standby)` and `serial / windows (self-hosted standby)` lanes re-prove the complete unsharded aggregates on master pushes.
The [superseded-CI cancellation policy](../../../../.github/workflows/ci.yml) governs master pushes and manual runs in the same workflow/ref group, including standby drills. Rapid master updates can starve a drill before it reaches a verdict. Use the latest completed standby verdict and check its age and commit before treating it as readiness evidence; a cancelled or merely scheduled run is not proof of readiness.
diff --git a/.agents/notes/implemented/process/2026-07-26-ci-failover-runbook.zh.md b/.agents/notes/implemented/process/2026-07-26-ci-failover-runbook.zh.md
index fafeda5b1d..e72908e3fc 100644
--- a/.agents/notes/implemented/process/2026-07-26-ci-failover-runbook.zh.md
+++ b/.agents/notes/implemented/process/2026-07-26-ci-failover-runbook.zh.md
@@ -6,11 +6,11 @@ Status: implemented
## 问题
-[CI](../../../../.github/workflows/ci.yml) 中三个必需的 Linux 工作作业（`node 24 / static`、`node 24 / coverage`、`node 24 / snapshots and artifacts`）运行在托管的企业级 32 核池上；聚合它们的必需判定作业（`all checks passed`）运行在标准 `ubuntu-latest` 上；[原生 Windows 作业](2026-08-08-native-windows-pull-request-ci.zh.md)运行在托管的 `dsh-windows-2025-16core` 大型运行器上。当企业池发生故障——作业无限排队或企业标签消失——所有开启的拉取请求都无法合并，而"合并一个修复"这一常规恢复手段本身正被那些无法运行的必需检查死锁。**适用范围：两个独立开关，每个平台一个。**`DSH_CI_FAILOVER_LINUX` 恢复企业级 Linux 池故障（三个必需的 Linux 工作作业加 `all checks passed` 判定作业）；`DSH_CI_FAILOVER_WINDOWS` 恢复托管 Windows 池故障（原生 Windows 作业）。Linux 池故障无需重定向 Windows 作业，反之亦然。[Node 兼容性作业](../../../../.github/workflows/ci.yml)也通过隔离设置跟随 Linux 开关；判定作业的 `node-24-bench`、`python-sdk` 和 `python-runtime` 依赖仍留在标准托管运行器上；若更大范围的 GitHub 托管容量故障连标准池一并击倒，这些依赖仍会阻塞 `all checks passed`。因此故障需要一个任何具备仓库写权限的响应者都能在不合并任何代码的情况下触发的开关。
+[CI](../../../../.github/workflows/ci.yml) 中三个必需的 Linux 工作作业（`node 24 / static`、`node 24 / coverage`、`node 24 / snapshots and artifacts`）运行在托管的企业级 32 核池上；聚合它们的必需判定作业（`all checks passed`）运行在标准 `ubuntu-latest` 上；[原生 Windows 作业](2026-08-08-native-windows-pull-request-ci.zh.md)（位于 [CI Windows](../../../../.github/workflows/ci-windows.yml)）运行在托管的 `dsh-windows-2025-16core` 大型运行器上。当企业池发生故障——作业无限排队或企业标签消失——所有开启的拉取请求都无法合并，而"合并一个修复"这一常规恢复手段本身正被那些无法运行的必需检查死锁。**适用范围：两个独立开关，每个平台一个。**`DSH_CI_FAILOVER_LINUX` 恢复企业级 Linux 池故障（三个必需的 Linux 工作作业加 `all checks passed`、`windows checks passed` 与 `python checks passed` 判定作业）；`DSH_CI_FAILOVER_WINDOWS` 恢复托管 Windows 池故障（原生 Windows 作业）。Linux 池故障无需重定向 Windows 作业，反之亦然。[Node 兼容性作业](../../../../.github/workflows/ci.yml)也通过隔离设置跟随 Linux 开关；判定作业的 `node-24-bench`、`python-sdk` 和 `python-runtime` 依赖仍留在标准托管运行器上，CI Python 的 `python-runtime` 也是如此；若更大范围的 GitHub 托管容量故障连标准池一并击倒，这些依赖仍会阻塞要求它们的判定。因此故障需要一个任何具备仓库写权限的响应者都能在不合并任何代码的情况下触发的开关。
## 决策
-三个主要 Linux 作业（`node-24`、`node-24-coverage`、`node-24-consumers`）、两个 `node-compat` 矩阵条目和 `all-checks-passed` 通过 `DSH_CI_FAILOVER_LINUX` 解析；原生 Windows 作业通过 `DSH_CI_FAILOVER_WINDOWS` 解析。一个平台的开关不会重定向另一个平台。仓库写者将变量设为 `selfhosted` 时，适用的可信作业选择 `vm-backup` 或 `dsh-win-ci`；`blacksmith` 取值按 [blacksmith 故障切换支路笔记](2026-09-09-blacksmith-failover-leg.zh.md) 路由参与切换的作业；未设置或任何其它值保留工作流定义的托管回退。Node 兼容性作业要求同仓库且非 fork 的头部以及非 Dependabot 作者，使用隔离运行时设置，并在未设置与非特殊值下保留 `ubuntu-latest` 回退；blacksmith 分支不带上述任何条件。在 `selfhosted` 取值下，Linux 故障切换会限制快照并发，并跳过托管软件包缓存恢复。判定作业跟随工作作业，避免继续在不可用的托管池排队。每个开关都是写者可管理的仓库状态而非一次合并，因此在检查失败时仍然有效。`serial / linux (self-hosted standby)` 与 `serial / windows (self-hosted standby)` 通道在 master 推送上重新验证完整的未分片聚合流程。
+三个主要 Linux 作业（`node-24`、`node-24-coverage`、`node-24-consumers`）、两个 `node-compat` 矩阵条目，以及 `all-checks-passed`、`windows-checks-passed`、`python-checks-passed` 三个判定作业通过 `DSH_CI_FAILOVER_LINUX` 解析；原生 Windows 作业通过 `DSH_CI_FAILOVER_WINDOWS` 解析。一个平台的开关不会重定向另一个平台。仓库写者将变量设为 `selfhosted` 时，适用的可信作业选择 `vm-backup` 或 `dsh-win-ci`；`blacksmith` 取值按 [blacksmith 故障切换支路笔记](2026-09-09-blacksmith-failover-leg.zh.md) 路由参与切换的作业；未设置或任何其它值保留工作流定义的托管回退。Node 兼容性作业要求同仓库且非 fork 的头部以及非 Dependabot 作者，使用隔离运行时设置，并在未设置与非特殊值下保留 `ubuntu-latest` 回退；blacksmith 分支不带上述任何条件。在 `selfhosted` 取值下，Linux 故障切换会限制快照并发，并跳过托管软件包缓存恢复。三个判定作业跟随 Linux 开关，避免继续在不可用的托管池排队。每个开关都是写者可管理的仓库状态而非一次合并，因此在检查失败时仍然有效。`serial / linux (self-hosted standby)` 与 `serial / windows (self-hosted standby)` 通道在 master 推送上重新验证完整的未分片聚合流程。
[被取代 CI 的取消策略](../../../../.github/workflows/ci.yml) 管理同一工作流/引用组内的 master 推送和手动运行，包括热备演练。master 快速更新可能让演练因反复被取消而始终无法得出结论。判断就绪状态时，使用最近一次已完成的热备结论，并核对其时间和提交；已取消或仅被调度的运行不构成就绪证据。
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
index 360ed3d315..8c2c549e30 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.i18n.yaml
@@ -9,11 +9,11 @@
en: 3e229ecf646af866
zh: d358507b1e1d381f
/agent-note-wine-and-native-windows-ci/decision:
- en: 5a74ef2d98f6b4cf
- zh: 4a539303a3cd4ed8
+ en: 1125b44a170f70fb
+ zh: 37838b9da2003651
/agent-note-wine-and-native-windows-ci/alternatives-considered:
- en: f6c5e77fe3f05739
- zh: 8de640d12d3a38c4
+ en: 0e9a322cfc38d313
+ zh: f7bdeb86ba4fea1a
/agent-note-wine-and-native-windows-ci/consequences:
- en: 58069228d4e904c6
- zh: 2601a48b82400903
+ en: 3dc1ae32e0a74331
+ zh: ab0e9d00aad92d62
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
index 478c5a8ba3..cb14645f13 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.md
@@ -14,9 +14,9 @@ A coverage audit found that stale branch state had restored temporary exclusions
The master-only `windows` job in [ci-master.yml](../../../../.github/workflows/ci-master.yml) runs `windows node 24 / wine` on `ubuntu-latest`. It retains the checksum-verified Windows Node, Wine apt and pnpm caches, a hoisted install confined to a workspace snapshot, and the [shared Wine gate script](../../../../scripts/wine-windows-gates.sh) that runs the workspace build and production site. Node distribution transfers use bounded retries; when nodejs.org stalls on the large archive, a range-capable transport mirror resumes the same bytes, but nodejs.org remains the version and SHA-256 authority and the archive is never promoted before that checksum passes. Wine is outside the PR aggregate under the [master-only platform policy](../../../../.github/workflows/ci-master.yml). The [archived Wine experiment](../../archived/process/2026-07-27-wine-windows-gates-experiment.md) preserves its measured trade-offs, while this note owns the current dual topology.
-Every pull request starts three native jobs: `windows-build`, `windows-coverage`, and `windows-native-tests`. Each job enables Developer Mode for workspace symlinks, provisions the repository-pinned pnpm through `pnpm/action-setup`, performs an immutable install without a transferred store archive, and runs its inventory under native PowerShell. The Windows failover variable (`DSH_CI_FAILOVER_WINDOWS`) selects the organization-owned `dsh-windows-2025-16core` runner by default, the in-house pool under `selfhosted`, or Blacksmith runners under `blacksmith` (see the [blacksmith failover leg note](2026-09-09-blacksmith-failover-leg.md)). Blacksmith build and coverage jobs request 16 vCPU; file-serial native tests request 2 vCPU. Per-job deadlines range from 60 to 120 minutes.
+Every pull request starts three native jobs in the separate [CI Windows workflow](../../../../.github/workflows/ci-windows.yml): `windows-build`, `windows-coverage`, and `windows-native-tests`. GitHub re-runs failed jobs only after every job of a run finishes, so a separate workflow lets maintainers re-run a failed Linux job while Windows jobs are still running, and the reverse. Each job enables Developer Mode for workspace symlinks, provisions the repository-pinned pnpm through `pnpm/action-setup`, performs an immutable install without a transferred store archive, and runs its inventory under native PowerShell. The Windows failover variable (`DSH_CI_FAILOVER_WINDOWS`) selects the organization-owned `dsh-windows-2025-16core` runner by default, the in-house pool under `selfhosted`, or Blacksmith runners under `blacksmith` (see the [blacksmith failover leg note](2026-09-09-blacksmith-failover-leg.md)). Blacksmith build and coverage jobs request 16 vCPU; file-serial native tests request 2 vCPU. Per-job deadlines range from 60 to 120 minutes.
-`windows-build` and `windows-native-tests` are dependencies of `all checks passed`; their workspace-build and targeted native-process results are blocking. After its blocking build and production-site checks succeed, `windows-build` runs `check:ci:windows-observational-ready` in the same workspace. This step uses `continue-on-error`, disables fail-fast, and has a 15-minute timeout; failures produce a workflow warning because Linux owns the blocking static, documentation, package, and built-artifact verdicts. The required verdict waits for the step to finish but does not require its diagnostics to pass. `windows-coverage` remains outside aggregate `needs`, so its 100%-per-file result stays red and visible without delaying the verdict.
+`windows-build` and `windows-native-tests` are dependencies of the required `windows checks passed` verdict; their workspace-build and targeted native-process results are blocking. After its blocking build and production-site checks succeed, `windows-build` runs `check:ci:windows-observational-ready` in the same workspace. This step uses `continue-on-error`, disables fail-fast, and has a 15-minute timeout; failures produce a workflow warning because Linux owns the blocking static, documentation, package, and built-artifact verdicts. The required verdict waits for the step to finish but does not require its diagnostics to pass. `windows-coverage` remains outside aggregate `needs`, so its 100%-per-file result stays red and visible without delaying the verdict.
`windows-coverage` runs [in-job partitioned coverage](../../../../scripts/coverage-partitions.ts) without a preceding build, matching the Linux coverage lane: four single-worker instrumented shards beside a two-worker exempt-heavy gate; workspace imports resolve to `src` through the tsconfig paths map, and the lib-consuming suites self-skip on unbuilt checkouts. Both coverage gates raise Vitest's per-test, expect.poll, and hook budgets through `DSH_COVERAGE_TEST_TIMEOUT_MS=90000`. The observational step reuses the successful build, retains the distinct MPA documentation build, starts independent static gates together, and uses CI worker defaults for `publint`, with an eight-worker override on shared self-hosted runners. Its built-bin smoke starts only after every other observational gate settles, including failed gates. The ready aggregate requires a successful prior workspace build; it removes only that build and its internal dependency edges from the shared internal inventory. This keeps bounded real-application startup measurements from competing with tool-catalog, NodeNext, package, and documentation processes. The script-only translation-pairing merge suite runs in the exempt-heavy gate because it imports only `scripts/` sources and child processes; V8 instrumentation contributes no threshold coverage there but magnifies Git-process latency. Lefthook concurrency fixtures retain their outcomes with 30-second case budgets and a 10-second process-ready probe, while the installer allows five seconds for a preempted lock owner to publish its record after exclusive creation. Directory-picker composition gives its debounced config write an explicit 15-second poll budget; workspace-context composition fixtures use a test-owned signal without an unrelated one-second deadline. The LSP sources and the ACL-sandbox sources remain in the Windows denominator: stub-based failure-path suites carry every in-process ACL-sandbox file to 100%, and only the runner entry stays excluded — it executes exclusively as a spawned child outside the instrumented run, its behavior pinned end-to-end by the runner suite. Narrow annotated V8 ignores cover only unreachable branches (peer-platform arms and lifecycle-unreachable guards), with their behavior tests retained on the owning platform.
@@ -36,7 +36,7 @@ Shiki disables lazy TextMate-regex compilation and warms each boot grammar befor
## Alternatives considered
-**Make every native Windows result a dependency of `all checks passed`.** This gives the aggregate the highest-fidelity Windows verdict, but makes every merge wait for coverage and the duplicated observational inventory. Requiring the build and targeted native-process suite retains fast native correctness signals while the other results remain automatic.
+**Make every native Windows result a dependency of `windows checks passed`.** This gives the aggregate the highest-fidelity Windows verdict, but makes every merge wait for coverage and the duplicated observational inventory. Requiring the build and targeted native-process suite retains fast native correctness signals while the other results remain automatic.
**Run only Wine on pull requests.** Wine reaches blocking win32 toolchain branches quickly, but can report green while a real NT, NTFS, PowerShell, process, or addon contract is broken.
@@ -50,7 +50,7 @@ Shiki disables lazy TextMate-regex compilation and warms each boot grammar befor
## Consequences
-Wine provides post-merge toolchain evidence. Native coverage may still be pending or red when `all checks passed` turns green. Observational diagnostics finish inside the required build job. A diagnostic failure leaves the PR check successful; the failed step, workflow warning, and run summary expose the failure.
+Wine provides post-merge toolchain evidence. Native coverage may still be pending or red when `windows checks passed` turns green. Observational diagnostics finish inside the required build job. A diagnostic failure leaves the PR check successful; the failed step, workflow warning, and run summary expose the failure.
Every pull request receives a real NT kernel, NTFS, PowerShell, Windows process, native addon, and supported-source coverage signal. Observational checks reuse the successful build workspace, avoiding a second checkout, dependency installation, and workspace build. Their sequential position extends the build job and can delay the required verdict; it also separates diagnostic processes from compilation. The ready and master aggregates share one internal diagnostic inventory; master retains its own workspace build and full checks.
diff --git a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
index f3c8dc5fff..b999ac8ef8 100644
--- a/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
+++ b/.agents/notes/implemented/process/2026-08-08-native-windows-pull-request-ci.zh.md
@@ -14,9 +14,9 @@ Wine 在 Linux 内核与区分大小写的 ext4 之上采用 hoisted 依赖布
[ci-master.yml](../../../../.github/workflows/ci-master.yml) 中仅 master 触发的 `windows` 作业在 `ubuntu-latest` 上运行 `windows node 24 / wine`。它保留经过校验和验证的 Windows Node、Wine apt 与 pnpm 缓存、仅限工作区快照的 hoisted 安装，以及运行工作区构建与生产网站的[共享 Wine 门禁脚本](../../../../scripts/wine-windows-gates.sh)。Node 分发文件传输采用有界重试；nodejs.org 的大文件传输停滞时，由支持范围请求的传输镜像续传相同字节，但版本和 SHA-256 权威仍属于 nodejs.org，归档通过该校验前绝不会投入使用。根据[仅 master 平台策略](../../../../.github/workflows/ci-master.yml)，Wine 不参与 PR 聚合。[已归档的 Wine 实验](../../archived/process/2026-07-27-wine-windows-gates-experiment.md)保留其实测取舍，而本文负责当前双通道拓扑。
-每个拉取请求都会启动三个原生作业：`windows-build`、`windows-coverage` 和 `windows-native-tests`。每个作业都会为 workspace 符号链接启用开发者模式，通过 `pnpm/action-setup` 提供仓库固定版本的 pnpm，在不传输 store 归档的情况下执行不可变安装，并在原生 PowerShell 下运行自己的清单。Windows 故障切换变量（`DSH_CI_FAILOVER_WINDOWS`）默认选择组织自有的 `dsh-windows-2025-16core` 运行器，在 `selfhosted` 下选择公司内部运行器池，在 `blacksmith` 下选择 Blacksmith 运行器（见 [blacksmith 故障切换支路笔记](2026-09-09-blacksmith-failover-leg.zh.md)）。Blacksmith 构建和覆盖率作业请求 16 vCPU；逐文件串行的原生测试请求 2 vCPU。各作业的截止时间为 60 至 120 分钟。
+每个拉取请求都会在独立的 [CI Windows 工作流](../../../../.github/workflows/ci-windows.yml)中启动三个原生作业：`windows-build`、`windows-coverage` 和 `windows-native-tests`。GitHub 只有在一次运行的所有作业结束后才会重新运行失败的作业，因此独立工作流让维护者能在 Windows 作业仍在运行时重新运行失败的 Linux 作业，反之亦然。每个作业都会为 workspace 符号链接启用开发者模式，通过 `pnpm/action-setup` 提供仓库固定版本的 pnpm，在不传输 store 归档的情况下执行不可变安装，并在原生 PowerShell 下运行自己的清单。Windows 故障切换变量（`DSH_CI_FAILOVER_WINDOWS`）默认选择组织自有的 `dsh-windows-2025-16core` 运行器，在 `selfhosted` 下选择公司内部运行器池，在 `blacksmith` 下选择 Blacksmith 运行器（见 [blacksmith 故障切换支路笔记](2026-09-09-blacksmith-failover-leg.zh.md)）。Blacksmith 构建和覆盖率作业请求 16 vCPU；逐文件串行的原生测试请求 2 vCPU。各作业的截止时间为 60 至 120 分钟。
-`windows-build` 与 `windows-native-tests` 是 `all checks passed` 的依赖项；其工作区构建和定向原生进程结果具有阻断性。阻断性构建和生产网站检查成功后，`windows-build` 在同一工作区运行 `check:ci:windows-observational-ready`。该步骤使用 `continue-on-error`、关闭 fail-fast，并设置 15 分钟超时；失败时会产生工作流警告，因为静态检查、文档、包与构建产物的阻断性判定由 Linux 负责。必需判定会等待该步骤结束，但不要求其诊断通过。`windows-coverage` 仍在聚合流程的 `needs` 之外，因此逐文件 100% 覆盖率结果会保持红灯并可见，却不会延迟判定。
+`windows-build` 与 `windows-native-tests` 是必需判定 `windows checks passed` 的依赖项；其工作区构建和定向原生进程结果具有阻断性。阻断性构建和生产网站检查成功后，`windows-build` 在同一工作区运行 `check:ci:windows-observational-ready`。该步骤使用 `continue-on-error`、关闭 fail-fast，并设置 15 分钟超时；失败时会产生工作流警告，因为静态检查、文档、包与构建产物的阻断性判定由 Linux 负责。必需判定会等待该步骤结束，但不要求其诊断通过。`windows-coverage` 仍在聚合流程的 `needs` 之外，因此逐文件 100% 覆盖率结果会保持红灯并可见，却不会延迟判定。
`windows-coverage` 与 Linux 覆盖率通道一致，不先构建工作区就运行[job 内分区覆盖率](../../../../scripts/coverage-partitions.ts)：4 个单 worker 插桩分片与一个双 worker 的豁免重型门禁并行运行；工作区导入通过 tsconfig paths 映射解析到 `src`，消费构建产物的套件在未构建的检出上会自跳。两项覆盖率门禁都通过 `DSH_COVERAGE_TEST_TIMEOUT_MS=90000` 提高 Vitest 的单测试、expect.poll 与 hook 预算。观测步骤复用成功的构建，保留独立的 MPA 文档构建，一起启动相互独立的静态门禁，并让 `publint` 使用 CI worker 默认值，在共享自托管运行器上覆盖为 8 个 worker。其 built-bin 冒烟测试只在其他所有观测性门禁结算后启动，包括失败的门禁。ready 聚合要求此前已成功构建工作区；它仅从内部共用清单中移除该构建及其内部依赖边。这可避免有界的真实应用启动测量与 tool-catalog、NodeNext、包及文档进程争抢资源。translation-pairing 合并套件只导入 `scripts/` 源码和子进程，因此放入豁免重型套件门禁；V8 插桩不会为它贡献任何阈值覆盖率，却会放大 Git 进程延迟。Lefthook 并发 fixture 保留原有结果，采用 30 秒单用例预算与 10 秒进程就绪探测；安装器则允许被抢占的 lock 持有者在独占创建后用 5 秒发布记录。directory-picker 组合为防抖配置写入提供显式的 15 秒轮询预算；workspace-context 组合 fixture 使用测试自有、没有无关 1 秒截止时间的信号。LSP 源码与 ACL 沙箱源码仍计入 Windows 分母：基于 stub 的失败路径套件把每个进程内 ACL 沙箱文件都带到 100%，只有 runner 入口保持排除——它只作为 spawn 出的子进程在插桩运行之外执行，其行为由 runner 套件端到端钉住。窄范围且带注释的 V8 ignore 只覆盖不可达分支（另一平台专属分支、生命周期内不可达的防御守卫），其行为测试仍保留在所属平台。
@@ -36,7 +36,7 @@ Shiki 会禁用 TextMate 正则的延迟编译，并在用户内容进入保持
## 曾考虑的替代方案
-**让每项原生 Windows 结果都成为 `all checks passed` 的依赖项。** 这会为聚合流程提供保真度最高的 Windows 判定，但也会让每次合并等待覆盖率和重复的观测性清单。要求构建与定向原生进程套件通过，可以保留快速的原生正确性信号，同时继续自动产生其他结果。
+**让每项原生 Windows 结果都成为 `windows checks passed` 的依赖项。** 这会为聚合流程提供保真度最高的 Windows 判定，但也会让每次合并等待覆盖率和重复的观测性清单。要求构建与定向原生进程套件通过，可以保留快速的原生正确性信号，同时继续自动产生其他结果。
**只在拉取请求上运行 Wine。** Wine 能快速触达阻断性 win32 工具链分支，但即使真实 NT、NTFS、PowerShell、进程或原生插件约定已经损坏，也可能报告绿灯。
@@ -50,7 +50,7 @@ Shiki 会禁用 TextMate 正则的延迟编译，并在用户内容进入保持
## 后果
-Wine 提供合并后的工具链证据。`all checks passed` 变绿时，原生覆盖率仍可能处于待处理或红灯状态。观测诊断在必需的构建作业内完成。诊断失败时，PR 检查仍显示成功；失败步骤、工作流警告和运行摘要会展示该失败。
+Wine 提供合并后的工具链证据。`windows checks passed` 变绿时，原生覆盖率仍可能处于待处理或红灯状态。观测诊断在必需的构建作业内完成。诊断失败时，PR 检查仍显示成功；失败步骤、工作流警告和运行摘要会展示该失败。
每个拉取请求都会获得真实 NT 内核、NTFS、PowerShell、Windows 进程、原生插件和受支持源码覆盖率信号。观测检查复用成功构建的工作区，省去第二次检出、依赖安装和工作区构建。顺序执行会延长构建作业，并可能延迟必需判定；它也让诊断进程与编译分开运行。ready 与 master 聚合共用一份内部诊断清单；master 保留自己的工作区构建和完整检查。
diff --git a/.agents/notes/implemented/process/2026-09-06-python-runtime-windows-hosted.i18n.yaml b/.agents/notes/implemented/process/2026-09-06-python-runtime-windows-hosted.i18n.yaml
index 52e1d7fc30..a235ab080c 100644
--- a/.agents/notes/implemented/process/2026-09-06-python-runtime-windows-hosted.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-09-06-python-runtime-windows-hosted.i18n.yaml
@@ -9,8 +9,8 @@
en: 81d36185575e6d77
zh: 19003ab154d93394
/agent-note-windows-python-runtime-ci-stays-on-github-hosted-windows/decision:
- en: 1169dd58149ad6b4
- zh: aeebaf9ca8769de6
+ en: 68aff432bf30d821
+ zh: 6633d254904a39f6
/agent-note-windows-python-runtime-ci-stays-on-github-hosted-windows/alternatives-considered:
en: 817e77f011ea35c8
zh: 2087bc653620a60f
diff --git a/.agents/notes/implemented/process/2026-09-06-python-runtime-windows-hosted.md b/.agents/notes/implemented/process/2026-09-06-python-runtime-windows-hosted.md
index 95b762f224..5f6beafcdc 100644
--- a/.agents/notes/implemented/process/2026-09-06-python-runtime-windows-hosted.md
+++ b/.agents/notes/implemented/process/2026-09-06-python-runtime-windows-hosted.md
@@ -10,7 +10,7 @@ The Windows x64 target in [build-exe-for-python-sdk.yml](../../../../.github/wor
## Decision
-The Windows x64 target always uses its hosted `matrix.runner` — `windows-2025` for pull-request CI — with the standard setup-python toolchain, the pnpm cache restore, and the pkg cache. The failover selector, the job-private Python setup step, the self-hosted dependency install and post-step cleanup, the private setup script, and the routing spec from #3629 are removed. `DSH_CI_FAILOVER_WINDOWS=selfhosted` again retargets only the native Windows jobs in [ci.yml](../../../../.github/workflows/ci.yml); the [failover runbook](2026-07-26-ci-failover-runbook.md) and [python/development.md](../../../../python/development.md) describe hosted-only runtime builds. The migration's UTF-8 mode exports existed because the persistent host used a GBK default code page; hosted images provide the locale the lane previously ran under.
+The Windows x64 target always uses its hosted `matrix.runner` — `windows-2025` for pull-request CI — with the standard setup-python toolchain, the pnpm cache restore, and the pkg cache. The failover selector, the job-private Python setup step, the self-hosted dependency install and post-step cleanup, the private setup script, and the routing spec from #3629 are removed. `DSH_CI_FAILOVER_WINDOWS=selfhosted` again retargets only the native Windows jobs in [ci-windows.yml](../../../../.github/workflows/ci-windows.yml); the [failover runbook](2026-07-26-ci-failover-runbook.md) and [python/development.md](../../../../python/development.md) describe hosted-only runtime builds. The migration's UTF-8 mode exports existed because the persistent host used a GBK default code page; hosted images provide the locale the lane previously ran under.
## Alternatives considered
diff --git a/.agents/notes/implemented/process/2026-09-06-python-runtime-windows-hosted.zh.md b/.agents/notes/implemented/process/2026-09-06-python-runtime-windows-hosted.zh.md
index e3f27788b0..9b06a99150 100644
--- a/.agents/notes/implemented/process/2026-09-06-python-runtime-windows-hosted.zh.md
+++ b/.agents/notes/implemented/process/2026-09-06-python-runtime-windows-hosted.zh.md
@@ -10,7 +10,7 @@ Status: implemented
## 决策
-Windows x64 目标始终使用托管的 `matrix.runner`——PR CI 为 `windows-2025`——配以标准 setup-python 工具链、pnpm 缓存恢复与 pkg 缓存。来自 #3629 的故障切换选择器、作业私有 Python 准备步骤、自托管依赖安装与后置清理、私有准备脚本及路由测试均被移除。`DSH_CI_FAILOVER_WINDOWS=selfhosted` 再次只重定向 [ci.yml](../../../../.github/workflows/ci.yml) 中的原生 Windows 作业；[故障切换手册](2026-07-26-ci-failover-runbook.zh.md)与 [python/development.zh.md](../../../../python/development.zh.md) 描述仅托管的 runtime 构建。迁移中的 UTF-8 模式导出之所以存在，是因为持久主机使用 GBK 默认代码页；托管镜像提供该通道此前运行的区域设置。
+Windows x64 目标始终使用托管的 `matrix.runner`——PR CI 为 `windows-2025`——配以标准 setup-python 工具链、pnpm 缓存恢复与 pkg 缓存。来自 #3629 的故障切换选择器、作业私有 Python 准备步骤、自托管依赖安装与后置清理、私有准备脚本及路由测试均被移除。`DSH_CI_FAILOVER_WINDOWS=selfhosted` 再次只重定向 [ci-windows.yml](../../../../.github/workflows/ci-windows.yml) 中的原生 Windows 作业；[故障切换手册](2026-07-26-ci-failover-runbook.zh.md)与 [python/development.zh.md](../../../../python/development.zh.md) 描述仅托管的 runtime 构建。迁移中的 UTF-8 模式导出之所以存在，是因为持久主机使用 GBK 默认代码页；托管镜像提供该通道此前运行的区域设置。
## 已考虑的替代方案
diff --git a/.agents/notes/implemented/process/2026-09-09-blacksmith-failover-leg.i18n.yaml b/.agents/notes/implemented/process/2026-09-09-blacksmith-failover-leg.i18n.yaml
index be7e6eb89c..585429e528 100644
--- a/.agents/notes/implemented/process/2026-09-09-blacksmith-failover-leg.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-09-09-blacksmith-failover-leg.i18n.yaml
@@ -9,8 +9,8 @@
en: 43ecfec1601f933e
zh: 3db5365403ffeac5
/agent-note-blacksmith-as-a-failover-leg-for-ci-pools/decision:
- en: fac195b5006faa2d
- zh: 7c0ea86638c54e95
+ en: 667aae1665477840
+ zh: ff95c9c5fd9d1793
/agent-note-blacksmith-as-a-failover-leg-for-ci-pools/alternatives-considered:
en: a605440fed0ccc2a
zh: 621b35ad2850ca1b
diff --git a/.agents/notes/implemented/process/2026-09-09-blacksmith-failover-leg.md b/.agents/notes/implemented/process/2026-09-09-blacksmith-failover-leg.md
index 4fb4ed4ccb..1749462cef 100644
--- a/.agents/notes/implemented/process/2026-09-09-blacksmith-failover-leg.md
+++ b/.agents/notes/implemented/process/2026-09-09-blacksmith-failover-leg.md
@@ -12,7 +12,7 @@ The [failover runbook](2026-07-26-ci-failover-runbook.md) routes degraded enterp
`DSH_CI_FAILOVER_LINUX` and `DSH_CI_FAILOVER_WINDOWS` additionally accept the value `blacksmith`. When any repository writer sets it, the platform's participating jobs retarget onto Blacksmith's hosted runners at each job's configured vCPU size; any other value (or unset) keeps today's runner, and `selfhosted` keeps routing to the in-house pools. Like the existing values this is writer-manageable repository state — no merge, re-run the affected jobs — and it costs money only while set, which is why it is an explicit outage or experiment choice, never the default.
-Participating jobs under `blacksmith`: the three enterprise Linux workers, the `node-compat` legs, the `all-checks-passed` verdict, and the three Windows jobs in [ci.yml](../../../../.github/workflows/ci.yml), using the per-job runner sizes declared there; `expected-filenames`; the sandbox bwrap leg; and the two manual benchmark matrices, whose 4-32 vCPU tiers map to Blacksmith equivalents while the 64/96-core rows keep the fleet labels because Blacksmith offers no such tier. The blacksmith branches carry no Dependabot exclusion: Blacksmith runners are ephemeral, so the persistent-VM rationale that keeps Dependabot on the hosted pool does not apply. The python-runtime builder stays hosted in full: its PR and master callers (`ci.yml`'s and `ci-master.yml`'s `python-runtime` jobs) pass real-API credentials (`DEEPSEEK_API_KEY_EXTERNAL`) into the reusable workflow, its macOS and arm64 single-exe legs need GitHub's images, and its wheel output feeds the PyPI publication chain. The docs-pages workflow is a tag-dispatched release publication, so it stays hosted too.
+Participating jobs under `blacksmith`: the three enterprise Linux workers, the `node-compat` legs, and the `all-checks-passed` verdict in [ci.yml](../../../../.github/workflows/ci.yml), plus the three Windows jobs and the `windows-checks-passed` verdict in [ci-windows.yml](../../../../.github/workflows/ci-windows.yml), plus the `python-checks-passed` verdict in [ci-python.yml](../../../../.github/workflows/ci-python.yml), using the per-job runner sizes declared there; `expected-filenames`; the sandbox bwrap leg; and the two manual benchmark matrices, whose 4-32 vCPU tiers map to Blacksmith equivalents while the 64/96-core rows keep the fleet labels because Blacksmith offers no such tier. The blacksmith branches carry no Dependabot exclusion: Blacksmith runners are ephemeral, so the persistent-VM rationale that keeps Dependabot on the hosted pool does not apply. The python-runtime builder stays hosted in full: its PR and master callers (the `python-runtime` jobs in `ci-python.yml` and `ci-master.yml`) pass real-API credentials (`DEEPSEEK_API_KEY_EXTERNAL`) into the reusable workflow, its macOS and arm64 single-exe legs need GitHub's images, and its wheel output feeds the PyPI publication chain. The docs-pages workflow is a tag-dispatched release publication, so it stays hosted too.
Everything else keeps its own runner under every value: jobs pinned to standard hosted runners by workflow spec (`node-24-bench`, `python-sdk`, the master Wine gate, `release-publish` and `release-vendor-publish`, the Cloudflare preview, the weighted-approval pair); jobs that hold credentials (the real-API e2e lanes, the issue App-token jobs, the npm and PyPI publishers); jobs that need a host capability Blacksmith lacks (the Landlock legs and their pack verification, the Seatbelt leg, the linux-arm64 single-exe leg); and the release-shaped chains — the npm publishers, the PyPI publishers, the node-addon-system release chain, and the Pages deployment workflow — which stay entirely hosted because their artifacts feed published registry output. The release rehearsal jobs in `release.yml` and `release-vendor.yml` (`dependencies`, `pack`) keep their existing pre-change routing unchanged: they carry only the pre-existing `selfhosted` branch, so under `blacksmith` they fall back to their hosted `ubuntu-24.04` default exactly as under an unset variable, and they gain no `blacksmith` branch.
diff --git a/.agents/notes/implemented/process/2026-09-09-blacksmith-failover-leg.zh.md b/.agents/notes/implemented/process/2026-09-09-blacksmith-failover-leg.zh.md
index c2c4ee76a3..c110566000 100644
--- a/.agents/notes/implemented/process/2026-09-09-blacksmith-failover-leg.zh.md
+++ b/.agents/notes/implemented/process/2026-09-09-blacksmith-failover-leg.zh.md
@@ -12,7 +12,7 @@ Status: implemented
`DSH_CI_FAILOVER_LINUX` 与 `DSH_CI_FAILOVER_WINDOWS` 额外接受值 `blacksmith`。任何仓库写者设置它时，该平台参与切换的作业按各作业配置的 vCPU 档位重定向到 Blacksmith 托管运行器；任何其它值（或未设置）保持今天的运行器，`selfhosted` 继续路由到自有池。与既有取值一样，这是写者可管理的仓库状态——无需合并，重跑受影响的作业即可——并且只在设置期间产生费用，这正是它作为明确的故障或实验选择、而非默认的原因。
-`blacksmith` 下参与切换的作业：[ci.yml](../../../../.github/workflows/ci.yml) 中三个企业级 Linux 工作作业、`node-compat` 各腿、`all-checks-passed` 判定作业与三个 Windows 作业，使用该工作流为各作业声明的运行器规格；`expected-filenames`；sandbox 的 bwrap 腿；以及两个手动基准矩阵——其 4-32 vCPU 档位映射到 Blacksmith 等价档，64/96 核行保留自有池标签，因为 Blacksmith 没有对应档位。blacksmith 分支不带 Dependabot 排除：Blacksmith 运行器是临时的，因此把 Dependabot 留在托管池的持久虚拟机理由不适用。python-runtime 构建器整体保持托管：其 PR 与 master 调用方（`ci.yml` 与 `ci-master.yml` 的 `python-runtime` 作业）会把真实 API 凭据（`DEEPSEEK_API_KEY_EXTERNAL`）传入该可复用工作流，其 macOS 与 arm64 单文件分支需要 GitHub 镜像，且其 wheel 产物供给 PyPI 发布链。docs-pages 工作流是 tag 派发的发布，因此同样保持托管。
+`blacksmith` 下参与切换的作业：[ci.yml](../../../../.github/workflows/ci.yml) 中三个企业级 Linux 工作作业、`node-compat` 各腿与 `all-checks-passed` 判定作业，以及 [ci-windows.yml](../../../../.github/workflows/ci-windows.yml) 中三个 Windows 作业与 `windows-checks-passed` 判定作业，以及 [ci-python.yml](../../../../.github/workflows/ci-python.yml) 中的 `python-checks-passed` 判定作业，使用这些工作流为各作业声明的运行器规格；`expected-filenames`；sandbox 的 bwrap 腿；以及两个手动基准矩阵——其 4-32 vCPU 档位映射到 Blacksmith 等价档，64/96 核行保留自有池标签，因为 Blacksmith 没有对应档位。blacksmith 分支不带 Dependabot 排除：Blacksmith 运行器是临时的，因此把 Dependabot 留在托管池的持久虚拟机理由不适用。python-runtime 构建器整体保持托管：其 PR 与 master 调用方（`ci-python.yml` 与 `ci-master.yml` 中的 `python-runtime` 作业）会把真实 API 凭据（`DEEPSEEK_API_KEY_EXTERNAL`）传入该可复用工作流，其 macOS 与 arm64 单文件分支需要 GitHub 镜像，且其 wheel 产物供给 PyPI 发布链。docs-pages 工作流是 tag 派发的发布，因此同样保持托管。
其余作业在任何取值下都保留自己的运行器：被 workflow spec 钉死在标准托管运行器上的作业（`node-24-bench`、`python-sdk`、master 的 Wine 门禁、`release-publish` 与 `release-vendor-publish`、Cloudflare preview、weighted-approval 一对）；持有凭据的作业（真实 API 的 e2e 通道、issue App token 作业、npm 与 PyPI 发布作业）；需要 Blacksmith 缺失的宿主能力的作业（Landlock 各腿及其打包校验、Seatbelt 腿、linux-arm64 单文件分支）；以及发布形态的链——npm 发布、PyPI 发布、node-addon-system 发布链与 Pages 部署工作流——它们整体保持托管，因为其产物供给已发布的 registry 输出。`release.yml` 与 `release-vendor.yml` 中的发布演练作业（`dependencies`、`pack`）保持改动前既有的路由不变：它们只带既有的 `selfhosted` 分支，因此在 `blacksmith` 取值下与变量未设置时一样回落到托管的 `ubuntu-24.04` 默认，并不新增 `blacksmith` 分支。
diff --git a/.agents/notes/implemented/process/2026-09-11-persistence-type-history.i18n.yaml b/.agents/notes/implemented/process/2026-09-11-persistence-type-history.i18n.yaml
index 246e224b7f..74cacfcfd5 100644
--- a/.agents/notes/implemented/process/2026-09-11-persistence-type-history.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-09-11-persistence-type-history.i18n.yaml
@@ -9,14 +9,14 @@
en: c8e926bfc65d7195
zh: e0e007960b68fe80
/agent-note-in-tree-persistence-type-history/decision:
- en: 94be3d6c7df3063b
- zh: 7e8fb08d7fd95f85
+ en: 3d4b2935c4db54b2
+ zh: eb0da7083e301ef4
/agent-note-in-tree-persistence-type-history/decision/finalized-checkpoints:
en: b508035a163340a3
zh: ba5b2b7e8cef4b2f
/agent-note-in-tree-persistence-type-history/alternatives-considered:
- en: 1cf6d0a5555ae50a
- zh: 70ea1ba535e09442
+ en: a581d63455788d48
+ zh: 0a3781d2f827e35d
/agent-note-in-tree-persistence-type-history/consequences:
en: 672c8cb59d291dc2
zh: cbec90fbca92320a
diff --git a/.agents/notes/implemented/process/2026-09-11-persistence-type-history.md b/.agents/notes/implemented/process/2026-09-11-persistence-type-history.md
index add0904f42..5c98588230 100644
--- a/.agents/notes/implemented/process/2026-09-11-persistence-type-history.md
+++ b/.agents/notes/implemented/process/2026-09-11-persistence-type-history.md
@@ -16,6 +16,8 @@ One normalized type model supplies the readable persistence catalog, the complet
The dedicated [persistence-change records](../../../../docs/persistence-changes/README.md) bind acknowledgement to the after digest of each affected root. A generated companion stores complete after schemas. The initial record covers all roots; later records name each root's predecessor. A predecessor's after schema supplies the next before schema. Verification rejects ambiguous history and requires current source to match the terminal recorded state without consulting Git history or remote services.
+Every schema file stores one node table keyed by a 16-hexadecimal-digit prefix of each node's canonical subgraph digest; roots and types locate their graphs through their own digests. A type change therefore rewrites only the changed nodes, their ancestors, and the affected digests. Parsers accept only the exact generated text, and all committed files share this layout.
+
Automatic classification permits optional body additions, required-to-optional body changes, and ordinary event additions within one version. The scoped [source-attribution policy](2026-09-17-persistence-schema-review.md) also permits qualified new producer kinds when both saved schemas opt in. The [event-payload version rule](../../../../docs/persistence-changes/README.md#compatibility-rules) admits higher numeric payload versions when every old alternative remains readable and records the older-reader limitation. Other structural changes require an explicit same-version choice in the recording CLI or an increasing header version. Every structural difference needs an acknowledgement; its Compatibility and Verification sections explain both reader directions and executed checks. CI validates saved decisions without inferring how they were authored. The [format-version procedure](../../../../docs/cookbook/adding-a-session-format-version.md) owns adjacent migration work when a bump is required.
The persistence-change document kind preserves compatibility reasoning and evidence for a historical type transition. Agent Notes retain mechanism-level decisions; they do not become a growing inventory of individual acknowledgements. Machine declarations remain identical across the bilingual pair and are parsed once.
@@ -44,6 +46,8 @@ Finalization records acceptance independently of publication. The [status record
**Infer behavior from types or require proof of human review.** A type graph cannot establish replay semantics, and a recorded choice cannot establish how it was authored. The checker validates declared transitions and header-version constraints. Reviewers inspect actual reader behavior and the acknowledgement’s explanation independently.
+**Keep positional node indices or also read the previous layout.** Positional indices renumber every later node when a union gains a variant, and per-root graphs repeat shared types, so a one-variant change rewrote thousands of lines. Digest-keyed nodes keep diffs proportional to the change. Reading two layouts would leave two parsers to maintain and two accepted texts per inventory; migrating every committed file once keeps a single format.
+
## Consequences
Authors retain one snapshot per affected root per accepted transition and resolve history forks when integrating competing changes to that root. Independent roots can advance without rewriting unrelated acknowledgements. The [cookbook](../../../../docs/cookbook/reviewing-persistence-type-changes.md) provides the local authoring and verification procedure.
diff --git a/.agents/notes/implemented/process/2026-09-11-persistence-type-history.zh.md b/.agents/notes/implemented/process/2026-09-11-persistence-type-history.zh.md
index fade8ff41b..dae77a7810 100644
--- a/.agents/notes/implemented/process/2026-09-11-persistence-type-history.zh.md
+++ b/.agents/notes/implemented/process/2026-09-11-persistence-type-history.zh.md
@@ -16,6 +16,8 @@ Status: implemented
专用的[持久化变更记录](../../../../docs/persistence-changes/README.zh.md)将确认绑定到每个受影响根的变更后摘要。生成的伴随文件保存完整的变更后 schema。初始记录覆盖所有根；后续记录为每个根指定前驱。前驱的变更后 schema 提供下一次的变更前 schema。验证拒绝有歧义的历史，并要求当前源码匹配最终记录状态，无需查询 Git 历史或远端服务。
+每个 schema 文件保存一张节点表，以每个节点规范子图摘要的 16 位十六进制前缀为键；根与类型通过各自的摘要定位其图。因此类型变更只改写发生变化的节点、其祖先节点以及受影响的摘要。解析器只接受精确生成的文本，所有已提交文件共用此布局。
+
自动分类允许可选事件体新增、事件体属性从必选改为可选，以及普通事件新增保持同一版本。当双方保存的 schema 均声明支持时，受限的[消息源归属策略](2026-09-17-persistence-schema-review.zh.md)也允许添加符合条件的生产者 kind。[事件载荷版本规则](../../../../docs/persistence-changes/README.zh.md#compatibility-rules)允许在每个旧分支仍可读取时增加更高的数字载荷版本，并记录旧读取器限制。其他结构变更要求在记录 CLI 中显式选择同版本，或递增头版本。每个结构差异都需要确认；其兼容性与验证部分说明两个方向的读取器行为及已执行检查。CI 验证保存的决策，不推断其编写方式。需要升版本时，[格式版本流程](../../../../docs/cookbook/adding-a-session-format-version.zh.md)负责相邻迁移工作。
持久化变更文档类型保留历史类型转换的兼容性说明和证据。Agent Note 保留机制层面的决策，不积累单次确认清单。双语对中的机器声明保持相同，且只解析一次。
@@ -44,6 +46,8 @@ Status: implemented
**从类型推断行为，或要求人类评审证明。** 类型图无法证明回放语义，所记录的选择也无法证明其编写方式。检查器验证声明的转换与头版本约束。评审者独立检查实际读取器行为与确认说明。
+**保留按位置编号的节点索引，或同时读取旧布局。** 联合类型新增分支时，按位置编号的索引会为其后的每个节点重新编号，而逐根图会重复共享类型，因此单个分支变更曾改写数千行。以摘要为键的节点使差异规模与变更成正比。同时读取两种布局需要维护两个解析器，且每个清单会有两种可接受文本；将所有已提交文件一次性迁移后只保留单一格式。
+
## 影响
作者为每次已接受转换中的每个受影响根保留一份快照，并在集成该根的竞争变更时解决历史分叉。独立根可以演进而不改写无关确认。[实操手册](../../../../docs/cookbook/reviewing-persistence-type-changes.zh.md)提供本地编写与验证流程。
diff --git a/.agents/notes/implemented/process/2026-09-15-shipped-optional-bundles.i18n.yaml b/.agents/notes/implemented/process/2026-09-15-shipped-optional-bundles.i18n.yaml
index e3ffc60e70..13804455ce 100644
--- a/.agents/notes/implemented/process/2026-09-15-shipped-optional-bundles.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-09-15-shipped-optional-bundles.i18n.yaml
@@ -9,8 +9,8 @@
en: dc43ba84345e1405
zh: dbc03572ab7710d2
/agent-note-ship-optional-bundles-with-the-installation/decision:
- en: 5210b3b746cfee78
- zh: f1907f4807ae0098
+ en: 1362533f342b31f4
+ zh: 90689262acefb43d
/agent-note-ship-optional-bundles-with-the-installation/alternatives-considered:
en: 95b48b61757f1f13
zh: e9fb2d6ea492a4bc
diff --git a/.agents/notes/implemented/process/2026-09-15-shipped-optional-bundles.md b/.agents/notes/implemented/process/2026-09-15-shipped-optional-bundles.md
index 151cc8ccad..c55de4e8fd 100644
--- a/.agents/notes/implemented/process/2026-09-15-shipped-optional-bundles.md
+++ b/.agents/notes/implemented/process/2026-09-15-shipped-optional-bundles.md
@@ -10,7 +10,7 @@ The Web plugin page manages only the bundles a person installed into the profile
## Decision
-The launcher names in `OPTIONAL_BUNDLES` (`packages/boot/app-boot/src/profile.ts`, beside the profile templates) the bundles the installation ships for a person to switch on. Each must be a runtime dependency of `apps/cli` that declares `dsh.bundle.patch`, and no shipped profile template selects it. The plugin manager's `listBundles` reports such a bundle as `optional`: switched off until selected, never removable, resolved from the installation like any installation-supplied bundle. The Web plugin page opens its Official group with the optional bundles, tagged experimental when the package is experimental, ahead of the profile's own installed bundles.
+The launcher names in `OPTIONAL_BUNDLES` (`packages/boot/app-boot/src/profile.ts`, beside the profile templates) the bundles the installation ships for a person to switch on. Each must be a runtime dependency of `apps/cli` that declares `dsh.bundle.patch`, and no shipped profile template selects it. The plugin manager's `listBundles` reports such a bundle as `optional`: switched off until selected, never removable, resolved from the installation like any installation-supplied bundle. The Web plugin page presents offered optional bundles in its Official group, tagged experimental when the package is experimental, ahead of the profile's own installed bundles. The [persistent-terminal bundle](../../../../packages/experimental/terminal-bundle/README.md) remains available to the Host but has no page switch, even when enabled; its existing profile selection remains intact.
Default-product isolation keeps its rules with one declared exception: an optional bundle's dependency graph is outside the default product. The static gate skips the `dependencies` edge from `@deepseek-ai/dsh` to a listed bundle and still rejects a runtime import, a shipped composition, a preset, or a default template that names it, an experimental dependency the list does not name, and a listed name that is not a runtime dependency or not a bundle. The workspace-constraints check accepts the same `dependencies` edges and no other runtime section, and the packed-install release check skips them from the installed entry package while requiring each listed bundle to be installed.
diff --git a/.agents/notes/implemented/process/2026-09-15-shipped-optional-bundles.zh.md b/.agents/notes/implemented/process/2026-09-15-shipped-optional-bundles.zh.md
index 9ddd54da88..7c82d124ab 100644
--- a/.agents/notes/implemented/process/2026-09-15-shipped-optional-bundles.zh.md
+++ b/.agents/notes/implemented/process/2026-09-15-shipped-optional-bundles.zh.md
@@ -10,7 +10,7 @@ Web 插件页只管理用户装进 profile 的组合包。像 Agent Teams 这样
## 决策
-启动器在 `OPTIONAL_BUNDLES`（`packages/boot/app-boot/src/profile.ts`，与 profile 模板并列）里点名安装随附、供用户开启的组合包。每一个都必须是 `apps/cli` 声明了 `dsh.bundle.patch` 的运行时依赖，且不被任何随附 profile 模板选中。插件管理器的 `listBundles` 把这类组合包报告为 `optional`：选中前保持关闭、永不可卸载、像其他安装提供的组合包一样从安装目录解析。Web 插件页以可选组合包开启「官方」分组，属于实验包的带实验性标签，排在 profile 自己已安装的组合包之前。
+启动器在 `OPTIONAL_BUNDLES`（`packages/boot/app-boot/src/profile.ts`，与 profile 模板并列）里点名安装随附、供用户开启的组合包。每一个都必须是 `apps/cli` 声明了 `dsh.bundle.patch` 的运行时依赖，且不被任何随附 profile 模板选中。插件管理器的 `listBundles` 把这类组合包报告为 `optional`：选中前保持关闭、永不可卸载、像其他安装提供的组合包一样从安装目录解析。Web 插件页在「官方」分组展示可供选择的可选组合包，属于实验包的带实验性标签，排在 profile 自己已安装的组合包之前。[持久终端组合包](../../../../packages/experimental/terminal-bundle/README.zh.md)仍可供 Host 使用，但即使已启用也不提供页面开关；已有的 profile 选择保持不变。
默认产品隔离的规则保持不变，只声明一个例外：可选组合包的依赖图在默认产品之外。静态门禁跳过从 `@deepseek-ai/dsh` 到列表中组合包的 `dependencies` 边，仍然拒绝运行时 import、随附组合、preset 或默认模板对它的引用，拒绝列表没有点名的实验依赖，也拒绝不是运行时依赖或不是组合包的列表项。workspace 约束检查接受同样的 `dependencies` 边而不接受其他运行时依赖段；发布时的 packed-install 检查对已安装入口包跳过这些边，并要求列表中的每个组合包都已安装。
diff --git a/.agents/notes/implemented/process/2026-10-05-pr-artifact-typechecks.i18n.yaml b/.agents/notes/implemented/process/2026-10-05-pr-artifact-typechecks.i18n.yaml
index 1ab57007ef..121838e838 100644
--- a/.agents/notes/implemented/process/2026-10-05-pr-artifact-typechecks.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-10-05-pr-artifact-typechecks.i18n.yaml
@@ -9,8 +9,8 @@
en: e5c984fa32cc5e69
zh: 25d5742b2106d830
/agent-note-pr-artifact-builds-and-aggregate-typescript-checks/decision:
- en: 26a903fdfeffcea7
- zh: f6ea094ec32a7b14
+ en: 8353d57b20ca01c3
+ zh: e0b74906846d759c
/agent-note-pr-artifact-builds-and-aggregate-typescript-checks/alternatives-considered:
en: f61da066f9ddcd62
zh: 816fd6e0063017cd
diff --git a/.agents/notes/implemented/process/2026-10-05-pr-artifact-typechecks.md b/.agents/notes/implemented/process/2026-10-05-pr-artifact-typechecks.md
index b6f5bc1743..0b403e7892 100644
--- a/.agents/notes/implemented/process/2026-10-05-pr-artifact-typechecks.md
+++ b/.agents/notes/implemented/process/2026-10-05-pr-artifact-typechecks.md
@@ -20,7 +20,7 @@ The Python executable builder selects `build:artifacts` artifact compilation wit
PR artifact builds in CI invoke the root manifest's `build:artifacts`; a PR that edits these root manifest scripts activates the separate native-addon platform matrix, a trade-off [the build split](2026-10-11-build-artifacts-check-split.md) records. The vendor rehearsal and benchmark lanes invoke the internal build helpers directly.
-Job inventory, runner selectors, and benchmark sample counts stay fixed; gate and worker ceilings do not increase. The two compatibility cases run one job at a time; the two-target Python runtime matrix starts after the keyless Python SDK job succeeds. Four Linux lanes, the Python SDK, three Windows lanes, and one compatibility job permit at most nine worker jobs initially. Once the SDK job finishes, the remaining seven independent lanes, one compatibility job, and two runtime targets permit at most ten. The runtime plan and wheel stages precede those targets and each use one job. This permits runtime validation to overlap the Node 24.9 build within the original ten-job ceiling. Coverage partitions reuse compact file-cost metadata within their platform and runner pool. Parallel release packing uses pnpm's existing bounded scheduler; serial publication keeps family order.
+Job inventory, runner selectors, and benchmark sample counts stay fixed; gate and worker ceilings do not increase. The two compatibility cases run one job at a time; both x64 Python runtime targets start after the keyless Python SDK job succeeds in CI Python. Four Linux lanes, one compatibility job, three Windows lanes, and the Python SDK job permit at most nine worker jobs initially. Once the SDK job finishes, those four Linux lanes, one compatibility job, and three Windows lanes run beside the two runtime targets, permitting at most ten. Each runtime caller's plan and wheel stages precede its target and each use one job. This permits runtime validation to overlap the Node 24.9 build within the original ten-job ceiling. Coverage partitions reuse compact file-cost metadata within their platform and runner pool. Parallel release packing uses pnpm's existing bounded scheduler; serial publication keeps family order.
Each Node version runs the same eight source compatibility specs in one serial Vitest invocation. Both file parallelism and the CLI worker limit are fixed to one, and the gate sets `VITEST_MAX_WORKERS=1` because that environment variable overrides Vitest's CLI limit. Files retain fork isolation; the build-backed Node 24.9 lazy-search smoke keeps its separate build dependency. The original seven-spec paired samples preserve all 253 assertion outcomes and reduce startup-only median time from 11.52 to 8.69 seconds, without increasing owned descendant-process peak.
diff --git a/.agents/notes/implemented/process/2026-10-05-pr-artifact-typechecks.zh.md b/.agents/notes/implemented/process/2026-10-05-pr-artifact-typechecks.zh.md
index 52756c1176..56fa7cbaa5 100644
--- a/.agents/notes/implemented/process/2026-10-05-pr-artifact-typechecks.zh.md
+++ b/.agents/notes/implemented/process/2026-10-05-pr-artifact-typechecks.zh.md
@@ -20,7 +20,7 @@ Python executable builder 在验证 runtime closure 后，通过 `--build-artifa
CI 的 PR 产物构建调用 root manifest 中的 `build:artifacts`；修改 root manifest 中这些 script 的 PR 会激活独立的 native-addon 平台矩阵，[构建拆分](2026-10-11-build-artifacts-check-split.zh.md)记录这一取舍。vendor 演练与 benchmark lane 直接调用内部 build helper。
-job 清单、runner 选择和 benchmark sample 数量保持固定；gate 与 worker 上限不提高。两个 compatibility case 每次运行一个 job；双目标 Python runtime 矩阵在 keyless Python SDK job 成功后启动。四个 Linux lane、Python SDK、三个 Windows lane 和一个 compatibility job，初始最多占用九个 worker job。SDK job 完成后，剩余七个独立 lane、一个 compatibility job 和两个 runtime target，最多占用十个 job。runtime plan 与 wheel 阶段先于这些 target，各占一个 job。这允许 runtime 验证与 Node 24.9 构建重叠，同时保持原有十个 job 的上限。覆盖率分区在各自的平台和 runner pool 内复用精简的文件成本元数据。并行 release 打包使用 pnpm 现有的有界调度器；串行发布保持 family 顺序。
+job 清单、runner 选择和 benchmark sample 数量保持固定；gate 与 worker 上限不提高。两个 compatibility case 每次运行一个 job；两个 x64 Python runtime target 都在 CI Python 中于 keyless Python SDK job 成功后启动。四个 Linux lane、一个 compatibility job、三个 Windows lane 与 Python SDK job，初始最多占用九个 worker job。SDK job 完成后，这四个 Linux lane、一个 compatibility job 与三个 Windows lane 与两个 runtime target 并行，最多占用十个 job。每个 runtime 调用方的 plan 与 wheel 阶段先于其 target，各占一个 job。这允许 runtime 验证与 Node 24.9 构建重叠，同时保持原有十个 job 的上限。覆盖率分区在各自的平台和 runner pool 内复用精简的文件成本元数据。并行 release 打包使用 pnpm 现有的有界调度器；串行发布保持 family 顺序。
每个 Node 版本在一次串行 Vitest 调用中运行相同的八个 source compatibility spec。文件并行和 CLI worker 上限均固定为一，gate 还设置 `VITEST_MAX_WORKERS=1`，因为该环境变量会覆盖 Vitest 的 CLI 上限。文件保持 fork 隔离；依赖构建的 Node 24.9 lazy-search smoke 保留独立的 build 依赖。原来七个 spec 的成对样本保持全部 253 个 assertion outcome，将启动开销比较的 median 从 11.52 秒降至 8.69 秒，且不增加所拥有 descendant process 的峰值。
diff --git a/.agents/notes/implemented/process/2026-10-20-weighted-approval-status-gate-with-check-run-label.i18n.yaml b/.agents/notes/implemented/process/2026-10-20-weighted-approval-status-gate-with-check-run-label.i18n.yaml
new file mode 100644
index 0000000000..cc5e19892d
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-10-20-weighted-approval-status-gate-with-check-run-label.i18n.yaml
@@ -0,0 +1,22 @@
+# Bilingual-pair consistency record for 2026-10-20-weighted-approval-status-gate-with-check-run-label.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+# pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-10-20-weighted-approval-status-gate-with-check-run-label.md
+/agent-note-weighted-approval-keeps-its-commit-status-gate-and-adds-a-decision-check-run:
+ en: a1f0f9fd657c7d35
+ zh: e8fa02fb5bde6075
+/agent-note-weighted-approval-keeps-its-commit-status-gate-and-adds-a-decision-check-run/problem:
+ en: 8e854872edfc0729
+ zh: 6f3ed495fcb690a4
+/agent-note-weighted-approval-keeps-its-commit-status-gate-and-adds-a-decision-check-run/decision:
+ en: 03de94946d7532d7
+ zh: cf2f585f715d3295
+/agent-note-weighted-approval-keeps-its-commit-status-gate-and-adds-a-decision-check-run/verification:
+ en: 8298cff64cce6467
+ zh: a121d509c2302c00
+/agent-note-weighted-approval-keeps-its-commit-status-gate-and-adds-a-decision-check-run/alternatives-considered:
+ en: 197255cd82aabef7
+ zh: dc03f4bf77150f22
+/agent-note-weighted-approval-keeps-its-commit-status-gate-and-adds-a-decision-check-run/consequences:
+ en: 25e1ac1c8cab089a
+ zh: 84e10cccb1b9eda7
diff --git a/.agents/notes/implemented/process/2026-10-20-weighted-approval-status-gate-with-check-run-label.md b/.agents/notes/implemented/process/2026-10-20-weighted-approval-status-gate-with-check-run-label.md
new file mode 100644
index 0000000000..386ff345df
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-10-20-weighted-approval-status-gate-with-check-run-label.md
@@ -0,0 +1,37 @@
+# Agent Note: Weighted approval keeps its commit status gate and adds a decision check run
+
+Status: implemented
+
+English | [中文](2026-10-20-weighted-approval-status-gate-with-check-run-label.zh.md)
+
+## Problem
+
+The `weighted approval` commit status is the record this repository's branch rules require, and below the approval threshold it stays `pending`. A commit status has no action-required state, so readers cannot tell an approval wait from running work. Moving the gate to a check run does not work: after that change, the check run completed as `success` on the pull-request head and both the REST API and `gh pr checks` listed it, while the merge box kept reporting the same `weighted approval decision` context as `Expected — Waiting for status to be reported`, and two pull requests needed an administrator bypass. That change was reverted.
+
+## Decision
+
+The publisher keeps writing the `weighted approval` commit status exactly as before: `pending` while the policy is unmet, `success` when it holds, and `error` when setup or evaluation fails. Branch rules keep requiring that status. That behavior, including keeping an unmet policy `pending`, is what the [archived decision](../../archived/process/2026-09-09-blocked-weighted-approvals-remain-pending.md) records; this change adds the label beside it instead of changing the gate.
+
+The publisher additionally writes a `weighted approval decision` check run for the same evaluation: `action_required` while the policy is unmet, `success` when it holds, and `failure` when setup or evaluation fails. The check run's title carries the score or the blocker. Branch rules do not require it, so it never blocks a merge; it names the blocked state beside the status that does.
+
+A head keeps one GitHub Actions run with the check-run name: the publisher updates the head's existing run and creates one only when none exists. The setup phase creates the run as `in_progress` on a head without one and deals with a published success by rewriting its conclusion to `action_required`, because GitHub accepts but does not apply a return to `in_progress`. A failed check-run write is logged and never changes the status, so a token without the checks permission, or a check-run API failure, leaves the gate as the status wrote it. The publisher identifies its own runs by the `external_id` marker it sets on creation, which excludes check runs that workflow jobs produce for a same-named job. It revokes a published `success` before dependency setup, because GitHub accepts but does not apply a return to `in_progress`.
+
+## Verification
+
+[Approval policy tests](../../../../.github/review-ownership/check-approval.test.mjs) pin the unchanged status states, the check-run conclusion for a met and an unmet policy, the phase writes, revoking a published success through its conclusion, one run per head, and invalid list responses. [Workflow tests](../../../../scripts/ci-workflow.spec.ts) pin the `checks: write` and `statuses: write` permissions and the setup phase commands.
+
+The check-run limit was measured on 2026-10-20 with the reverted attempt on this repository: the `weighted approval decision` check run completed as `success` on the pull-request head, the REST API and `gh pr checks` listed it, and the merge box kept reporting the same context as expected.
+
+## Alternatives considered
+
+**Require the check run instead of the commit status.** Measured above: the ruleset does not match a check run published through the default-branch workflow's token, so the gate cannot be satisfied.
+
+**Publish the commit status as `failure` while the policy is unmet.** The status would complete, but this changes the required record's meaning and would report an unmet, reversible condition as a malfunction.
+
+**Publish only the check run and leave the status untouched.** The status would keep its last state from an earlier evaluation, so the gate and the label could disagree.
+
+**Publish the required check run from a dedicated GitHub App.** A check run whose app the ruleset names would let the required entry carry the action-required conclusion itself. The repository has no App with the checks permission; with one, the label could move onto the required record and the status could be retired.
+
+## Consequences
+
+A job that ends between the `pending` write and the fallback step, such as a lost runner or a cancellation that skips the final step, leaves the status `pending`; that is the original symptom of this status, not a regression from the added label. While reviewers are pending, the merge box reports `weighted approval` as pending (the gate) and the `weighted approval decision` entry as `action_required`, with the score or blocker in its title; `gh pr checks` lists both. A published success is revoked by rewriting the check run's conclusion, and the status follows the unchanged policy states.
diff --git a/.agents/notes/implemented/process/2026-10-20-weighted-approval-status-gate-with-check-run-label.zh.md b/.agents/notes/implemented/process/2026-10-20-weighted-approval-status-gate-with-check-run-label.zh.md
new file mode 100644
index 0000000000..75089f2f13
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-10-20-weighted-approval-status-gate-with-check-run-label.zh.md
@@ -0,0 +1,37 @@
+# Agent Note: Weighted approval 保留其 commit status 门禁并新增决策 check run
+
+Status: implemented
+
+[English](2026-10-20-weighted-approval-status-gate-with-check-run-label.md) | 中文
+
+## 问题
+
+`weighted approval` commit status 是本仓库分支规则要求的记录，在批准阈值下方时保持 `pending`。commit status 没有 action-required 状态，读者无法区分等待批准与正在运行的工作。把门禁改成 check run 并不可行：该改动后 check run 在 PR head 上以 `success` 完成，REST API 与 `gh pr checks` 都能列出它，而合并框始终把同一上下文报告为 `Expected — Waiting for status to be reported`，两个 PR 需要管理员绕过才能合并。该改动已回退。
+
+## 决定
+
+publisher 继续完全按原样写 `weighted approval` commit status：策略未满足时为 `pending`，满足时为 `success`，安装或评估失败时为 `error`。分支规则继续要求该 status。该行为——包括未满足的策略保持 `pending`——正是[已归档决定](../../archived/process/2026-09-09-blocked-weighted-approvals-remain-pending.md)记录的；本次变更在该门禁旁边新增标签，而不改变门禁。
+
+publisher 为同一次评估额外写一个 `weighted approval decision` check run：策略未满足时为 `action_required`，满足时为 `success`，安装或评估失败时为 `failure`。check run 的标题携带分数或 blocker。分支规则不要求它，因此它从不阻止合并；它在会阻止合并的那条 status 旁边命名被阻止的状态。
+
+每个 head 只保留一个同名 GitHub Actions run：publisher 更新 head 上已有的 run，仅在不存在时创建。setup 阶段对没有 run 的 head 以 `in_progress` 创建，并把已发布的 success 的 conclusion 改写为 `action_required`，因为 GitHub 接受但不执行改回 `in_progress` 的更新。check run 写入失败会被记录，且从不改变 status，因此没有 checks 权限的 token 或 check-run API 失败时，门禁保持 status 写入的结果。publisher 用创建时设置的 `external_id` 标记识别自己的 run，从而排除 workflow job 为同名 job 产生的 check run。它在依赖安装前撤销已发布的 `success`，因为 GitHub 接受但不执行改回 `in_progress` 的更新。
+
+## 验证
+
+[批准策略测试](../../../../.github/review-ownership/check-approval.test.mjs)锁定未改动的 status 状态、策略满足与未满足两种情况下 check run 的 conclusion、阶段写入、通过 conclusion 撤销已发布的成功、每个 head 只有一个 run，以及无效的列表响应。[工作流测试](../../../../scripts/ci-workflow.spec.ts)锁定 `checks: write` 与 `statuses: write` 权限以及 setup 阶段命令。
+
+check run 的限制于 2026-10-20 在本仓库用被回退的尝试实测：`weighted approval decision` check run 在 PR head 上以 `success` 完成，REST API 与 `gh pr checks` 都能列出它，而合并框始终把同一个 `weighted approval decision` 上下文报告为 expected。
+
+## 考虑过的替代方案
+
+**把 check run 作为必需检查。** 见上面的实测：ruleset 不匹配默认分支 workflow 的 token 发布的 check run，门禁无法满足。
+
+**策略未满足时把 commit status 发布为 `failure`。** status 会完成，但改变了必需记录的含义，并把尚未满足且可撤销的条件报告为故障。
+
+**只发布 check run 而不动 status。** status 会保留上一次评估的状态，门禁与标签可能不一致。
+
+**由专用 GitHub App 发布必需 check run。** 由 ruleset 指定 app 的 check run 可以让必需条目本身携带 action-required 结论。本仓库没有具备 checks 权限的 App；有了之后可以把标签移到必需记录上并停用 status。
+
+## 后果
+
+job 在 `pending` 写入与兜底步骤之间结束（例如 runner 丢失，或取消导致最后一步未执行）会让 status 保持 `pending`；这是该 status 既有的表现，不是新增标签带来的回归。评审未完成时，合并框把 `weighted approval` 报告为 pending（门禁），并把 `weighted approval decision` 条目报告为 `action_required`，标题里是分数或 blocker；`gh pr checks` 会列出两者。已发布的 success 通过改写 check run 的 conclusion 撤销，status 继续按未改动的策略状态变化。
diff --git a/.agents/notes/implemented/simplification/2026-10-13-text-derived-message-quotes.i18n.yaml b/.agents/notes/implemented/simplification/2026-10-13-text-derived-message-quotes.i18n.yaml
new file mode 100644
index 0000000000..0b25c139c2
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-10-13-text-derived-message-quotes.i18n.yaml
@@ -0,0 +1,22 @@
+# Bilingual-pair consistency record for 2026-10-13-text-derived-message-quotes.md (docs/i18n/README.md): per heading
+# section, a hash of its English and Chinese blocks outside code blocks and generated regions.
+# After editing either side, bring the other along and re-record with:
+# pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-10-13-text-derived-message-quotes.md
+/agent-note-recognize-message-quotes-from-markdown-text:
+ en: a2abd7f693937d51
+ zh: f9e4bb817536dbbe
+/agent-note-recognize-message-quotes-from-markdown-text/problem:
+ en: d71ebbacbd9bd8a3
+ zh: 45c1f7fd1d797f61
+/agent-note-recognize-message-quotes-from-markdown-text/decision:
+ en: 0abb09d5ba396f69
+ zh: dd067b0ca5fd376f
+/agent-note-recognize-message-quotes-from-markdown-text/alternatives-considered:
+ en: 05c6009796927583
+ zh: 9f08229767c07b31
+/agent-note-recognize-message-quotes-from-markdown-text/verification:
+ en: 790598fd0f3f0c67
+ zh: 0399e0e322ffca40
+/agent-note-recognize-message-quotes-from-markdown-text/consequences:
+ en: 21f96c04f6edcc1d
+ zh: 8ea3f42a8e981592
diff --git a/.agents/notes/implemented/simplification/2026-10-13-text-derived-message-quotes.md b/.agents/notes/implemented/simplification/2026-10-13-text-derived-message-quotes.md
new file mode 100644
index 0000000000..2a6ecaa833
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-10-13-text-derived-message-quotes.md
@@ -0,0 +1,29 @@
+# Agent Note: Recognize message quotes from Markdown text
+
+Status: implemented
+
+English | [中文](2026-10-13-text-derived-message-quotes.zh.md)
+
+## Problem
+
+Quote-only content indexes duplicate information in Markdown text and require coordinated prompt, source, echo, and queue metadata. The same visible blockquote can acquire different presentation and direct-input behavior depending on how it was created.
+
+## Decision
+
+Messages contain ordinary Markdown text. The shared blockquote matcher recognizes consecutive explicitly marked lines for UserText presentation. Hand-written and composer-created blockquotes have identical sent-message behavior. Quote previews display decoded text without running UserText rules over their contents. Session-reference and skill processing applies normally to quoted text; recognized Session labels retain the same presentation as the surrounding quote text.
+
+The [rich-text quote feature](../feature/2026-08-26-web-rich-text-quotes.md) retains atomic draft nodes and semantic restoration spans. This decision supersedes only its durable quote-index distinction. UserText nodes and recognition ranges remain derived values.
+
+## Alternatives considered
+
+**Keep quote-only indexes.** Indexes preserve a distinction between typed and inserted quotes, but that distinction is unnecessary for sent messages and requires metadata coordination across every producer and renderer.
+
+**Remove atomic draft spans.** Plain text cannot restore whole-node editing, undo, Session switching, or failed-send restoration. Draft spans remain browser-owned editing state.
+
+## Verification
+
+Matcher tests cover original offsets, explicit line markers, blank excerpts, and literal nested quotes. Composer tests assert ordinary text submission. The shipped Web scenario checks text-only persistence and quote display after reload.
+
+## Consequences
+
+Messages need no quote fields or content indexes. Typed blockquotes also display as quotes without changing direct-input processing. Recognition deliberately covers explicit quote lines rather than Markdown lazy continuation or fenced-code parsing. Source navigation still requires a separate durable-coordinate design.
diff --git a/.agents/notes/implemented/simplification/2026-10-13-text-derived-message-quotes.zh.md b/.agents/notes/implemented/simplification/2026-10-13-text-derived-message-quotes.zh.md
new file mode 100644
index 0000000000..c9ee20f906
--- /dev/null
+++ b/.agents/notes/implemented/simplification/2026-10-13-text-derived-message-quotes.zh.md
@@ -0,0 +1,29 @@
+# Agent Note: 从 Markdown 文本识别消息 quote
+
+Status: implemented
+
+[English](2026-10-13-text-derived-message-quotes.md) | 中文
+
+## 问题
+
+纯 quote content 索引重复了 Markdown 文本中的信息，并要求 prompt、source、回显与队列协同携带元数据。同样可见的 blockquote 会因创建方式不同而获得不同的展示与直接输入行为。
+
+## 决策
+
+消息包含普通 Markdown 文本。共享 blockquote 匹配器识别连续的显式标记行，用于 UserText 展示。手写与输入框创建的 blockquote 在发送后具有相同行为。Quote 预览直接展示还原后的文本，不对正文再次运行 UserText 规则。Session-reference 与 skill 处理照常作用于引用文本；已识别的 Session 标签与周围引用文字保持相同样式。
+
+[富文本 quote 功能](../feature/2026-08-26-web-rich-text-quotes.zh.md)保留原子草稿节点与语义恢复范围。本决策仅取代其持久 quote 索引区分。UserText 节点与识别范围仍是派生值。
+
+## 考虑过的替代方案
+
+**保留纯 quote 索引。** 索引保留手写与插入 quote 的区别，但发送后的消息无需这一区分，且要求每个生产方与渲染器协同处理元数据。
+
+**移除原子草稿范围。** 纯文本无法恢复整节点编辑、撤销、Session 切换或发送失败恢复。草稿范围仍是浏览器拥有的编辑状态。
+
+## 验证
+
+匹配器测试覆盖原始偏移、显式行标记、空白摘录与字面的嵌套 quote。Composer 测试断言普通文本提交。已发布 Web 场景检查仅文本的持久化与刷新后的 quote 展示。
+
+## 后果
+
+消息无需 quote 字段或 content 索引。手写 blockquote 也显示为 quote，不改变直接输入处理。识别有意限定为显式引用行，不涵盖 Markdown 懒惰续行或代码围栏解析。来源导航仍需独立设计持久坐标。
diff --git a/.agents/notes/implemented/testing/2026-08-23-installed-python-wheel-black-box-ci.i18n.yaml b/.agents/notes/implemented/testing/2026-08-23-installed-python-wheel-black-box-ci.i18n.yaml
index 4f8b351852..7da2ecf5cb 100644
--- a/.agents/notes/implemented/testing/2026-08-23-installed-python-wheel-black-box-ci.i18n.yaml
+++ b/.agents/notes/implemented/testing/2026-08-23-installed-python-wheel-black-box-ci.i18n.yaml
@@ -21,8 +21,8 @@
en: 0f98f5b5f78b5603
zh: 95ee8bafa66d6b1b
/agent-note-installed-wheel-python-runtime-pull-request-validation/decision/required-targets:
- en: 7a33cde000508475
- zh: 142fb5ec6b59a280
+ en: ff9f43ef5d3480c8
+ zh: eb8d94581522f1ec
/agent-note-installed-wheel-python-runtime-pull-request-validation/existing-decisions-and-supersession:
en: 04aa439d4e607324
zh: f4c1d24b6a418cc4
diff --git a/.agents/notes/implemented/testing/2026-08-23-installed-python-wheel-black-box-ci.md b/.agents/notes/implemented/testing/2026-08-23-installed-python-wheel-black-box-ci.md
index dfa71a9787..5ef6fc6e91 100644
--- a/.agents/notes/implemented/testing/2026-08-23-installed-python-wheel-black-box-ci.md
+++ b/.agents/notes/implemented/testing/2026-08-23-installed-python-wheel-black-box-ci.md
@@ -30,7 +30,7 @@ Fork and Dependabot pull requests never receive the repository secret. Their nat
### Required targets
-The pull-request `python-runtime` job calls the reusable builder for Linux x64 and Windows x64; master pushes select Linux arm64 and both macOS architectures under the [master-only platform policy](../../../../.github/workflows/ci-master.yml). Its aggregate result remains a dependency of `all checks passed`, so a failed, cancelled, or missing native carrier blocks the required verdict. The [sdk-runtime README](../../../../python/sdk-runtime/README.md) owns the Windows target and its PowerShell-specific minimal snapshot.
+The pull-request `python-runtime` job in CI Python calls the reusable builder for Linux x64 and Windows x64; master pushes select Linux arm64 and both macOS architectures under the [master-only platform policy](../../../../.github/workflows/ci-master.yml). Its aggregate result is a dependency of CI Python's required verdict, `python checks passed`, so a failed, cancelled, or missing native carrier blocks the required verdict. The [sdk-runtime README](../../../../python/sdk-runtime/README.md) owns the Windows target and its PowerShell-specific minimal snapshot.
## Existing decisions and supersession
diff --git a/.agents/notes/implemented/testing/2026-08-23-installed-python-wheel-black-box-ci.zh.md b/.agents/notes/implemented/testing/2026-08-23-installed-python-wheel-black-box-ci.zh.md
index fe2e6b6ece..03b015e0a4 100644
--- a/.agents/notes/implemented/testing/2026-08-23-installed-python-wheel-black-box-ci.zh.md
+++ b/.agents/notes/implemented/testing/2026-08-23-installed-python-wheel-black-box-ci.zh.md
@@ -30,7 +30,7 @@ Fork 与 Dependabot 拉取请求永远不会获得仓库密钥。它们的原生
### 必需目标
-拉取请求的 `python-runtime` job 针对 Linux x64 与 Windows x64 调用可复用构建器；master 推送根据[仅 master 平台策略](../../../../.github/workflows/ci-master.yml)选择 Linux arm64 与两种 macOS 架构。其聚合结果仍是 `all checks passed` 的依赖项，因此任一原生载体失败、取消或缺失都会阻止必需判定通过。[sdk-runtime README](../../../../python/sdk-runtime/README.zh.md) 负责 Windows 目标及其 PowerShell 专属极简快照。
+拉取请求的 `python-runtime` job 在 CI Python 中针对 Linux x64 与 Windows x64 调用可复用构建器；master 推送根据[仅 master 平台策略](../../../../.github/workflows/ci-master.yml)选择 Linux arm64 与两种 macOS 架构。其聚合结果是 CI Python 必需判定 `python checks passed` 的依赖项，因此任一原生载体失败、取消或缺失都会阻止必需判定通过。[sdk-runtime README](../../../../python/sdk-runtime/README.zh.md) 负责 Windows 目标及其 PowerShell 专属极简快照。
## Existing decisions and supersession
diff --git a/.agents/skills/dsh-client-ui-ux/SKILL.md b/.agents/skills/dsh-client-ui-ux/SKILL.md
index 4fbfa1a876..6d293a5f86 100644
--- a/.agents/skills/dsh-client-ui-ux/SKILL.md
+++ b/.agents/skills/dsh-client-ui-ux/SKILL.md
@@ -56,7 +56,7 @@ Scrollbars stay inside their container: use the shared scrollbar styles rather t
## Responsive layouts
-Use [dsh-responsive-ui](../dsh-responsive-ui/SKILL.md) for responsive layouts, text truncation, title wrapping, icon-only controls, and focus during width changes.
+Use [dsh-responsive-ui](../dsh-responsive-ui/SKILL.md) for responsive layouts, mobile and touch detection, text truncation, title wrapping, icon-only controls, and focus during width changes.
## Platform window adaptation
diff --git a/.agents/skills/dsh-code-review/SKILL.md b/.agents/skills/dsh-code-review/SKILL.md
index 9b0b48bc57..e5cf8c079f 100644
--- a/.agents/skills/dsh-code-review/SKILL.md
+++ b/.agents/skills/dsh-code-review/SKILL.md
@@ -23,6 +23,7 @@ description: Use when reviewing a pull request in the deepseek-harness repo —
- [dsh-ci-test-reliability](../dsh-ci-test-reliability/SKILL.md): isolation and regression-proof rules for resource-owning, asynchronous, or flaky tests and fixtures.
- [dsh-client-ui-ux](../dsh-client-ui-ux/SKILL.md): feedback-surface choice, overlay safety, platform window adaptation, and visual token discipline for product-user-visible GUI changes.
- [dsh-error-handling](../dsh-error-handling/SKILL.md): failure classification, handling ownership, containment, state guarantees, and actionable reports.
+- [dsh-session-projection](../dsh-session-projection/SKILL.md): projection ownership, state size, historical reads, and migrations.
- [docs/testing.md](../../../docs/testing.md) and the [quality-gates reference](../../../docs/testing.md): required test tiers and gates.
- [Agent Notes](../../notes/README.md): design rationale. Treat disagreement with an Agent Note as a design discussion, not an automatic veto.
- For bilingual changes, read [translation-rules.md](../../../docs/i18n/translation-rules.md) and [terminology.md](../../../docs/i18n/terminology.md); the extended translation skill is outside automatic review and runs only on explicit user invocation.
diff --git a/.agents/skills/dsh-prose-standard/SKILL.md b/.agents/skills/dsh-prose-standard/SKILL.md
index bb8347823b..338ff29a21 100644
--- a/.agents/skills/dsh-prose-standard/SKILL.md
+++ b/.agents/skills/dsh-prose-standard/SKILL.md
@@ -55,7 +55,7 @@ This is not a one-way shortening pass. Add or restore prose when code, types, an
- **Postmortems:** retain the incident sequence, evidence, causal chain, impact, and prevention. Remove repeated persuasion or implementation detail that does not establish causality.
- **Skills and agent instructions:** state behavioral guardrails and explicit scope limitations such as “guidance, not a script/checklist.” Keep the workflow concise and link its source of truth.
- **Examples and configuration comments:** explain access limits, non-obvious wiring or load order, security stance, replay behavior, exceptions, and likely misuse. Do not narrate entries that the configuration already shows.
-- **Prompts and visible strings:** treat wording as behavior. Client UI copy belongs in typed locale dictionaries and reaches Cordis-free primitives as explicit localized props; inspect text, accessibility names, tooltips, placeholders, and format templates together, then run `verify-client-ui-i18n`. Update the owning runnable snapshot for model-visible text and repository-required GUI evidence. If the authorized scope has no owning scenario, leave the wording unchanged and report the deferral; do not silently fold it into a prose-only edit.
+- **Prompts and visible strings:** treat wording as behavior. Client UI copy belongs in typed locale dictionaries and reaches Cordis-free primitives as explicit localized props; inspect text, accessibility names, tooltips, placeholders, and format templates together, then run `verify-client-ui-i18n`. English UI copy, including plugin `meta.title` and `meta.description`, uses sentence case: capitalize only the first word, proper nouns, and product names such as `Chrome DevTools`, `Git`, or `MCP` (`Git worktrees`, not `Git Worktrees`). Chinese copy keeps its own conventions. Update the owning runnable snapshot for model-visible text and repository-required GUI evidence. If the authorized scope has no owning scenario, leave the wording unchanged and report the deferral; do not silently fold it into a prose-only edit.
- **Diagnostics:** name the failing subject or path, violated rule, and correction when it is non-obvious. Remove internal execution narration.
Preserve searchable mechanism names and meaningful modal, temporal, or negative emphasis. Normalize decorative emphasis only.
diff --git a/.agents/skills/dsh-responsive-ui/SKILL.md b/.agents/skills/dsh-responsive-ui/SKILL.md
index a9ee2f3a37..73e0a8f944 100644
--- a/.agents/skills/dsh-responsive-ui/SKILL.md
+++ b/.agents/skills/dsh-responsive-ui/SKILL.md
@@ -1,6 +1,6 @@
---
name: dsh-responsive-ui
-description: Use when designing, implementing, or reviewing responsive client layouts, text truncation, title wrapping, icon-only controls, mobile hover, tooltips and keyboard behavior, and focus during width changes in DeepSeek Harness.
+description: Use when designing, implementing, or reviewing responsive client layouts, mobile and touch detection, text truncation, title wrapping, icon-only controls, mobile hover, tooltips and keyboard behavior, and focus during width changes in DeepSeek Harness.
---
# Responsive client UI
@@ -39,10 +39,10 @@ Use a viewport width of 390 CSS px as the primary acceptance minimum. There must
## 6. Mobile hover behavior
-1. Enable mouse-hover effects only on devices that support hovering. Use `@media (hover: hover)`, not viewport width, to determine this.
-2. Tapping on a phone must not leave behind backgrounds, highlights, or action-button visibility intended only for hover.
-3. Preserve normal selected, enabled, and pressed states, as well as focus indicators for keyboard interaction.
-4. Try to preserve focus when the width changes, unless the focused element disappears from the page as a result.
+1. Enable hover effects under `@media (hover: hover)`, independently of viewport width. This queries the primary pointing device, not the current event; JavaScript hover handlers must ignore touch events on mixed-input devices.
+2. Tapping on a phone must not leave behind backgrounds, highlights, or action-button visibility intended only for hover. Without hover, actions remain visible or reachable through an explicit control. Keyboard users can reach and reveal the same actions.
+3. Preserve normal selected, expanded, enabled, and pressed states, as well as focus indicators. Keep these styles independent of hover capability. Do not clear focus to remove a hover effect; `:focus-visible` can also apply to text fields focused by touch.
+4. Preserve focus during width changes when the control remains visible and interactive. Avoid remounting controls only to change layout. If the focused control is hidden or removed, move focus to a suitable remaining control without opening the mobile keyboard unnecessarily.
## 7. Mobile tooltips
@@ -52,3 +52,8 @@ Use a viewport width of 390 CSS px as the primary acceptance minimum. There must
## 8. Mobile keyboard
On mobile, do not raise the input keyboard automatically unless it is explicitly intended.
+
+## 9. Input capabilities and mobile text fields
+
+1. Prefer CSS media features for presentation: `(pointer: coarse)` describes the primary pointer's accuracy, `(hover: none)` describes its inability to hover, and width queries select layout breaks. These queries do not detect a physical keyboard. Never branch layout on a parsed user agent.
+2. Text fields take a 16px floor under `(pointer: coarse)` to avoid iOS Safari's focus zoom. Fine pointers keep the existing compact field sizes. Use the field rules in `packages/client/ui-plugin-manager/src/client/PluginManagerPage.module.css` as the reference.
diff --git a/.agents/skills/dsh-session-projection/SKILL.md b/.agents/skills/dsh-session-projection/SKILL.md
new file mode 100644
index 0000000000..e709e70598
--- /dev/null
+++ b/.agents/skills/dsh-session-projection/SKILL.md
@@ -0,0 +1,19 @@
+---
+name: dsh-session-projection
+description: Use when creating, extending, or reviewing a DeepSeek Harness session projection, or migrating a fold helper to one.
+---
+
+# DeepSeek Harness Session Projections
+
+Follow the [projection API](../../../packages/session/session-projection/README.md) for registration and lifecycle details.
+
+1. Decide whether to extend an existing projection or create one; check whether an existing owner already maintains the needed state.
+2. Follow the README's [service ownership rules](../../../packages/session/session-projection/README.md#register-and-read): keep projection definitions and handles private to the owning service's implementation, and expose domain methods to consumers.
+3. Require `sessionProjections` when the service needs projected state to function. Optional registration is for contributions the service can operate without.
+4. Evaluate retained state size as the session grows. Do not accumulate state proportional to session length, including collections of event sequence numbers. Growth is acceptable only when slow enough to remain negligible. When the data would keep growing, consider incremental loading instead of retaining the complete state.
+5. `apply` is synchronous; historical reads belong in asynchronous consumers. When later reads need event payloads, consider retaining sequence numbers within rule 4's state-size limits and letting consumers resolve them asynchronously.
+6. When replacing a helper such as `foldSessionTitle` with a projection, remove the superseded helper.
+7. After migrating to Session persistence, stop using `fold` in names and descriptions of the migrated logic.
+8. Do not add calls to deprecated synchronous readers (`snapshotEvents`, `eventAt`, `ownEvents`) or wrappers exposing the same access ([decision](../../notes/implemented/architecture/2026-09-09-deprecate-synchronous-session-event-reads.md)). Assume the full event log is not resident in memory and random reads may require asynchronous disk access.
+9. Consider state size, replay cost, and per-event work; add complexity only for a concrete performance need.
+10. Asynchronous `register()` is usually called in `[Service.init]`. If event listeners are registered afterward, check initialization ordering: when needed, install listeners before awaiting registration; if a listener needs the returned handle, await its readiness in a callback that supports asynchronous waiting. Otherwise, an event may fire before the listener is installed and be missed. Determine whether this race exists from the actual initialization flow and event trigger paths; do not move listeners earlier or add waits mechanically.
diff --git a/.github/AGENTS.md b/.github/AGENTS.md
index 299f6426c7..35f0103169 100644
--- a/.github/AGENTS.md
+++ b/.github/AGENTS.md
@@ -1,6 +1,6 @@
# AGENTS.md — GitHub Actions
-Run jobs on Windows runners (`windows-*` labels) under native `pwsh`. Native Windows build and process checks contribute to the pull-request `all checks passed` verdict; Wine runs Windows Node on hosted Linux only in `ci-master.yml`. Python runtime CI checks Linux/Windows x64 on pull requests and Linux ARM64 plus both macOS architectures on master pushes; releases retain all five targets ([platform policy](workflows/ci-master.yml)). `ci.yml` is pull-request-only. Master-only platform checks, Linux/Windows self-hosted standbys, and manual runner benchmarks live in `ci-master.yml`, which listens to master pushes and `workflow_dispatch`, not `pull_request`; separating workflow triggers keeps master-only jobs out of PR check panels. The master standbys validate the self-hosted failover targets; preserve the existing per-platform switches (values `selfhosted` for the in-house standbys and `blacksmith` for Blacksmith's hosted runners) and the Dependabot hosted fallback under the `selfhosted` values ([failover runbook](../.agents/notes/implemented/process/2026-07-26-ci-failover-runbook.md), [blacksmith failover leg note](../.agents/notes/implemented/process/2026-09-09-blacksmith-failover-leg.md)).
+Run jobs on Windows runners (`windows-*` labels) under native `pwsh`. Native Windows pull-request jobs live in `ci-windows.yml` and Python pull-request jobs in `ci-python.yml`, so each PR workflow can be re-run independently; their checks feed the required `windows checks passed` and `python checks passed` verdicts, as Linux jobs in `ci.yml` feed `all checks passed`; Wine runs Windows Node on hosted Linux only in `ci-master.yml`. Python runtime CI checks Linux/Windows x64 on pull requests and Linux ARM64 plus both macOS architectures on master pushes; releases retain all five targets ([platform policy](workflows/ci-master.yml)). `ci.yml`, `ci-windows.yml`, and `ci-python.yml` are pull-request-only. Master-only platform checks, Linux/Windows self-hosted standbys, and manual runner benchmarks live in `ci-master.yml`, which listens to master pushes and `workflow_dispatch`, not `pull_request`; separating workflow triggers keeps master-only jobs out of PR check panels. The master standbys validate the self-hosted failover targets; preserve the existing per-platform switches (values `selfhosted` for the in-house standbys and `blacksmith` for Blacksmith's hosted runners) and the Dependabot hosted fallback under the `selfhosted` values ([failover runbook](../.agents/notes/implemented/process/2026-07-26-ci-failover-runbook.md), [blacksmith failover leg note](../.agents/notes/implemented/process/2026-09-09-blacksmith-failover-leg.md)).
The manual [Windows packaging workflow](workflows/windows-package.yml) uses the dedicated self-hosted Windows x64 label `dsh-win-package-trial` under native `pwsh`; preserve this routing separately from the automatic CI lanes.
diff --git a/.github/review-ownership/README.md b/.github/review-ownership/README.md
index 26ae70e6f6..c115acf172 100644
--- a/.github/review-ownership/README.md
+++ b/.github/review-ownership/README.md
@@ -16,7 +16,7 @@ The [`weighted-approval` workflow](../workflows/weighted-approval.yml) publishes
## Approval scoring
-The weighted approval workflow exposes two pull-request checks. The `weighted approval publisher` Actions job reports whether evaluation and status publication completed, while the `weighted approval` commit status carries the approval decision on the pull request head. Branch rules must require only the commit status with GitHub Actions as its expected source; a context-only requirement can accept a same-named status from another integration. The publisher marks the head pending before Python setup or lexer installation, so failed setup or an interrupted history fetch cannot leave a previous success in place. Setup and evaluation failures publish an error status. A completed evaluation returns `pending` below two approval points, while the pull request is a draft, or while a write-capable reviewer has an effective `CHANGES_REQUESTED` review; the blocker keeps the status pending even when counted approvals reach the threshold. It returns `success` only when the threshold is met, the pull request is ready, and no such blocker exists. If evaluation fails, the publisher writes an `error` status.
+The weighted approval workflow exposes two pull-request checks. The `weighted approval publisher` Actions job reports whether evaluation and status publication completed, while the `weighted approval` commit status carries the approval decision on the pull request head. Branch rules must require only the commit status with GitHub Actions as its expected source; a context-only requirement can accept a same-named status from another integration. The publisher marks the head pending before Python setup or lexer installation, so failed setup or an interrupted history fetch cannot leave a previous success in place. Setup and evaluation failures publish an error status. A completed evaluation returns `pending` below two approval points, while the pull request is a draft, or while a write-capable reviewer has an effective `CHANGES_REQUESTED` review; the blocker keeps the status pending even when counted approvals reach the threshold. It returns `success` only when the threshold is met, the pull request is ready, and no such blocker exists. If evaluation fails, the publisher writes an `error` status. The publisher also writes a `weighted approval decision` check run that reports the same decision as a conclusion — `action_required` while the policy is unmet, `success` when it holds, and `failure` on setup or evaluation failures — with the score or blocker in its title. Branch rules do not require that check run, so it never blocks a merge; it names the blocked state beside the status that gates the merge. A failed check-run write is logged and never changes the status.
Reviewers whose calculated base repository permission is `write` or `admin` count. The [approval policy](approval-policy.json) gives `@07akioni`, `@imccyu`, `@tianyicui`, `@tianyicui-bot`, `@turtle1999`, and `@turtle2099` two points each; every other write-capable reviewer gets one point. The pull-request author’s own review and reviewers without write permission do not count.
diff --git a/.github/review-ownership/check-approval.mjs b/.github/review-ownership/check-approval.mjs
index 5792299c46..1f499ff170 100644
--- a/.github/review-ownership/check-approval.mjs
+++ b/.github/review-ownership/check-approval.mjs
@@ -11,6 +11,8 @@ const API_VERSION = '2026-03-10'
const MAX_PULL_REQUEST_RECORDS = 3_000
const PAGE_SIZE = 100
const STATUS_CONTEXT = 'weighted approval'
+const CHECK_NAME = 'weighted approval decision'
+const CHECK_RUN_MARKER = 'weighted-approval-decision'
const WRITABLE_PERMISSIONS = new Set(['admin', 'write'])
const REVIEW_STATES = new Set(['APPROVED', 'CHANGES_REQUESTED', 'COMMENTED', 'DISMISSED', 'PENDING'])
@@ -332,6 +334,7 @@ export async function runApprovalCheck({ event, policySource, api, runUrl, getOw
}
} catch (error) {
await publishStatus(api, pull, 'error', 'Approval evaluation failed.', runUrl)
+ await tryPublishCheck(api, pull, 'failure', 'Approval evaluation failed.', runUrl, write)
throw error
}
write(result.authorCredit
@@ -343,6 +346,7 @@ export async function runApprovalCheck({ event, policySource, api, runUrl, getOw
writeList(write, 'Blocking change requests', result.blockers.map(login => `@${login}`))
writeList(write, 'Ignored reviewers without write access', result.ignoredReviewers.map(login => `@${login}`))
await publishStatus(api, pull, result.state, result.description, runUrl)
+ await tryPublishCheck(api, pull, result.state === 'success' ? 'success' : 'action_required', result.description, runUrl, write)
write(`Published ${JSON.stringify(STATUS_CONTEXT)} status ${JSON.stringify(result.state)}.`)
try {
await requestDelegatedReviews(result, api, write)
@@ -354,13 +358,25 @@ export async function runApprovalCheck({ event, policySource, api, runUrl, getOw
/**
* Revoke a previous success before dependency installation, or report its failure.
- * @param {{event: unknown, api: (path: string, options: object) => Promise, runUrl: string, phase: string}} options Publication inputs.
- * @returns {Promise} Completion of the status write.
+ * @param {{event: unknown, api: (path: string, options: object) => Promise, runUrl: string, phase: string, write?: (line: string) => void}} options Publication inputs.
+ * @returns {Promise} Completion of the status write and the corresponding check-run write.
*/
-export async function publishApprovalPhase({ event, api, runUrl, phase }) {
- if (!['pending', 'error'].includes(phase)) throw new Error('invalid approval setup phase')
- await publishStatus(api, pullRequestFromEvent(event), phase,
- phase === 'pending' ? 'Preparing approval evaluation.' : 'Approval setup or evaluation failed.', runUrl)
+export async function publishApprovalPhase({ event, api, runUrl, phase, write = line => process.stdout.write(`${line}\n`) }) {
+ const pull = pullRequestFromEvent(event)
+ if (phase === 'pending') {
+ await publishStatus(api, pull, 'pending', 'Preparing approval evaluation.', runUrl)
+ try {
+ await revokeApproval(api, pull, runUrl)
+ } catch (error) {
+ write(`Decision check run not revoked; the commit status is unchanged: ${JSON.stringify(error instanceof Error ? error.message : String(error))}`)
+ }
+ return
+ }
+ if (phase === 'error') {
+ await publishStatus(api, pull, 'error', 'Approval setup or evaluation failed.', runUrl)
+ return tryPublishCheck(api, pull, 'failure', 'Approval setup or evaluation failed.', runUrl, write)
+ }
+ throw new Error('invalid approval setup phase')
}
/**
@@ -467,6 +483,73 @@ async function reviewerPermission(api, repository, login) {
return response.permission.toLowerCase()
}
+// The required gate is the commit status; this check run reports the same decision as a conclusion
+// label and is not required. A failed label write is reported and never changes the gate, including
+// for a replayed workflow whose token has no checks permission.
+async function tryPublishCheck(api, pull, conclusion, title, runUrl, write) {
+ try {
+ await publishCheck(api, pull, conclusion, title, runUrl)
+ } catch (error) {
+ write(`Decision check run not published; the commit status is unchanged: ${JSON.stringify(error instanceof Error ? error.message : String(error))}`)
+ }
+}
+
+async function publishCheck(api, pull, conclusion, title, runUrl) {
+ requireHttpsRunUrl(runUrl)
+ const body = { status: 'completed', conclusion, details_url: runUrl, output: { title, summary: `${title} [Workflow run](${runUrl})` } }
+ const runs = await decisionRuns(api, pull)
+ if (runs.length === 0) {
+ await api(`/repos/${pull.repository}/check-runs`, {
+ method: 'POST',
+ body: { name: CHECK_NAME, head_sha: pull.headSha, external_id: CHECK_RUN_MARKER, ...body },
+ })
+ return
+ }
+ for (const run of runs) {
+ if (!Number.isSafeInteger(run.id)) throw new Error('check run has no valid id')
+ await api(`/repos/${pull.repository}/check-runs/${run.id}`, { method: 'PATCH', body })
+ }
+}
+
+// A head without a decision starts in progress; a published success becomes action_required, so an
+// interrupted evaluation cannot leave a success that its current inputs no longer support.
+async function revokeApproval(api, pull, runUrl) {
+ requireHttpsRunUrl(runUrl)
+ const title = 'Preparing approval evaluation.'
+ const output = { title, summary: `${title} [Workflow run](${runUrl})` }
+ const runs = await decisionRuns(api, pull)
+ if (runs.length === 0) {
+ await api(`/repos/${pull.repository}/check-runs`, {
+ method: 'POST',
+ body: { name: CHECK_NAME, head_sha: pull.headSha, status: 'in_progress', details_url: runUrl, output },
+ })
+ return
+ }
+ for (const run of runs) {
+ if (!Number.isSafeInteger(run.id)) throw new Error('check run has no valid id')
+ // The label is not a gate; only a published success has to stop claiming the policy holds.
+ if (run.conclusion !== 'success') continue
+ await api(`/repos/${pull.repository}/check-runs/${run.id}`, {
+ method: 'PATCH',
+ body: { status: 'completed', conclusion: 'action_required', details_url: runUrl, output },
+ })
+ }
+}
+
+// A completed check run never returns to in_progress: GitHub answers 200 and leaves it completed.
+async function decisionRuns(api, pull) {
+ const listed = await api(`/repos/${pull.repository}/commits/${pull.headSha}/check-runs?check_name=${encodeURIComponent(CHECK_NAME)}&filter=all&per_page=100`)
+ if (!isRecord(listed) || !Array.isArray(listed.check_runs) || listed.total_count !== listed.check_runs.length) {
+ throw new Error('check-run list response is invalid or incomplete')
+ }
+ return listed.check_runs.filter(run => isRecord(run) && isRecord(run.app) && run.app.slug === 'github-actions'
+ && (run.external_id === CHECK_RUN_MARKER || run.external_id === ''))
+}
+
+function requireHttpsRunUrl(runUrl) {
+ if (!/^https:\/\/[^\s]+$/u.test(runUrl)) throw new Error('workflow run URL must use HTTPS')
+}
+
async function publishStatus(api, pull, state, description, runUrl) {
if (!/^https:\/\/[^\s]+$/u.test(runUrl)) throw new Error('workflow run URL must use HTTPS')
if (description.length > 140) throw new Error('commit status description exceeds 140 characters')
diff --git a/.github/review-ownership/check-approval.test.mjs b/.github/review-ownership/check-approval.test.mjs
index b5d0b6cbb3..979661be10 100644
--- a/.github/review-ownership/check-approval.test.mjs
+++ b/.github/review-ownership/check-approval.test.mjs
@@ -11,13 +11,18 @@ import {
evaluateApproval as evaluateWithHistory,
listPullRequestReviews,
parseApprovalPolicy,
- runApprovalCheck as runWithHistory,
+ runApprovalCheck as runPublisher,
publishApprovalPhase,
} from './check-approval.mjs'
const policySource = readFileSync(new URL('approval-policy.json', import.meta.url), 'utf8')
-const withoutComments = api => (path, options) => path.includes('/comments?') ? [] : api(path, options)
+const emptyCheckRuns = { total_count: 0, check_runs: [] }
+const isCheckRunsList = path => path.includes('/commits/') && path.includes('/check-runs?')
+const withoutChecks = api => (path, options) =>
+ isCheckRunsList(path) ? emptyCheckRuns : path.includes('/check-runs') ? {} : api(path, options)
+const withoutComments = api => withoutChecks((path, options) => path.includes('/comments?') ? [] : api(path, options))
const evaluateApproval = options => evaluateWithHistory({ getMergedCount: async () => 0, ...options, api: withoutComments(options.api) })
+const runWithHistory = options => runPublisher({ ...options, api: withoutChecks(options.api) })
const runApprovalCheck = options => runWithHistory({ getMergedCount: async () => 0, ...options, api: withoutComments(options.api) })
const HEAD_SHA = '1234567890abcdef1234567890abcdef12345678'
@@ -475,16 +480,94 @@ test('uses policy endpoints and formats only the displayed score', async () => {
test('publishes setup phases without evaluating or installing dependencies', async () => {
const states = []
+ const phases = []
const options = {
event: pullRequestEvent(), runUrl: 'https://github.example/run/1',
- api: async (path, { body }) => { assert.match(path, /\/statuses\//u); states.push(body.state) },
+ api: async (path, options = {}) => {
+ if (isCheckRunsList(path)) return emptyCheckRuns
+ if (path.includes('/check-runs')) { phases.push(options.body?.conclusion ?? options.body?.status); return {} }
+ assert.match(path, /\/statuses\//u)
+ states.push(options.body.state)
+ },
}
await publishApprovalPhase({ ...options, phase: 'pending' })
await publishApprovalPhase({ ...options, phase: 'error' })
assert.deepEqual(states, ['pending', 'error'])
+ assert.deepEqual(phases, ['in_progress', 'failure'])
await assert.rejects(publishApprovalPhase({ ...options, phase: 'success' }), /invalid approval setup phase/u)
})
+test('keeps the status gate when the label write fails', async () => {
+ const writes = []
+ const states = []
+ await runPublisher({
+ event: pullRequestEvent(), policySource, runUrl: 'https://github.example/run/1',
+ write: line => writes.push(line),
+ getOwnership: async () => ({ totalLines: 100, reviewerLines: { turtle2099: 25 } }),
+ api: async (path, options = {}) => {
+ if (path.includes('/reviews?')) return [review('turtle2099', 'APPROVED')]
+ if (path.includes('/collaborators/turtle2099/permission')) return { permission: 'write' }
+ if (path.includes('/comments?')) return []
+ if (path.includes('/statuses/')) { states.push(options.body.state); return {} }
+ if (path.includes('/check-runs')) throw new Error('check runs unavailable')
+ throw new Error(`unexpected API path ${path}`)
+ },
+ })
+ assert.deepEqual(states, ['pending', 'success'])
+ assert.ok(writes.some(line => /Decision check run not published/.test(line)))
+})
+
+test('reports the decision on a non-required check run beside the status', async () => {
+ const calls = []
+ const api = async (path, options = {}) => {
+ calls.push({ path, method: options.method, body: options.body })
+ if (path.includes('/reviews?')) return [review('writer', 'APPROVED')]
+ if (path.includes('/collaborators/writer/permission')) return { permission: 'write' }
+ if (path.includes('/comments?')) return []
+ if (isCheckRunsList(path)) return emptyCheckRuns
+ if (path.includes('/check-runs') || path.includes('/statuses/')) return {}
+ throw new Error(`unexpected API path ${path}`)
+ }
+ const result = await runPublisher({
+ event: pullRequestEvent(), policySource, runUrl: 'https://github.example/run/1', write: () => {},
+ getOwnership: async () => ({ totalLines: 0, reviewerLines: {} }),
+ getMergedCount: async () => 0,
+ api,
+ })
+ const status = calls.filter(call => call.path.includes('/statuses/')).at(-1)
+ const check = calls.filter(call => call.path.endsWith('/check-runs')).at(-1)
+ assert.equal(result.state, 'pending')
+ assert.equal(status.body.state, 'pending')
+ assert.equal(check.body.name, 'weighted approval decision')
+ assert.equal(check.body.conclusion, 'action_required')
+})
+
+test('revokes a published success check run and updates one run per head', async () => {
+ const calls = []
+ const checkRuns = [
+ { id: 7, app: { slug: 'github-actions' }, conclusion: 'success', external_id: '' },
+ { id: 8, app: { slug: 'github-actions' }, conclusion: 'action_required', external_id: 'weighted-approval-decision' },
+ { id: 9, app: { slug: 'other-app' }, conclusion: 'success', external_id: '' },
+ { id: 10, app: { slug: 'github-actions' }, conclusion: 'success', external_id: 'a-job-check-run' },
+ ]
+ await publishApprovalPhase({
+ event: pullRequestEvent(), runUrl: 'https://github.example/run/1', phase: 'pending',
+ api: async (path, options = {}) => {
+ calls.push({ path, method: options.method, body: options.body })
+ return isCheckRunsList(path) ? { total_count: checkRuns.length, check_runs: checkRuns } : {}
+ },
+ })
+ assert.deepEqual(calls.map(call => call.path), [
+ `/repos/deepseek-harness/deepseek-harness/statuses/${HEAD_SHA}`,
+ `/repos/deepseek-harness/deepseek-harness/commits/${HEAD_SHA}/check-runs?check_name=weighted%20approval%20decision&filter=all&per_page=100`,
+ '/repos/deepseek-harness/deepseek-harness/check-runs/7',
+ ])
+ for (const call of calls.slice(2)) {
+ assert.equal(call.method, 'PATCH')
+ assert.equal(call.body.conclusion, 'action_required')
+ }
+})
+
for (const [mergedCount, credit] of [[0, 0], [1, 0.011], [50, 0.55], [99, 1.089], [100, 1.1], [101, 1.1], [200, 1.1]]) {
test(`author with ${mergedCount} merged PRs contributes ${credit} points but cannot approve alone`, async () => {
const result = await evaluateApproval({
diff --git a/.github/workflows/ci-python.yml b/.github/workflows/ci-python.yml
new file mode 100644
index 0000000000..baabdd143c
--- /dev/null
+++ b/.github/workflows/ci-python.yml
@@ -0,0 +1,87 @@
+name: CI Python
+
+# Python pull-request lanes run in their own workflow so a slow runtime build
+# does not keep the CI run in progress: GitHub re-runs failed jobs only after
+# every job of a run finishes, so each workflow can be re-run without waiting
+# for the others. Branch protection requires this workflow's "python checks
+# passed" verdict beside CI's "all checks passed" and CI Windows' "windows
+# checks passed".
+on:
+ pull_request:
+permissions:
+ contents: read
+
+env:
+ PRIMARY_NODE_VERSION: '24'
+ # CI runs must never report to the production telemetry endpoint baked
+ # into apps/cli/cordis.yml (AppCLIEntry disables the row when set).
+ DSH_TELEMETRY_DISABLED: '1'
+
+# Cancel a superseded pull-request run on a new push, as in ci.yml.
+concurrency:
+ group: ${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ python-sdk:
+ if: github.event_name == 'pull_request'
+ runs-on: ubuntu-latest
+ name: python 3.10 / keyless SDK
+ steps:
+ - uses: actions/checkout@v7.0.1
+
+ - uses: actions/setup-python@v6.3.0
+ with:
+ python-version: '3.10'
+ cache: pip
+
+ - name: Install uv
+ run: python -m pip install uv==0.11.23
+
+ - uses: actions/setup-node@v7.0.0
+ with:
+ node-version: 24
+
+ - name: Test production blame scoring
+ run: uv run --python 3.10 --with-requirements .github/review-ownership/requirements.txt python -m unittest discover -s .github/review-ownership -p 'test_*.py'
+
+ - name: Run complete keyless Python suite
+ run: uv run --python 3.10 --group test --project python/sdk pytest
+
+ # The reusable builder owns each published executable, wheel, clean-install,
+ # keyless black-box, and trusted real-API path. Linux and Windows x64 block
+ # pull requests; Linux ARM64 and both macOS architectures run in
+ # ci-master.yml.
+ python-runtime:
+ if: github.event_name == 'pull_request'
+ needs: python-sdk
+ name: python runtime / release-shaped matrix
+ uses: ./.github/workflows/build-exe-for-python-sdk.yml
+ with:
+ targets: node24-linux-x64,node24-win-x64
+ ci: true
+ secrets:
+ DEEPSEEK_API_KEY_EXTERNAL: ${{ secrets.DEEPSEEK_API_KEY_EXTERNAL }}
+
+ # Stable required check for the Python lanes, with the same semantics as
+ # ci.yml's "all checks passed": every blocking job in THIS workflow is
+ # listed in `needs`. The bookkeeping job follows the Linux failover switch
+ # like the other verdicts.
+ python-checks-passed:
+ name: python checks passed
+ runs-on: >-
+ ${{ vars.DSH_CI_FAILOVER_LINUX == 'blacksmith' && 'blacksmith-4vcpu-ubuntu-2404'
+ || vars.DSH_CI_FAILOVER_LINUX == 'selfhosted'
+ && github.event.pull_request.user.login != 'dependabot[bot]'
+ && fromJSON('["self-hosted", "linux", "x64", "vm-backup"]')
+ || 'ubuntu-latest' }}
+ needs: [python-sdk, python-runtime]
+ if: ${{ !cancelled() && github.event_name == 'pull_request' }}
+ steps:
+ - name: Fail if any needed job did not succeed
+ if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') || contains(needs.*.result, 'skipped')
+ run: |
+ echo "::error::Needed job results: ${{ join(needs.*.result, ', ') }}"
+ exit 1
+ - name: Python checks passed
+ run: echo "All needed jobs succeeded (${{ join(needs.*.result, ', ') }})"
diff --git a/.github/workflows/ci-windows.yml b/.github/workflows/ci-windows.yml
new file mode 100644
index 0000000000..bf6b02d382
--- /dev/null
+++ b/.github/workflows/ci-windows.yml
@@ -0,0 +1,258 @@
+name: CI Windows
+
+# Native Windows pull-request lanes run in their own workflow so a slow Windows
+# job does not keep the CI run in progress: GitHub re-runs failed jobs only
+# after every job of a run finishes, so each workflow can be re-run without
+# waiting for the others. Branch protection requires this workflow's
+# "windows checks passed" verdict beside CI's "all checks passed" and CI
+# Python's "python checks passed".
+on:
+ pull_request:
+permissions:
+ contents: read
+
+env:
+ PRIMARY_NODE_VERSION: '24'
+ # CI runs must never report to the production telemetry endpoint baked
+ # into apps/cli/cordis.yml (AppCLIEntry disables the row when set).
+ DSH_TELEMETRY_DISABLED: '1'
+
+# Cancel a superseded pull-request run on a new push, as in ci.yml.
+concurrency:
+ group: ${{ github.workflow }}-${{ github.ref }}
+ cancel-in-progress: true
+
+jobs:
+ # Native builds and process tests block pull requests independently of coverage.
+ # Observational checks reuse the successful build and remain non-blocking.
+ # Dependabot PRs are excluded from the self-hosted pool and stay queued for
+ # the hosted runner.
+ # Blacksmith uses 2 vCPU for file-serial native tests and 16 for coverage
+ # and the shared build/observational workspace.
+ windows-build:
+ if: github.event_name == 'pull_request'
+ runs-on: >-
+ ${{ vars.DSH_CI_FAILOVER_WINDOWS == 'blacksmith' && 'blacksmith-16vcpu-windows-2025'
+ || vars.DSH_CI_FAILOVER_WINDOWS == 'selfhosted'
+ && github.event.pull_request.user.login != 'dependabot[bot]'
+ && fromJSON('["self-hosted", "dsh-win-ci", "windows"]')
+ || 'dsh-windows-2025-16core' }}
+ name: windows node 24 / build & observational
+ timeout-minutes: 60
+ env:
+ # A failing build or site aborts the sibling gate on the same runner.
+ DSH_GATE_FAIL_FAST: '1'
+ steps:
+ - uses: actions/checkout@v7.0.1
+ with:
+ persist-credentials: false
+ - name: Enable Developer Mode (symlink support)
+ shell: pwsh
+ run: >-
+ reg add "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock"
+ /t REG_DWORD /f /v "AllowDevelopmentWithoutDevLicense" /d "1"
+ - uses: pnpm/action-setup@v5.0.0
+ with:
+ dest: ${{ runner.temp }}/setup-pnpm-js-${{ github.run_id }}-${{ github.run_attempt }}-${{ github.job }}
+ - uses: actions/setup-node@v7.0.0
+ with:
+ node-version: ${{ env.PRIMARY_NODE_VERSION }}
+ - name: Install (immutable)
+ shell: pwsh
+ # See 2026-08-30-windows-refs-store-block-clone-install for the
+ # ReFS block-clone rationale; detect the workspace filesystem and
+ # pass --package-import-method=clone only on ReFS.
+ run: >-
+ $drive = (Split-Path -Qualifier $env:GITHUB_WORKSPACE).TrimEnd(':');
+ $fs = (Get-Volume -DriveLetter $drive).FileSystem;
+ if ($fs -eq 'ReFS') {
+ corepack pnpm install --frozen-lockfile --package-import-method=clone
+ } else {
+ pnpm install --frozen-lockfile
+ }
+ - name: Run blocking Windows builds
+ shell: pwsh
+ run: pnpm run check:ci:windows-blocking
+ - name: Parse Windows runner supervision scripts
+ shell: pwsh
+ run: |
+ foreach ($path in @('apps/desktop/scripts/windows-runner-task.ps1', 'apps/desktop/scripts/run-windows-runner-task.ps1', 'apps/desktop/tests/windows-runner-task.ps1', 'apps/desktop/tests/windows-runner-launcher.ps1')) {
+ $tokens = $null
+ $parseErrors = $null
+ $null = [Management.Automation.Language.Parser]::ParseFile((Join-Path $env:GITHUB_WORKSPACE $path), [ref]$tokens, [ref]$parseErrors)
+ if ($parseErrors.Count) { throw ($parseErrors -join "`n") }
+ }
+ - name: Verify windowless Windows runner launcher
+ shell: pwsh
+ run: ./apps/desktop/tests/windows-runner-launcher.ps1
+ - name: Verify Windows packaging priority inheritance
+ shell: pwsh
+ run: ./apps/desktop/tests/windows-packaging-priority.ps1
+ - name: Run Windows observational gates on built artifacts
+ id: observational
+ continue-on-error: true
+ timeout-minutes: 15
+ shell: pwsh
+ env:
+ DSH_GATE_FAIL_FAST: ''
+ DSH_PUBLINT_CONCURRENCY: ${{ vars.DSH_CI_FAILOVER_WINDOWS == 'selfhosted' && github.event.pull_request.user.login != 'dependabot[bot]' && '8' || '' }}
+ run: pnpm run check:ci:windows-observational-ready
+ - name: Report Windows observational failures
+ continue-on-error: true
+ if: steps.observational.outcome == 'failure'
+ shell: pwsh
+ run: |
+ $message = 'Windows observational checks failed; see the observational step for diagnostics.'
+ Write-Output "::warning::$message"
+ $message | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Encoding utf8 -Append
+
+ windows-coverage:
+ if: github.event_name == 'pull_request'
+ runs-on: >-
+ ${{ vars.DSH_CI_FAILOVER_WINDOWS == 'blacksmith' && 'blacksmith-16vcpu-windows-2025'
+ || vars.DSH_CI_FAILOVER_WINDOWS == 'selfhosted'
+ && github.event.pull_request.user.login != 'dependabot[bot]'
+ && fromJSON('["self-hosted", "dsh-win-ci", "windows"]')
+ || 'dsh-windows-2025-16core' }}
+ name: windows node 24 / coverage
+ timeout-minutes: 120
+ env:
+ # Shared hosts expose host CPUs, not an isolated allocation.
+ DSH_COVERAGE_MAX_WORKERS: ${{ vars.DSH_CI_FAILOVER_WINDOWS == 'selfhosted' && github.event.pull_request.user.login != 'dependabot[bot]' && '6' || '' }}
+ DSH_COVERAGE_PARTITIONS: ${{ vars.DSH_CI_FAILOVER_WINDOWS == 'selfhosted' && github.event.pull_request.user.login != 'dependabot[bot]' && '4' || '' }}
+ DSH_GATE_CONCURRENCY: ${{ vars.DSH_CI_FAILOVER_WINDOWS == 'selfhosted' && github.event.pull_request.user.login != 'dependabot[bot]' && '3' || '' }}
+ DSH_COVERAGE_TEST_TIMEOUT_MS: '90000'
+ # A gate failure aborts the sibling gate instead of waiting out its
+ # multi-minute instrumented run.
+ DSH_GATE_FAIL_FAST: '1'
+ steps:
+ - uses: actions/checkout@v7.0.1
+ with:
+ persist-credentials: false
+ # Checkout removes the gitignored duration history, so restore it from
+ # the GitHub cache before coverage and save the updated one afterwards.
+ # The coordinator then weights partitions by measured durations on the
+ # second run instead of degrading to a file-count split. GitHub cache
+ # entries are immutable, so the save key is unique per run and the
+ # restore matches the newest entry through the stable prefix.
+ - name: Restore coverage duration history
+ uses: actions/cache/restore@v6.1.0
+ with:
+ path: .coverage-times.json
+ key: coverage-times-Windows-${{ runner.environment }}-${{ vars.DSH_CI_FAILOVER_WINDOWS || 'enterprise' }}-${{ github.run_id }}-${{ github.run_attempt }}
+ restore-keys: |
+ coverage-times-Windows-${{ runner.environment }}-${{ vars.DSH_CI_FAILOVER_WINDOWS || 'enterprise' }}-
+ - name: Enable Developer Mode (symlink support)
+ shell: pwsh
+ run: >-
+ reg add "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock"
+ /t REG_DWORD /f /v "AllowDevelopmentWithoutDevLicense" /d "1"
+ - uses: pnpm/action-setup@v5.0.0
+ with:
+ dest: ${{ runner.temp }}/setup-pnpm-js-${{ github.run_id }}-${{ github.run_attempt }}-${{ github.job }}
+ - uses: actions/setup-node@v7.0.0
+ with:
+ node-version: ${{ env.PRIMARY_NODE_VERSION }}
+ - name: Install (immutable)
+ shell: pwsh
+ # See 2026-08-30-windows-refs-store-block-clone-install for the
+ # ReFS block-clone rationale; detect the workspace filesystem and
+ # pass --package-import-method=clone only on ReFS.
+ run: >-
+ $drive = (Split-Path -Qualifier $env:GITHUB_WORKSPACE).TrimEnd(':');
+ $fs = (Get-Volume -DriveLetter $drive).FileSystem;
+ if ($fs -eq 'ReFS') {
+ corepack pnpm install --frozen-lockfile --package-import-method=clone
+ } else {
+ pnpm install --frozen-lockfile
+ }
+ # No build before coverage, matching the Linux lane: workspace imports
+ # resolve to src through the tsconfig paths map, and the lib-consuming
+ # suites (webworker-packer image-loadable, webworker-runtime
+ # transform-corpus, client ui-trajectory client-bundle) self-skip on
+ # unbuilt checkouts.
+ - name: Run Windows coverage
+ shell: pwsh
+ run: pnpm run check:ci:coverage
+ - name: Save coverage duration history
+ # Coverage flakes must not prevent the cache from building; the
+ # measured durations remain useful even when a partition failed. The
+ # per-run key keeps every save a fresh immutable cache entry.
+ if: ${{ !cancelled() }}
+ uses: actions/cache/save@v6.1.0
+ with:
+ path: .coverage-times.json
+ key: coverage-times-Windows-${{ runner.environment }}-${{ vars.DSH_CI_FAILOVER_WINDOWS || 'enterprise' }}-${{ github.run_id }}-${{ github.run_attempt }}
+
+ windows-native-tests:
+ if: github.event_name == 'pull_request'
+ runs-on: >-
+ ${{ vars.DSH_CI_FAILOVER_WINDOWS == 'blacksmith' && 'blacksmith-2vcpu-windows-2025'
+ || vars.DSH_CI_FAILOVER_WINDOWS == 'selfhosted'
+ && github.event.pull_request.user.login != 'dependabot[bot]'
+ && fromJSON('["self-hosted", "dsh-win-ci", "windows"]')
+ || 'dsh-windows-2025-16core' }}
+ name: windows node 24 / native tests
+ timeout-minutes: 60
+ steps:
+ - uses: actions/checkout@v7.0.1
+ with:
+ persist-credentials: false
+ - name: Enable Developer Mode (symlink support)
+ shell: pwsh
+ run: >-
+ reg add "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock"
+ /t REG_DWORD /f /v "AllowDevelopmentWithoutDevLicense" /d "1"
+ - uses: pnpm/action-setup@v5.0.0
+ with:
+ dest: ${{ runner.temp }}/setup-pnpm-js-${{ github.run_id }}-${{ github.run_attempt }}-${{ github.job }}
+ - uses: actions/setup-node@v7.0.0
+ with:
+ node-version: ${{ env.PRIMARY_NODE_VERSION }}
+ - name: Install (immutable)
+ shell: pwsh
+ # See 2026-08-30-windows-refs-store-block-clone-install for the
+ # ReFS block-clone rationale; detect the workspace filesystem and
+ # pass --package-import-method=clone only on ReFS.
+ run: >-
+ $drive = (Split-Path -Qualifier $env:GITHUB_WORKSPACE).TrimEnd(':');
+ $fs = (Get-Volume -DriveLetter $drive).FileSystem;
+ if ($fs -eq 'ReFS') {
+ corepack pnpm install --frozen-lockfile --package-import-method=clone
+ } else {
+ pnpm install --frozen-lockfile
+ }
+ - name: Run Windows-specific native tests
+ shell: pwsh
+ run: >-
+ pnpm exec vitest run
+ --no-file-parallelism
+ --testTimeout 90000
+ packages/shell/tool-pwsh/tests/loader.spec.ts
+ packages/workflow/workflow-ptc/tests/workflow-ptc.spec.ts
+ packages/experimental/tool-ralph/tests/integration.spec.ts
+ packages/subprocess/subprocess-local/tests/process-exit.spec.ts
+
+ # Stable required check for the Windows lanes, with the same semantics as
+ # ci.yml's "all checks passed": every blocking job in THIS workflow is
+ # listed in `needs`. windows-coverage stays outside the verdict, so its
+ # per-file result remains visible without blocking. The bookkeeping job
+ # follows the Linux failover switch like the CI verdict.
+ windows-checks-passed:
+ name: windows checks passed
+ runs-on: >-
+ ${{ vars.DSH_CI_FAILOVER_LINUX == 'blacksmith' && 'blacksmith-4vcpu-ubuntu-2404'
+ || vars.DSH_CI_FAILOVER_LINUX == 'selfhosted'
+ && github.event.pull_request.user.login != 'dependabot[bot]'
+ && fromJSON('["self-hosted", "linux", "x64", "vm-backup"]')
+ || 'ubuntu-latest' }}
+ needs: [windows-build, windows-native-tests]
+ if: ${{ !cancelled() && github.event_name == 'pull_request' }}
+ steps:
+ - name: Fail if any needed job did not succeed
+ if: contains(needs.*.result, 'failure') || contains(needs.*.result, 'cancelled') || contains(needs.*.result, 'skipped')
+ run: |
+ echo "::error::Needed job results: ${{ join(needs.*.result, ', ') }}"
+ exit 1
+ - name: Windows checks passed
+ run: echo "All needed jobs succeeded (${{ join(needs.*.result, ', ') }})"
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 96f5219a15..ae9db81e61 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -12,7 +12,7 @@ env:
DSH_TELEMETRY_DISABLED: '1'
# Cancel a superseded pull-request run on a new push so a fresh head does not
-# queue a second full 9-job run behind a stale one (paid enterprise runners
+# queue a second full run behind a stale one (paid enterprise runners
# would otherwise stack with no auto-cancellation).
concurrency:
group: ${{ github.workflow }}-${{ github.ref }}
@@ -36,9 +36,8 @@ jobs:
# Blacksmith's hosted runners sized per workload (see
# .agents/notes/implemented/process/2026-09-09-blacksmith-failover-leg.md). The
# in-house pool's readiness is re-proven on every master push by the
- # serial-linux-selfhosted standby lane in ci-master.yml. The Windows failover
- # switch is the separate DSH_CI_FAILOVER_WINDOWS variable on the windows-native
- # job below.
+ # serial-linux-selfhosted standby lane in ci-master.yml. Native Windows jobs
+ # and their separate DSH_CI_FAILOVER_WINDOWS switch live in ci-windows.yml.
node-24:
if: github.event_name == 'pull_request'
runs-on: >-
@@ -478,261 +477,13 @@ jobs:
- name: Check Loader internal shape detection
run: pnpm exec vitest run packages/boot/app-boot/tests/loader-shape.compat.spec.ts
- python-sdk:
- if: github.event_name == 'pull_request'
- runs-on: ubuntu-latest
- name: python 3.10 / keyless SDK
- steps:
- - uses: actions/checkout@v7.0.1
-
- - uses: actions/setup-python@v6.3.0
- with:
- python-version: '3.10'
- cache: pip
-
- - name: Install uv
- run: python -m pip install uv==0.11.23
-
- - uses: actions/setup-node@v7.0.0
- with:
- node-version: 24
-
- - name: Test production blame scoring
- run: uv run --python 3.10 --with-requirements .github/review-ownership/requirements.txt python -m unittest discover -s .github/review-ownership -p 'test_*.py'
-
- - name: Run complete keyless Python suite
- run: uv run --python 3.10 --group test --project python/sdk pytest
-
- # The reusable builder owns each published executable, wheel, clean-install,
- # keyless black-box, and trusted real-API path. Linux/Windows x64 block PRs;
- # Linux ARM64 and both macOS architectures run in ci-master.yml.
- python-runtime:
- if: github.event_name == 'pull_request'
- needs: python-sdk
- name: python runtime / release-shaped matrix
- uses: ./.github/workflows/build-exe-for-python-sdk.yml
- with:
- targets: node24-linux-x64,node24-win-x64
- ci: true
- secrets:
- DEEPSEEK_API_KEY_EXTERNAL: ${{ secrets.DEEPSEEK_API_KEY_EXTERNAL }}
-
- # Native builds and process tests block pull requests independently of coverage.
- # Observational checks reuse the successful build and remain non-blocking.
- # Dependabot PRs are excluded from the self-hosted pool and stay queued for
- # the hosted runner.
- # Blacksmith uses 2 vCPU for file-serial native tests and 16 for coverage
- # and the shared build/observational workspace.
- windows-build:
- if: github.event_name == 'pull_request'
- runs-on: >-
- ${{ vars.DSH_CI_FAILOVER_WINDOWS == 'blacksmith' && 'blacksmith-16vcpu-windows-2025'
- || vars.DSH_CI_FAILOVER_WINDOWS == 'selfhosted'
- && github.event.pull_request.user.login != 'dependabot[bot]'
- && fromJSON('["self-hosted", "dsh-win-ci", "windows"]')
- || 'dsh-windows-2025-16core' }}
- name: windows node 24 / build & observational
- timeout-minutes: 60
- env:
- # A failing build or site aborts the sibling gate on the same runner.
- DSH_GATE_FAIL_FAST: '1'
- steps:
- - uses: actions/checkout@v7.0.1
- with:
- persist-credentials: false
- - name: Enable Developer Mode (symlink support)
- shell: pwsh
- run: >-
- reg add "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock"
- /t REG_DWORD /f /v "AllowDevelopmentWithoutDevLicense" /d "1"
- - uses: pnpm/action-setup@v5.0.0
- with:
- dest: ${{ runner.temp }}/setup-pnpm-js-${{ github.run_id }}-${{ github.run_attempt }}-${{ github.job }}
- - uses: actions/setup-node@v7.0.0
- with:
- node-version: ${{ env.PRIMARY_NODE_VERSION }}
- - name: Install (immutable)
- shell: pwsh
- # See 2026-08-30-windows-refs-store-block-clone-install for the
- # ReFS block-clone rationale; detect the workspace filesystem and
- # pass --package-import-method=clone only on ReFS.
- run: >-
- $drive = (Split-Path -Qualifier $env:GITHUB_WORKSPACE).TrimEnd(':');
- $fs = (Get-Volume -DriveLetter $drive).FileSystem;
- if ($fs -eq 'ReFS') {
- corepack pnpm install --frozen-lockfile --package-import-method=clone
- } else {
- pnpm install --frozen-lockfile
- }
- - name: Run blocking Windows builds
- shell: pwsh
- run: pnpm run check:ci:windows-blocking
- - name: Parse Windows runner supervision scripts
- shell: pwsh
- run: |
- foreach ($path in @('apps/desktop/scripts/windows-runner-task.ps1', 'apps/desktop/scripts/run-windows-runner-task.ps1', 'apps/desktop/tests/windows-runner-task.ps1', 'apps/desktop/tests/windows-runner-launcher.ps1')) {
- $tokens = $null
- $parseErrors = $null
- $null = [Management.Automation.Language.Parser]::ParseFile((Join-Path $env:GITHUB_WORKSPACE $path), [ref]$tokens, [ref]$parseErrors)
- if ($parseErrors.Count) { throw ($parseErrors -join "`n") }
- }
- - name: Verify windowless Windows runner launcher
- shell: pwsh
- run: ./apps/desktop/tests/windows-runner-launcher.ps1
- - name: Verify packaging process priority inheritance
- shell: pwsh
- run: ./apps/desktop/tests/windows-packaging-priority.ps1
- - name: Run Windows observational gates on built artifacts
- id: observational
- continue-on-error: true
- timeout-minutes: 15
- shell: pwsh
- env:
- DSH_GATE_FAIL_FAST: ''
- DSH_PUBLINT_CONCURRENCY: ${{ vars.DSH_CI_FAILOVER_WINDOWS == 'selfhosted' && github.event.pull_request.user.login != 'dependabot[bot]' && '8' || '' }}
- run: pnpm run check:ci:windows-observational-ready
- - name: Report Windows observational failures
- continue-on-error: true
- if: steps.observational.outcome == 'failure'
- shell: pwsh
- run: |
- $message = 'Windows observational checks failed; see the observational step for diagnostics.'
- Write-Output "::warning::$message"
- $message | Out-File -FilePath $env:GITHUB_STEP_SUMMARY -Encoding utf8 -Append
-
- windows-coverage:
- if: github.event_name == 'pull_request'
- runs-on: >-
- ${{ vars.DSH_CI_FAILOVER_WINDOWS == 'blacksmith' && 'blacksmith-16vcpu-windows-2025'
- || vars.DSH_CI_FAILOVER_WINDOWS == 'selfhosted'
- && github.event.pull_request.user.login != 'dependabot[bot]'
- && fromJSON('["self-hosted", "dsh-win-ci", "windows"]')
- || 'dsh-windows-2025-16core' }}
- name: windows node 24 / coverage
- timeout-minutes: 120
- env:
- # Shared hosts expose host CPUs, not an isolated allocation.
- DSH_COVERAGE_MAX_WORKERS: ${{ vars.DSH_CI_FAILOVER_WINDOWS == 'selfhosted' && github.event.pull_request.user.login != 'dependabot[bot]' && '6' || '' }}
- DSH_COVERAGE_PARTITIONS: ${{ vars.DSH_CI_FAILOVER_WINDOWS == 'selfhosted' && github.event.pull_request.user.login != 'dependabot[bot]' && '4' || '' }}
- DSH_GATE_CONCURRENCY: ${{ vars.DSH_CI_FAILOVER_WINDOWS == 'selfhosted' && github.event.pull_request.user.login != 'dependabot[bot]' && '3' || '' }}
- DSH_COVERAGE_TEST_TIMEOUT_MS: '90000'
- # A gate failure aborts the sibling gate instead of waiting out its
- # multi-minute instrumented run.
- DSH_GATE_FAIL_FAST: '1'
- steps:
- - uses: actions/checkout@v7.0.1
- with:
- persist-credentials: false
- # Checkout removes the gitignored duration history, so restore it from
- # the GitHub cache before coverage and save the updated one afterwards.
- # The coordinator then weights partitions by measured durations on the
- # second run instead of degrading to a file-count split. GitHub cache
- # entries are immutable, so the save key is unique per run and the
- # restore matches the newest entry through the stable prefix.
- - name: Restore coverage duration history
- uses: actions/cache/restore@v6.1.0
- with:
- path: .coverage-times.json
- key: coverage-times-Windows-${{ runner.environment }}-${{ vars.DSH_CI_FAILOVER_WINDOWS || 'enterprise' }}-${{ github.run_id }}-${{ github.run_attempt }}
- restore-keys: |
- coverage-times-Windows-${{ runner.environment }}-${{ vars.DSH_CI_FAILOVER_WINDOWS || 'enterprise' }}-
- - name: Enable Developer Mode (symlink support)
- shell: pwsh
- run: >-
- reg add "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock"
- /t REG_DWORD /f /v "AllowDevelopmentWithoutDevLicense" /d "1"
- - uses: pnpm/action-setup@v5.0.0
- with:
- dest: ${{ runner.temp }}/setup-pnpm-js-${{ github.run_id }}-${{ github.run_attempt }}-${{ github.job }}
- - uses: actions/setup-node@v7.0.0
- with:
- node-version: ${{ env.PRIMARY_NODE_VERSION }}
- - name: Install (immutable)
- shell: pwsh
- # See 2026-08-30-windows-refs-store-block-clone-install for the
- # ReFS block-clone rationale; detect the workspace filesystem and
- # pass --package-import-method=clone only on ReFS.
- run: >-
- $drive = (Split-Path -Qualifier $env:GITHUB_WORKSPACE).TrimEnd(':');
- $fs = (Get-Volume -DriveLetter $drive).FileSystem;
- if ($fs -eq 'ReFS') {
- corepack pnpm install --frozen-lockfile --package-import-method=clone
- } else {
- pnpm install --frozen-lockfile
- }
- # No build before coverage, matching the Linux lane: workspace imports
- # resolve to src through the tsconfig paths map, and the lib-consuming
- # suites (webworker-packer image-loadable, webworker-runtime
- # transform-corpus, client ui-trajectory client-bundle) self-skip on
- # unbuilt checkouts.
- - name: Run Windows coverage
- shell: pwsh
- run: pnpm run check:ci:coverage
- - name: Save coverage duration history
- # Coverage flakes must not prevent the cache from building; the
- # measured durations remain useful even when a partition failed. The
- # per-run key keeps every save a fresh immutable cache entry.
- if: ${{ !cancelled() }}
- uses: actions/cache/save@v6.1.0
- with:
- path: .coverage-times.json
- key: coverage-times-Windows-${{ runner.environment }}-${{ vars.DSH_CI_FAILOVER_WINDOWS || 'enterprise' }}-${{ github.run_id }}-${{ github.run_attempt }}
-
- windows-native-tests:
- if: github.event_name == 'pull_request'
- runs-on: >-
- ${{ vars.DSH_CI_FAILOVER_WINDOWS == 'blacksmith' && 'blacksmith-2vcpu-windows-2025'
- || vars.DSH_CI_FAILOVER_WINDOWS == 'selfhosted'
- && github.event.pull_request.user.login != 'dependabot[bot]'
- && fromJSON('["self-hosted", "dsh-win-ci", "windows"]')
- || 'dsh-windows-2025-16core' }}
- name: windows node 24 / native tests
- timeout-minutes: 60
- steps:
- - uses: actions/checkout@v7.0.1
- with:
- persist-credentials: false
- - name: Enable Developer Mode (symlink support)
- shell: pwsh
- run: >-
- reg add "HKLM\SOFTWARE\Microsoft\Windows\CurrentVersion\AppModelUnlock"
- /t REG_DWORD /f /v "AllowDevelopmentWithoutDevLicense" /d "1"
- - uses: pnpm/action-setup@v5.0.0
- with:
- dest: ${{ runner.temp }}/setup-pnpm-js-${{ github.run_id }}-${{ github.run_attempt }}-${{ github.job }}
- - uses: actions/setup-node@v7.0.0
- with:
- node-version: ${{ env.PRIMARY_NODE_VERSION }}
- - name: Install (immutable)
- shell: pwsh
- # See 2026-08-30-windows-refs-store-block-clone-install for the
- # ReFS block-clone rationale; detect the workspace filesystem and
- # pass --package-import-method=clone only on ReFS.
- run: >-
- $drive = (Split-Path -Qualifier $env:GITHUB_WORKSPACE).TrimEnd(':');
- $fs = (Get-Volume -DriveLetter $drive).FileSystem;
- if ($fs -eq 'ReFS') {
- corepack pnpm install --frozen-lockfile --package-import-method=clone
- } else {
- pnpm install --frozen-lockfile
- }
- - name: Run Windows-specific native tests
- shell: pwsh
- run: >-
- pnpm exec vitest run
- --no-file-parallelism
- --testTimeout 90000
- packages/shell/tool-pwsh/tests/loader.spec.ts
- packages/workflow/workflow-ptc/tests/workflow-ptc.spec.ts
- packages/experimental/tool-ralph/tests/integration.spec.ts
- packages/subprocess/subprocess-local/tests/process-exit.spec.ts
-
# Single stable required check for branch protection: require "all checks
# passed" instead of enumerating matrix legs whose names change as lanes and
# node versions evolve. Every blocking job in THIS workflow must be listed in
- # `needs`. Native Windows build and process checks are required; Wine and
- # the deferred Python runtime targets live in ci-master.yml and do not
- # participate in this PR verdict. `needs` cannot cross workflow files.
+ # `needs`. `needs` cannot cross workflow files: native Windows jobs report
+ # the separate "windows checks passed" verdict from ci-windows.yml, Python
+ # jobs report "python checks passed" from ci-python.yml, and Wine plus the
+ # master-only runtime targets live in ci-master.yml.
# An explicit status function runs the verdict after failed/skipped needs
# without keeping a cancelled workflow alive for an obsolete verdict.
all-checks-passed:
@@ -752,7 +503,7 @@ jobs:
&& github.event.pull_request.user.login != 'dependabot[bot]'
&& fromJSON('["self-hosted", "linux", "x64", "vm-backup"]')
|| 'ubuntu-latest' }}
- needs: [node-24, node-24-coverage, node-24-bench, node-24-consumers, node-compat, python-sdk, python-runtime, windows-build, windows-native-tests]
+ needs: [node-24, node-24-coverage, node-24-bench, node-24-consumers, node-compat]
if: ${{ !cancelled() && github.event_name == 'pull_request' }}
steps:
- name: Fail if any needed job did not succeed
diff --git a/.github/workflows/weighted-approval.yml b/.github/workflows/weighted-approval.yml
index eb6f2fe3ba..2a20d83d5b 100644
--- a/.github/workflows/weighted-approval.yml
+++ b/.github/workflows/weighted-approval.yml
@@ -10,6 +10,7 @@ on:
types: [completed]
permissions:
+ checks: write
contents: read
pull-requests: write
statuses: write
diff --git a/AGENTS.md b/AGENTS.md
index 5ee465f84d..69dbd7d69e 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -135,6 +135,7 @@ Real-API tests/demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`, and
- **Switch on discriminant tags.** Closed unions end in `assertNever`; merge-extensible unions fall through a documented default.
- **Waterfall listeners MUST call `next()`** to delegate; returning without it short-circuits the chain ([semantics](docs/cordis-primer.md#cordis-waterfall-semantics)).
- **Model-visible ⟺ logged**: anything that reaches a model request must be reconstructable from the session log; a new model-visible input requires a session event.
+- **Session projections:** follow [dsh-session-projection](.agents/skills/dsh-session-projection/SKILL.md) when creating, extending, or reviewing one, or migrating a fold helper to one.
- **Plugins, not loop changes**: new behavior goes on documented extension points; changing `agent-loop` requires updating docs/architecture.md.
- **A capability seam comprises Service Definition / Service Provider / Consumer roles.** It is complete, never one role; split only when roles evolve independently ([glossary](docs/glossary.md#capability-seam)).
- **Prefer maintained dependencies over hand-rolling** when they genuinely delete owned code and tests ([policy](.agents/notes/implemented/process/2026-07-26-dependencies-over-hand-rolling.md)).
@@ -154,7 +155,7 @@ Real-API tests/demos read `DEEPSEEK_API_KEY`, optional `DEEPSEEK_BASE_URL`, and
- **Tests describe behavior, not correctness.** Change obsolete behavior with its tests; explain why in the PR.
- **Create Agent Notes only for durable decision rationale;** mechanical/local edits are exempt, including local UI changes ([scope](.agents/notes/README.md#when-to-write-one)). Archived notes are frozen: never edit or treat them as current authority ([archive policy](.agents/notes/README.md#archiving-and-deletion)).
- **Official plugin artwork:** use [dsh-official-plugin-artwork](.agents/skills/dsh-official-plugin-artwork/SKILL.md) for official and official experimental plugin icons; obtain designer approval before landing new glyphs.
-- **Client UI copy is locale-owned.** Route product text through typed dictionaries and `t` or localized primitive props; `verify-client-ui-i18n` rejects hardcoded copy ([decision](.agents/notes/implemented/architecture/2026-08-23-locale-owned-client-ui-copy.md)).
+- **Client UI copy is locale-owned.** Route product text through typed dictionaries and `t` or localized primitive props; `verify-client-ui-i18n` rejects hardcoded copy ([decision](.agents/notes/implemented/architecture/2026-08-23-locale-owned-client-ui-copy.md)). English copy, including plugin titles, uses sentence case ([rule](.agents/skills/dsh-prose-standard/SKILL.md#required-coverage-by-prose-location)).
- **Testing policy** — [docs/testing.md](docs/testing.md). Every non-trivial model- or product-user-visible change updates a keyless recorded-session snapshot; [snapshot ownership](snapshots/AGENTS.md) reserves the top-level tree for session-driven cases and keeps other expected output owner-local. Fixtures replay on macOS/Linux; fix fixtures, not normalizers.
- **Design each tool's UI presentation up front.** Host presenters stay pure; Web cards derive from raw events and persisted result metadata ([cookbook](docs/cookbook/adding-a-tool.md)).
- **Plan unit, e2e, and snapshot coverage** for capability seams, lifecycle paths, and transcript output; include missing snapshot-harness support in the same change.
diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
index 43b8d64815..b08c83a529 100644
--- a/THIRD_PARTY_NOTICES.md
+++ b/THIRD_PARTY_NOTICES.md
@@ -78,6 +78,7 @@ External packages installed for runtime use or embedded in distributed Host or b
| [`ajv`](https://github.com/ajv-validator/ajv) | MIT |
| [`anser`](https://github.com/IonicaBizau/anser) | MIT |
| [`big.js`](https://github.com/MikeMcl/big.js) | MIT |
+| [`birpc`](https://github.com/antfu-collective/birpc) | MIT |
| [`buffer`](https://github.com/feross/buffer) | MIT |
| [`chokidar`](https://github.com/paulmillr/chokidar) | MIT |
| [`chrome-devtools-frontend`](https://github.com/ChromeDevTools/devtools-frontend) | BSD-3-Clause |
@@ -113,6 +114,7 @@ External packages installed for runtime use or embedded in distributed Host or b
| [`micromark-util-classify-character`](https://github.com/micromark/micromark/tree/main/packages/micromark-util-classify-character) | MIT |
| [`micromark-util-sanitize-uri`](https://github.com/micromark/micromark/tree/main/packages/micromark-util-sanitize-uri) | MIT |
| [`micromark-util-symbol`](https://github.com/micromark/micromark/tree/main/packages/micromark-util-symbol) | MIT |
+| [`mime`](https://github.com/broofa/mime) | MIT |
| [`mime-types`](https://github.com/jshttp/mime-types) | MIT |
| [`minisearch`](https://github.com/lucaong/minisearch) | MIT |
| [`negotiator`](https://github.com/jshttp/negotiator) | MIT |
diff --git a/apps/cli/composition.md b/apps/cli/composition.md
index 781c08b12c..21150774cc 100644
--- a/apps/cli/composition.md
+++ b/apps/cli/composition.md
@@ -40,8 +40,6 @@ flowchart LR
cfg --> plugin_dsh_base_user_questions
plugin_dsh_base_agent["agent {
- return harness.tools.execute({
+ return executeModelToolFixture(harness, {
callId: ToolCallId(`keyless-code-${++keylessCall}`),
name: RUN_CODE_NAME,
arguments: { code, description: 'Run the e2e program' },
@@ -308,7 +309,7 @@ describe('PTC mode typed values: keyless real-process contracts', () => {
return { provider: provider.id, names: inspected.data.tools.map(tool => tool.name) };
`, testToolSignal, agent))
- expect(value).toEqual({ provider: 'Tool', names: ['cordis_inspect_list', 'cordis_inspect_query', 'run_code'] })
+ expect(value).toEqual({ provider: 'Tool', names: ['cordis_inspect_list', 'cordis_inspect_query'] })
})
})
diff --git a/apps/cli/tests/profiles/headless/tests/source-tool.built.e2e.ts b/apps/cli/tests/profiles/headless/tests/source-tool.built.e2e.ts
index 4988ef80fd..03f94856f4 100644
--- a/apps/cli/tests/profiles/headless/tests/source-tool.built.e2e.ts
+++ b/apps/cli/tests/profiles/headless/tests/source-tool.built.e2e.ts
@@ -58,7 +58,6 @@ describe.skipIf(!existsSync(join(repoRoot, 'apps/cli/lib/bin.js')))('dsh SOURCE
DSH_HOME: join(root, 'home'),
DSH_AGENTS_HOME: join(root, 'agents'),
DSH_TELEMETRY_DISABLED: '1',
- DSH_TOOLS_MODE: 'native',
DSH_CLI_MOCK_FAILURE: '0',
},
input: '',
diff --git a/apps/cli/tests/profiles/sdk/dynamic-tool-cache.e2e.ts b/apps/cli/tests/profiles/sdk/dynamic-tool-cache.e2e.ts
index b1b2c88128..ec5fe6ad94 100644
--- a/apps/cli/tests/profiles/sdk/dynamic-tool-cache.e2e.ts
+++ b/apps/cli/tests/profiles/sdk/dynamic-tool-cache.e2e.ts
@@ -85,7 +85,6 @@ describe.skipIf(!process.env.DEEPSEEK_API_KEY)('SDK native tool updates with rea
retryPolicy: { mode: 'normal', maxRetries: 0 } satisfies RetryPolicyConfig,
models: [{ id: 'deepseek-flash', systemPromptUpdate: 'in-history', toolUpdate: 'addition-only' }],
} },
- { id: 'tools', config: { mode: 'native' } },
{ id: 'session-log-deepseek', disabled: true },
{ id: 'plugin-package-inventory-deepseek', disabled: true },
{ insert: [{ id: 'sdk-dynamic-tool-cache-fixture', name: fixturePath, config: { evidencePath, callsPath, sampleLabel, updatePrompt } }] },
diff --git a/apps/cli/tests/profiles/sdk/keyless-smoke.e2e.ts b/apps/cli/tests/profiles/sdk/keyless-smoke.e2e.ts
index a65f11c29e..6f8add8c49 100644
--- a/apps/cli/tests/profiles/sdk/keyless-smoke.e2e.ts
+++ b/apps/cli/tests/profiles/sdk/keyless-smoke.e2e.ts
@@ -3,9 +3,9 @@ import { cp, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/pr
import { tmpdir } from 'node:os'
import { dirname, join } from 'node:path'
import { fileURLToPath } from 'node:url'
-import { promisify } from 'node:util'
-import { zstdDecompress } from 'node:zlib'
+import { zstdDecompressSync } from 'node:zlib'
import { resolveExampleLaunch } from '@deepseek-ai/dsh-loader-smoke'
+import { scanZstdFrames } from '@deepseek-ai/dsh-session-persistence-jsonl/src/zstd.js'
import { execa } from 'execa'
import { describe, expect, it, onTestFinished } from 'vitest'
import { workspaceDependencyPaths, type PrimaryRuntimeManifest } from '@deepseek-ai/dsh-tool-workspace-dependencies'
@@ -17,7 +17,6 @@ const launch = resolveExampleLaunch({
srcBin: fileURLToPath(new URL('../../../src/bin.ts', import.meta.url)),
mode: 'lib',
})
-const decompress = promisify(zstdDecompress)
function waitForLine(
@@ -58,7 +57,7 @@ describe('Python SDK dsh profile keyless smoke', () => {
{ label: 'reports max-token turns with mapping enabled through env', envValue: 'true', editorEnabled: false },
{ label: 'reports max-token turns with mapping disabled through env', envValue: 'false', editorEnabled: false },
{ label: 'allows an explicit patch to enable str_replace_editor', envValue: undefined, editorEnabled: true },
- { label: 'uses desktop tools through the PTC environment switch', envValue: undefined, editorEnabled: false, ptc: true },
+ { label: 'uses the PTC executor overlay despite the retired environment selector', envValue: undefined, editorEnabled: false, ptc: true },
])('$label', async (scenario) => {
const { envValue, editorEnabled } = scenario
const ptc = 'ptc' in scenario && scenario.ptc
@@ -92,6 +91,7 @@ describe('Python SDK dsh profile keyless smoke', () => {
'--profile',
'sdk',
...(editorEnabled ? ['--patch', editorPatch] : []),
+ ...(ptc ? ['--patch', join(repoRoot, 'apps/cli/config/examples/ptc.yml')] : []),
], {
cwd: repoRoot,
env: {
@@ -99,7 +99,7 @@ describe('Python SDK dsh profile keyless smoke', () => {
DSH_HOME: join(root, '.dsh'),
DSH_PERMISSION_MODE: 'danger-full-access',
DSH_TELEMETRY_DISABLED: '1',
- DSH_TOOLS_MODE: ptc ? 'ptc' : 'native',
+ DSH_TOOLS_MODE: ptc ? 'native' : 'ptc',
DEEPSEEK_API_KEY: 'keyless-smoke-no-call',
DEEPSEEK_BASE_URL: `http://127.0.0.1:${address.port}`,
...(envValue === undefined ? {} : { DSH_MAX_TOKENS_AS_SUCCESS: envValue }),
@@ -198,11 +198,30 @@ describe('Python SDK dsh profile keyless smoke', () => {
expect(exit.exitCode, `signal=${String(exit.signal)}; stderr=${stderr}`).toBe(0)
const sessionsRoot = join(root, '.dsh', 'sessions')
const files = await readdir(sessionsRoot, { recursive: true })
- const log = files.find(file => file.endsWith('.jsonl.zstd'))
+ // Session logs are JSONL across one zstd frame per batch, header frame
+ // first. Decompress frames explicitly: a single call over concatenated
+ // frames returned only the first frame on Node 24.19 and returns every
+ // frame on 24.22, so neither behavior may back the assertion.
+ const logs: { compressed: Buffer; header: Record }[] = []
+ for (const file of files.filter(file => file.endsWith('.jsonl.zstd'))) {
+ const compressed = await readFile(join(sessionsRoot, file))
+ expect(compressed.subarray(0, 4).toString('hex')).toBe('28b52ffd')
+ const first = scanZstdFrames(compressed).frames[0]
+ if (first === undefined) continue
+ const headerLine = zstdDecompressSync(compressed.subarray(first.start, first.end)).toString().trim().split('\n')[0]
+ if (headerLine === undefined) continue
+ logs.push({ compressed, header: JSON.parse(headerLine) as Record })
+ }
+ const log = logs.find(entry => entry.header.type === 'session' && entry.header.id === 'main')
expect(log).toBeDefined()
- const compressed = await readFile(join(sessionsRoot, log!))
- expect(compressed.subarray(0, 4).toString('hex')).toBe('28b52ffd')
- expect(JSON.parse((await decompress(compressed)).toString())).toMatchObject({ type: 'session', id: 'main' })
+ const { frames, tornStart } = scanZstdFrames(log!.compressed)
+ expect(tornStart).toBeUndefined()
+ const records = frames
+ .flatMap(({ start, end }) => zstdDecompressSync(log!.compressed.subarray(start, end)).toString().trim().split('\n'))
+ .map(line => JSON.parse(line) as Record)
+ expect(records[0]).toMatchObject({ type: 'session', id: 'main' })
+ expect(records.length).toBeGreaterThan(1)
+ expect(records.some(record => record.type === 'turn/end')).toBe(true)
} finally {
// No-op after exit; reject: false settles on every outcome, so cleanup never races teardown.
child.kill('SIGKILL')
diff --git a/apps/cli/tests/profiles/sdk/office-cli.e2e.ts b/apps/cli/tests/profiles/sdk/office-cli.e2e.ts
index 2c90e5fc6e..7c8a94748d 100644
--- a/apps/cli/tests/profiles/sdk/office-cli.e2e.ts
+++ b/apps/cli/tests/profiles/sdk/office-cli.e2e.ts
@@ -58,7 +58,7 @@ it.skipIf(!process.env.DEEPSEEK_API_KEY || process.platform === 'win32')(`agent
], {
cwd: root, env: {
PATH: path, DSH_HOME: join(root, 'home'), DSH_AGENTS_HOME: join(root, 'agents'),
- DSH_PERMISSION_MODE: 'danger-full-access', DSH_TELEMETRY_DISABLED: '1', DSH_TOOLS_MODE: 'native',
+ DSH_PERMISSION_MODE: 'danger-full-access', DSH_TELEMETRY_DISABLED: '1',
DSH_PRIMARY_RUNTIME: carrier === 'sdk' ? undefined : '',
},
timeout: 110_000, killSignal: 'SIGKILL', reject: false,
diff --git a/apps/cli/tests/profiles/sdk/schedule-resume.e2e.ts b/apps/cli/tests/profiles/sdk/schedule-resume.e2e.ts
index 46b880cb78..f3efcf6dd1 100644
--- a/apps/cli/tests/profiles/sdk/schedule-resume.e2e.ts
+++ b/apps/cli/tests/profiles/sdk/schedule-resume.e2e.ts
@@ -49,7 +49,7 @@ it('delivers an overdue reminder with the SDK route and lets the client resume t
await new Promise(resolve => server.listen(0, '127.0.0.1', resolve))
const address = server.address()
if (address === null || typeof address === 'string') throw new Error('model fixture has no port')
- const env = { ...process.env, DSH_TOOLS_MODE: 'native', DSH_PERMISSION_MODE: 'danger-full-access', DSH_TELEMETRY_DISABLED: '1',
+ const env = { ...process.env, DSH_PERMISSION_MODE: 'danger-full-access', DSH_TELEMETRY_DISABLED: '1',
DEEPSEEK_API_KEY: 'keyless-schedule-fixture', DEEPSEEK_BASE_URL: `http://127.0.0.1:${String(address.port)}` }
clearAmbientProxyEnv(env)
const first = new DeepSeekHarness({ cwd: root, dshHome: join(root, '.dsh'), patches: [patch],
diff --git a/apps/cli/tests/profiles/sdk/user-questions.e2e.ts b/apps/cli/tests/profiles/sdk/user-questions.e2e.ts
index 3185cf4aa9..b13b0dd542 100644
--- a/apps/cli/tests/profiles/sdk/user-questions.e2e.ts
+++ b/apps/cli/tests/profiles/sdk/user-questions.e2e.ts
@@ -3,6 +3,7 @@ import { createServer } from 'node:http'
import { mkdtemp, rm } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join } from 'node:path'
+import { fileURLToPath } from 'node:url'
import { DeepSeekHarness, type SdkUserQuestionRequest } from '@deepseek-ai/dsh-sdk-client'
import { clearAmbientProxyEnv } from '../../../../../scripts/test-proxy-environment.ts'
import { expect, it, onTestFinished } from 'vitest'
@@ -47,13 +48,14 @@ it.each([
await new Promise(resolve => server.listen(0, '127.0.0.1', resolve))
const address = server.address()
if (address === null || typeof address === 'string') throw new Error('model fixture has no port')
- const env = { ...process.env, DSH_TOOLS_MODE: mode, DSH_PERMISSION_MODE: 'danger-full-access', DSH_TELEMETRY_DISABLED: '1',
+ const env = { ...process.env, DSH_PERMISSION_MODE: 'danger-full-access', DSH_TELEMETRY_DISABLED: '1',
DEEPSEEK_API_KEY: 'keyless-question-fixture', DEEPSEEK_BASE_URL: `http://127.0.0.1:${String(address.port)}` }
clearAmbientProxyEnv(env)
const seen: SdkUserQuestionRequest[] = []
const entered = Promise.withResolvers()
const harness = state.harness = new DeepSeekHarness({
cwd: root, dshHome: join(root, '.dsh'), env, model: 'deepseek-v4-pro', maxTokens: 1234, initializeTimeoutMs: 30_000,
+ patches: mode === 'ptc' ? [fileURLToPath(new URL('../../../config/examples/ptc.yml', import.meta.url))] : [],
onUserQuestion: async (request, { signal }) => {
expect(signal.aborted).toBe(false)
seen.push(request)
diff --git a/apps/cli/tests/profiles/web/tests/fixtures/creator-plugin-manager.mjs b/apps/cli/tests/profiles/web/tests/fixtures/creator-plugin-manager.mjs
index b13cc06455..3b0f7bdc32 100644
--- a/apps/cli/tests/profiles/web/tests/fixtures/creator-plugin-manager.mjs
+++ b/apps/cli/tests/profiles/web/tests/fixtures/creator-plugin-manager.mjs
@@ -1,4 +1,6 @@
/** Test-only IPC assertions over real Creator presets and profile management. */
+import { executeModelToolFixture } from '@deepseek-ai/dsh-tool-testkit'
+
export const inject = ['agents', 'agentPresets', 'tools', 'pluginManager', 'permissionPresets']
export function apply(ctx, config) {
@@ -30,7 +32,7 @@ export function apply(ctx, config) {
try {
const first = await make(`${phase}-first`)
const before = names(first)
- const manage = args => ctx.tools.execute({ name: 'plugin_manager', arguments: args, agent: first,
+ const manage = args => executeModelToolFixture(ctx, { name: 'plugin_manager', arguments: args, agent: first,
callId: `${phase}-manage`, signal: new AbortController().signal })
ctx.permissionPresets.set(first.session, 'workspace-write')
first.session.append('turn/start', { turn: 1 })
@@ -45,7 +47,7 @@ export function apply(ctx, config) {
const second = await make(`${phase}-second`)
const after = names(first)
const other = names(second)
- const ping = await ctx.tools.execute({ name: 'mcp__demo__ping', arguments: {}, agent: first,
+ const ping = await executeModelToolFixture(ctx, { name: 'mcp__demo__ping', arguments: {}, agent: first,
callId: `${phase}-ping`, signal: new AbortController().signal })
const removed = phase === 'restart'
? JSON.parse((await manage({ action: 'remove_bundle', target: '@test/creator-mcp' })).value) : undefined
diff --git a/apps/cli/tests/web-agent-presets.e2e.ts b/apps/cli/tests/web-agent-presets.e2e.ts
index 9bc37e78b2..b06fd1b4e4 100644
--- a/apps/cli/tests/web-agent-presets.e2e.ts
+++ b/apps/cli/tests/web-agent-presets.e2e.ts
@@ -1,3 +1,4 @@
+import { executeToolFixture } from '@deepseek-ai/dsh-tool-testkit'
import { agentPresetProjectionDefinition } from '@deepseek-ai/dsh-agent-preset-registry'
import { subagentModelSelectionProjectionDefinition } from '@deepseek-ai/dsh-tool-subagent/src/model-selection-state.ts'
import { createRequire } from 'node:module'
@@ -300,7 +301,7 @@ describe('the shipped Web composition', () => {
// depend on ripgrep being present on the machine.
expect(toolNames(ctx, handle.agent).filter(name => name !== 'glob' && name !== 'grep')).toEqual([
'ask_user_question', 'bash', 'create_goal', 'edit', 'exit_plan_mode',
- 'get_goal', 'interrupt_agent', 'job_kill', 'job_list', 'job_output', 'list_agents', 'list_subagent_models', 'present', 'read', 'read_image',
+ 'get_goal', 'interrupt_agent', 'job_kill', 'job_list', 'job_output', 'list_agents', 'list_subagent_models', 'plugin_manager', 'present', 'read', 'read_image',
'schedule_create', 'schedule_delete', 'schedule_list', 'schedule_update',
'send_message', 'skill',
'subagent', 'subagent_fork', 'todo_write', 'update_goal', 'web_fetch', 'web_search',
@@ -629,7 +630,7 @@ describe('the shipped Web composition', () => {
expect(scoped).toContain('project-proof')
// The preset's own loader tool resolves the global-layer skill.
- const loaded = await ctx.tools.execute({
+ const loaded = await executeToolFixture(ctx, {
callId: ToolCallId('preset-skills-load'),
name: 'skill',
arguments: { name: 'dsh-badge' },
@@ -787,7 +788,7 @@ describe('a user preset declared from the shipped cordis rows', () => {
]))
}
const signal = new AbortController().signal
- const listed = await copyCtx.tools.execute({
+ const listed = await executeToolFixture(copyCtx, {
callId: ToolCallId('copied-preset-inspect-list'),
name: 'cordis_inspect_list',
arguments: {},
@@ -802,7 +803,7 @@ describe('a user preset declared from the shipped cordis rows', () => {
// The `Tool` provider is the one built over the host context: it
// answers with the shared registry's view of the REQUESTING agent,
// so the copy sees its own preset's tools, not the host's empty set.
- const queried = await copyCtx.tools.execute({
+ const queried = await executeToolFixture(copyCtx, {
callId: ToolCallId('copied-preset-inspect-tools'),
name: 'cordis_inspect_query',
arguments: { platform: 'host', provider: 'Tool', method: 'listTools' },
@@ -819,12 +820,12 @@ describe('a user preset declared from the shipped cordis rows', () => {
expect(queriedText).toContain(`"name": "${toolName}"`)
}
- // The `Config` provider reads the booted profile tree: the shipped `tools` row declares a Config,
+ // The `Config` provider reads the booted profile tree: the Agent loop declares a Config,
// and the bootstrap include row is a carrier. The name filter keeps each page small.
type ConfigRow = { id: string; patchId: string; name: string; status: string }
type ConfigPage = { data: { entries: ConfigRow[]; total: number; nextOffset: number | null } }
const listConfigs = async (input: Record, callId: string): Promise => {
- const page = await copyCtx.tools.execute({
+ const page = await executeToolFixture(copyCtx, {
callId: ToolCallId(callId),
name: 'cordis_inspect_query',
arguments: { platform: 'host', provider: 'Config', method: 'listConfigs', input },
@@ -834,16 +835,16 @@ describe('a user preset declared from the shipped cordis rows', () => {
expect(page.isError, resultText(page)).toBe(false)
return (JSON.parse(resultText(page)) as ConfigPage).data
}
- const toolsRows = await listConfigs({ name: '@deepseek-ai/dsh-tools' }, 'copied-preset-inspect-configs')
+ const toolsRows = await listConfigs({ name: '@deepseek-ai/dsh-agent-loop' }, 'copied-preset-inspect-configs')
const toolsRow = toolsRows.entries[0]
- expect(toolsRow).toMatchObject({ patchId: 'tools', status: 'schema' })
+ expect(toolsRow).toMatchObject({ patchId: 'agent-loop', status: 'schema' })
expect(toolsRows).toMatchObject({ total: 1, nextOffset: null })
const includes = await listConfigs({ name: 'cordis:include' }, 'copied-preset-inspect-includes')
expect(includes.entries.find(entry => entry.patchId === 'include')).toMatchObject({ status: 'tree' })
const firstPage = await listConfigs({ limit: 5 }, 'copied-preset-inspect-page')
expect(firstPage.entries).toHaveLength(5)
expect(firstPage.nextOffset).toBe(5)
- const projected = await copyCtx.tools.execute({
+ const projected = await executeToolFixture(copyCtx, {
callId: ToolCallId('copied-preset-inspect-config'),
name: 'cordis_inspect_query',
arguments: { platform: 'host', provider: 'Config', method: 'listConfigs', input: { entry: toolsRow!.id } },
@@ -855,7 +856,7 @@ describe('a user preset declared from the shipped cordis rows', () => {
const { data } = JSON.parse(resultText(projected)) as { data: Projected }
expect(data.status).toBe('schema')
expect(data.schema.$defs).toHaveProperty('loaderExpression')
- expect(JSON.stringify(data.schema)).toContain('"mode"')
+ expect(JSON.stringify(data.schema)).toContain('"maxParallelToolCalls"')
} finally {
await copied.dispose()
await shipped.dispose()
@@ -954,7 +955,7 @@ describe('a delegated child', () => {
] as const
for (const [name, args] of calls) {
expect(toolNames(ctx, child.agent)).toContain(name)
- const result = await ctx.tools.execute({
+ const result = await executeToolFixture(ctx, {
callId: ToolCallId(`child-${name}`), signal: new AbortController().signal,
name, arguments: args, agent: child.agent,
})
diff --git a/apps/desktop-host/package.json b/apps/desktop-host/package.json
index e79792f570..f6e0f4c73a 100644
--- a/apps/desktop-host/package.json
+++ b/apps/desktop-host/package.json
@@ -30,6 +30,14 @@
"devDependencies": {
"@deepseek-ai/cordis-plugin-loader": "workspace:~",
"@deepseek-ai/cordis-plugin-include": "workspace:~",
- "@deepseek-ai/dsh-skill": "workspace:*"
+ "@deepseek-ai/dsh-skill": "workspace:*",
+ "@deepseek-ai/dsh-fs": "workspace:*",
+ "@deepseek-ai/dsh-fs-local": "workspace:*",
+ "@deepseek-ai/dsh-session": "workspace:*",
+ "@deepseek-ai/dsh-session-persistence": "workspace:*",
+ "@deepseek-ai/dsh-sandbox-policy": "workspace:*",
+ "@deepseek-ai/dsh-util-workspace-path": "workspace:*",
+ "@deepseek-ai/dsh-brand": "workspace:*",
+ "@deepseek-ai/dsh-tool-executor-native": "workspace:*"
}
}
diff --git a/apps/desktop-host/src/file-drag.ts b/apps/desktop-host/src/file-drag.ts
new file mode 100644
index 0000000000..473ab67e56
--- /dev/null
+++ b/apps/desktop-host/src/file-drag.ts
@@ -0,0 +1,64 @@
+/** Resolve desktop-only file references through the active Host filesystem and Session. */
+import { createHash } from 'node:crypto'
+import type { Context } from '@deepseek-ai/cordis'
+import type {} from '@deepseek-ai/dsh-fs'
+import type {} from '@deepseek-ai/dsh-session'
+import type {} from '@deepseek-ai/dsh-session-persistence'
+import type {} from '@deepseek-ai/dsh-sandbox-policy'
+import type { SessionId } from '@deepseek-ai/dsh-session/types'
+import { parseFileAddress } from '@deepseek-ai/dsh-util-workspace-path'
+
+/** Private Host-to-main answer; never exposed to renderer JavaScript. */
+export interface LocalDragResource {
+ readonly path: string
+ readonly sha256: string
+ readonly size: number
+}
+
+/**
+ * Authorize an unmodified local file through the composed filesystem's actual read operations.
+ * @param ctx - booted Desktop Host.
+ * @param address - Session-scoped resource reference.
+ * @param cancellation - caller cancellation, combined with the read deadline.
+ * @returns verified Host-local path and content identity, or null for nonlocal resources.
+ */
+export async function localDragResource(ctx: Context, address: string, cancellation?: AbortSignal): Promise {
+ const resource = parseFileAddress(address)
+ if (resource?.scope !== 'session') throw new Error('File drag requires a Session resource')
+ const sessions = ctx.get('sessions')
+ const persistence = ctx.get('sessionPersistence')
+ const fs = ctx.get('fs')
+ const policy = ctx.get('sandboxPolicy')
+ if (fs === undefined || sessions === undefined || policy === undefined) throw new Error('File access unavailable')
+ const sessionId = resource.sessionId as SessionId
+ const header = sessions.get(sessionId)?.header ?? (await persistence?.stat(sessionId))?.header
+ if (header === undefined) throw new Error('File drag Session unavailable')
+ const signal = cancellation === undefined ? AbortSignal.timeout(10_000) : AbortSignal.any([cancellation, AbortSignal.timeout(10_000)])
+ signal.throwIfAborted()
+ const cwd = header.cwd ?? policy.workspaceRoot
+ const entry = await fs.lstat(resource.path, { cwd }, signal)
+ if (entry?.type !== 'file') return null
+ const target = await fs.resolve(resource.path, { cwd, signal })
+ const path = fs.processPath(target)
+ const mapped = fs.processPathFromHostPath(path)
+ if (mapped === undefined) return null
+ const roundTrip = await fs.resolve(mapped, { signal })
+ if (roundTrip.targetKey !== target.targetKey) return null
+ const info = await fs.stat(target, signal)
+ if (info?.type !== 'file' || info.size === undefined) return null
+ const hash = createHash('sha256')
+ let size = 0
+ while (size < info.size) {
+ signal.throwIfAborted()
+ const data = await fs.readByteRange(target, { offset: size, length: Math.min(64 * 1024, info.size - size) }, signal)
+ if (data.length === 0) return null
+ hash.update(data)
+ size += data.length
+ }
+ // Even empty files require a read authorization check.
+ if (size === 0) await fs.readByteRange(target, { offset: 0, length: 1 }, signal)
+ const after = await fs.stat(target, signal)
+ signal.throwIfAborted()
+ if (after?.version !== info.version || after.size !== size) return null
+ return { path, size, sha256: hash.digest('hex') }
+}
diff --git a/apps/desktop-host/src/index.ts b/apps/desktop-host/src/index.ts
index 7ff0cb6473..3109537b63 100644
--- a/apps/desktop-host/src/index.ts
+++ b/apps/desktop-host/src/index.ts
@@ -9,6 +9,7 @@ import type {} from '@deepseek-ai/dsh-host-webserver'
import type {} from '@deepseek-ai/dsh-deepseek-account'
import { resolveDshHome } from '@deepseek-ai/dsh-home-paths'
import * as desktopOffice from './office.ts'
+import { localDragResource } from './file-drag.ts'
import { installDesktopUpdateTaskControl } from './update-tasks.ts'
import { installDesktopQuitInspection } from './quit-inspection.ts'
@@ -41,6 +42,8 @@ async function main(): Promise {
}),
})
let stopping: Promise | undefined
+ const dragReads = new Map()
+ const dragTasks = new Set>()
const control: {
updateTasks?: ReturnType
quitInspection?: ReturnType
@@ -50,6 +53,8 @@ async function main(): Promise {
process.send(message, (error) => { if (error === null) resolve(); else reject(error) })
})
const stop = (): Promise => stopping ??= (async () => {
+ for (const abort of dragReads.values()) abort.abort()
+ await Promise.allSettled(dragTasks)
// Startup failure is reported by main; shutdown only owns a tree that booted.
const running = await application.catch(() => undefined)
await running?.shutdown.shutdown(0)
@@ -62,6 +67,31 @@ async function main(): Promise {
process.on('message', (message: unknown) => {
if (typeof message !== 'object' || message === null || !('type' in message)) return
if (message.type === 'shutdown') { void stop(); return }
+ if (message.type === 'file-drag-cancel') {
+ if ('requestId' in message && typeof message.requestId === 'number') dragReads.get(message.requestId)?.abort()
+ return
+ }
+ if (message.type === 'file-drag-resource') {
+ if (!('requestId' in message) || typeof message.requestId !== 'number' || !Number.isSafeInteger(message.requestId)
+ || !('address' in message) || typeof message.address !== 'string') return
+ const { requestId, address } = message
+ const abort = new AbortController()
+ dragReads.set(requestId, abort)
+ const task = (async () => {
+ try {
+ if (stopping !== undefined) throw new Error('Host stopping')
+ const { ctx } = await application
+ const resource = await localDragResource(ctx, address, abort.signal)
+ await send({ type: 'file-drag-resource', requestId, resource })
+ } catch (error) {
+ if (!abort.signal.aborted) console.error(error)
+ await send({ type: 'file-drag-resource', requestId, resource: null, error: 'File drag resource unavailable' })
+ } finally { dragReads.delete(requestId) }
+ })().catch((error: unknown) => { console.error(error) })
+ dragTasks.add(task)
+ void task.finally(() => { dragTasks.delete(task) })
+ return
+ }
if (message.type === 'quit-inspection') {
if (!('requestId' in message) || !Number.isSafeInteger(message.requestId)) return
const requestId = message.requestId
@@ -104,7 +134,7 @@ async function main(): Promise {
if (process.connected) process.send?.({ type: 'platform-session', session })
})
const url = ctx.connection.authenticatedUrl(`${ctx.webServer.protocol}//127.0.0.1:${String(ctx.webServer.port)}`)
- if (process.connected) process.send?.({ type: 'ready', url, injections: ctx.webServer.collectIndexInjections() }, (error) => { if (error !== null) console.error(error) })
+ if (process.connected) process.send?.({ type: 'ready', url, injections: ctx.webServer.collectIndexInjections(ctx.connection.browserPeer) }, (error) => { if (error !== null) console.error(error) })
}
/** Upper bound of the startup diagnostic carried over IPC; the head holds the message and stack. */
diff --git a/apps/desktop-host/tests/file-drag.spec.ts b/apps/desktop-host/tests/file-drag.spec.ts
new file mode 100644
index 0000000000..437a062e05
--- /dev/null
+++ b/apps/desktop-host/tests/file-drag.spec.ts
@@ -0,0 +1,82 @@
+import { createHash } from 'node:crypto'
+import { mkdtemp, realpath, rm, symlink, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { Context } from '@deepseek-ai/cordis'
+import { LocalFileSystem } from '@deepseek-ai/dsh-fs-local'
+import SessionStore from '@deepseek-ai/dsh-session'
+import { SessionId } from '@deepseek-ai/dsh-session/types'
+import { sessionFileAddress } from '@deepseek-ai/dsh-util-workspace-path'
+import { expect, it, onTestFinished, vi } from 'vitest'
+import { localDragResource } from '../src/file-drag.ts'
+
+async function fixture() {
+ const root = await mkdtemp(join(tmpdir(), 'dsh-host-drag-'))
+ const ctx = new Context()
+ onTestFinished(async () => { await ctx.fiber.dispose(); await rm(root, { recursive: true, force: true }) })
+ await ctx.plugin(LocalFileSystem, { cwd: root })
+ await ctx.plugin(SessionStore)
+ ctx.provide('sandboxPolicy', { workspaceRoot: root } as never)
+ const id = SessionId('file-drag-test')
+ ctx.sessions.create(id, { meta: { cwd: root, origin: 'subagent' } })
+ const path = join(root, '报告.pdf')
+ const bytes = Buffer.from('%PDF-1.4\n原始内容\n%%EOF')
+ await writeFile(path, bytes)
+ return { ctx, root, id, path, bytes, address: sessionFileAddress(id, '报告.pdf') }
+}
+
+it('authorizes Session-relative file reads and returns their original digest privately to main', async () => {
+ const f = await fixture()
+ expect(await localDragResource(f.ctx, f.address)).toEqual({
+ path: await realpath(f.path), size: f.bytes.length, sha256: createHash('sha256').update(f.bytes).digest('hex'),
+ })
+})
+
+it('rejects unscoped references and missing Sessions', async () => {
+ const f = await fixture()
+ await expect(localDragResource(f.ctx, f.path)).rejects.toThrow('Session resource')
+ await expect(localDragResource(f.ctx, sessionFileAddress('missing', f.path))).rejects.toThrow('Session unavailable')
+ await expect(localDragResource(f.ctx, sessionFileAddress(f.id, f.root))).resolves.toBeNull()
+})
+
+it('does not authorize borrowing when the filesystem has no Host mapping', async () => {
+ const f = await fixture()
+ vi.spyOn(f.ctx.fs, 'processPathFromHostPath').mockReturnValue(undefined)
+ expect(await localDragResource(f.ctx, f.address)).toBeNull()
+})
+
+it('honors filesystem read denial without returning a path', async () => {
+ const f = await fixture()
+ vi.spyOn(f.ctx.fs, 'readByteRange').mockRejectedValue(new Error('read denied'))
+ await expect(localDragResource(f.ctx, f.address)).rejects.toThrow('read denied')
+})
+
+it.skipIf(process.platform === 'win32')('declines symlink borrowing so the authorized byte reader can copy it', async () => {
+ const f = await fixture()
+ await symlink(f.path, join(f.root, 'linked.pdf'))
+ expect(await localDragResource(f.ctx, sessionFileAddress(f.id, 'linked.pdf'))).toBeNull()
+})
+
+it('stops a chunked authorization read when the caller cancels', async () => {
+ const f = await fixture()
+ const pending = Promise.withResolvers()
+ const reading = vi.spyOn(f.ctx.fs, 'readByteRange').mockReturnValue(pending.promise)
+ const abort = new AbortController()
+ const preparing = localDragResource(f.ctx, f.address, abort.signal)
+ const rejected = expect(preparing).rejects.toThrow()
+ await vi.waitFor(() => { expect(reading).toHaveBeenCalledOnce() })
+ const signal = reading.mock.calls[0]![2]
+ abort.abort()
+ expect(signal?.aborted).toBe(true)
+ pending.resolve(f.bytes)
+ await rejected
+})
+
+it('authorizes empty files and detects content changes while reading', async () => {
+ const f = await fixture()
+ await writeFile(f.path, '')
+ expect(await localDragResource(f.ctx, f.address)).toMatchObject({ size: 0, sha256: createHash('sha256').digest('hex') })
+ await writeFile(f.path, f.bytes)
+ vi.spyOn(f.ctx.fs, 'readByteRange').mockResolvedValueOnce(new Uint8Array())
+ await expect(localDragResource(f.ctx, f.address)).resolves.toBeNull()
+})
diff --git a/apps/desktop-host/tests/office.spec.ts b/apps/desktop-host/tests/office.spec.ts
index 02e741d4ce..33adbf68e7 100644
--- a/apps/desktop-host/tests/office.spec.ts
+++ b/apps/desktop-host/tests/office.spec.ts
@@ -1,3 +1,4 @@
+import * as NativeToolExecutor from '@deepseek-ai/dsh-tool-executor-native'
import { cp, mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join, sep } from 'node:path'
@@ -29,7 +30,7 @@ it('loads Desktop Office CLI paths and removes them on disposal', async () => {
expect('default' in desktopOffice).toBe(false)
expect(ctx.loader.unwrapExports(desktopOffice)).toBe(desktopOffice)
const modules = new Map([
- ['agents', AgentRegistry], ['systemPrompt', SystemPrompt], ['tools', ToolRuntime],
+ ['agents', AgentRegistry], ['systemPrompt', SystemPrompt], ['tools', ToolRuntime], ['toolExecutor', NativeToolExecutor],
['skills', SkillRegistry], ['office', desktopOffice],
])
ctx.loader.internal = {
diff --git a/apps/desktop-host/tsconfig.json b/apps/desktop-host/tsconfig.json
index 31c64f179b..58eaa722db 100644
--- a/apps/desktop-host/tsconfig.json
+++ b/apps/desktop-host/tsconfig.json
@@ -30,6 +30,24 @@
},
{
"path": "../../packages/credentials/deepseek-account"
+ },
+ {
+ "path": "../../packages/fs/fs"
+ },
+ {
+ "path": "../../packages/core/session"
+ },
+ {
+ "path": "../../packages/session/session-persistence"
+ },
+ {
+ "path": "../../packages/sandbox/sandbox-policy"
+ },
+ {
+ "path": "../../packages/util/workspace-path"
+ },
+ {
+ "path": "../../packages/util/brand"
}
]
}
diff --git a/apps/desktop/README.i18n.yaml b/apps/desktop/README.i18n.yaml
index bda88b0fc6..f554ad3863 100644
--- a/apps/desktop/README.i18n.yaml
+++ b/apps/desktop/README.i18n.yaml
@@ -21,8 +21,8 @@
en: 5f2d25a1d8472647
zh: 2acb5c5d7d1917e2
/deepseek-harness-desktop/closing-the-window-and-quitting:
- en: 24387a07ae4eb8e7
- zh: 0119352685cf273c
+ en: bb35a022c37955c9
+ zh: ab2ef22d398d83a0
/deepseek-harness-desktop/key-technical-decisions:
en: 3724c53da4f7647b
zh: 76ae549d43c99bb4
@@ -33,8 +33,8 @@
en: 372297005b57a08b
zh: 074a635ac17e4362
/deepseek-harness-desktop/installation-ownership:
- en: 22153a298a6662e1
- zh: 3600803c8c9d0274
+ en: 7cbb1f9e5006bd34
+ zh: 01e9e15a75a90450
/deepseek-harness-desktop/installation-ownership/runtime-and-plugin-activation:
en: a1a47b09f4a72ba4
zh: 7b1cf27f0b72cf31
@@ -45,8 +45,8 @@
en: faf7676ba18bbf2f
zh: f1d7b75ad348c548
/deepseek-harness-desktop/develop/startup-onboarding:
- en: a51346b8d880ddba
- zh: 7913214c1c66063c
+ en: d87d51b901b72ecd
+ zh: 525da1c4d56af659
/deepseek-harness-desktop/develop/welcome-window-appearance:
en: 617a89aeb28131b9
zh: 4d84bd5d86501c86
@@ -57,14 +57,14 @@
en: 9b90a2651a6d2b52
zh: 86d4d9c4358aad80
/deepseek-harness-desktop/updates:
- en: 87db37529b51da62
- zh: 4fc0d752e437e7d6
+ en: 67bf0a18faa7aa76
+ zh: 782e14ce62bb939f
/deepseek-harness-desktop/updates/local-desktop-settings:
en: 2e57457c44c85b5f
zh: 5b8510a3dc4c6c9d
/deepseek-harness-desktop/updates/mandatory-update-policy:
- en: 54596bef0706d305
- zh: 48737302dcf3c939
+ en: 182a9c6705213e13
+ zh: 681762f83490f4c6
/deepseek-harness-desktop/updates/local-updater-qualification:
en: 68ec2f8bd5763ea6
zh: 23b932dfe8503602
@@ -72,8 +72,8 @@
en: 8264b135871e8978
zh: 0939aafb1b2961fc
/deepseek-harness-desktop/known-limitations:
- en: c63d4dc7a9104954
- zh: a4c676e5b46a6ac0
+ en: b1eeadfefb338056
+ zh: 28683fbdf1e98685
/deepseek-harness-desktop/dev-note:
en: 8e26b460ba31f21b
zh: fbcd0307b3867125
diff --git a/apps/desktop/README.md b/apps/desktop/README.md
index 45c94d62c7..931401ec77 100644
--- a/apps/desktop/README.md
+++ b/apps/desktop/README.md
@@ -70,7 +70,7 @@ Closing the main window (macOS close button and ⌘W; Windows ×, Alt+F4, and th
Windows keeps a tray icon for the whole run. Its tooltip is the product name, a single click shows and focuses the window, and the context menu offers Open DeepSeek Harness and Quit DeepSeek Harness in the shell locale. Before the first hide, the shared update-dialog overlay explains that running tasks continue and the window can be reopened from the system tray. Confirm hides the window and writes `background-close-confirmed` under Electron userData; Escape, dismissal, or dialog failure keeps the window visible and does not record acknowledgement. Repeated close requests focus the existing shell dialog. In-place updates retain the marker and uninstall removes it. The old `background-notice-shown` marker does not suppress this confirmation. Closing the window sends no system notification. The tray bitmaps are `resources/tray-windows.ico`, rendered from `resources/icon-windows.svg` at 16, 20, 24, 32, 40, 48, and 64 pixels by `pnpm run render:tray-icon`, and packaged as `resources/tray.ico`. macOS ships no menu bar icon.
-Every ordinary quit entry — ⌘Q, the application menu, the Dock menu, the Windows tray and caption Application menu, and the quits caused by closing the mandatory-update or welcome window — asks the Host what it would interrupt. The Host answers over the private IPC channel with two facts: active tasks under the same rule as the update restart check (running agents including subagents and approval waits, queued messages, running or stopping jobs), and armed scheduled reminders reported by the `schedule` family of `workspace/session-activity` for the sessions loaded during this run. Neither fact, the quit proceeds silently. Otherwise a native message box without an owner window — hidden windows stay hidden — shows **Quit DeepSeek Harness?** with one of three localized explanations: running tasks will be interrupted, scheduled tasks will not run while the application is closed, or both. Quit is the default button and Cancel answers Esc; macOS places Cancel left of Quit, Windows places Quit left of Cancel, and the Windows task dialog shows the application icon and stays light regardless of the application theme. A Host that has not reached ready or has failed cannot run tasks, so the quit proceeds without asking. An inspection failure or a Host that misses the two-second deadline is treated as running tasks. While the box is open, another quit request joins it instead of stacking a second one (macOS also raises it; Electron exposes no handle to the Windows task dialog), the explanation does not change when work starts or ends, Quit stops the application without re-inspecting, and Cancel changes nothing. Cancelling a quit that closing the welcome window started shows the welcome window again.
+Every ordinary quit entry — ⌘Q, the application menu, the Dock menu, the Windows tray and caption Application menu, and the quit caused by closing the welcome window — asks the Host what it would interrupt. The Host answers over the private IPC channel with two facts: active tasks under the same rule as the update restart check (running agents including subagents and approval waits, queued messages, running or stopping jobs), and armed scheduled reminders reported by the `schedule` family of `workspace/session-activity` for the sessions loaded during this run. Neither fact, the quit proceeds silently. Otherwise a native message box without an owner window — hidden windows stay hidden — shows **Quit DeepSeek Harness?** with one of three localized explanations: running tasks will be interrupted, scheduled tasks will not run while the application is closed, or both. Quit is the default button and Cancel answers Esc; macOS places Cancel left of Quit, Windows places Quit left of Cancel, and the Windows task dialog shows the application icon and stays light regardless of the application theme. A Host that has not reached ready or has failed cannot run tasks, so the quit proceeds without asking. An inspection failure or a Host that misses the two-second deadline is treated as running tasks. While the box is open, another quit request joins it instead of stacking a second one (macOS also raises it; Electron exposes no handle to the Windows task dialog), the explanation does not change when work starts or ends, Quit stops the application without re-inspecting, and Cancel changes nothing. Cancelling a quit that closing the welcome window started shows the welcome window again.
The mandatory update confirmation includes the installation wait notice on Windows; macOS uses the shorter restart explanation.
@@ -142,6 +142,8 @@ Electron owns `$DSH_HOME/profiles/desktop`. Its `dependencies` contains packages
The application preload exposes boot readiness, fatal startup reporting, native directory selection, the `__DSH_HOST_PATHS__` bridge for composer path references, and the lease-scoped Browser bridge only to `dsh-app://app` documents. The same preload forwards the main-process machine description from `dshDesktop.deviceInfo()` as `name=value` fields separated by `; `: `platform`, `os`, `app_arch` (the architecture the application binary runs as, which differs from the hardware architecture under emulation), `cpu`, and `memory_gib` (total physical memory in GiB with one decimal). A field is omitted when its source is unavailable. The description carries no hostname, user name, or serial number. Product documents use the shared authenticated HTTP APIs and receive the Desktop marker, update presentation, and an action that opens native confirmation; they cannot choose artifacts or authorize installation. Plugin management uses the Web application's authenticated HTTP APIs. Electron serves update-dialog documents and assets locally at `dsh-app://shell/`, independently of Host readiness. Electron exposes no plugin-management IPC or separate management document. No renderer receives filesystem access, raw Electron IPC, a shell, or arbitrary pnpm arguments.
+The file-drag bridge accepts arbitrary file bytes or Session-scoped resource references from the owned product main frame. The Host authorizes resource reads through its composed filesystem, confirms a local mapping, and returns a private content digest; main checks content and the shared export filename before borrowing the source. Native startup checks the prepared file’s device, inode, size, modification time, and change time without rereading its bytes. Borrowed files are never deleted. Renamed, transformed, remote, or Blob content uses a private temporary copy. MIME data completes names without restricting file types; compatible suffixes such as `.jpeg` survive. Temporary preparations, partial writes, and retained exports share 64 MiB; unused files release on pointer leave, and OS-delivered copies expire after 60 seconds. Exhaustion reports the generic retry message until capacity is reclaimed. Caller cancellation and shutdown abort Host reads and main-process verification, interrupt icon waits, and release unused files. Shutdown waits for writes/releases and retries failed removals without waiting for the icon service. Update preparation attempts cleanup before stopping the Host; cleanup failures are logged and do not block installation or shutdown. Failed installation restores the bridge. Asynchronous system file icons avoid decoding original images in main.
+
Only the main application window enables ``. Guest attachment must match a main-issued lease and partition; guests keep sandbox, context isolation and Web security without Node integration or guest preload. Browser IPC listeners are created only for the application document. [Sidebar Browser](../../packages/client/ui-sidebar-browser/README.md) describes storage grouping and guest limitations; Host authentication remains required independently of URL filtering.
The `dsh-app://shell/` origin serves packaged update documents, scripts, and styles without contacting the Host. Static requests retain GET/HEAD, path-containment, and MIME handling; each update document keeps its isolated preload and owned-window IPC checks.
@@ -150,7 +152,7 @@ The product UI retains Web actions, including "Open In..." through the shared au
Update copy preserves the complete version, including prerelease suffixes, without adding v or V. When no update is available, the dialog title reports the result and the body shows the current version.
-Electron chooses typed English or Chinese shell copy from its application locale and falls back to English. The macOS application bundle declares English and Simplified Chinese in `CFBundleLocalizations`, allowing macOS to match the initial application language to the user’s preferred languages. Saved Client UI language preferences still take precedence for the main interface. On Windows, the main document's language updates desktop menus, recovery and update prompts. The repository Client UI i18n gate checks desktop sources.
+Electron chooses typed English, Chinese, or Japanese shell copy from its application locale and falls back to English. The macOS application bundle declares English, Simplified Chinese, and Japanese in `CFBundleLocalizations`, allowing macOS to match the initial application language to the user’s preferred languages. Saved Client UI language preferences still take precedence for the main interface. Windows NSIS installer resources live in one JSON file per language under `installer/locales/`; packaging generates NSIS strings and discovers the installer language list from these files. English, Simplified Chinese, and Japanese resources must have matching keys and format placeholders; `pnpm run check:i18n` validates them. The native installer test builds and exercises each configured language. Platform account pages and onboarding artwork use English for languages other than Chinese. On Windows, the main document's language updates desktop menus, recovery and update prompts. The repository Client UI i18n gate checks desktop sources.
Windows and macOS relay native fullscreen transitions and the state after each page load to the renderer, so overlays can adapt their caption clearance.
@@ -218,7 +220,7 @@ Repeated launches and `dsh://open` keep the workspace hidden until the startup c
Desktop checks configured model API-key references after the Host starts and before opening the workspace. With no configured key, the welcome window offers the API-key page. Save and continue writes through the existing credential service using the official DeepSeek provider's configured reference, then opens the workspace. Set up later opens the workspace without saving the draft or a completion setting; the next process launch checks credentials again. Back to sign in returns to the entry and clears the unsaved key and validation message. Buttons keep their labels and block competing actions while saving or opening the workspace. The Desktop preload marker suppresses the Web credential dialog, while retaining the Models settings page and the welcome notice.
-The welcome window reads the shared `locale.preference` before it appears. An explicit English or Chinese choice wins; otherwise Desktop picks the first supported OS language and falls back to English. The main UI reads the same preference and OS language order through its isolated preload before mounting. Language changes in Settings update the shell’s current dictionary and menu; automatic selection writes no preference. The welcome window has no language selector.
+The welcome window reads the shared `locale.preference` before it appears. An explicit English, Chinese, or Japanese choice wins; otherwise Desktop picks the first supported OS language and falls back to English. The main UI reads the same preference and OS language order through its isolated preload before mounting. Language changes in Settings update the shell’s current dictionary and menu; automatic selection writes no preference. The welcome window has no language selector.
The browser-login waiting page offers a copy-link action for the current pending authorization, a loading indicator, and cancellation. Clipboard failures leave the copy action available for retry. Copy feedback resets after two seconds; the copied state disables the link until it resets. Welcome text uses Montserrat Light with system fallbacks; large action buttons keep the system font, while text buttons use Montserrat Light. English introductory copy is 24px throughout. Chinese introductory copy is 24px with a 26px product name. Login action buttons are 240px wide with 14px labels. Authorization status headings use 20px Montserrat Regular text. The API-key page uses a 20px heading and a 14px back action, with 84px between the secondary button’s bottom edge and the window bottom.
@@ -271,9 +273,11 @@ On Windows, the downloaded-update confirmation explains that the application clo
On macOS, installation preparation waits for the product window to leave fullscreen before displaying the restart confirmation. Cancelling leaves the window in normal mode; destroying it during the native transition cancels installation before task teardown. If macOS does not report completion within five seconds, preparation fails without stopping the Host; the localized error asks the user to exit fullscreen and retry. Installation failure recovery uses the normal window.
-Native update overlays wait for a ready document and a visible parent, and reappear when that parent is shown again. Closing an overlay releases its input interception and parent listeners. The [local window qualification](tests/README.md#verification-overlay) exercises these transitions without starting a workspace.
+Ordinary update dialogs use an isolated shell-origin WebContentsView inside the product window, so loading a result does not raise a separate native window. The document remains available before the workspace Host is ready. While attached, it intercepts product keyboard input; closing it releases its listeners and view. The Windows caption lies outside the view; its native and product Web controls remain operable. Caption clicks can toggle the sidebar, create or reuse a blank Session, and switch the underlying page. Application menu actions such as About or CLI command management can replace and cancel the current ordinary prompt; this does not approve installation or clear mandatory policy. Product keyboard shortcuts and editing-key forwarding remain blocked while the view is attached.
-Packaged applications check fixed Nightly asynchronously at startup. Ordinary polling uses a ten-minute base interval with independently sampled ±20% jitter. Each check failure doubles the base delay up to one hour; success resets it. The randomized delay is bounded by that cap and starts after all joined callers settle. Foreground and system-resume checks respect the same monotonic deadline; the localized Check for Updates menu item, including in the Windows caption's Application menu, runs immediately and joins an in-flight check. A newly received mandatory policy also requests an immediate feed check. Automatic checks never open dialogs or download packages. Manual checks display checking, failure, or no-update feedback with the installed version. Ordinary update dialogs fade in and out in place; consecutive prompts replace the card content and reset its scroll position while retaining the dark translucent backdrop without blurring the parent page. On Windows, dismissal hides the modal before destroying it so the parent is enabled before native window activation changes.
+Ordinary update dialogs, the Windows first-close notice, and mandatory-update documents share the UI design tokens bundled with the shell. Before displaying a card, each document resolves Electron's application theme through `prefers-color-scheme` and updates its dark-theme attribute when the palette changes. Welcome and update documents use the same initialization script. Explicit light/dark preferences and system appearance share this path; the isolated document keeps its background transparent, and dark mode adds a 1 CSS px token-based inset outline without changing the card size; light mode has no outline.
+
+Packaged applications check fixed Nightly asynchronously at startup. Ordinary polling uses a ten-minute base interval with independently sampled ±20% jitter. Each check failure doubles the base delay up to one hour; success resets it. The randomized delay is bounded by that cap and starts after all joined callers settle. Foreground and system-resume checks respect the same monotonic deadline; the localized Check for Updates menu item, including in the Windows caption's Application menu, runs immediately and joins an in-flight check. A newly received mandatory policy also requests an immediate feed check. Automatic checks never open dialogs or download packages. Manual checks display checking, failure, or no-update feedback with the installed version. Ordinary update dialogs fade in and out in place; consecutive prompts replace the card content and reset its scroll position while retaining the dark translucent backdrop without blurring the parent page.
`DSH_DESKTOP_UPDATE_CHECK_INTERVAL_MS` configures the ordinary base interval, and `DSH_DESKTOP_UPDATE_CHECK_MAX_BACKOFF_MS` configures the cap; both accept integer milliseconds from 1000 through 2147483647, with the cap at least the interval. An omitted cap defaults to the larger of one hour and the interval. `DSH_DESKTOP_UPDATE_CHECK_JITTER` sets the fractional jitter from 0 through 1, defaulting to `0.2`; the final delay is at least one second and never exceeds the cap. These settings do not change mandatory-policy polling or authorize download retries.
@@ -330,10 +334,12 @@ When permitted, login is offered during user-initiated checks and the packaged a
Login and policy requests share an in-memory Session, separate from product windows and the updater; restarting requires a new login. Closing cancels login, and navigation failure provides localized retry guidance. Returning to the service triggers a fresh policy query; a redirect, cookie, or HTTP 422 is not a valid policy decision. Cancellation, expiry, and invalid responses retain any known mandatory block. Fixed login outcomes appear in process diagnostics and the optional update journal; cookies, OAuth parameters, and remote error text are not recorded by the login controller. Live Harness gateway/API integration and macOS login qualification remain unverified.
-A flattened `40005` opens a shell-owned modal and refuses subsequent plugin mutations without stopping existing Host tasks. Server title and detail are optional plain text and fall back to client copy; an absent or unapproved download URL hides the external-page actions without clearing the block. On macOS the mandatory overlay fades in and out in place, keeps its backdrop during update-state changes, and redirects parent-window focus and keyboard input to the overlay. On Windows the isolated application preload mounts a shell-origin frame inside the main window, covering the content below the 40 DIP caption with a backdrop and dialog. It blocks background page input without creating another native window; moving and maximizing affect only the main window. Caption menus retain mouse and keyboard operation; Web controls in the caption remain reachable. The shared DOM is a presentation constraint, not a security boundary: product scripts can hide the overlay but cannot clear main-process policy or authorize installation through it. Update actions and state use a private MessageChannel between the isolated preload and shell frame. The parent remains enabled for native move, resize, minimize, maximize, and close controls. Closing the application performs cleanup without clearing the update requirement; Esc does not dismiss the overlay. Once installation is approved, installer-owned quit releases the modal before Electron closes windows. Download, file verification including preparation, task inspection, and installation confirmation share this same modal. Only the second user approval permits task teardown and installation; deferral retains the block and package. Restart feedback mentions task stopping only when affected tasks exist. Policy is not persisted across application restarts, and policy responses never revoke or replace an updater artifact.
+A flattened `40005` opens a shell-owned modal and refuses subsequent plugin mutations without stopping existing Host tasks. Server title and detail are optional plain text and fall back to client copy; an absent or unapproved download URL hides the external-page actions without clearing the block. On macOS the mandatory overlay uses an isolated shell-origin WebContentsView inside its native owner. It fades in and out in place, retains its backdrop across update-state changes, and blocks product keyboard input. Loading or updating the view never shows or activates a separate native window; returning to an already focused owner focuses the view. Closing its native owner follows the [normal window-close behavior](#closing-the-window-and-quitting). View loading failures retain policy and input blocking without changing the owner title. A native recovery dialog appears only while the owner is visible and focused, showing the policy explanation and available target version. Open download page uses the policy URL after the existing origin validation and is omitted when no approved URL is available; Quit uses normal application exit confirmation. No Cancel button is offered; non-action dismissals retain blocking and reopen recovery. Hiding the owner, policy clearance, successful loading, and disposal dismiss the recovery dialog; obsolete responses have no effect. This recovery covers the isolated view, not the Windows embedded frame. On Windows the isolated application preload mounts a shell-origin frame inside the main window, covering the content below the 40 DIP caption with a backdrop and dialog. It blocks background page input without creating another native window; moving and maximizing affect only the main window. Caption menus retain mouse and keyboard operation; Web controls in the caption remain reachable. The shared DOM is a presentation constraint, not a security boundary: product scripts can hide the overlay but cannot clear main-process policy or authorize installation through it. Update actions and state use a private MessageChannel between the isolated preload and shell frame. The parent remains enabled for native move, resize, minimize, maximize, and close controls. Closing the application performs cleanup without clearing the update requirement; Esc does not dismiss the overlay. Once installation is approved, installer-owned quit releases the modal before Electron closes windows. Download, file verification including preparation, task inspection, and installation confirmation share this same modal. Only the second user approval permits task teardown and installation; deferral retains the block and package. Restart feedback mentions task stopping only when affected tasks exist. Policy is not persisted across application restarts, and policy responses never revoke or replace an updater artifact.
Failures retain blocking, localized retry guidance, and folded diagnostics inside the modal. The allowed download-page action appears in recovery states, not beside normal download or installation. Requesting the browser immediately exposes a copy alternative even while the OS request is pending; a resolved request does not prove the page opened. Copy failure reveals the complete, read-only address for manual copying. Browser and clipboard outcomes do not overwrite updater errors. Only a fresh valid no-force response clears the block; the top-menu check remains available while blocked.
+Selecting Check for Updates while mandatory policy is already blocking focuses its existing interface. If a manual check finishes with mandatory policy active, it also restores, shows, and focuses the owner even after the user has switched applications, minimized, or hidden it. This explicit foreground request is retained independently of the view carrier; the ordinary-result path does not make that request. Focusing the interface does not authorize downloading, installation, or task stopping. The asynchronous mandatory-result foreground path has not received a dedicated background/fullscreen manual qualification.
+
Background mandatory-installation confirmation requests Windows taskbar attention or an informational macOS Dock bounce plus one silent notification per readiness episode. It does not restore or focus the app. Notification clicks only return to current confirmation. Foreground return, installation, policy clearance, and shutdown clear owned reminders. System permissions and focus modes can suppress notifications; installed Windows and macOS notification qualification remains required.
### Local updater qualification
@@ -375,7 +381,7 @@ When an expired account returns to Welcome, the main process retains a one-time
An expired login displays a timeout heading with explicit Sign in again and Add API Key actions. Opening the API-key form dismisses the authorization view; late account-state notifications do not replace an in-progress key entry.
-Embedded Platform views remain hidden until document loading completes so the renderer loading indicator stays visible. Closing or replacing a pending view prevents it from appearing later. Reloading or replacing the owning application document, renderer termination, and window closure also destroy the native view without relying on React cleanup.
+Embedded Platform views remain hidden until document loading completes so the renderer loading indicator stays visible. Closing or replacing a pending view prevents it from appearing later. Update policy and ordinary update prompts refuse Platform admission, including a pending open whose storage cleanup completes after blocking starts. Reloading or replacing the owning application document, renderer termination, and window closure also destroy the native view without relying on React cleanup.
Private Platform deployment headers are injected by the embedded browser session only for its configured origin, including document and API requests. Cookie overrides merge by name. Cross-origin requests discard deployment headers; bootstrap exposes only origin, token, and resolved language.
diff --git a/apps/desktop/README.zh.md b/apps/desktop/README.zh.md
index 0504c7004c..262eee3ac7 100644
--- a/apps/desktop/README.zh.md
+++ b/apps/desktop/README.zh.md
@@ -70,7 +70,7 @@ macOS 安装会创建 `/usr/local/bin/dsh`；目录权限需要时，系统会
Windows 在整个运行期间常驻托盘图标。悬停提示为产品名，单击显示并聚焦窗口，右键菜单提供壳语言下的"打开 DeepSeek Harness"和"退出 DeepSeek Harness"。首次隐藏前复用更新弹窗，显示“正在运行的任务不会中断，可在系统托盘中重新打开窗口”和“确认”按钮。确认后隐藏窗口，并在 Electron userData 下写入 `background-close-confirmed`；Esc、关闭弹窗或加载失败均保持主窗口可见，不记录确认。重复关闭请求会聚焦已有壳弹窗。覆盖更新保留标记，卸载删除标记。旧的 `background-notice-shown` 标记不会跳过此确认。关闭窗口不发送系统通知。托盘位图是 `resources/tray-windows.ico`，由 `pnpm run render:tray-icon` 从 `resources/icon-windows.svg` 按 16、20、24、32、40、48、64 像素分别渲染，打包为 `resources/tray.ico`。macOS 不提供菜单栏图标。
-所有普通退出入口——⌘Q、应用菜单、Dock 菜单、Windows 托盘和标题栏"应用程序"菜单，以及关闭强制更新窗口或欢迎窗口引起的退出——都先向 Host 查询退出会中断什么。Host 通过私有 IPC 通道回答两项事实：与更新重启检查同一口径的运行中任务（运行中的 agent，包括子代理和等待审批的回合、排队消息、运行中或停止中的后台任务），以及本次运行中已加载会话里由 `workspace/session-activity` 的 `schedule` family 报告的已挂定时器的提醒。两项都没有时直接退出，不弹框。否则弹出一个没有父窗口的原生消息框——隐藏的窗口保持隐藏——标题为**退出 DeepSeek Harness？**，正文为三种本地化说明之一：正在运行的任务将会中断、应用关闭期间定时任务不会运行，或两者兼有。"退出"是默认按钮，Esc 等同"取消"；macOS 上"取消"在"退出"左侧，Windows 上"退出"在"取消"左侧，Windows 任务对话框显示应用图标且不跟随应用主题、始终为浅色。Host 尚未就绪或已失败时不可能有任务在跑，直接退出。查询失败或 Host 超过两秒截止时间未答复，按运行中任务处理。弹框打开期间，再次请求退出只会并入同一弹框而不叠加新弹框（macOS 上还会把它提到前面；Electron 不暴露 Windows 任务对话框的句柄）；任务开始或结束不会改变文案；点"退出"不再重新查询即停止应用；点"取消"不发生任何变化。取消由关闭欢迎窗口引起的退出时，欢迎窗口会重新显示。
+所有普通退出入口——⌘Q、应用菜单、Dock 菜单、Windows 托盘和标题栏"应用程序"菜单，以及关闭欢迎窗口引起的退出——都先向 Host 查询退出会中断什么。Host 通过私有 IPC 通道回答两项事实：与更新重启检查同一口径的运行中任务（运行中的 agent，包括子代理和等待审批的回合、排队消息、运行中或停止中的后台任务），以及本次运行中已加载会话里由 `workspace/session-activity` 的 `schedule` family 报告的已挂定时器的提醒。两项都没有时直接退出，不弹框。否则弹出一个没有父窗口的原生消息框——隐藏的窗口保持隐藏——标题为**退出 DeepSeek Harness？**，正文为三种本地化说明之一：正在运行的任务将会中断、应用关闭期间定时任务不会运行，或两者兼有。"退出"是默认按钮，Esc 等同"取消"；macOS 上"取消"在"退出"左侧，Windows 上"退出"在"取消"左侧，Windows 任务对话框显示应用图标且不跟随应用主题、始终为浅色。Host 尚未就绪或已失败时不可能有任务在跑，直接退出。查询失败或 Host 超过两秒截止时间未答复，按运行中任务处理。弹框打开期间，再次请求退出只会并入同一弹框而不叠加新弹框（macOS 上还会把它提到前面；Electron 不暴露 Windows 任务对话框的句柄）；任务开始或结束不会改变文案；点"退出"不再重新查询即停止应用；点"取消"不发生任何变化。取消由关闭欢迎窗口引起的退出时，欢迎窗口会重新显示。
强制更新的安装确认在 Windows 上额外显示等待提示，macOS 只显示简短的重启说明。
@@ -142,6 +142,8 @@ Electron 拥有 `$DSH_HOME/profiles/desktop`。其 `dependencies` 包含 pnpm
应用 preload 只向 `dsh-app://app` 文档暴露启动就绪、致命启动失败上报、原生目录选择、用于 composer 路径引用的 `__DSH_HOST_PATHS__` 桥接和租约范围内的 Browser 桥接。同一个 preload 通过 `dshDesktop.deviceInfo()` 转发主进程采集的机器描述，按 `name=value` 字段以 `; ` 分隔：`platform`、`os`、`app_arch`（应用二进制实际运行的架构，模拟运行时与硬件架构不同）、`cpu` 和 `memory_gib`（物理内存总量，GiB，保留一位小数）。取值不可用时省略对应字段。该描述不包含主机名、用户名或序列号。产品页面还获得 Desktop 标记、更新展示数据和打开原生确认的操作，不能选择安装产物或授权安装。插件管理使用 Web 应用经过认证的 HTTP API；Electron 在 `dsh-app://shell/` 本地提供更新弹窗文档和资源，不依赖 Host 就绪。Electron 不提供插件管理 IPC 或独立管理页面。任何渲染进程都不会获得文件系统访问、原始 Electron IPC、shell 或任意 pnpm 参数。
+文件拖放桥接接受所属主应用主框架传入的任意文件字节或 Session 资源地址。Host 通过组合的文件系统授权读取、确认本地映射并返回私有内容摘要；主进程检查内容与统一解析的导出名后借用源文件。原生起拖核对准备时的设备、inode、大小、修改时间和变更时间，不再读取整份字节。借用文件不会被删除。改名、转换、远程或 Blob 内容使用私有临时副本。MIME 数据补全名称，不限制文件类型；`.jpeg` 等兼容后缀保持不变。临时准备、部分写入及保留的导出共享 64 MiB；指针移开释放未使用文件，已交给系统的副本在 60 秒后过期。空间耗尽时显示通用重试提示，容量回收后可重试。调用方取消及退出会中止 Host 读取和主进程验证、打断图标等待并释放未使用文件。退出等待写入和释放，重试失败的删除，但不等待图标服务。更新准备在停止 Host 前尝试清理；清理失败只记录日志，不阻断安装或退出。安装失败后恢复桥接。异步系统文件图标避免主进程解码原图。
+
只有主应用窗口启用 ``。guest 挂载必须匹配主进程签发的租约和分区；guest 保持 sandbox、context isolation 和 Web security，不启用 Node integration 或 guest preload。Browser IPC 监听只为应用文档创建。[Sidebar Browser](../../packages/client/ui-sidebar-browser/README.zh.md) 说明存储分组和 guest 限制；Host 鉴权仍独立于 URL 过滤而必需。
`dsh-app://shell/` 无需联系 Host 即可提供打包的更新文档、脚本和样式。静态请求保留 GET/HEAD、路径范围和 MIME 处理；每个更新文档继续使用隔离 preload 和所属窗口的 IPC 校验。
@@ -150,7 +152,7 @@ Electron 拥有 `$DSH_HOME/profiles/desktop`。其 `dependencies` 包含 pnpm
升级文案完整展示版本号（包括预发布后缀），不额外添加 v 或 V。无可用更新时，弹窗标题显示检查结果，正文显示当前版本。
-Electron 根据应用语言选择类型化的英文或中文 shell 文案，并回退到英文。macOS 应用包通过 `CFBundleLocalizations` 声明支持英语和简体中文，让 macOS 根据用户的首选语言匹配初始应用语言。主界面仍优先使用已保存的 Client UI 语言偏好。在 Windows 上，主文档的语言会更新桌面菜单、恢复与更新提示。仓库 Client UI i18n 检查覆盖桌面端源码。
+Electron 根据应用语言选择类型化的英文、中文或日文 shell 文案，并回退到英文。macOS 应用包通过 `CFBundleLocalizations` 声明支持英语、简体中文和日语，让 macOS 根据用户的首选语言匹配初始应用语言。主界面仍优先使用已保存的 Client UI 语言偏好。 Windows NSIS 安装器在 `installer/locales/` 下按语言保存独立 JSON 资源；打包从这些文件生成 NSIS 文案和安装器语言清单。英文、简体中文和日语资源的键与格式占位符必须一致，`pnpm run check:i18n` 负责检查。原生安装器测试逐个构建并验证配置中的语言。账户平台页面和引导插图对中文以外的语言使用英文。在 Windows 上，主文档的语言会更新桌面菜单、恢复与更新提示。仓库 Client UI i18n 检查覆盖桌面端源码。
Windows 和 macOS 会在原生全屏切换及每次页面加载后向渲染器同步全屏状态，让浮层调整顶栏避让距离。
@@ -218,7 +220,7 @@ API Key 输入框初始为空，并通过 `autocomplete="new-password"` 请求 C
Desktop 在 Host 启动后、打开工作区前检查模型 API Key 引用是否已配置。没有已配置的密钥时，欢迎窗口提供 API Key 页面。“保存并继续”通过现有凭证服务写入 DeepSeek 官方提供方配置的引用，然后打开工作区。“稍后配置”打开工作区，但不保存草稿或完成标记；下次进程启动时会重新检查凭证。“返回登录”回到入口并清空未保存的密钥和校验提示。保存或打开工作区期间，按钮保持原文案并禁用竞争操作。Desktop preload 标记使 Web 凭证弹窗不再显示，同时保留模型设置页和欢迎须知。
-欢迎窗口在显示前读取共享的 `locale.preference`。用户明确选择的英文或中文优先；否则 Desktop 按系统语言顺序匹配支持的语言，并以英文兜底。主界面在挂载前通过隔离 preload 读取同一偏好和系统语言顺序。在设置中切换语言会更新桌面壳的当前词典和菜单；自动选择不会写入偏好。欢迎窗口不提供语言切换入口。
+欢迎窗口在显示前读取共享的 `locale.preference`。用户明确选择的英文、中文或日文优先；否则 Desktop 按系统语言顺序匹配支持的语言，并以英文兜底。主界面在挂载前通过隔离 preload 读取同一偏好和系统语言顺序。在设置中切换语言会更新桌面壳的当前词典和菜单；自动选择不会写入偏好。欢迎窗口不提供语言切换入口。
等待浏览器登录时，欢迎页提供当前待授权请求的链接复制入口、加载指示和取消操作；剪贴板写入失败后可以重试复制，复制结果提示在两秒后恢复；已复制状态下链接禁用，恢复后可再次点击。Welcome 文字使用 Montserrat Light 并回退到系统字体，底部大按钮保留系统字体，文字按钮使用 Montserrat Light。英文欢迎正文及产品名均为 24px，中文欢迎正文为 24px、产品名为 26px。登录操作按钮宽 240px，文字为 14px。授权状态标题使用 20px Montserrat Regular 字重。API Key 页的标题为 20px，返回操作为 14px，次级按钮底边距窗口底部 84px。
@@ -271,9 +273,11 @@ Windows 下载完成后的更新确认说明应用会在安装期间关闭、完
macOS 在安装准备阶段等待产品主窗口退出全屏，再显示重启确认。取消确认后窗口保持普通模式；原生切换期间销毁窗口会在任务停止前取消安装。如果 macOS 未在五秒内报告切换完成，安装准备会报错且不停止 Host；本地化错误提示要求退出全屏后重试。安装失败后的恢复使用普通窗口。
-原生更新浮层在文档就绪且父窗口可见时显示，并在父窗口再次显示时恢复。关闭浮层会释放输入拦截和父窗口监听。[本地窗口验证](tests/README.zh.md#verification-overlay)无需启动工作区即可检查这些切换。
+普通更新弹窗使用产品窗口内、隔离的壳静态源 WebContentsView，检查结果加载不会抬升独立的原生窗口。工作区 Host 尚未就绪时，该文档仍可使用。视图挂载期间拦截产品键盘输入，关闭时释放监听和视图。Windows 顶栏位于视图覆盖范围外，其中的原生及产品 Web 控件仍可操作。点击顶栏可切换侧栏、创建或复用空 Session，并改变底层页面。“关于”或 CLI 命令管理等应用菜单操作可替换并取消当前普通提示，但不代表批准安装，也不会清除强更策略。视图挂载期间仍阻断产品键盘快捷键和编辑按键转发。
-打包应用在启动后异步检查固定 Nightly。常规轮询以十分钟为基础间隔，每次独立采样 ±20% 的随机抖动。每次检查失败将基础延迟翻倍，上限为一小时；成功后重置。随机延迟不超过该上限，并从全部复用调用结算后开始计时。本地化的“检查更新…”菜单项（Windows 可从顶栏的“应用”菜单进入）立即执行，并复用正在进行的检查。回到前台和系统恢复时遵守相同的单调时钟截止时间。新收到的强更策略也会立即请求检查更新清单。自动检查从不弹窗或下载安装包。手动检查显示正在检查、失败或包含已安装版本号的无更新反馈。常规更新弹窗原位渐入渐出；连续弹窗替换卡片内容并重置其滚动位置，保留黑色半透明蒙层，不模糊父页面。Windows 在销毁模态窗口前先隐藏它，确保原生窗口激活切换前父窗口已恢复启用。
+普通更新弹窗、Windows 首次关闭提示和强更文档共用随壳打包的 UI design token。各文档在显示卡片前通过 `prefers-color-scheme` 解析 Electron 的应用主题，配色变化时同步暗色主题属性。欢迎页与更新文档复用同一初始化脚本。明确选择浅色／暗色及跟随系统共用此路径，隔离文档保持透明背景，仅暗色模式以基于 token 的 1 CSS px 内描边区分卡片，不改变尺寸；浅色模式不描边。
+
+打包应用在启动后异步检查固定 Nightly。常规轮询以十分钟为基础间隔，每次独立采样 ±20% 的随机抖动。每次检查失败将基础延迟翻倍，上限为一小时；成功后重置。随机延迟不超过该上限，并从全部复用调用结算后开始计时。本地化的“检查更新…”菜单项（Windows 可从顶栏的“应用”菜单进入）立即执行，并复用正在进行的检查。回到前台和系统恢复时遵守相同的单调时钟截止时间。新收到的强更策略也会立即请求检查更新清单。自动检查从不弹窗或下载安装包。手动检查显示正在检查、失败或包含已安装版本号的无更新反馈。常规更新弹窗原位渐入渐出；连续弹窗替换卡片内容并重置其滚动位置，保留黑色半透明蒙层，不模糊父页面。
`DSH_DESKTOP_UPDATE_CHECK_INTERVAL_MS` 配置常规基础间隔，`DSH_DESKTOP_UPDATE_CHECK_MAX_BACKOFF_MS` 配置上限；两者均接受 1000 至 2147483647 的整数毫秒数，且上限不能小于间隔。省略上限时取一小时与间隔中的较大值。`DSH_DESKTOP_UPDATE_CHECK_JITTER` 配置 0 至 1 的抖动比例，默认 `0.2`；最终延迟至少一秒，且不超过上限。这些配置不改变强更策略轮询，也不授权下载重试。
@@ -330,10 +334,12 @@ Electron 主进程在启动时读取一次 `app.getPath('userData')/desktop/sett
登录和策略请求共用内存 Session，与产品窗口及 updater 隔离；应用重启后需要重新登录。关闭窗口取消登录，导航失败提供本地化重试提示。返回服务后重新查询策略；重定向、Cookie 或 HTTP 422 都不是有效策略决定。取消、登录过期及无效响应均保留已知强更阻塞。固定登录结果写入进程诊断及可选更新日志；登录控制器不记录 Cookie、OAuth 参数或远程错误原文。真实 Harness 网关/API 联调及 macOS 登录验收仍未完成。
-扁平化的 `40005` 打开壳拥有的模态窗口，并拒绝后续插件修改，不停止现有 Host 任务。服务端标题与详情是可选纯文本，缺失时使用客户端兜底文案；缺少下载地址或地址未获批准时隐藏外部页面操作，不解除阻塞。macOS 强更蒙层原位渐入渐出，在更新状态切换时保留蒙层，并将父窗口焦点和键盘输入重定向到蒙层。Windows 由隔离的应用 preload 在主窗口内挂载 shell 来源的 frame，以蒙层和弹窗覆盖 40 DIP 顶栏下方的内容区域。它阻止背景页面输入，不创建额外的原生窗口；移动和最大化只作用于主窗口。顶栏菜单保留鼠标和键盘操作，顶栏中的 Web 控件仍可触达。共享 DOM 只约束展示，不构成安全边界：产品脚本可以隐藏蒙层，但不能借此清除主进程策略或授权安装。更新操作与状态通过隔离 preload 和壳 frame 之间的私有 MessageChannel 传递。父窗口保持启用，原生移动、缩放、最小化、最大化和关闭控件仍可操作。退出应用会完成清理，不会解除更新要求；Esc 不会关闭覆盖层。批准安装后，安装器接管的退出流程会在 Electron 关闭窗口前释放模态窗口。下载、含准备步骤的文件校验、任务检查和安装确认共用同一弹窗。只有第二次用户批准才允许任务收尾和安装；稍后更新保留阻塞与安装包。仅存在受影响任务时，重启文案才提示正在停止任务。策略不跨应用重启持久化，策略响应也不作废或替换 updater 产物。
+扁平化的 `40005` 打开壳拥有的模态窗口，并拒绝后续插件修改，不停止现有 Host 任务。服务端标题与详情是可选纯文本，缺失时使用客户端兜底文案；缺少下载地址或地址未获批准时隐藏外部页面操作，不解除阻塞。macOS 强更蒙层使用原生窗口内、隔离的壳静态源 WebContentsView，原位渐入渐出，在更新状态切换时保留蒙层并拦截产品键盘输入。加载或更新视图不会显示或激活独立原生窗口；回到已获焦点的父窗口时聚焦视图。关闭原生父窗口遵循[常规关窗行为](#closing-the-window-and-quitting)。视图加载失败保留策略与输入阻断，不改写父窗口标题。仅当所属窗口可见且有焦点时显示原生恢复提示，包含策略说明与可用目标版本。打开下载页面使用现有来源校验后的策略 URL，缺少获准地址时不显示该按钮；退出走正常应用退出确认。不提供取消按钮，非操作性关闭保留阻断并重新显示恢复提示。隐藏窗口、策略解除、加载成功或释放控制器会撤销提示，过期响应无效。此恢复覆盖独立视图，不包含 Windows 内嵌 frame。Windows 由隔离的应用 preload 在主窗口内挂载 shell 来源的 frame，以蒙层和弹窗覆盖 40 DIP 顶栏下方的内容区域。它阻止背景页面输入，不创建额外的原生窗口；移动和最大化只作用于主窗口。顶栏菜单保留鼠标和键盘操作，顶栏中的 Web 控件仍可触达。共享 DOM 只约束展示，不构成安全边界：产品脚本可以隐藏蒙层，但不能借此清除主进程策略或授权安装。更新操作与状态通过隔离 preload 和壳 frame 之间的私有 MessageChannel 传递。父窗口保持启用，原生移动、缩放、最小化、最大化和关闭控件仍可操作。退出应用会完成清理，不会解除更新要求；Esc 不会关闭覆盖层。批准安装后，安装器接管的退出流程会在 Electron 关闭窗口前释放模态窗口。下载、含准备步骤的文件校验、任务检查和安装确认共用同一弹窗。只有第二次用户批准才允许任务收尾和安装；稍后更新保留阻塞与安装包。仅存在受影响任务时，重启文案才提示正在停止任务。策略不跨应用重启持久化，策略响应也不作废或替换 updater 产物。
失败时在同一弹窗内保留阻塞、本地化重试提示和折叠诊断。白名单下载页面操作只在恢复状态出现，不与正常下载或安装并列。请求打开浏览器后立即提供复制替代入口，即使系统请求尚未返回；请求成功不证明网页已打开。复制失败时展示完整、只读的地址供手动复制。浏览器与剪贴板结果不覆盖 updater 错误。只有新的有效无需强更响应才解除阻塞；阻塞期间仍可使用顶部菜单检查。
+已处于强更阻断状态时，选择“检查更新”会聚焦现有界面。手动检查完成时若强更策略已生效，也会恢复、显示并聚焦所属窗口，即使用户已切换应用、最小化或隐藏窗口。此显式置前行为独立于视图承载方式保留；普通检查结果路径不发起该请求。聚焦界面不代表批准下载、安装或停止任务。异步强更结果置前路径尚未单独完成后台／全屏人工验证。
+
后台强更安装确认请求 Windows 任务栏提醒或 macOS 信息级 Dock 弹跳，并在每轮就绪时尝试一次无声通知，不还原窗口或抢焦点。点击通知只返回当前确认界面。回到前台、安装、策略解除和退出时清理提醒。系统权限和专注模式可能抑制通知；仍需完成 Windows 与 macOS 安装包通知验收。
### 本地 updater 验证
@@ -375,7 +381,7 @@ node apps/desktop/node_modules/pnpm/bin/pnpm.mjs --dir apps/desktop run test:upd
登录超时后显示超时标题，并提供重新登录和添加 API Key 按钮。打开 API Key 表单会关闭授权视图；后续账号状态通知不会覆盖正在填写的密钥。
-内嵌 Platform 视图在文档加载完成前保持隐藏，让渲染层加载图标可见。关闭或替换待加载视图后，该视图不会再次出现。 所属应用文档刷新或替换、渲染进程终止以及窗口关闭也会销毁原生视图，不依赖 React 清理。
+内嵌 Platform 视图在文档加载完成前保持隐藏，让渲染层加载图标可见。关闭或替换待加载视图后，该视图不会再次出现。强更策略或普通更新提示阻止打开 Platform 视图；清理存储期间开始阻断时，待打开视图也不会挂载。 所属应用文档刷新或替换、渲染进程终止以及窗口关闭也会销毁原生视图，不依赖 React 清理。
私有 Platform 部署请求头由内嵌浏览器会话注入，仅用于配置来源的文档和 API 请求。Cookie 覆盖按名称合并。跨来源请求移除部署请求头；bootstrap 仅暴露 origin、token 和已解析的语言。
diff --git a/apps/desktop/electron-builder.config.d.mts b/apps/desktop/electron-builder.config.d.mts
index d6a1a63bfa..2973a6eacc 100644
--- a/apps/desktop/electron-builder.config.d.mts
+++ b/apps/desktop/electron-builder.config.d.mts
@@ -22,7 +22,10 @@ export interface DesktopElectronBuilderConfig {
...{ readonly from: string, readonly to: 'tray.ico' }[],
]
readonly mac: {
- readonly extendInfo: { readonly NSMicrophoneUsageDescription: string }
+ readonly extendInfo: {
+ readonly CFBundleLocalizations: readonly string[]
+ readonly NSMicrophoneUsageDescription: string
+ }
readonly entitlements: string
readonly entitlementsInherit: string
readonly identity: string | undefined
@@ -50,7 +53,7 @@ export interface DesktopElectronBuilderConfig {
readonly perMachine: false
readonly allowElevation: false
readonly allowToChangeInstallationDirectory: false
- readonly installerLanguages: readonly ['en_US', 'zh_CN']
+ readonly installerLanguages: readonly string[]
}
readonly beforeBuild: () => Promise
readonly beforePack: (context: BeforePackContext) => Promise
diff --git a/apps/desktop/installer/locales/en_US.json b/apps/desktop/installer/locales/en_US.json
new file mode 100644
index 0000000000..f522ad9b6d
--- /dev/null
+++ b/apps/desktop/installer/locales/en_US.json
@@ -0,0 +1,40 @@
+{
+ "nsisLanguage": "ENGLISH",
+ "strings": {
+ "INSTALLER_INSTALL": "Install now",
+ "INSTALLER_FINISH": "Finish",
+ "INSTALLER_NATIVE_PROGRESS": "Preparing installation… %d%%",
+ "INSTALLER_PROGRESS_EXTRACT": "Extracting files… %d%%",
+ "INSTALLER_PROGRESS_COPY": "Installing files… %d%%",
+ "INSTALLER_PROGRESS_REGISTER": "Finishing installation… %d%%",
+ "INSTALLER_PROGRESS_CLEAN": "Cleaning temporary files… %d%%",
+ "INSTALLER_CHOOSE_PATH": "Choose location",
+ "INSTALLER_BROWSE": "Browse",
+ "INSTALLER_LAUNCH": "Launch now",
+ "INSTALLER_LAUNCH_FAILED": "DeepSeek Harness could not be launched. Retry, or clear Launch now and close the installer.",
+ "INSTALLER_UI_ERROR": "The installer could not initialize its window. Close it and try again.",
+ "INSTALLER_THEME_ERROR": "Use /THEME=auto, /THEME=light or /THEME=dark.",
+ "INSTALLER_FAILED": "Installation did not finish. Close this installer and retry. If the problem persists, download the installer again.",
+ "INSTALLER_RUNNING": "DeepSeek Harness is running. Quit it from the system tray and try again.",
+ "INSTALLER_DIRECTORY_FAILED": "The installation directory could not be replaced.",
+ "INSTALLER_DIRECTORY_HINT": "Check access to the installation directory and close programs using its files, then run the installer again. Copy the error details if the problem persists.",
+ "INSTALLER_DIRECTORY_RESTORE_HINT": "The previous installation could not be restored. Keep the backup directory shown in the error details and contact support before installing again.",
+ "INSTALLER_PATH_INVALID": "Choose a full local folder path. Drive roots, system folders, links and special characters are not supported.",
+ "INSTALLER_PATH_OWNERSHIP": "Choose an empty folder or the registered DeepSeek Harness installation folder.",
+ "INSTALLER_PATH_WRITABLE": "This location is not writable. Choose a folder available to the current user.",
+ "INSTALLER_DISK_SPACE": "There is not enough free disk space. Choose another location.",
+ "INSTALLER_PER_USER": "This installer supports the current user only. Uninstall the existing all-users installation first.",
+ "INSTALLER_EXTRACT_FAILED": "The application files could not be extracted.",
+ "INSTALLER_EXTRACT_HINT": "Security software may have blocked a file, or the disk may be full. Close this installer and try again. If it keeps failing, send us the error details below.",
+ "INSTALLER_EXTRACT_COPY": "Copy error details",
+ "INSTALLER_EXTRACT_EXPAND": "Show details",
+ "INSTALLER_EXTRACT_COLLAPSE": "Hide details",
+ "INSTALLER_EXTRACT_SAVED": "The full report was saved to %s",
+ "INSTALLER_EXTRACT_UNSAVED": "The full report could not be saved. Use Copy error details to keep it.",
+ "INSTALLER_EXTRACT_COPIED": "Error details were copied to the clipboard."
+ },
+ "uninstaller": {
+ "welcome": "Welcome",
+ "finished": "has been uninstalled"
+ }
+}
diff --git a/apps/desktop/installer/locales/ja_JP.json b/apps/desktop/installer/locales/ja_JP.json
new file mode 100644
index 0000000000..ee614789c5
--- /dev/null
+++ b/apps/desktop/installer/locales/ja_JP.json
@@ -0,0 +1,40 @@
+{
+ "nsisLanguage": "JAPANESE",
+ "strings": {
+ "INSTALLER_INSTALL": "今すぐインストール",
+ "INSTALLER_FINISH": "完了",
+ "INSTALLER_NATIVE_PROGRESS": "インストールを準備しています… %d%%",
+ "INSTALLER_PROGRESS_EXTRACT": "ファイルを展開しています… %d%%",
+ "INSTALLER_PROGRESS_COPY": "ファイルをインストールしています… %d%%",
+ "INSTALLER_PROGRESS_REGISTER": "インストールを完了しています… %d%%",
+ "INSTALLER_PROGRESS_CLEAN": "一時ファイルを削除しています… %d%%",
+ "INSTALLER_CHOOSE_PATH": "インストール先を選択",
+ "INSTALLER_BROWSE": "参照",
+ "INSTALLER_LAUNCH": "今すぐ起動",
+ "INSTALLER_LAUNCH_FAILED": "DeepSeek Harness を起動できませんでした。再試行するか、「今すぐ起動」のチェックを外してインストーラーを閉じてください。",
+ "INSTALLER_UI_ERROR": "インストーラーのウィンドウを初期化できませんでした。閉じてから再試行してください。",
+ "INSTALLER_THEME_ERROR": "/THEME=auto、/THEME=light、/THEME=dark のいずれかを指定してください。",
+ "INSTALLER_FAILED": "インストールが完了しませんでした。インストーラーを閉じて再試行してください。問題が解決しない場合は、インストーラーを再度ダウンロードしてください。",
+ "INSTALLER_RUNNING": "DeepSeek Harness が実行中です。システムトレイから終了して再試行してください。",
+ "INSTALLER_DIRECTORY_FAILED": "インストール先のディレクトリを置き換えられませんでした。",
+ "INSTALLER_DIRECTORY_HINT": "インストール先へのアクセス権限を確認し、そのファイルを使用しているプログラムを閉じてから、インストーラーを再実行してください。問題が続く場合はエラーの詳細をコピーしてください。",
+ "INSTALLER_DIRECTORY_RESTORE_HINT": "以前のインストールを復元できませんでした。エラーの詳細に表示されたバックアップディレクトリを保持し、再インストール前にサポートへお問い合わせください。",
+ "INSTALLER_PATH_INVALID": "ローカルフォルダーの完全なパスを選択してください。ドライブのルート、システムフォルダー、リンク、特殊文字を含むパスは使用できません。",
+ "INSTALLER_PATH_OWNERSHIP": "空のフォルダー、または登録済みの DeepSeek Harness インストール先を選択してください。",
+ "INSTALLER_PATH_WRITABLE": "この場所には書き込めません。現在のユーザーが書き込めるフォルダーを選択してください。インストーラーは管理者権限を要求しません。",
+ "INSTALLER_DISK_SPACE": "ディスクの空き容量が不足しています。別の場所を選択してください。",
+ "INSTALLER_PER_USER": "このインストーラーは現在のユーザーのみを対象としています。先にすべてのユーザー向けの既存のインストールを削除してください。",
+ "INSTALLER_EXTRACT_FAILED": "アプリケーションのファイルを展開できませんでした。",
+ "INSTALLER_EXTRACT_HINT": "セキュリティソフトがファイルをブロックしたか、ディスクの空き容量が不足している可能性があります。インストーラーを閉じて再試行してください。問題が続く場合は、以下のエラーの詳細をお送りください。",
+ "INSTALLER_EXTRACT_COPY": "エラーの詳細をコピー",
+ "INSTALLER_EXTRACT_EXPAND": "詳細を表示",
+ "INSTALLER_EXTRACT_COLLAPSE": "詳細を非表示",
+ "INSTALLER_EXTRACT_SAVED": "完全なレポートを %s に保存しました",
+ "INSTALLER_EXTRACT_UNSAVED": "完全なレポートを保存できませんでした。「エラーの詳細をコピー」で保存してください。",
+ "INSTALLER_EXTRACT_COPIED": "エラーの詳細をクリップボードにコピーしました。"
+ },
+ "uninstaller": {
+ "welcome": "アンインストール ウィザードへようこそ",
+ "finished": "アンインストールされました"
+ }
+}
diff --git a/apps/desktop/installer/locales/zh_CN.json b/apps/desktop/installer/locales/zh_CN.json
new file mode 100644
index 0000000000..e3f40f13be
--- /dev/null
+++ b/apps/desktop/installer/locales/zh_CN.json
@@ -0,0 +1,40 @@
+{
+ "nsisLanguage": "SIMPCHINESE",
+ "strings": {
+ "INSTALLER_INSTALL": "立即安装",
+ "INSTALLER_FINISH": "完成",
+ "INSTALLER_NATIVE_PROGRESS": "正在准备安装… %d%%",
+ "INSTALLER_PROGRESS_EXTRACT": "正在解压文件… %d%%",
+ "INSTALLER_PROGRESS_COPY": "正在安装文件… %d%%",
+ "INSTALLER_PROGRESS_REGISTER": "正在完成安装… %d%%",
+ "INSTALLER_PROGRESS_CLEAN": "正在清理临时文件… %d%%",
+ "INSTALLER_CHOOSE_PATH": "选择安装位置",
+ "INSTALLER_BROWSE": "选择",
+ "INSTALLER_LAUNCH": "立即启动",
+ "INSTALLER_LAUNCH_FAILED": "无法启动 DeepSeek Harness。请重试，或取消勾选立即启动后关闭安装程序。",
+ "INSTALLER_UI_ERROR": "无法初始化安装窗口，请关闭后重试。",
+ "INSTALLER_THEME_ERROR": "主题参数须为 /THEME=auto、/THEME=light 或 /THEME=dark。",
+ "INSTALLER_FAILED": "安装未完成，请关闭安装程序后重试。如仍然失败，请重新下载安装包。",
+ "INSTALLER_RUNNING": "DeepSeek Harness 正在运行，请先在系统托盘中退出应用后重试。",
+ "INSTALLER_DIRECTORY_FAILED": "无法替换安装目录。",
+ "INSTALLER_DIRECTORY_HINT": "请检查安装目录的访问权限，关闭占用其中内容的程序后重新运行安装器。如仍失败，请复制错误详情。",
+ "INSTALLER_DIRECTORY_RESTORE_HINT": "未能恢复原安装目录。请保留错误详情中列出的备份目录，联系支持人员后再安装。",
+ "INSTALLER_PATH_INVALID": "请选择本地磁盘上的完整文件夹路径，不能使用磁盘根目录、系统目录、链接目录或包含特殊字符的路径。",
+ "INSTALLER_PATH_OWNERSHIP": "请选择空文件夹，或 DeepSeek Harness 原来的安装目录。",
+ "INSTALLER_PATH_WRITABLE": "无法写入此位置。请选择当前用户可写入的文件夹；安装程序不会申请管理员权限。",
+ "INSTALLER_DISK_SPACE": "此磁盘的可用空间不足，请选择其他位置。",
+ "INSTALLER_PER_USER": "此安装程序仅支持当前用户。请先卸载已有的所有用户安装版本。",
+ "INSTALLER_EXTRACT_FAILED": "无法解压应用程序文件。",
+ "INSTALLER_EXTRACT_HINT": "可能是安全软件拦截了文件，或磁盘空间不足。请关闭安装程序后重试；如仍然失败，请将下方错误信息发送给我们。",
+ "INSTALLER_EXTRACT_COPY": "复制错误信息",
+ "INSTALLER_EXTRACT_EXPAND": "显示详情",
+ "INSTALLER_EXTRACT_COLLAPSE": "隐藏详情",
+ "INSTALLER_EXTRACT_SAVED": "完整错误报告已保存到 %s",
+ "INSTALLER_EXTRACT_UNSAVED": "无法保存完整错误报告，请使用“复制错误信息”保留。",
+ "INSTALLER_EXTRACT_COPIED": "错误信息已复制到剪贴板。"
+ },
+ "uninstaller": {
+ "welcome": "欢迎",
+ "finished": "已从你"
+ }
+}
diff --git a/apps/desktop/installer/strings.nsh b/apps/desktop/installer/strings.nsh
deleted file mode 100644
index a1ac41b418..0000000000
--- a/apps/desktop/installer/strings.nsh
+++ /dev/null
@@ -1,63 +0,0 @@
-; NSIS owns installer localization independently of the Electron application locale.
-LangString INSTALLER_INSTALL ${LANG_ENGLISH} "Install now"
-LangString INSTALLER_INSTALL ${LANG_SIMPCHINESE} "立即安装"
-LangString INSTALLER_FINISH ${LANG_ENGLISH} "Finish"
-LangString INSTALLER_FINISH ${LANG_SIMPCHINESE} "完成"
-LangString INSTALLER_NATIVE_PROGRESS ${LANG_ENGLISH} "Preparing installation… %d%%"
-LangString INSTALLER_NATIVE_PROGRESS ${LANG_SIMPCHINESE} "正在准备安装… %d%%"
-LangString INSTALLER_PROGRESS_EXTRACT ${LANG_ENGLISH} "Extracting files… %d%%"
-LangString INSTALLER_PROGRESS_EXTRACT ${LANG_SIMPCHINESE} "正在解压文件… %d%%"
-LangString INSTALLER_PROGRESS_COPY ${LANG_ENGLISH} "Installing files… %d%%"
-LangString INSTALLER_PROGRESS_COPY ${LANG_SIMPCHINESE} "正在安装文件… %d%%"
-LangString INSTALLER_PROGRESS_REGISTER ${LANG_ENGLISH} "Finishing installation… %d%%"
-LangString INSTALLER_PROGRESS_REGISTER ${LANG_SIMPCHINESE} "正在完成安装… %d%%"
-LangString INSTALLER_PROGRESS_CLEAN ${LANG_ENGLISH} "Cleaning temporary files… %d%%"
-LangString INSTALLER_PROGRESS_CLEAN ${LANG_SIMPCHINESE} "正在清理临时文件… %d%%"
-LangString INSTALLER_CHOOSE_PATH ${LANG_ENGLISH} "Choose location"
-LangString INSTALLER_CHOOSE_PATH ${LANG_SIMPCHINESE} "选择安装位置"
-LangString INSTALLER_BROWSE ${LANG_ENGLISH} "Browse"
-LangString INSTALLER_BROWSE ${LANG_SIMPCHINESE} "选择"
-LangString INSTALLER_LAUNCH ${LANG_ENGLISH} "Launch now"
-LangString INSTALLER_LAUNCH ${LANG_SIMPCHINESE} "立即启动"
-LangString INSTALLER_LAUNCH_FAILED ${LANG_ENGLISH} "DeepSeek Harness could not be launched. Retry, or clear Launch now and close the installer."
-LangString INSTALLER_LAUNCH_FAILED ${LANG_SIMPCHINESE} "无法启动 DeepSeek Harness。请重试，或取消勾选立即启动后关闭安装程序。"
-LangString INSTALLER_UI_ERROR ${LANG_ENGLISH} "The installer could not initialize its window. Close it and try again."
-LangString INSTALLER_UI_ERROR ${LANG_SIMPCHINESE} "无法初始化安装窗口，请关闭后重试。"
-LangString INSTALLER_THEME_ERROR ${LANG_ENGLISH} "Use /THEME=auto, /THEME=light or /THEME=dark."
-LangString INSTALLER_THEME_ERROR ${LANG_SIMPCHINESE} "主题参数须为 /THEME=auto、/THEME=light 或 /THEME=dark。"
-LangString INSTALLER_FAILED ${LANG_ENGLISH} "Installation did not finish. Close this installer and retry. If the problem persists, download the installer again."
-LangString INSTALLER_FAILED ${LANG_SIMPCHINESE} "安装未完成，请关闭安装程序后重试。如仍然失败，请重新下载安装包。"
-LangString INSTALLER_RUNNING ${LANG_ENGLISH} "DeepSeek Harness is running. Quit it from the system tray and try again."
-LangString INSTALLER_RUNNING ${LANG_SIMPCHINESE} "DeepSeek Harness 正在运行，请先在系统托盘中退出应用后重试。"
-LangString INSTALLER_DIRECTORY_FAILED ${LANG_ENGLISH} "The installation directory could not be replaced."
-LangString INSTALLER_DIRECTORY_FAILED ${LANG_SIMPCHINESE} "无法替换安装目录。"
-LangString INSTALLER_DIRECTORY_HINT ${LANG_ENGLISH} "Check access to the installation directory and close programs using its files, then run the installer again. Copy the error details if the problem persists."
-LangString INSTALLER_DIRECTORY_HINT ${LANG_SIMPCHINESE} "请检查安装目录的访问权限，关闭占用其中内容的程序后重新运行安装器。如仍失败，请复制错误详情。"
-LangString INSTALLER_DIRECTORY_RESTORE_HINT ${LANG_ENGLISH} "The previous installation could not be restored. Keep the backup directory shown in the error details and contact support before installing again."
-LangString INSTALLER_DIRECTORY_RESTORE_HINT ${LANG_SIMPCHINESE} "未能恢复原安装目录。请保留错误详情中列出的备份目录，联系支持人员后再安装。"
-LangString INSTALLER_PATH_INVALID ${LANG_ENGLISH} "Choose a full local folder path. Drive roots, system folders, links and special characters are not supported."
-LangString INSTALLER_PATH_INVALID ${LANG_SIMPCHINESE} "请选择本地磁盘上的完整文件夹路径，不能使用磁盘根目录、系统目录、链接目录或包含特殊字符的路径。"
-LangString INSTALLER_PATH_OWNERSHIP ${LANG_ENGLISH} "Choose an empty folder or the registered DeepSeek Harness installation folder."
-LangString INSTALLER_PATH_OWNERSHIP ${LANG_SIMPCHINESE} "请选择空文件夹，或 DeepSeek Harness 原来的安装目录。"
-LangString INSTALLER_PATH_WRITABLE ${LANG_ENGLISH} "This location is not writable. Choose a folder available to the current user."
-LangString INSTALLER_PATH_WRITABLE ${LANG_SIMPCHINESE} "无法写入此位置。请选择当前用户可写入的文件夹；安装程序不会申请管理员权限。"
-LangString INSTALLER_DISK_SPACE ${LANG_ENGLISH} "There is not enough free disk space. Choose another location."
-LangString INSTALLER_DISK_SPACE ${LANG_SIMPCHINESE} "此磁盘的可用空间不足，请选择其他位置。"
-LangString INSTALLER_PER_USER ${LANG_ENGLISH} "This installer supports the current user only. Uninstall the existing all-users installation first."
-LangString INSTALLER_PER_USER ${LANG_SIMPCHINESE} "此安装程序仅支持当前用户。请先卸载已有的所有用户安装版本。"
-LangString INSTALLER_EXTRACT_FAILED ${LANG_ENGLISH} "The application files could not be extracted."
-LangString INSTALLER_EXTRACT_FAILED ${LANG_SIMPCHINESE} "无法解压应用程序文件。"
-LangString INSTALLER_EXTRACT_HINT ${LANG_ENGLISH} "Security software may have blocked a file, or the disk may be full. Close this installer and try again. If it keeps failing, send us the error details below."
-LangString INSTALLER_EXTRACT_HINT ${LANG_SIMPCHINESE} "可能是安全软件拦截了文件，或磁盘空间不足。请关闭安装程序后重试；如仍然失败，请将下方错误信息发送给我们。"
-LangString INSTALLER_EXTRACT_COPY ${LANG_ENGLISH} "Copy error details"
-LangString INSTALLER_EXTRACT_COPY ${LANG_SIMPCHINESE} "复制错误信息"
-LangString INSTALLER_EXTRACT_EXPAND ${LANG_ENGLISH} "Show details"
-LangString INSTALLER_EXTRACT_EXPAND ${LANG_SIMPCHINESE} "显示详情"
-LangString INSTALLER_EXTRACT_COLLAPSE ${LANG_ENGLISH} "Hide details"
-LangString INSTALLER_EXTRACT_COLLAPSE ${LANG_SIMPCHINESE} "隐藏详情"
-LangString INSTALLER_EXTRACT_SAVED ${LANG_ENGLISH} "The full report was saved to %s"
-LangString INSTALLER_EXTRACT_SAVED ${LANG_SIMPCHINESE} "完整错误报告已保存到 %s"
-LangString INSTALLER_EXTRACT_UNSAVED ${LANG_ENGLISH} "The full report could not be saved. Use Copy error details to keep it."
-LangString INSTALLER_EXTRACT_UNSAVED ${LANG_SIMPCHINESE} "无法保存完整错误报告，请使用“复制错误信息”保留。"
-LangString INSTALLER_EXTRACT_COPIED ${LANG_ENGLISH} "Error details were copied to the clipboard."
-LangString INSTALLER_EXTRACT_COPIED ${LANG_SIMPCHINESE} "错误信息已复制到剪贴板。"
diff --git a/apps/desktop/package.json b/apps/desktop/package.json
index 64a6bff8fc..23d5e49efe 100644
--- a/apps/desktop/package.json
+++ b/apps/desktop/package.json
@@ -82,6 +82,7 @@
"@deepseek-ai/dsh-client-ui-theme": "workspace:*",
"@deepseek-ai/dsh-client-shortcuts": "workspace:*",
"@deepseek-ai/dsh-atomic-write": "workspace:*",
- "@deepseek-ai/dsh-client-product-analytics": "workspace:*"
+ "@deepseek-ai/dsh-client-product-analytics": "workspace:*",
+ "@deepseek-ai/dsh-util-file-drag": "workspace:*"
}
}
diff --git a/apps/desktop/renderer/mandatory-update.css b/apps/desktop/renderer/mandatory-update.css
index 591a82b6ab..dc721b8a68 100644
--- a/apps/desktop/renderer/mandatory-update.css
+++ b/apps/desktop/renderer/mandatory-update.css
@@ -1,16 +1,19 @@
-#status, #version { margin-top: 12px; color: #555962; }
+#status, #version { margin-top: 12px; color: var(--dsw-alias-label-secondary); }
#status:empty, #version:empty { display: none; }
-#error { margin-top: 12px; color: #d93025; }
-#address { display: block; width: 100%; margin-top: 4px; padding: 8px; border: 1px solid #e6e7eb; border-radius: 8px; background: #f5f5f5; font: 12px/20px monospace; color: #555962; overflow-wrap: anywhere; resize: vertical; }
-#actions button:not(.primary) { min-height: 32px; padding: 5px 8px; color: #555962; background: transparent; }
+#error { margin-top: 12px; color: var(--dsw-alias-state-error-primary); }
+#address { display: block; width: 100%; margin-top: 4px; padding: 8px; border: 1px solid var(--dsw-alias-border-l2); border-radius: 8px; background: var(--dsw-alias-markdown-code-block); font: 12px/20px monospace; color: var(--dsw-alias-label-secondary); overflow-wrap: anywhere; resize: vertical; }
+#actions button:not(.primary) { min-height: 32px; padding: 5px 8px; color: var(--dsw-alias-label-secondary); background: transparent; }
#update, #refresh { border-radius: 100px; }
-#fallback { border-top: 1px solid #e6e7eb; margin-top: 12px; padding-top: 12px; }
-#fallback p, #manual-copy { font-size: 12px; line-height: 20px; color: #555962; }
-#copy { min-height: 32px; padding: 3px 0; background: transparent; color: #4d6bfe; font-size: 12px; }
-#copy-message { color: #d93025 !important; }
+#fallback { border-top: 1px solid var(--dsw-alias-border-l2); margin-top: 12px; padding-top: 12px; }
+#fallback p, #manual-copy { font-size: 12px; line-height: 20px; color: var(--dsw-alias-label-secondary); }
+#copy { min-height: 32px; padding: 3px 0; background: transparent; color: var(--dsw-alias-link); font-size: 12px; }
+#copy-message { color: var(--dsw-alias-state-error-primary) !important; }
#manual-copy { display: block; margin-top: 8px; }
-#progress { display: block; width: 100%; height: 4px; margin-top: 12px; border: 0; appearance: none; -webkit-appearance: none; background: #e6e7eb; accent-color: #0f1115; }
+#progress { display: block; width: 100%; height: 4px; margin-top: 12px; border: 0; appearance: none; -webkit-appearance: none; background: var(--dsw-alias-border-l2); accent-color: var(--dsw-alias-button-primary-fill); }
-#progress::-webkit-progress-bar { background: #e6e7eb; }
-#progress::-webkit-progress-value { background: #0f1115; }
-#progress::-moz-progress-bar { background: #0f1115; }
+#progress::-webkit-progress-bar { background: var(--dsw-alias-border-l2); }
+#progress::-webkit-progress-value { background: var(--dsw-alias-button-primary-fill); }
+#progress::-moz-progress-bar { background: var(--dsw-alias-button-primary-fill); }
+@media (hover: hover) {
+ #actions button:not(.primary):hover:not(:disabled), #copy:hover:not(:disabled) { background: var(--dsw-alias-interactive-bg-hover); }
+}
diff --git a/apps/desktop/renderer/mandatory-update.html b/apps/desktop/renderer/mandatory-update.html
index f009ab8a37..d4d1747cf9 100644
--- a/apps/desktop/renderer/mandatory-update.html
+++ b/apps/desktop/renderer/mandatory-update.html
@@ -5,10 +5,12 @@
diff --git a/apps/desktop/renderer/shell-theme.js b/apps/desktop/renderer/shell-theme.js
new file mode 100644
index 0000000000..bbc12f381b
--- /dev/null
+++ b/apps/desktop/renderer/shell-theme.js
@@ -0,0 +1,6 @@
+/** Shell documents follow Electron's app-resolved palette before displaying their content. */
+const palette = window.matchMedia('(prefers-color-scheme: dark)')
+const applyPalette = () => { document.body.toggleAttribute('data-ds-dark-theme', palette.matches) }
+applyPalette()
+palette.addEventListener('change', applyPalette)
+window.addEventListener('pagehide', () => { palette.removeEventListener('change', applyPalette) }, { once: true })
diff --git a/apps/desktop/renderer/update-dialog.css b/apps/desktop/renderer/update-dialog.css
index 98183989a5..dd50411d46 100644
--- a/apps/desktop/renderer/update-dialog.css
+++ b/apps/desktop/renderer/update-dialog.css
@@ -1,31 +1,37 @@
:root {
- color-scheme: light;
+ color-scheme: light dark;
font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Microsoft YaHei", sans-serif;
- color: #0f1115;
background: transparent;
}
* { box-sizing: border-box; }
-body { margin: 0; height: 100vh; display: grid; place-items: center; isolation: isolate; }
-body::before { content: ""; position: fixed; inset: 0; z-index: -1; background: rgb(0 0 0 / 24%); }
-main { width: min(380px, calc(100vw - 32px)); max-height: calc(100vh - 32px); overflow: auto; padding: 22px 24px 24px; border-radius: 24px; background: #fff; box-shadow: 0 0 1px rgb(0 0 0 / 20%), 0 0 4px rgb(0 0 0 / 2%), 0 12px 32px rgb(0 0 0 / 8%); }
+body { margin: 0; height: 100vh; display: grid; place-items: center; isolation: isolate; background: transparent; color: var(--dsw-alias-label-primary); color-scheme: light; }
+body[data-ds-dark-theme] { color-scheme: dark; }
+body::before { content: ""; position: fixed; inset: 0; z-index: -1; background: var(--dsw-alias-bg-mask-1); }
+main { width: min(380px, calc(100vw - 32px)); max-height: calc(100vh - 32px); overflow: auto; padding: 22px 24px 24px; border-radius: 24px; background: var(--dsw-alias-bg-layer-1); box-shadow: none; }
+body[data-ds-dark-theme] main { box-shadow: inset 0 0 0 1px var(--dsw-alias-border-l2); }
header { display: flex; align-items: flex-start; justify-content: space-between; gap: 8px; margin-bottom: 12px; }
main:focus { outline: none; }
h1 { margin: 0; min-height: 28px; font-size: 16px; font-weight: 500; line-height: 24px; overflow-wrap: anywhere; }
p { margin: 0; font-size: 14px; line-height: 22px; white-space: pre-wrap; overflow-wrap: anywhere; }
-#actions { display: flex; flex-direction: column; gap: 8px; margin-top: 20px; position: sticky; bottom: 0; background: #fff; }
-button { min-height: 44px; padding: 9px 16px; border: 0; border-radius: 12px; font-family: inherit; font-size: 14px; font-weight: 500; line-height: 22px; cursor: pointer; }
-.primary { background: #0f1115; color: #fff; }
-.secondary { background: #f5f5f5; color: inherit; }
+#actions { display: flex; flex-direction: column; gap: 8px; margin-top: 20px; position: sticky; bottom: 0; background: var(--dsw-alias-bg-layer-1); }
+button { min-height: 44px; padding: 9px 16px; border: 0; border-radius: 12px; font-family: inherit; font-size: 14px; font-weight: 500; line-height: 22px; color: inherit; cursor: pointer; }
+.primary { background: var(--dsw-alias-button-primary-fill); color: var(--dsw-alias-label-primary-inverted); }
+
+.secondary { background: var(--dsw-alias-button-primary-dimmed); color: inherit; }
.close { display: grid; place-items: center; flex: none; width: 28px; min-height: 28px; padding: 7px; border-radius: 50%; background: transparent; }
-.close img { width: 14px; height: 14px; }
-button:hover { filter: brightness(0.95); }
-button:focus-visible, summary:focus-visible, pre:focus-visible { outline: 2px solid #4d6bfe; outline-offset: 3px; }
+.close::before { content: ""; width: 14px; height: 14px; background: currentColor; mask: url("update-close.svg") center / contain no-repeat; }
+
+button:focus-visible, summary:focus-visible, pre:focus-visible { outline: 2px solid var(--dsw-alias-link); outline-offset: 3px; }
details { margin-top: 12px; font-size: 13px; line-height: 20px; }
-summary { cursor: pointer; color: #5b6472; }
-pre { margin: 8px 0 0; padding: 10px; max-height: min(180px, 30vh); overflow: auto; border-radius: 8px; background: #f5f5f5; font: 12px/18px monospace; white-space: pre-wrap; overflow-wrap: anywhere; }
+summary { cursor: pointer; color: var(--dsw-alias-label-secondary); }
+pre { margin: 8px 0 0; padding: 10px; max-height: min(180px, 30vh); overflow: auto; border-radius: 8px; background: var(--dsw-alias-markdown-code-block); font: 12px/18px monospace; white-space: pre-wrap; overflow-wrap: anywhere; }
button:disabled { opacity: 0.5; cursor: default; }
[hidden] { display: none !important; }
body.update-dialog { opacity: 0; transition: opacity 150ms ease; }
body.update-dialog.visible { opacity: 1; }
@starting-style { body.update-dialog.visible { opacity: 0; } }
@media (prefers-reduced-motion: reduce) { body.update-dialog { transition: none; } }
+@media (hover: hover) {
+ .primary:hover:not(:disabled) { background: var(--dsw-alias-button-primary-hover); }
+ .secondary:hover:not(:disabled), .close:hover { background: var(--dsw-alias-interactive-bg-hover); }
+}
diff --git a/apps/desktop/renderer/update-dialog.html b/apps/desktop/renderer/update-dialog.html
index 85a0f20abd..c6a913347d 100644
--- a/apps/desktop/renderer/update-dialog.html
+++ b/apps/desktop/renderer/update-dialog.html
@@ -5,11 +5,13 @@
-
+