diff --git a/.agents/notes/README.i18n.yaml b/.agents/notes/README.i18n.yaml
index c07b56468c..f6289cf96f 100644
--- a/.agents/notes/README.i18n.yaml
+++ b/.agents/notes/README.i18n.yaml
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write .agents/notes/README.md
-README.md: 9fdb4039b525bbc4051ab3c8058b117e4de5f2f4
-README.zh.md: 2d7e07b963d3c4d77da9148b011e1478fa2ae5da
+README.md: 6872de0a1390fa5a1707b9f464c9e0edeb2da4be
+README.zh.md: ced81f77fa904ad0b5cb5219383ef651d87392b8
diff --git a/.agents/notes/README.md b/.agents/notes/README.md
index 9fdb4039b5..6872de0a13 100644
--- a/.agents/notes/README.md
+++ b/.agents/notes/README.md
@@ -16,7 +16,7 @@ Every Agent Note has two axes, both encoded in its **path** — `{lifecycle}/{cl
The date in the filename is when the topic was **first proposed** (per git history). Cross-references between Agent Notes use relative markdown links (`[topic](../../implemented/architecture/2026-…-….md)`) — never bare prose or numbers — so they are mechanically checkable and survive moves between folders.
-The active lifecycle tree is the working inventory: browse its lifecycle/class folders or search the repository. Do not add a centralized `INDEX.md`; the [no-index Agent Note](implemented/process/2026-07-19-remove-generated-agent-note-index.md) owns the rationale. Low-future-value implemented records move to the separate frozen [`archived/`](archived/AGENTS.md) tree described below.
+The active lifecycle tree is the working inventory: browse its lifecycle/class folders or search the repository. Do not add a centralized `INDEX.md`; the [no-index Agent Note](implemented/process/2026-07-19-remove-generated-agent-note-index.md) owns the rationale. Implemented records with historical decision value but little future guidance move to the separate frozen [`archived/`](archived/AGENTS.md) tree described below.
## Classification
@@ -35,9 +35,9 @@ The `architecture` / `process` line: **architecture** is about the source we shi
## Archiving and deletion
-Archive an implemented Agent Note when the shipped decision is complete and its rationale is unlikely to guide future work. Keep it active when its alternatives, ownership boundary, negative guarantee, durable or wire semantics, security rule, or reintroduction condition remains useful. Never archive a proposed note: reject an obsolete proposal. Keep a rejected note only while it prevents a plausible mistake; otherwise delete its English, Chinese, and sidecar files together. Use the calibrated [`dsh-archive-agent-notes`](../skills/dsh-archive-agent-notes/SKILL.md) workflow rather than word count, age, or a target quota.
+Delete an implemented Agent Note that only describes small UI adjustments or purely mechanical changes; delete its English, Chinese, and sidecar files together and repair or remove inbound links. A local bug fix, performance change, new capability, or substantive behavior decision does not qualify merely because its implementation is small. Archive other implemented notes only when the shipped decision is complete, its rationale is unlikely to guide future work, and the record still has historical decision value. Keep it active when its alternatives, ownership boundary, negative guarantee, durable or wire semantics, security rule, or reintroduction condition remains useful. Never archive a proposed note: reject an obsolete proposal. Keep a rejected note only while it prevents a plausible mistake; otherwise delete its English, Chinese, and sidecar files together. Use the calibrated [`dsh-archive-agent-notes`](../skills/dsh-archive-agent-notes/SKILL.md) workflow rather than word count, age, or a target quota.
-The archive is path-encoded as `archived/{class}/yyyy-mm-dd-topic-title.md`; `implemented` is deliberately absent because only implemented notes can enter it. An archival change moves the complete English/Chinese/sidecar triplet, retains `Status: implemented`, inserts the same `Archived: YYYY-MM-DD` line immediately below that status in both language files, re-records the sidecar, and repairs or deletes inbound links. These are the only permitted content changes during archival.
+The archive is path-encoded as `archived/{class}/yyyy-mm-dd-topic-title.md`; `implemented` is deliberately absent because only implemented notes can enter it. An archival change moves the complete English/Chinese/sidecar triplet, retains `Status: implemented`, inserts the same `Archived: YYYY-MM-DD` line immediately below that status in both language files, re-records the sidecar, and repairs or deletes inbound links. These are the only permitted content changes during archival. Existing title punctuation, blank-line layout, and language-switcher wording do not block archival; preserve them with the body.
Once sealed, every archived triplet is permanently frozen. Do not edit, translate, reformat, update, move, or delete it, and do not treat it as authority for current behavior. Documentation gates skip archived sources, including their outbound links; active prose may still link into an archived note when it intentionally cites history. [`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) enforces the closed class tree, complete triplets, archive metadata, sidecar hashes, and the append-only frozen-content manifest. The [archive-policy Agent Note](implemented/process/2026-07-26-frozen-agent-note-archive.md) owns the rationale.
diff --git a/.agents/notes/README.zh.md b/.agents/notes/README.zh.md
index 2d7e07b963..ced81f77fa 100644
--- a/.agents/notes/README.zh.md
+++ b/.agents/notes/README.zh.md
@@ -16,7 +16,7 @@
文件名中的日期是该主题**首次提出**的时间（以 git 历史为准）。Agent Note 之间的交叉引用使用相对 Markdown 链接（`[topic](../../implemented/architecture/2026-…-….md)`），从不使用纯文字或编号，这样既可机械检查，也能在文件夹间移动时保持有效。
-活跃生命周期目录树就是工作清单：浏览其生命周期/类别文件夹，或搜索仓库即可。请勿添加集中式 `INDEX.md`；设计理由见[不设索引的 Agent Note](implemented/process/2026-07-19-remove-generated-agent-note-index.zh.md)。未来指导价值较低的已实施记录会移至下文所述、单独冻结的 [`archived/`](archived/AGENTS.md) 目录树。
+活跃生命周期目录树就是工作清单：浏览其生命周期/类别文件夹，或搜索仓库即可。请勿添加集中式 `INDEX.md`；设计理由见[不设索引的 Agent Note](implemented/process/2026-07-19-remove-generated-agent-note-index.zh.md)。具有历史决策价值但未来指导价值较低的已实施记录会移至下文所述、单独冻结的 [`archived/`](archived/AGENTS.md) 目录树。
@@ -37,9 +37,9 @@
## 归档与删除
-当一份 implemented Agent Note 记录的交付决策已经完整落地，且其决策依据不太可能再指导未来工作时，将其归档。如果其中的备选方案、归属边界、否定性保证、持久化语义或协议语义、安全规则，或者重新引入条件仍有价值，则继续作为活跃记录保留。绝不归档 proposed Agent Note：过时的提案应转为 rejected。仅当 rejected Agent Note 仍能避免一种可能发生的错误时保留；否则一并删除其英文、中文和伴随记录文件。请使用经过校准的 [`dsh-archive-agent-notes`](../skills/dsh-archive-agent-notes/SKILL.md) 工作流，不要根据字数、存续时间或目标配额来判断。
+仅描述小型 UI 调整或纯机械变更的 implemented Agent Note 直接删除；一并删除英文、中文和伴随记录文件，并修复或移除入站链接。局部 bug 修复、性能变更、新能力或实质行为决策，不会仅因实现规模小就符合删除条件。其他已实施记录只有在交付决策完整落地、其依据不太可能再指导未来工作，但仍具有历史决策价值时才归档。如果其中的备选方案、归属边界、否定性保证、持久化语义或协议语义、安全规则，或者重新引入条件仍有价值，则继续作为活跃记录保留。绝不归档 proposed Agent Note：过时的提案应转为 rejected。仅当 rejected Agent Note 仍能避免一种可能发生的错误时保留；否则一并删除其英文、中文和伴随记录文件。请使用经过校准的 [`dsh-archive-agent-notes`](../skills/dsh-archive-agent-notes/SKILL.md) 工作流，不要根据字数、存续时间或目标配额来判断。
-归档路径编码为 `archived/{class}/yyyy-mm-dd-topic-title.md`；其中有意省略 `implemented`，因为只有 implemented Agent Note 可以进入归档。归档变更会移动完整的英文、中文和伴随记录三个文件，保留 `Status: implemented`，在两种语言的文件中紧接该状态行插入相同的 `Archived: YYYY-MM-DD` 行，重新记录伴随记录，并修复或删除入站链接。归档时只允许对内容做这些更改。
+归档路径编码为 `archived/{class}/yyyy-mm-dd-topic-title.md`；其中有意省略 `implemented`，因为只有 implemented Agent Note 可以进入归档。归档变更会移动完整的英文、中文和伴随记录三个文件，保留 `Status: implemented`，在两种语言的文件中紧接该状态行插入相同的 `Archived: YYYY-MM-DD` 行，重新记录伴随记录，并修复或删除入站链接。归档时只允许对内容做这些更改。 既有标题标点、空行布局和语言切换栏措辞不阻止归档；与正文一起保留。
封存后，每组归档文件都永久冻结。禁止编辑、翻译、重新格式化、更新、移动或删除，也不得将其视为当前行为的权威依据。文档门禁会跳过归档源文件，包括其中的出站链接；当活跃文档有意引用历史时，仍可链接到归档 Agent Note。[`verify-archived-agent-notes`](../../scripts/verify-archived-agent-notes.ts) 强制执行封闭的类别目录树、完整的三文件配对、归档元数据、伴随记录 hash，以及仅追加的冻结内容 manifest（元数据清单）。[归档政策 Agent Note](implemented/process/2026-07-26-frozen-agent-note-archive.zh.md) 记录了设计依据。
diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml
index aad1a96be8..bb7be001de 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.i18n.yaml
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
-2026-08-09-client-conversation-node-assembly.md: 43f9f0359822f7d7c5b52c09646fd3ffbf80f783
-2026-08-09-client-conversation-node-assembly.zh.md: d7475f5ff8218419743448d455d5d5ffe3cc4091
+2026-08-09-client-conversation-node-assembly.md: bb1d68cc045710d46a44ffb295c2307628338521
+2026-08-09-client-conversation-node-assembly.zh.md: 6291211d589b3389e7dc9a42d15fe6ac0d9e7ab9
diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
index 43f9f03598..bb1d68cc04 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.md
@@ -291,7 +291,7 @@ Page size, record packing, the number of history loads, and RAF coalescing affec
Inbox demonstrates that every Event can be a start-only instantaneous-state Context; not every business requires a start/update pair. Reader links each next-step state to the prior same-kind Context instead of inventing a lifecycle ID for the entire Inbox. The state itself shares immutable pending splice nodes and one current claimed-batch Set, while unconsumed next-turn input remains outside Conversation because no Chat or Trajectory classification reads it.
-Request Prompt demonstrates shared pure interpretation without shared target State: Chat and Trajectory call `inspectRequestPrompt()` from their own Definitions. The function canonicalizes the full header and classifies model-visible system/tool differences; each target then chooses its own output. Chat materializes a non-empty initial system field, a real system change, and each `series` snapshot that explicitly begins a message series or follows a surface replacement. An unchanged `resume` remains in Trajectory and reconstruction state but does not repeat the visible Chat row once its predecessor is loaded. Ordinary append-only later Turns do not write another unchanged header. The first header in a Step follows the provider envelope rather than the header Event position: step one uses the owning Turn start and later steps use their Step start, placing the system field before the request's user-role messages; a later header in the same Step stays at its own Event after the surface rewrite that began the new series. When the preceding header is outside a partial window, a non-`initial` header stays at its own Event and renders conservatively. Prepending an identical predecessor hides an unchanged resume without withdrawing its stable Node key; a real change remains visible. Every header is a full snapshot, so a first loaded `resume`, `change`, or `series` header can render its system field without fabricating a comparison to unloaded history ([resume presentation decision](../bug-fix/2026-09-03-resume-headers-do-not-repeat-system-prompts.md)).
+Request Prompt demonstrates shared pure interpretation without shared target State: Chat and Trajectory call `inspectRequestPrompt()` from their own Definitions. The function canonicalizes the full header and classifies model-visible system/tool differences; each target then chooses its own output. Chat materializes a non-empty initial system field, a real system change, and each `series` snapshot that explicitly begins a message series or follows a surface replacement. Resume headers retain a Chat prompt card even when the system text is unchanged. Ordinary append-only later Turns do not write another unchanged header. The first header in a Step follows the provider envelope rather than the header Event position: step one uses the owning Turn start and later steps use their Step start, placing the system field before the request's user-role messages; a later header in the same Step stays at its own Event after the surface rewrite that began the new series. When the preceding header is outside a partial window, a non-`initial` header stays at its own Event and renders conservatively. Prepending an identical predecessor can hide an unchanged `change` header without withdrawing its stable Node key; resume and explicit series-start cards remain visible. Every header is a full snapshot, so a first loaded `resume`, `change`, or `series` header can render its system field without fabricating a comparison to unloaded history ([request-prompt Definition](../../../../packages/client/ui-chat/src/client/conversation-nodes/request-prompt.ts)).
Retry, Assistant, and Turn Tail demonstrate independent claims on one Event. Each Definition updates only its own State and produces its own atomic Chat Node.
diff --git a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
index d7475f5ff8..6291211d58 100644
--- a/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-09-client-conversation-node-assembly.zh.md
@@ -291,7 +291,7 @@ Chat `order` 的结构性变化仍可能重排当前可见 key；纯 data 更新
Inbox 展示了“每条 Event 都是一个 start-only 瞬间态 Context”，不是所有业务都需要 start/update 配对。每个 next-step state 通过 Reader 与前一个同 kind Context 形成连续 fold，而非给整个 Inbox 人工制造生命周期 ID。state 自身共享不可变 pending splice 节点和一个当前 claimed-batch Set；未消费的 next-turn input 不进入 Conversation，因为 Chat 与 Trajectory 都不读取它来分类。
-Request Prompt 展示了如何在不共享 target State 的前提下共用纯解释逻辑：Chat 与 Trajectory 各自在自己的 Definition 中调用 `inspectRequestPrompt()`。该函数规范化完整 header，并判定面向模型的 system/tool 差异；随后每个 target 自行选择产物。Chat 会物化非空的初始 system 字段、真实 system 变化，以及每个显式开启消息序列或紧随表层替换的 `series` 快照。未变化的 `resume` 会留在 Trajectory 和重建状态中，但前序 header 已加载时不会重复可见的 Chat 行。普通的仅追加后续 Turn 不会再次写入未变 header。一个 Step 中的首条 header 遵循提供方信封，而不是 header Event 位置：step one 使用所属 Turn start，后续 step 使用各自的 Step start，把 system 字段放到该请求的 user-role 消息之前；同一 Step 的后续 header 保留在开启新序列的表层改写之后。部分窗口未包含前序 header 时，非 `initial` header 会保留在自身 Event 并保守渲染。prepend 补入相同的前序 header 后，内容未变的 resume 会隐藏但不撤回其稳定 Node key；真实变化仍然可见。每条 header 都是完整快照，因此已加载窗口中的首条 `resume`、`change` 或 `series` header 无需凭空构造与未加载历史的比较，也能渲染其 system 字段（[resume 展示决策](../bug-fix/2026-09-03-resume-headers-do-not-repeat-system-prompts.zh.md)）。
+Request Prompt 展示了如何在不共享 target State 的前提下共用纯解释逻辑：Chat 与 Trajectory 各自在自己的 Definition 中调用 `inspectRequestPrompt()`。该函数规范化完整 header，并判定面向模型的 system/tool 差异；随后每个 target 自行选择产物。Chat 会物化非空的初始 system 字段、真实 system 变化，以及每个显式开启消息序列或紧随表层替换的 `series` 快照。即使 system 文本未变化，resume header 仍保留 Chat prompt 卡片。普通的仅追加后续 Turn 不会再次写入未变 header。一个 Step 中的首条 header 遵循提供方信封，而不是 header Event 位置：step one 使用所属 Turn start，后续 step 使用各自的 Step start，把 system 字段放到该请求的 user-role 消息之前；同一 Step 的后续 header 保留在开启新序列的表层改写之后。部分窗口未包含前序 header 时，非 `initial` header 会保留在自身 Event 并保守渲染。prepend 补入相同的前序 header 后，内容未变的 `change` header 可以隐藏，但不撤回其稳定 Node key；resume 和显式序列起点的卡片仍然可见。每条 header 都是完整快照，因此已加载窗口中的首条 `resume`、`change` 或 `series` header 无需凭空构造与未加载历史的比较，也能渲染其 system 字段（[request-prompt Definition](../../../../packages/client/ui-chat/src/client/conversation-nodes/request-prompt.ts)）。
Retry、Assistant 和 Turn Tail 展示了同一 Event 被多个 Definition 独立认领。每个 Definition 只更新自己的 State，最终分别生成原子 Chat Node。
diff --git a/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.i18n.yaml b/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.i18n.yaml
index fff8e98bc5..cdf124f72a 100644
--- a/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.i18n.yaml
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.md
-2026-08-23-client-derived-tool-presentation.md: 703960cb24f90eb678fda381f929efb3f94bbd28
-2026-08-23-client-derived-tool-presentation.zh.md: 7f161379553f3aca33c72c2edf93e114d27eb7f9
+2026-08-23-client-derived-tool-presentation.md: 8befe840b08006a7d2ee0fa1b7875c2c989d4779
+2026-08-23-client-derived-tool-presentation.zh.md: 249366f10e6eb06941b344977169609358786413
diff --git a/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.md b/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.md
index 703960cb24..8befe840b0 100644
--- a/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.md
+++ b/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.md
@@ -64,7 +64,7 @@ The Host `ToolDefinition.presentCall`, `ToolDefinition.presentResult`, `ToolCall
**Client card model** means the pure props data under `ui-tool/src/client/tool/models/` consumed directly by `TerminalBlock`, `DiffBlock`, `ReadBlock`, `SearchBlock`, `WebBlock`, or `ToolRow`.
-**Specialized card** means the structured terminal, diff, read, search, or web body. Titles, summaries, status dots, and ordinary IN/OUT text remain part of the generic tool row.
+**Specialized card** means the structured terminal, diff, read, search, or web body. Titles, summaries, lifecycle styling, business glyphs, and ordinary IN/OUT text remain part of the generic tool row.
**Equivalent** means that the same supported input produces the user-visible result and interaction pinned by the existing component, assembly, and browser evidence. It does not require the same intermediate TypeScript types or internal calls.
@@ -301,7 +301,7 @@ The Client terminal model derives existing `TerminalBlock` props from the tool n
| Input | Preserved result |
|---|---|
| running standard `bash`/`pwsh` foreground call | terminal prompt, description, cwd, and running state |
-| successful standard foreground call | terminal output, exit code/signal, and success or failure status dot |
+| successful standard foreground call | terminal output, exit code/signal, and settled state presentation |
| `run_in_background:true` | Generic row and raw result |
| tool execution error | Generic IN/OUT and error summary |
| running persistent `bash`/`pwsh` | terminal prompt |
diff --git a/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.zh.md b/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.zh.md
index 7f16137955..249366f10e 100644
--- a/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.zh.md
@@ -64,7 +64,7 @@ Host 的 `ToolDefinition.presentCall`、`ToolDefinition.presentResult`、`ToolCa
**Client card model**指 `ui-tool/src/client/tool/models/` 下直接供 `TerminalBlock`、`DiffBlock`、`ReadBlock`、`SearchBlock`、`WebBlock` 或 `ToolRow` 使用的纯 props 数据。
-**专用卡片**指 terminal、diff、read、search 与 web 的结构化正文；标题、摘要、状态点和普通 IN／OUT 文本仍属于通用工具行。
+**专用卡片**指 terminal、diff、read、search 与 web 的结构化正文；标题、摘要、生命周期样式、业务图形和普通 IN／OUT 文本仍属于通用工具行。
**对等**指同一受支持输入产生由现有组件、组装与浏览器证据固定的用户可见结果和交互，不要求相同的中间 TypeScript 类型或内部函数调用。
@@ -301,7 +301,7 @@ Client terminal model 从工具名称、调用参数、结果 content、error
| 输入 | 保持的结果 |
|---|---|
| 标准 `bash`／`pwsh` 前台 running | terminal prompt、description、cwd、running 状态 |
-| 标准前台 success | terminal output、exit code/signal、成功或失败状态点 |
+| 标准前台 success | terminal output、exit code/signal 与结算状态呈现 |
| `run_in_background:true` | Generic 行与原始结果 |
| 工具执行 error | Generic IN／OUT 与错误摘要 |
| persistent `bash`／`pwsh` running | terminal prompt |
diff --git a/.agents/notes/implemented/architecture/2026-09-05-shared-client-control-primitives.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-05-shared-client-control-primitives.i18n.yaml
index 89a705592d..55f30d278a 100644
--- a/.agents/notes/implemented/architecture/2026-09-05-shared-client-control-primitives.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-09-05-shared-client-control-primitives.i18n.yaml
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-05-shared-client-control-primitives.md
-2026-09-05-shared-client-control-primitives.md: 14128497cf4152659a62136cbdeb74b92ee3fbf0
-2026-09-05-shared-client-control-primitives.zh.md: 66268b48f81887181c3981bf89ead30eb74250af
+2026-09-05-shared-client-control-primitives.md: db8cb9a8bc515918867b27b216fe8edb50c392db
+2026-09-05-shared-client-control-primitives.zh.md: 6d4b04a21bf224eaa32b5fbdfb2bf1c3a2cd804d
diff --git a/.agents/notes/implemented/architecture/2026-09-05-shared-client-control-primitives.md b/.agents/notes/implemented/architecture/2026-09-05-shared-client-control-primitives.md
index 14128497cf..db8cb9a8bc 100644
--- a/.agents/notes/implemented/architecture/2026-09-05-shared-client-control-primitives.md
+++ b/.agents/notes/implemented/architecture/2026-09-05-shared-client-control-primitives.md
@@ -18,15 +18,15 @@ Neither half of the fix was available to an author. No checklist told them to lo
`Switch` is the two-state toggle, at the 36×20 track and 16px thumb `ui-settings-plugins` established. `label` is required and has no default, so a render site cannot omit the accessible name; `title` carries a lock reason where a deployment disables the control.
-`StateDotState` gains `idle`, a static grey dot in the same halo-and-core construction as `done`, `warning`, and `error`. The plugin inventory's `pending` and `unloading` phases mean no activity is in progress, and the four existing states had no member for that; without `idle` those two phases lose their marker entirely. The addition is safe for the eight packages already consuming `StateDot` because each of them produces a `StateDotState` from its own closed status union and none switches over `StateDotState` itself.
+`StateDotState` includes `idle` for a tracked subject with no activity in progress. The plugin inventory's `pending` and `unloading` phases need that semantic member; without it those two phases lose their marker entirely. The five-state union remains safe for consumers because each package produces a `StateDotState` from its own closed status union and none switches over `StateDotState` itself. The current solid-dot palette and rotating `ongoing` loader are owned by the later [StateDot visual language decision](../feature/2026-09-17-state-dot-visual-language.md).
-**The component catalog in the `ui-primitives` README is what makes the rule usable.** It lists every exported component with its purpose and the case it is wrong for, and it names the three pairs that are easy to confuse: `Tag` against `Pill`, `DisclosureRow` against card-shaped disclosure, and the package-internal `FoldToggle` against the exported surface. `Pill` is the selectable capsule button — it takes `active` and `onClick` and drives view switchers and filters; `Tag` is the read-only badge and takes neither. `Pill`'s own header comment previously advertised itself for badges, which contradicted the catalog, and no longer does.
+**The component catalog in the `ui-primitives` README is what makes the rule usable.** It lists every exported component with its purpose and the case it is wrong for, and it names the three pairs that are easy to confuse: `Tag` against `Pill`, `DisclosureRow` against card-shaped disclosure, and the package-internal `FoldToggle` against the exported surface. `Pill` is the selectable capsule button — it takes `active` and `onClick` and drives view switchers and filters; `Tag` is the read-only badge and takes neither. The component comments use the same distinction.
The rule is stated in [packages/client/AGENTS.md](../../../../packages/client/AGENTS.md) as the first step of the new-component checklist, and [docs/web-styling.md](../../../../docs/web-styling.md) points at the catalog so an author arriving from the styling side reaches it too.
## Finding the duplicates
-A name-based search undercounts. `.badge`, `.tag`, `.chip`, and `.configTag` miss a capsule named for its role rather than its appearance — `PluginCard`'s unsaved marker is `.pending`, and its rule was byte-identical to the badge two files away. What finds them is the geometry: a CSS Modules rule carrying both `border-radius: 999px` and `padding: 1px 8px`. After this change that signature matches exactly two rules: `Tag` itself and the broken badge below. The unsaved marker keeps only a `flex: none` placement class, which the signature no longer matches.
+A name-based search undercounts. `.badge`, `.tag`, `.chip`, and `.configTag` miss a capsule named for its role rather than its appearance — `PluginCard`'s unsaved marker is `.pending`. Geometry is the reliable probe: search CSS Modules rules carrying both `border-radius: 999px` and `padding: 1px 8px`. That signature belongs to `Tag` and the deliberately local broken badge below; the unsaved marker keeps only its `flex: none` placement class.
## What stays local
@@ -34,7 +34,6 @@ A name-based search undercounts. `.badge`, `.tag`, `.chip`, and `.configTag` mis
A mechanical search groups these controls with the promoted three. They stay in their own packages, because the grouping is superficial:
- **`ui-trajectory`'s toolbar toggle** carries `role="switch"` but is an 88px labelled control with an inline track, and it currently renders `hidden`. It is not the same widget as `Switch`.
-- **`ui-schedule`'s status dot** is a static blue dot for the next run that turns amber when overdue. `StateDot` has no static blue — its only blue is `ongoing`, an animated pixel matrix — and one animation per row in a schedule list would misstate the meaning as well as the appearance.
- **`ui-plan`'s mode chip** and **`ui-conversation`'s `ReferenceChip`** are interactive: the first is a warning-toned button with hover, focus, disabled, and a close affordance; the second is a Lexical atom node with its own truncation. Neither is a read-only badge.
- **`ui-trajectory`'s cell tag** and **`ui-user-questions`'s recommendation badge** use their own geometry — a 6px radius at table density, and a 6px radius at 600 weight on the sidebar accent. Forcing either into the capsule baseline would change a deliberate design, not an accidental one.
- **`TerminalBlock`'s exit-status pill** stays a static `Pill`. It sits on a 24px command line at the pill's own geometry, and `Tag`'s 11px capsule would not fit that row. The read-only/selectable split is the usual guide, but size decides this one, and the catalog says so.
@@ -52,7 +51,7 @@ A mechanical search groups these controls with the promoted three. They stay in
**A two-axis `variant × tone` API for `Tag`.** Rejected. Three variants against six tones describes eighteen combinations of which eight ship, and it lets a caller request combinations with no defined appearance. The flat eight-member union maps each value to exactly one shipped appearance.
-**Rendering no dot for `pending` and `unloading` instead of adding `idle`.** Rejected. Those rows show a grey dot today, and dropping it would remove information from the inventory in a change whose purpose is to consolidate presentation.
+**Rendering no dot for `pending` and `unloading` instead of adding `idle`.** Rejected. Those phases need a compact inactive or transitional marker; dropping it would remove information from the inventory in a change whose purpose is to consolidate presentation.
**Putting the reuse rule in the root `AGENTS.md`.** Rejected. The rule governs `packages/client` alone, and the root file sits exactly at its 1950-word ceiling in `scripts/doc-budgets.manifest.json`, so stating it there would have to displace an unrelated repository-wide rule.
@@ -60,15 +59,15 @@ A mechanical search groups these controls with the promoted three. They stay in
`Tag`, `Switch`, and the extended `StateDot` carry component specs in `packages/client/ui-primitives/tests`, inside the per-file 100% coverage gate. `StateDot`'s palette is pinned by reading its stylesheet: CSS Modules resolve to class-name maps in the component suites, so a state whose color rule is missing renders on the inherited color and no render assertion notices.
-The migrated render sites keep their existing package specs unchanged. The web e2e goldens are ARIA snapshots, and the full replayed web suite passes without re-recording, because the migration preserves every role, accessible name, and state — `Switch` keeps `role="switch"` with `aria-checked`, and the inventory's phase dot keeps its `role="img"` name on a wrapper, since `StateDot` is `aria-hidden`.
+The migrated render sites keep package specs for their role, accessible name, state mapping, and interaction. Web ARIA snapshots cover the assembled presentations — `Switch` keeps `role="switch"` with `aria-checked`, and the inventory's phase dot keeps its `role="img"` name on a wrapper because `StateDot` is `aria-hidden`.
-That is also the limit of the automated evidence. No gate in this repository compares pixels, so the capsule geometry, the dot halo, and the font-weight change are verified by review against the light and dark screenshots in the pull request.
+The component and stylesheet specs pin the capsule geometry, StateDot artwork, animation, tokens, and font weight; Web snapshots pin accessible structure. Manual visual inspection remains responsible for the rendered result across themes.
## Consequences
- A new client control now has one place to check and one place to add, and the catalog makes the check a single file read rather than a `grep` over forty exports.
- `TagTone` is eight members wide because eight appearances shipped. Adding a ninth requires a render site that needs it, not a symmetry argument.
-- The plugin inventory's tags change from a 5px rectangle to a capsule, and the disabled tag's fill moves from `--dsw-alias-bg-layer-1` to the `neutral` tone's `--dsw-alias-bg-module-platform`, which is a visible grey where it used to be near-transparent. Its phase dots gain a halo and animate through `loading` and `unloading`. The unconfigured-secret badge in the plugin settings fields moves from 400 to the baseline 500 weight. These are deliberate visual changes, recorded here so a later reader does not treat them as regressions.
-- The migration removes a literal `#b45309`. The plugin inventory's `conditional` tag read `var(--dsw-alias-state-warning-primary, #b45309)`, and no such alias exists — the real token is `--dsw-alias-state-warn-primary` — so both themes had been painting the hardcoded fallback that [docs/web-styling.md](../../../../docs/web-styling.md) forbids.
+- The plugin inventory uses capsule tags; the disabled tag uses the `neutral` tone's visible `--dsw-alias-bg-module-platform` fill. Its phase markers use the shared `StateDot`, including the rotating loader for active transitions. The unconfigured-secret badge in the plugin settings fields uses the baseline 500 weight.
+- The plugin inventory palette contains no literal `#b45309`. The conditional tag uses the real `--dsw-alias-state-warn-primary` token rather than the nonexistent `--dsw-alias-state-warning-primary` alias and its hardcoded fallback.
- The rule cannot be checked mechanically. A future author can still copy a control, and only review will catch it. That is the accepted cost of not gating: the alternative rejects legitimate work, and the packages that stay local above are proof that legitimate work exists.
-- `ui-primitives` grows two components that one package each consumes today. The switch in particular is a single-consumer primitive, promoted because it is a general control and because the plugin-management work already in flight will adopt it rather than adding two further copies.
+- `Tag` and `Switch` are shared across settings and preset packages; future consumers extend these primitives only when an existing prop cannot express a deliberate difference.
diff --git a/.agents/notes/implemented/architecture/2026-09-05-shared-client-control-primitives.zh.md b/.agents/notes/implemented/architecture/2026-09-05-shared-client-control-primitives.zh.md
index 66268b48f8..6d4b04a21b 100644
--- a/.agents/notes/implemented/architecture/2026-09-05-shared-client-control-primitives.zh.md
+++ b/.agents/notes/implemented/architecture/2026-09-05-shared-client-control-primitives.zh.md
@@ -18,15 +18,15 @@ Status: implemented
`Switch` 是双态开关，采用 `ui-settings-plugins` 确立的 36×20 轨道与 16px 滑块。`label` 必填且没有默认值，渲染点无法省略无障碍名称；`title` 在部署禁用该控件时承载锁定原因。
-`StateDotState` 增加 `idle`，一个静态灰点，与 `done`、`warning`、`error` 采用同样的光晕加实心核结构。插件清单的 `pending` 与 `unloading` 相位表示没有进行中的活动，原有四态没有对应成员；没有 `idle`，这两个相位会彻底失去标记。这次增补对已经消费 `StateDot` 的八个包是安全的：它们各自从自己的闭合状态联合**产生** `StateDotState`，没有任何一个对 `StateDotState` 本身做 switch。
+`StateDotState` 包含 `idle`，表示一个被跟踪的对象当前没有进行中的活动。插件清单的 `pending` 与 `unloading` 相位需要这个语义成员；没有 `idle`，这两个相位会彻底失去标记。五态联合对消费方保持安全，因为每个包都从自己的闭合状态联合**产生** `StateDotState`，没有任何一个对 `StateDotState` 本身做 switch。当前的纯色点配色与旋转 `ongoing` loading 由后续的 [StateDot 视觉语言决策](../feature/2026-09-17-state-dot-visual-language.zh.md)负责。
-**`ui-primitives` README 里的组件目录，是这条规则得以可用的前提。** 它列出每个导出组件的用途，以及它不适用的场合，并点名三组容易混淆的配对：`Tag` 与 `Pill`、`DisclosureRow` 与卡片式折叠、包内的 `FoldToggle` 与对外导出面。`Pill` 是可选中的胶囊按钮——它接受 `active` 与 `onClick`，用于视图切换与筛选器；`Tag` 是只读徽章，两者都不接受。`Pill` 自己的头注释此前把自身宣传为可用作徽章，与目录互相矛盾，现已改掉。
+**`ui-primitives` README 里的组件目录，是这条规则得以可用的前提。** 它列出每个导出组件的用途，以及它不适用的场合，并点名三组容易混淆的配对：`Tag` 与 `Pill`、`DisclosureRow` 与卡片式折叠、包内的 `FoldToggle` 与对外导出面。`Pill` 是可选中的胶囊按钮——它接受 `active` 与 `onClick`，用于视图切换与筛选器；`Tag` 是只读徽章，两者都不接受。组件注释使用同一套区分。
规则写在 [packages/client/AGENTS.md](../../../../packages/client/AGENTS.md) 新组件清单的第一步，[docs/web-styling.md](../../../../docs/web-styling.zh.md) 指向该目录，让从样式一侧进来的作者也能到达。
## 如何找出重复
-按名字搜会漏。`.badge`、`.tag`、`.chip`、`.configTag` 找不到以角色而非外观命名的胶囊——`PluginCard` 的未保存标记叫 `.pending`，而它的规则与两个文件之外的徽章逐字节相同。能找出它们的是几何特征：同时带有 `border-radius: 999px` 与 `padding: 1px 8px` 的 CSS Modules 规则。本次改动后，这个特征恰好匹配两条规则：`Tag` 本身与下面那个损坏徽章。未保存标记只剩一个 `flex: none` 布局类，已不再匹配该特征。
+按名字搜会漏。`.badge`、`.tag`、`.chip`、`.configTag` 找不到以角色而非外观命名的胶囊——`PluginCard` 的未保存标记叫 `.pending`。几何特征才是可靠探针：搜索同时带有 `border-radius: 999px` 与 `padding: 1px 8px` 的 CSS Modules 规则。这个特征属于 `Tag` 与下面那个有意保留在原包的损坏徽章；未保存标记只保留自己的 `flex: none` 布局类。
## 保留在原包的控件
@@ -34,7 +34,6 @@ Status: implemented
机械搜索会把下面这些控件归到被提升的那三类里。它们留在各自的包中，因为那种归并只是表面相似：
- **`ui-trajectory` 的工具栏开关**带 `role="switch"`，但它是 88px 宽的带标签控件、轨道内联，而且当前渲染为 `hidden`。它和 `Switch` 不是同一个部件。
-- **`ui-schedule` 的状态点**是表示下次运行的静态蓝点，逾期转为琥珀色。`StateDot` 没有静态蓝——它唯一的蓝是 `ongoing`，一个动画像素方阵——日程列表里每行一个动画，既说错了含义也说错了观感。
- **`ui-plan` 的模式 chip** 与 **`ui-conversation` 的 `ReferenceChip`** 都是可交互的：前者是警告色调的按钮，带 hover、focus、disabled 与关闭操作；后者是带自有截断逻辑的 Lexical 原子节点。两者都不是只读徽章。
- **`ui-trajectory` 的单元格 tag** 与 **`ui-user-questions` 的推荐徽章**使用各自的几何——一个是表格密度下的 6px 圆角，一个是侧栏强调色上 600 字重的 6px 圆角。把它们塞进胶囊基准，改掉的是有意的设计，不是意外的分歧。
- **`TerminalBlock` 的退出状态胶囊**保持为静态 `Pill`。它落在 24px 的命令行上、用的是 pill 自己的几何，`Tag` 的 11px 胶囊放不进那一行。只读与可选中的区分是通常的判据，但这一处由尺寸决定，目录里也是这么写的。
@@ -52,7 +51,7 @@ Status: implemented
**给 `Tag` 设计 `variant × tone` 双轴 API。** 否决。三个 variant 乘六个 tone 描述十八种组合，其中八种会发布，而且它允许调用方请求没有定义外观的组合。扁平的八成员联合把每个值映射到恰好一种已发布外观。
-**让 `pending` 与 `unloading` 不渲染点，而不是新增 `idle`。** 否决。这两行今天显示灰点，在一个目的是统一呈现的改动里把它删掉，等于从清单中拿走信息。
+**让 `pending` 与 `unloading` 不渲染点，而不是新增 `idle`。** 否决。这些阶段需要紧凑的未活动或过渡标记；在一个目的是统一呈现的改动里把它删掉，等于从清单中拿走信息。
**把复用规则写进根 `AGENTS.md`。** 否决。这条规则只管 `packages/client`，而根文件正好处在 `scripts/doc-budgets.manifest.json` 给它的 1950 词上限上，写在那里就必须挤掉一条不相干的仓库级规则。
@@ -60,15 +59,15 @@ Status: implemented
`Tag`、`Switch` 与扩展后的 `StateDot` 在 `packages/client/ui-primitives/tests` 中各有组件测试，处于每文件 100% 覆盖率门禁之内。`StateDot` 的配色通过读取其样式表来钉住：CSS Modules 在组件测试里解析为类名映射，因此某个状态缺了配色规则时会落到继承色上，而任何渲染断言都不会察觉。
-迁移后的渲染点保留各自包内原有的测试，未作改动。web e2e 的 golden 是 ARIA 快照，完整的 replay web 套件无需重录即可通过，因为这次迁移保住了每一个 role、无障碍名称与状态——`Switch` 保留带 `aria-checked` 的 `role="switch"`，而由于 `StateDot` 是 `aria-hidden`，插件清单的相位点把 `role="img"` 名称保留在外层包裹元素上。
+迁移后的渲染点保留包级测试，覆盖 role、无障碍名称、状态映射与交互。Web ARIA 快照覆盖装配后的呈现——`Switch` 保留带 `aria-checked` 的 `role="switch"`，而由于 `StateDot` 是 `aria-hidden`，插件清单的相位点把 `role="img"` 名称保留在外层包裹元素上。
-这同时也是自动化证据的边界。本仓库没有任何门禁比较像素，因此胶囊几何、状态点光晕与字重变化，只能由评审对照 PR 中的明暗两套截图来确认。
+组件与样式表测试固定胶囊几何、StateDot 图稿、动画、token 与字重；Web 快照固定无障碍结构。明暗主题下的最终渲染仍由人工视觉检查负责。
## Consequences
- 新的客户端控件现在有一处可查、一处可加，而目录把这次查询变成读一个文件，而不是在四十多个导出上 `grep`。
- `TagTone` 有八个成员，因为发布了八种外观。加第九个需要一个真的需要它的渲染点，而不是一个对称性论证。
-- 插件清单的标签从 5px 矩形变为胶囊，其中"已停用"标签的底色从 `--dsw-alias-bg-layer-1` 变为 `neutral` 色调的 `--dsw-alias-bg-module-platform`，由近乎透明变成可见的灰底。相位点获得光晕，并在 `loading` 与 `unloading` 两个相位动画。插件设置字段中"未配置"徽章的字重从 400 改为基准的 500。这些都是有意的视觉变更，记录在此，以免后来的读者把它们当成回归。
-- 本次迁移移除了一个 `#b45309` 字面量。插件清单的 `conditional` 标签写的是 `var(--dsw-alias-state-warning-primary, #b45309)`，而这个别名并不存在——真正的 token 是 `--dsw-alias-state-warn-primary`——所以明暗两套主题一直在绘制那个被 [docs/web-styling.md](../../../../docs/web-styling.zh.md) 禁止的硬编码兜底色。
+- 插件清单使用胶囊标签；"已停用"标签使用 `neutral` 色调下可见的 `--dsw-alias-bg-module-platform` 填充。相位标记使用共享 `StateDot`，活动转换采用旋转 loading。插件设置字段中的"未配置"徽章使用基准 500 字重。
+- 插件清单调色板不含 `#b45309` 字面量。`conditional` 标签使用真实的 `--dsw-alias-state-warn-primary` token，而不是不存在的 `--dsw-alias-state-warning-primary` 别名及其硬编码兜底色。
- 这条规则无法被机械检查。将来的作者仍然可以复制一个控件，只有评审能拦住。这是不设门禁所接受的代价：另一条路会拒绝正当的工作，而上面那份保留在原包的清单就是正当工作确实存在的证据。
-- `ui-primitives` 多出两个各自只有一个消费方的组件。开关尤其如此，提升它是因为它是一个通用控件，也因为正在进行中的插件管理工作会采用它，而不是再加两份拷贝。
+- `Tag` 与 `Switch` 由多个设置和预设包共享；只有现有 prop 无法表达明确差异时，后续消费方才扩展这些原语。
diff --git a/.agents/notes/implemented/architecture/2026-09-05-sidebar-tab-types-and-navigation.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-05-sidebar-tab-types-and-navigation.i18n.yaml
index 2ccfc07ac8..577fbe18d0 100644
--- a/.agents/notes/implemented/architecture/2026-09-05-sidebar-tab-types-and-navigation.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-09-05-sidebar-tab-types-and-navigation.i18n.yaml
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-05-sidebar-tab-types-and-navigation.md
-2026-09-05-sidebar-tab-types-and-navigation.md: 834a26e55f87e5db54d57f06fec592e4fdb9f61c
-2026-09-05-sidebar-tab-types-and-navigation.zh.md: 9884db9eef49162e8883c390dd71bdbf9d45489f
+2026-09-05-sidebar-tab-types-and-navigation.md: 599ce36ed4bb1dfc2cce063a461903e1a4aeb40e
+2026-09-05-sidebar-tab-types-and-navigation.zh.md: e4e8de5a389fea77aae705d63cc4fb16f88af647
diff --git a/.agents/notes/implemented/architecture/2026-09-05-sidebar-tab-types-and-navigation.md b/.agents/notes/implemented/architecture/2026-09-05-sidebar-tab-types-and-navigation.md
index 834a26e55f..599ce36ed4 100644
--- a/.agents/notes/implemented/architecture/2026-09-05-sidebar-tab-types-and-navigation.md
+++ b/.agents/notes/implemented/architecture/2026-09-05-sidebar-tab-types-and-navigation.md
@@ -36,7 +36,7 @@ interface SidebarRightTabDefinition {
`priority` is one of three literal bands, spelled as strings so that a type from another package needs no runtime import: `extension` is the band of a type from outside the product and the highest, so a type that declares nothing outranks every viewer shipped here; `builtin` is the ordinary band for shipped types; `fallback` is the plain-content position that anything more specific should beat, which VS Code's text editor holds implicitly and our text preview holds explicitly. `candidates(address)` returns every type whose globs match and whose `canOpen` does not veto, ranked by band, then by the length of the longest pattern that matched, then by registration order. `claim(address, kind?)` takes the best candidate, or the named kind's type in force when the caller overrides (its globs are not consulted; naming the type is the decision), and throws for an address nothing will open — a wiring mistake, not a user error. `get(kind)` returns the type in force; `entries()` and `guide()` list the types and their guide boxes in force; `subscribe` observes changes.
-`title(address)`, `guide[].title()`, and optional `guide[].description()` are thunks read on every use, so a language change needs no re-registration. [Guide start page and stat pill refinements](../feature/2026-09-10-guide-start-page-and-stat-pill-refinements.md) owns the current description visibility and fallback-glyph rules. The registry itself is a plain object provided at `apply`'s top level **without** `Service.tracker`: a tracker would rebind `this.ctx` to the caller's context, and a cross-package `register()` would then add its effect to the caller's fiber while that fiber is the active scope, stalling the browser boot with no error.
+`title(address)`, `guide[].title()`, and optional `guide[].description()` are thunks read on every use, so a language change needs no re-registration. The [Sidebar README](../../../../packages/client/ui-sidebar-right/README.md#the-guide) defines description visibility and fallback-glyph rules. The registry itself is a plain object provided at `apply`'s top level **without** `Service.tracker`: a tracker would rebind `this.ctx` to the caller's context, and a cross-package `register()` would then add its effect to the caller's fiber while that fiber is the active scope, stalling the browser boot with no error.
### Bodies and titles: keyed Slot seats under the definition's `id`
diff --git a/.agents/notes/implemented/architecture/2026-09-05-sidebar-tab-types-and-navigation.zh.md b/.agents/notes/implemented/architecture/2026-09-05-sidebar-tab-types-and-navigation.zh.md
index 9884db9eef..e4e8de5a38 100644
--- a/.agents/notes/implemented/architecture/2026-09-05-sidebar-tab-types-and-navigation.zh.md
+++ b/.agents/notes/implemented/architecture/2026-09-05-sidebar-tab-types-and-navigation.zh.md
@@ -36,7 +36,7 @@ interface SidebarRightTabDefinition {
`priority` 是三个字面量档位之一，写成字符串，好让别的包的类型不需要任何运行时引入：`extension` 是来自产品之外的类型的档位也是最高档，所以什么都不声明的类型压过这里随包交付的每个查看器；`builtin` 是随包类型的常规档；`fallback` 是任何更具体的东西都应压过的纯内容位置，VS Code 的文本编辑器隐含地占据它，我们的文本预览明确地占据它。`candidates(address)` 返回 glob 命中且 `canOpen` 未否决的每个类型，按档位、再按命中的最长 pattern 长度、再按注册顺序排序。`claim(address, kind?)` 取最佳候选，或在调用方指定时取该 kind 生效的类型（不查它的 glob；点名即决定），对无人愿开的地址抛错——这是接线错误，不是用户错误。`get(kind)` 返回生效类型；`entries()` 与 `guide()` 列出生效类型及其引导入口；`subscribe` 观察变化。
-`title(address)`、`guide[].title()` 与可选的 `guide[].description()` 都是每次使用时重读的 thunk，语言切换无需重新注册。[引导起始页与统计 pill 的细化](../feature/2026-09-10-guide-start-page-and-stat-pill-refinements.zh.md)负责当前的描述显示与兜底图标规则。注册表本身是 `apply` 顶层提供的普通对象，**不带** `Service.tracker`：tracker 会把 `this.ctx` 重绑到调用方上下文，跨包 `register()` 就会在调用方 fiber 仍是活动作用域时往它上加 effect，浏览器启动会无声卡死。
+`title(address)`、`guide[].title()` 与可选的 `guide[].description()` 都是每次使用时重读的 thunk，语言切换无需重新注册。[Sidebar README](../../../../packages/client/ui-sidebar-right/README.zh.md#the-guide)定义描述显示与兜底图标规则。注册表本身是 `apply` 顶层提供的普通对象，**不带** `Service.tracker`：tracker 会把 `this.ctx` 重绑到调用方上下文，跨包 `register()` 就会在调用方 fiber 仍是活动作用域时往它上加 effect，浏览器启动会无声卡死。
### 正文与标题：按定义 `id` keyed 的 Slot 坑位
diff --git a/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.i18n.yaml
index 60e03dbff7..414fda0806 100644
--- a/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.i18n.yaml
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-08-document-preview-operations.md
-2026-09-08-document-preview-operations.md: 980e2e443db13d6a956d554172bc765a5c11b435
-2026-09-08-document-preview-operations.zh.md: 364ef9ced6f8d98313f9bc287588c98daa408837
+2026-09-08-document-preview-operations.md: be3a835a6296cb28d9a90c5c5e8b9bf7367598c2
+2026-09-08-document-preview-operations.zh.md: efb87e16cc126001c1a6eb2bf938124d7e00044a
diff --git a/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.md b/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.md
index 980e2e443d..be3a835a62 100644
--- a/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.md
+++ b/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.md
@@ -18,7 +18,7 @@ Readable files use `dsh-resource://file/session//`. The path ma
[Document Preview](../../../../packages/client/ui-sidebar-documentpreview/README.md) owns format selection and loading policy. Metadata registers with `ctx.documentPreviews`; components register separately into the keyed `sidebar.right.tab.document` Slot. Extension registrations precede builtins, then longer suffixes and registration order decide. The toolbar lists supported alternatives and remembers a manual choice per tab. Plain text remains available for unknown extensions and text-compatible renderers. Registered binary suffixes determine text compatibility independently of loading mode; HTML and SVG remain outside those suffixes and retain source viewing. A single candidate renders no viewer control. Registered binary suffixes omit plain text; known binary suffixes without a renderer show an unsupported state without reading the file ([sidebar preview polish](../feature/2026-09-11-sidebar-document-preview-polish.md)). The child receives accumulated text or complete native bytes, the original resource address, and the standard `useResource` and `useTabInfo` hooks. Preview calls existing `read`, `readAll`, and `readRelated` through ordinary injection and decodes bytes in its own `rpc.ts`. Refresh remains per tab, with no resource reload, shared `changed` acknowledgement, extra resource wrapper, or content Session.
-Markdown and code reuse the incremental primitives with cumulative paged text. HTML, PDF, and images read complete `Uint8Array` data; Host transport remains base64. Published buffers are borrowed read-only and never persist into layout or Session JSON. PDF.js runs in an owned Worker with version-matched bundled font and decoder data, and copies input before transfer to preserve Preview's retained buffer. HTML runs in a Blob iframe with `sandbox="allow-scripts"`, without same-origin, popup, form, download, or top-navigation privileges. The browser retains its normal external-network rules. Bounded static local JS/CSS reads stay in the parent; the opaque frame creates its own asset Blobs, because it cannot load parent-origin Blobs. PNG, JPEG, GIF, WebP, BMP, ICO, and SVG use image-specific Blob URLs in an `` static-image context. An image wider than the pane scales down to its width at its aspect ratio; a smaller image keeps its intrinsic CSS-pixel dimensions centred by auto margins, and a taller image extends the shared scroller's vertical range ([sidebar preview polish](../feature/2026-09-11-sidebar-document-preview-polish.md)). The renderer provides no zoom or drag-to-pan. SVG markup never enters the application DOM or an iframe, so scripts remain inert and cannot reach the parent page. Replacing HTML or an image revokes its root Blob URL.
+Markdown and code reuse the incremental primitives with cumulative paged text. HTML, PDF, and images read complete `Uint8Array` data; Host transport remains base64. Published buffers are borrowed read-only and never persist into layout or Session JSON. PDF.js runs in an owned Worker with version-matched bundled font and decoder data, and copies input before transfer to preserve Preview's retained buffer. With [Developer tools](../feature/2026-09-17-developer-tools-settings.md) enabled, HTML runs in a Blob iframe with `sandbox="allow-scripts"`, without same-origin, popup, form, download, or top-navigation privileges. The browser retains its normal external-network rules. Bounded static local JS/CSS reads stay in the parent; the opaque frame creates its own asset Blobs, because it cannot load parent-origin Blobs. PNG, JPEG, GIF, WebP, BMP, ICO, and SVG use image-specific Blob URLs in an `` static-image context. An image wider than the pane scales down to its width at its aspect ratio; a smaller image keeps its intrinsic CSS-pixel dimensions centred by auto margins, and a taller image extends the shared scroller's vertical range ([sidebar preview polish](../feature/2026-09-11-sidebar-document-preview-polish.md)). The renderer provides no zoom or drag-to-pan. SVG markup never enters the application DOM or an iframe, so scripts remain inert and cannot reach the parent page. Replacing HTML or an image revokes its root Blob URL.
PDF.js's official TextLayerBuilder owns selection boundaries and copy normalization over the width-fitted canvas, with shared page cleanup and a component-owned resize observer. Responsive sizing uses the CSS `scale` property independently of PDF.js's page rotation and translation transforms. Its end-of-content marker and stacking rules constrain selection in blank regions; line-break highlighting is suppressed. Per-page cancellation uses the builder's cleanup rather than aborting the first page's signal, because the official selection listeners are shared across pages.
diff --git a/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.zh.md b/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.zh.md
index 364ef9ced6..efb87e16cc 100644
--- a/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.zh.md
+++ b/.agents/notes/implemented/architecture/2026-09-08-document-preview-operations.zh.md
@@ -18,7 +18,7 @@ Document Preview 将资源观察与内容读取分开。[资源模型](2026-09-0
[Document Preview](../../../../packages/client/ui-sidebar-documentpreview/README.zh.md) 负责格式选择和加载策略。元数据通过 `ctx.documentPreviews` 注册；组件单独注册到 keyed `sidebar.right.tab.document` Slot。扩展注册优先于内置注册，其次比较后缀长度和注册顺序。工具栏列出受支持的候选，按 tab 记住手动选择。未知扩展名及文本兼容的渲染器仍可使用纯文本。文本兼容性由注册的二进制后缀决定，与加载方式无关；HTML 和 SVG 不属于二进制后缀，保留源码查看。只有一个候选时不显示查看器控件。注册声明为二进制的后缀不提供纯文本；已知二进制后缀没有注册渲染器时不发起读取，并显示不支持预览的空态（[侧边栏预览打磨](../feature/2026-09-11-sidebar-document-preview-polish.zh.md)）。子组件收到累积文本或完整原生字节、原始资源地址，以及标准 `useResource` 和 `useTabInfo` 钩子。Preview 经普通注入调用既有 `read`、`readAll` 与 `readRelated`，在自己的 `rpc.ts` 解码字节。刷新仍按 tab 独立进行，不引入资源 reload、共享 `changed` 确认、额外资源包装层或内容 Session。
-Markdown 和代码通过累积的分页文本复用增量渲染原语。HTML、PDF 和图片读取完整 `Uint8Array` 数据；Host 传输保持 base64。发布后的缓冲区只读借用，绝不持久化进布局或 Session JSON。PDF.js 在自有 Worker 中运行，字体和解码数据以相同版本随包发布，转移输入前先复制，以保留 Preview 的缓冲区。HTML 在 Blob iframe 中运行，设置 `sandbox="allow-scripts"`，不授予同源、弹窗、表单、下载或顶层导航权限。浏览器保持正常的外部网络规则。有上限的静态本地 JS/CSS 读取由父页面负责；不透明源 iframe 创建自己的资源 Blob，因为它不能加载父源创建的 Blob。PNG、JPEG、GIF、WebP、BMP、ICO 和 SVG 使用图片专用 Blob URL，在 `` 静态图片上下文中渲染。比面板宽的图片按纵横比缩小到面板宽度；较小的图片保留固有 CSS 像素尺寸并由 auto margin 居中，较高的图片扩展共享滚动区的纵向范围（[侧边栏预览打磨](../feature/2026-09-11-sidebar-document-preview-polish.zh.md)）。渲染器不提供缩放或拖拽平移。SVG 标记绝不进入应用 DOM 或 iframe，因此脚本保持不可执行，也无法访问父页面。替换 HTML 或图片时会撤销其根 Blob URL。
+Markdown 和代码通过累积的分页文本复用增量渲染原语。HTML、PDF 和图片读取完整 `Uint8Array` 数据；Host 传输保持 base64。发布后的缓冲区只读借用，绝不持久化进布局或 Session JSON。PDF.js 在自有 Worker 中运行，字体和解码数据以相同版本随包发布，转移输入前先复制，以保留 Preview 的缓冲区。开启[开发者工具](../feature/2026-09-17-developer-tools-settings.zh.md)时，HTML 在 Blob iframe 中运行，设置 `sandbox="allow-scripts"`，不授予同源、弹窗、表单、下载或顶层导航权限。浏览器保持正常的外部网络规则。有上限的静态本地 JS/CSS 读取由父页面负责；不透明源 iframe 创建自己的资源 Blob，因为它不能加载父源创建的 Blob。PNG、JPEG、GIF、WebP、BMP、ICO 和 SVG 使用图片专用 Blob URL，在 `` 静态图片上下文中渲染。比面板宽的图片按纵横比缩小到面板宽度；较小的图片保留固有 CSS 像素尺寸并由 auto margin 居中，较高的图片扩展共享滚动区的纵向范围（[侧边栏预览打磨](../feature/2026-09-11-sidebar-document-preview-polish.zh.md)）。渲染器不提供缩放或拖拽平移。SVG 标记绝不进入应用 DOM 或 iframe，因此脚本保持不可执行，也无法访问父页面。替换 HTML 或图片时会撤销其根 Blob URL。
PDF.js 官方 TextLayerBuilder 在适配宽度的 canvas 上负责选择边界和复制规范化，共享页面清理，并使用由组件拥有的 resize observer。响应式尺寸适配使用独立的 CSS `scale` 属性，与 PDF.js 的页面旋转和平移变换组合。其内容结束标记和堆叠规则限制空白区域中的选择；换行高亮被抑制。逐页取消使用 builder 的清理操作，而不 abort 第一页的信号，因为官方选择监听器跨页面共享。
diff --git a/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.i18n.yaml
index e4d4d80da4..97cdb07d3f 100644
--- a/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.i18n.yaml
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.md
-2026-09-09-workspace-file-read-authority.md: 35ac15f5e463910be3b3a0cfe7b80dc69c129ad3
-2026-09-09-workspace-file-read-authority.zh.md: 559a59af0bfa988ff880fad22470397e4e74f296
+2026-09-09-workspace-file-read-authority.md: d1a5b9d9634381cb74b17651c67f2b701402ff1c
+2026-09-09-workspace-file-read-authority.zh.md: f8b0fae4325a90548c6b9dc33ac46b17248b04e7
diff --git a/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.md b/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.md
index 35ac15f5e4..d1a5b9d963 100644
--- a/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.md
+++ b/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.md
@@ -14,7 +14,7 @@ Workspace Files serves both file content and workspace navigation. Applying work
`list` and `changes` remain workspace-scoped because they expose workspace navigation and observation rather than a named file read. `list` rejects a directory outside the root, and `changes` filters observations through the backend's workspace-containment predicate.
-`readRelated` resolves a relative path from the base file's directory. A `..` path may therefore read JavaScript or CSS outside the workspace when the Session backend permits it. Document Preview packages bounded, statically declared local scripts and stylesheets into an HTML Blob iframe with `sandbox="allow-scripts"`; the opaque origin blocks parent access, but the browser retains normal network access. This exposure is an intentional security trade-off for rendering static generated HTML.
+`readRelated` resolves a relative path from the base file's directory. A `..` path may therefore read JavaScript or CSS outside the workspace when the Session backend permits it. With [Developer tools](../feature/2026-09-17-developer-tools-settings.md) enabled, Document Preview packages bounded, statically declared local scripts and stylesheets into an HTML Blob iframe with `sandbox="allow-scripts"`; the opaque origin blocks parent access, but the browser retains normal network access. This exposure is an intentional security trade-off for rendering static generated HTML.
The [Workspace Files service](2026-09-05-workspace-files-service.md) owns paging, file checks, listing, and observation. [Document Preview](2026-09-08-document-preview-operations.md) owns which related files are packaged and the iframe sandbox.
@@ -26,4 +26,4 @@ The [Workspace Files service](2026-09-05-workspace-files-service.md) owns paging
## Consequences
-Any caller holding a valid Session file address can receive bytes from every regular file that the Session filesystem backend permits it to read, including files outside the workspace. A previewed HTML document can execute packaged local JavaScript and make network requests. Outside files do not produce `changes` frames, so their previews require explicit refresh to observe updates.
+Any caller holding a valid Session file address can receive bytes from every regular file that the Session filesystem backend permits it to read, including files outside the workspace. With Developer tools enabled, a previewed HTML document can execute packaged local JavaScript and make network requests. Outside files do not produce `changes` frames, so their previews require explicit refresh to observe updates.
diff --git a/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.zh.md b/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.zh.md
index 559a59af0b..f8b0fae432 100644
--- a/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.zh.md
+++ b/.agents/notes/implemented/architecture/2026-09-09-workspace-file-read-authority.zh.md
@@ -14,7 +14,7 @@ Workspace Files 同时提供文件内容与工作区导航。对所有操作应
`list` 与 `changes` 仍限于工作区，因为它们暴露工作区导航和观察，而不是读取一个具名文件。`list` 拒绝根外目录，`changes` 通过后端的工作区包含判定过滤观察。
-`readRelated` 从基准文件所在目录解析相对路径。因此，只要 Session 后端允许，`..` 路径就可以读取工作区外的 JavaScript 或 CSS。Document Preview 把有界、静态声明的本地脚本与样式表打包进带 `sandbox="allow-scripts"` 的 HTML Blob iframe；不透明源阻止访问父应用，但浏览器保留正常网络访问。这种暴露是为渲染静态生成 HTML 而有意接受的安全取舍。
+`readRelated` 从基准文件所在目录解析相对路径。因此，只要 Session 后端允许，`..` 路径就可以读取工作区外的 JavaScript 或 CSS。开启[开发者工具](../feature/2026-09-17-developer-tools-settings.zh.md)时，Document Preview 把有界、静态声明的本地脚本与样式表打包进带 `sandbox="allow-scripts"` 的 HTML Blob iframe；不透明源阻止访问父应用，但浏览器保留正常网络访问。这种暴露是为渲染静态生成 HTML 而有意接受的安全取舍。
[Workspace Files 服务](2026-09-05-workspace-files-service.zh.md)负责分页、文件检查、列举和观察。[Document Preview](2026-09-08-document-preview-operations.zh.md)负责选择要打包的关联文件及 iframe sandbox。
@@ -26,4 +26,4 @@ Workspace Files 同时提供文件内容与工作区导航。对所有操作应
## Consequences
-持有有效 Session 文件地址的调用方可以接收 Session 文件系统后端允许读取的每个普通文件的字节，包括工作区外文件。预览的 HTML 文档可以执行已打包的本地 JavaScript，并发起网络请求。工作区外文件不会产生 `changes` 帧，因此其预览需要显式刷新才能观察更新。
+持有有效 Session 文件地址的调用方可以接收 Session 文件系统后端允许读取的每个普通文件的字节，包括工作区外文件。开启开发者工具时，预览的 HTML 文档可以执行已打包的本地 JavaScript，并发起网络请求。工作区外文件不会产生 `changes` 帧，因此其预览需要显式刷新才能观察更新。
diff --git a/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.i18n.yaml
index 5ab066c127..c27ef04676 100644
--- a/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.i18n.yaml
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-11-node-office-kit.md
-2026-09-11-node-office-kit.md: d77d6c5392532f39a9993af60faad6474bc8f36c
-2026-09-11-node-office-kit.zh.md: a0cbd22e4f06bd4f2878adf27852f9d2378b8b33
+2026-09-11-node-office-kit.md: 6cab947d7cb8d4c2c416a83f0b765813c7f98ea9
+2026-09-11-node-office-kit.zh.md: 8ed1a81922249cf0b9c1a74b06e5ce9d44696e0a
diff --git a/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.md b/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.md
index d77d6c5392..6cab947d7c 100644
--- a/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.md
+++ b/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.md
@@ -22,7 +22,7 @@ The kit owns default serif, sans-serif, and monospace preference groups, includi
DSH exports raster images at configurable resolution, defaulting to 192 DPI for the shared PDF canvas's 96 CSS DPI at device-pixel ratio 2. Text and vectors remain scalable; explicit bookmark export preserves the engine default when JSON filter options replace it. Node WASM downscales images with LibreOffice's CPU filter. Native conversion uses its separate platform engine.
-The [Office viewer](../../../../packages/client/ui-sidebar-documentpreview/README.md#office-preview) lives under Document Preview’s `client/office/` directory, alongside the loading lifecycle, PDF body, and reader types it uses. Keeping these components in one package removes an independent UI boot entry without creating cross-plugin runtime imports. Its bounded cache validates authorized source metadata, shares pending conversions between readers, cancels only when the final reader leaves, excludes failures, and clears on connection reset. Conversion starts when a user opens a preview. Missing declared font families accompany the PDF and appear in a dismissible notice above the Office scrollport; font-table inventories and unrelated engine defaults are not warnings. The shared preview entry’s `office` cache settings use the existing page-global injection channel because the module boot graph carries package identities, not Loader configuration. Reloading the page adopts updated YAML values.
+The [Office viewer](../../../../packages/client/ui-sidebar-documentpreview/README.md#office-preview) lives under Document Preview’s `client/office/` directory, alongside the loading lifecycle, PDF body, and reader types it uses. Keeping these components in one package removes an independent UI boot entry without creating cross-plugin runtime imports. Its bounded cache validates authorized source metadata, shares pending conversions between readers, cancels only when the final reader leaves, excludes failures, and clears on connection reset. Conversion starts when a user opens a preview. Missing declared font families accompany the PDF and are available from the document toolbar’s warning icon; font-table inventories and unrelated engine defaults are not warnings. The shared preview entry’s `office` cache settings use the existing page-global injection channel because the module boot graph carries package identities, not Loader configuration. Reloading the page adopts updated YAML values.
Ordinary file reads and Office responses share `documentFileBytes()`, which decodes into one typed byte buffer rather than materializing a JavaScript element array from the binary string. Element-array expansion can exhaust the browser heap for a PDF that the configured Host limits permit. A child-process regression checks byte equality within a fixed heap, while the built browser scenario verifies the transport and PDF Worker together. Cache byte limits do not bound transient transport or viewer memory.
diff --git a/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.zh.md b/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.zh.md
index a0cbd22e4f..8ed1a81922 100644
--- a/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.zh.md
+++ b/.agents/notes/implemented/architecture/2026-09-11-node-office-kit.zh.md
@@ -22,7 +22,7 @@ kit 维护 serif、sans-serif 和 monospace 的默认优先组，其中包含中
DSH 按可配置分辨率导出栅格图片，默认 192 DPI，对应共享 PDF 画布在设备像素比 2 时的 96 CSS DPI。文本与矢量仍可缩放；JSON 过滤选项替代隐式选项时，显式书签导出保留引擎默认行为。Node WASM 使用 LibreOffice 的 CPU 过滤器降采样图片。原生转换使用独立的平台引擎。
-[Office 查看器](../../../../packages/client/ui-sidebar-documentpreview/README.zh.md#office-preview)位于文档预览的 `client/office/` 目录，与其使用的加载生命周期、PDF 正文和读取器类型同属一个包。这些组件放在同一包中，既减少一个独立 UI 启动入口，也无需跨插件运行时导入。其有界缓存校验已授权的源元数据，在读取方之间共享待完成转换，仅在最后一个读取方离开时取消，不缓存失败，并在连接重置时清空。用户打开预览时才开始转换。缺失的已声明字体族随 PDF 返回，在 Office 滚动区上方显示可关闭的提示；字体表清单与无关的引擎默认字体不构成警告。共享预览入口的 `office` 缓存设置复用页面全局注入通道，因为模块启动图携带包标识而不传递 Loader 配置。重新加载页面后采用更新的 YAML 值。
+[Office 查看器](../../../../packages/client/ui-sidebar-documentpreview/README.zh.md#office-preview)位于文档预览的 `client/office/` 目录，与其使用的加载生命周期、PDF 正文和读取器类型同属一个包。这些组件放在同一包中，既减少一个独立 UI 启动入口，也无需跨插件运行时导入。其有界缓存校验已授权的源元数据，在读取方之间共享待完成转换，仅在最后一个读取方离开时取消，不缓存失败，并在连接重置时清空。用户打开预览时才开始转换。缺失的已声明字体族随 PDF 返回，可通过文档工具栏的警告图标查看；字体表清单与无关的引擎默认字体不构成警告。共享预览入口的 `office` 缓存设置复用页面全局注入通道，因为模块启动图携带包标识而不传递 Loader 配置。重新加载页面后采用更新的 YAML 值。
普通文件读取与 Office 响应共享 `documentFileBytes()`，解码使用一个类型化字节缓冲区，不将二进制字符串物化为 JavaScript 元素数组。即使 PDF 符合 Host 配置的大小限制，元素数组展开也可能耗尽浏览器堆内存。子进程回归测试在固定堆容量内检查字节一致性，构建后的浏览器场景则一起验证传输和 PDF Worker。缓存字节限制不约束临时传输或查看器内存。
diff --git a/.agents/notes/implemented/architecture/2026-09-15-bounded-office-conversion.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-15-bounded-office-conversion.i18n.yaml
index 8ddfd2d49e..2f64b37f55 100644
--- a/.agents/notes/implemented/architecture/2026-09-15-bounded-office-conversion.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-09-15-bounded-office-conversion.i18n.yaml
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-15-bounded-office-conversion.md
-2026-09-15-bounded-office-conversion.md: 78a2fc46d97500575262d2263bf5549037872264
-2026-09-15-bounded-office-conversion.zh.md: 88cb15c8cbf2200a9365b9a42cb5802c1bfb65d8
+2026-09-15-bounded-office-conversion.md: b15aa5421c575451ddb4a7bf91169bcb2fa38d3c
+2026-09-15-bounded-office-conversion.zh.md: f23c38096764cf32207125cc0c3ebbdf1c04d009
diff --git a/.agents/notes/implemented/architecture/2026-09-15-bounded-office-conversion.md b/.agents/notes/implemented/architecture/2026-09-15-bounded-office-conversion.md
index 78a2fc46d9..b15aa5421c 100644
--- a/.agents/notes/implemented/architecture/2026-09-15-bounded-office-conversion.md
+++ b/.agents/notes/implemented/architecture/2026-09-15-bounded-office-conversion.md
@@ -37,3 +37,7 @@ The cache is transient and cannot bypass source authorization. Oversized PDFs ca
Office preview checks source authorization and versions through Workspace Files, then reads raw input with `fs.readBytes` within its conversion reservation. Office input limits govern that read. The Host conversion path avoids base64 source allocation; PDF responses encode only the converted output.
Controlled source and engine completions verify pre-read admission, content joining, priority, cancellation isolation, delayed resource release, LRU/alias limits, stale versions, and converter replacement. Loader composition and native conversion checks exercise the shared provider independently of presentation consumers.
+
+## Related
+
+The [background scheduling proposal](../../proposed/simplification/2026-09-17-defer-office-background-scheduling.md) questions the need for speculative priority without a production caller; this note remains the authority for the implemented behavior.
diff --git a/.agents/notes/implemented/architecture/2026-09-15-bounded-office-conversion.zh.md b/.agents/notes/implemented/architecture/2026-09-15-bounded-office-conversion.zh.md
index 88cb15c8cb..f23c380967 100644
--- a/.agents/notes/implemented/architecture/2026-09-15-bounded-office-conversion.zh.md
+++ b/.agents/notes/implemented/architecture/2026-09-15-bounded-office-conversion.zh.md
@@ -37,3 +37,7 @@ Office 预览和显式文档检查可能请求相同转换。仅缓存已完成
Office 预览通过 Workspace Files 检查源文件授权与版本，再使用 `fs.readBytes` 在转换预留容量内读取原始输入。该读取受 Office 输入上限约束。Host 转换路径不分配 base64 源数据；PDF 响应只编码转换后的输出。
受控的源读取和引擎完成验证读取前准入、内容合并、优先级、取消隔离、延迟资源释放、LRU 与别名限额、过期版本及转换器替换。Loader 组合与原生转换检查独立于展示消费者验证共享提供方。
+
+## 相关记录
+
+[后台调度提案](../../proposed/simplification/2026-09-17-defer-office-background-scheduling.zh.md) 质疑没有生产调用方时保留推测性优先级的必要性；本记录仍定义已实现的行为。
diff --git a/.agents/notes/implemented/architecture/2026-09-16-desktop-policy-login-loading.md b/.agents/notes/implemented/architecture/2026-09-16-desktop-policy-login-loading.md
deleted file mode 100644
index 26fd635c6c..0000000000
--- a/.agents/notes/implemented/architecture/2026-09-16-desktop-policy-login-loading.md
+++ /dev/null
@@ -1,37 +0,0 @@
-# Agent Note: Show a local document while the policy login page loads
-
-Status: implemented
-
-English | [中文](2026-09-16-desktop-policy-login-loading.zh.md)
-
-## Problem
-
-The test-deployment login window ([mandatory-update client](../feature/2026-09-11-desktop-mandatory-update-client.md)) navigated straight to the policy origin. Until that document committed and painted, the window was blank, and the remote page can take seconds to appear. A user pressed "Sign in with Feishu" and saw an empty window with no sign that anything was happening — while the window had to stay closable and must never cover a page that had become interactive.
-
-## Decision
-
-[policy-test-auth.ts](../../../../apps/desktop/src/policy-test-auth.ts) loads [renderer/policy-login-loading.html](../../../../apps/desktop/renderer/policy-login-loading.html) as the window's first document and requests the policy origin only after that document has committed. The placeholder is a packaged, self-contained file whose only text is the label the main process passes through `loadFile`'s query, so the copy stays in the shell locale dictionary (`policyLoginLoading`). The first committed remote document replaces it.
-
-The placeholder never coexists with the remote page, so there is no removal step and no timer: Chromium keeps the placeholder frame until the remote document's first frame is ready, and from then on the third-party page owns the window. A redirect chain keeps the placeholder until the last document commits. The window is created visible and closable as before.
-
-Two places recognize the placeholder's own load by file name and nothing else: the Session's `onBeforeRequest` filter, which cancels document requests outside the policy and Feishu origins, and the `did-fail-load` handler, which fails the login on a main-frame error. The `will-navigate` and `will-redirect` guards still require an allowed HTTPS origin, so the remote page cannot steer the window back to a local file. A placeholder that cannot load is not a login failure: the login request starts anyway and the window is blank exactly as it was before this change.
-
-## Alternatives considered
-
-**Overlay the window with a `WebContentsView` (or `BrowserView`) and remove it when the page is ready.** It would show feedback even earlier and can be removed at any chosen signal, but it needs a second renderer, a position that follows window resizes, and an explicit removal point. Every available removal signal is either late (`did-finish-load` still waits for subresources) or a guess (`dom-ready` can precede the first paint), and a view left in place covers an interactive page.
-
-**Inject an overlay element into the login page with a preload script.** The one approach the decision has to keep out: it puts a shell-owned DOM layer inside a third-party page, and it would give that page a preload bridge the isolated Session deliberately withholds (`webPreferences.preload` is unset).
-
-**Keep the window hidden until the remote page finishes loading.** It removes the blank flash by removing the feedback, and it delays the user's first view of the page until every subresource completes.
-
-**Show a native splash window, or the loading text in the window title.** A second window adds a focus and lifetime problem for a two-second wait, and a title is not visible feedback inside the window.
-
-**Reveal the page with a fixed delay.** A timer cannot distinguish a slow origin from a fast one, and it either covers a ready page or uncovers a blank one.
-
-## Consequences
-
-The login window gives immediate local feedback that cannot depend on the network: the placeholder's CSP sets `default-src 'none'`, so the document has no origin, font, image, or connection to reach. Because the placeholder is the window's document rather than a layer, nothing about it can survive into the third-party page, and a slow subresource on the login page cannot extend it.
-
-The placeholder shares the login Session, so its request passes through the same document filter; the filter's exemption is name-scoped and does not widen the allowed-origin check for navigation. The window title remains the shell-owned login title (the renderer prevents `page-title-updated`), so the placeholder contributes no copy of its own.
-
-[policy-test-auth.spec.ts](../../../../apps/desktop/tests/policy-test-auth.spec.ts) covers the order (placeholder first, remote page only after it settles), the filter's acceptance of the placeholder, a failed placeholder load that must not fail the login, and a window closed while the placeholder is loading that never starts the remote page. [policy-login-loading.spec.ts](../../../../apps/desktop/tests/policy-login-loading.spec.ts) loads the packaged document under jsdom and checks that it renders the label it is given, leaves the label empty without one, and forbids every network source. The placeholder's rendered frames and the first-paint timing of the substituted login page remain unverified against a real login window.
diff --git a/.agents/notes/implemented/architecture/2026-09-16-desktop-policy-login-loading.zh.md b/.agents/notes/implemented/architecture/2026-09-16-desktop-policy-login-loading.zh.md
deleted file mode 100644
index 16de25323a..0000000000
--- a/.agents/notes/implemented/architecture/2026-09-16-desktop-policy-login-loading.zh.md
+++ /dev/null
@@ -1,37 +0,0 @@
-# Agent Note: 策略登录页加载期间显示本地文档
-
-Status: implemented
-
-[English](2026-09-16-desktop-policy-login-loading.md) | 中文
-
-## 问题
-
-测试部署的登录窗口（[强制更新客户端](../feature/2026-09-11-desktop-mandatory-update-client.zh.md)）直接导航到策略 origin。在该文档提交并绘制之前，窗口是空白的，而远端页面可能需要数秒才出现。用户点击“通过飞书登录”后只看到一个空窗口，没有任何正在进行的迹象——同时窗口必须保持可关闭，也绝不能遮挡已经可交互的页面。
-
-## 决策
-
-[policy-test-auth.ts](../../../../apps/desktop/src/policy-test-auth.ts)把 [renderer/policy-login-loading.html](../../../../apps/desktop/renderer/policy-login-loading.html) 作为窗口的首个文档载入，并在该文档提交之后才请求策略 origin。占位页是随包发布的、自包含的文件，其中唯一的文本是主进程通过 `loadFile` 的 query 传入的文案，因此文案仍由 shell 本地化字典（`policyLoginLoading`）拥有。首个提交的远端文档会替换它。
-
-占位页从不与远端页面共存，因此没有移除步骤，也没有计时器：Chromium 会一直保留占位帧，直到远端文档的首帧就绪；此后窗口归第三方页面所有。重定向链会把占位页保持到最后一个文档提交。窗口仍与之前一样在创建时即显示且可关闭。
-
-只有两处按文件名识别占位页自身的加载，不识别其他任何东西：Session 的 `onBeforeRequest` 过滤器（它会取消策略与飞书 origin 之外的文档请求）以及 `did-fail-load` 处理器（主框架出错时让登录失败）。`will-navigate` 与 `will-redirect` 守卫仍然要求允许的 HTTPS origin，因此远端页面无法把窗口引回本地文件。占位页无法载入不算登录失败：登录请求照常开始，窗口与本次改动之前一样保持空白。
-
-## 考虑过的替代方案
-
-**用 `WebContentsView`（或 `BrowserView`）覆盖窗口，并在页面就绪时移除。** 它能更早显示反馈，也可以在任选信号处移除，但需要第二个渲染器、一个随窗口尺寸变化的位置，以及一个明确的移除时机。可用的移除信号要么偏晚（`did-finish-load` 仍会等待子资源），要么只是猜测（`dom-ready` 可能早于首帧绘制）；而一旦忘记移除，视图就会遮挡可交互的页面。
-
-**通过 preload 脚本向登录页注入覆盖元素。** 这是决策必须排除的做法：它把 shell 拥有的 DOM 层放进第三方页面，并且会给该页面一个隔离 Session 刻意不提供的 preload 桥（`webPreferences.preload` 未设置）。
-
-**在远端页面加载完成前保持窗口隐藏。** 它通过取消反馈来消除空白闪烁，并把用户第一次看到页面的时间推迟到所有子资源完成之后。
-
-**使用原生启动窗口，或把加载文本放进窗口标题。** 为一个两秒的等待增加第二个窗口会带来焦点与生命周期问题，而标题不是窗口内的可见反馈。
-
-**用固定延时揭示页面。** 计时器无法区分慢 origin 与快 origin，结果要么遮挡已就绪的页面，要么在空白页面上取消遮挡。
-
-## 结果
-
-登录窗口给出不依赖网络的即时本地反馈：占位页的 CSP 设置了 `default-src 'none'`，因此该文档没有任何 origin、字体、图片或连接可用。由于占位页是窗口的文档而不是覆盖层，它的任何部分都不会残留到第三方页面中，登录页上缓慢的子资源也无法延长它的存在。
-
-占位页共享登录 Session，因此它的请求会经过同一个文档过滤器；该过滤器的豁免按文件名限定，不会放宽导航所用的允许 origin 检查。窗口标题仍是 shell 拥有的登录标题（渲染器阻止了 `page-title-updated`），因此占位页不贡献自己的文案。
-
-[policy-test-auth.spec.ts](../../../../apps/desktop/tests/policy-test-auth.spec.ts)覆盖顺序（先占位页，只有它稳定后才请求远端页面）、过滤器对占位页的接受、占位页载入失败不得导致登录失败，以及占位页加载期间关闭窗口后绝不启动远端页面。[policy-login-loading.spec.ts](../../../../apps/desktop/tests/policy-login-loading.spec.ts)在 jsdom 下载入随包发布的文档，检查它渲染传入的文案、在没有文案时保持为空，并禁止一切网络来源。占位页的实际渲染帧与替代登录页的首帧时机仍未在真实登录窗口上验证。
diff --git a/.agents/notes/implemented/architecture/2026-09-16-nested-tooltip-suppression.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-16-nested-tooltip-suppression.i18n.yaml
deleted file mode 100644
index 7079d4ec79..0000000000
--- a/.agents/notes/implemented/architecture/2026-09-16-nested-tooltip-suppression.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
-# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-16-nested-tooltip-suppression.md
-2026-09-16-nested-tooltip-suppression.md: 1b06a3a1a4f754aa78e821ee8a1479dab19873ff
-2026-09-16-nested-tooltip-suppression.zh.md: 96063f78b281deb3561045bb73fcffa64a2c1ef8
diff --git a/.agents/notes/implemented/architecture/2026-09-16-nested-tooltip-suppression.md b/.agents/notes/implemented/architecture/2026-09-16-nested-tooltip-suppression.md
deleted file mode 100644
index 1b06a3a1a4..0000000000
--- a/.agents/notes/implemented/architecture/2026-09-16-nested-tooltip-suppression.md
+++ /dev/null
@@ -1,35 +0,0 @@
-# Agent Note: Suppress an enclosing tooltip while a nested one is shown
-
-Status: implemented
-
-English | [中文](2026-09-16-nested-tooltip-suppression.zh.md)
-
-## Problem
-
-The collapsed sidebar renders its update badge through the `sidebar.toggle.badge` slot inside the expand button, and both the button and the badge attach a `Tooltip`. Hovering the badge showed two bubbles at once — the version notice and "Open sidebar" — because the badge is a DOM descendant of the button: the button's hover state stays true for as long as the pointer rests on the badge, and each tooltip correctly follows its own anchor.
-
-## Decision
-
-[Tooltip](../../../../packages/client/ui-primitives/src/Tooltip.tsx) provides a suppression setter through an internal `TooltipSuppression` context wrapped around its cloned anchor and its bubble. A nested tooltip consumes the nearest setter and announces whenever its own bubble becomes visible. An enclosing tooltip that receives a suppression claim keeps its hover/focus triggers and its measured position but does not render its bubble, so the enclosing bubble returns in the same commit that the nested one disappears.
-
-The nested tooltip announces synchronously inside `show()` and through a `visible` effect. The synchronous call keeps a nested pair that becomes visible in one React commit from painting both bubbles for a frame; the effect releases the claim on every other path that hides a bubble, including unmount and a `disabled` flip.
-
-No component in `ui-sidebar` or `ui-settings-general` changed: the badge already renders inside the toggle's anchor, so the shared primitive resolves the overlap for any future nested pair as well.
-
-## Alternatives considered
-
-**Disable the toggle tooltip whenever an update exists.** The simplest guard, and wrong: it removes "Open sidebar" from ordinary rail hovers for the whole time an update is available, including hovers that never touch the badge.
-
-**Disable the toggle tooltip while the pointer is over the badge.** Hover-scoped, but `Tooltip` clears its hover and focus triggers when it is disabled, and no new `mouseenter` fires on the button while the pointer moves from the badge onto the button's own area. The enclosing bubble would stay gone until the pointer left and re-entered the button.
-
-**Stop the badge's `mouseenter` from reaching the button.** It only helps a pointer that enters the badge directly; a pointer that enters the button first and then moves onto the badge already has the enclosing bubble visible, because the enclosing hover never ended.
-
-**Render the badge outside the toggle's anchor.** The slot is declared inside the toggle button, and the badge must sit on the button's corner; moving the anchor out of the button would either detach the bubble from the control or change the slot's declared placement.
-
-## Consequences
-
-The rule is a property of tooltip nesting, not of the update badge: any tooltip whose anchor contains another tooltip now yields the bubble to the innermost visible one. A tooltip with no nested tooltip is unaffected — it consumes a null context and never announces.
-
-The enclosing tooltip's bubble is withdrawn only while a descendant is visible; its trigger state survives, so no re-entry is needed to restore it. Suppression does not change what the anchors do: the button still toggles the sidebar and the badge remains a non-interactive marker.
-
-[Tooltip tests](../../../../packages/client/ui-primitives/tests/tooltip.client.spec.tsx) cover withdrawal, restoration when the nested anchor is left for the enclosing one with a real `relatedTarget`, and release when a shown nested tooltip unmounts. The [sidebar shell test](../../../../packages/client/ui-sidebar/tests/sidebar-root.client.spec.tsx) covers the product wiring: the rail badge replaces the toggle bubble after the toggle's own hover delay has already elapsed.
diff --git a/.agents/notes/implemented/architecture/2026-09-16-nested-tooltip-suppression.zh.md b/.agents/notes/implemented/architecture/2026-09-16-nested-tooltip-suppression.zh.md
deleted file mode 100644
index 96063f78b2..0000000000
--- a/.agents/notes/implemented/architecture/2026-09-16-nested-tooltip-suppression.zh.md
+++ /dev/null
@@ -1,35 +0,0 @@
-# Agent Note: 嵌套提示显示时抑制外层提示
-
-Status: implemented
-
-[English](2026-09-16-nested-tooltip-suppression.md) | 中文
-
-## 问题
-
-侧边栏收起时，更新蓝点通过 `sidebar.toggle.badge` 插槽渲染在展开按钮内部，而按钮和蓝点各自挂了一个 `Tooltip`。hover 蓝点会同时出现两个气泡——版本提示和“打开侧边栏”——因为蓝点是按钮的 DOM 后代：只要指针停在蓝点上，按钮的 hover 状态就保持为真，而两个 tooltip 都在正确地跟随各自的 anchor。
-
-## 决策
-
-[Tooltip](../../../../packages/client/ui-primitives/src/Tooltip.tsx)通过内部 `TooltipSuppression` context 提供一个抑制 setter，并把该 context 包在克隆后的 anchor 与气泡外层。嵌套的 tooltip 消费最近的 setter，并在自己的气泡可见时上报。收到抑制声明后，外层 tooltip 保留 hover/focus 触发状态与已测量的位置，但不渲染自己的气泡，因此嵌套气泡消失的同一提交里外层气泡就会回来。
-
-嵌套 tooltip 既在 `show()` 中同步上报，也通过 `visible` effect 上报。同步调用避免在同一 React 提交中同时可见的一对工具提示多绘制一帧的两个气泡；effect 则在其他所有隐藏气泡的路径上释放抑制，包括卸载和 `disabled` 翻转。
-
-`ui-sidebar` 与 `ui-settings-general` 中的组件无需改动：蓝点本就渲染在 toggle 的 anchor 内，因此共享 primitive 也顺带解决了未来任何嵌套组合。
-
-## 考虑过的替代方案
-
-**只要存在更新就禁用 toggle 的 tooltip。** 这是最简单的防护，但也是错的：它会在更新可用的整个期间移除普通 rail hover 的“打开侧边栏”，包括根本不会碰到蓝点的 hover。
-
-**指针位于蓝点上时禁用 toggle 的 tooltip。** 作用域正确，但 `Tooltip` 被禁用时会清空自己的 hover 与 focus 触发状态，而指针从蓝点移到按钮自身区域时按钮不会再触发新的 `mouseenter`。外层气泡会一直消失，直到指针离开按钮并重新进入。
-
-**阻止蓝点的 `mouseenter` 传播到按钮。** 这只能帮助直接从蓝点进入的指针；先进入按钮再移到蓝点上的指针，其外层气泡早已可见，因为外层的 hover 从未结束过。
-
-**把蓝点渲染到 toggle 的 anchor 之外。** 该插槽声明在 toggle 按钮内部，蓝点必须落在按钮角上；把 anchor 移出按钮要么让气泡脱离控件，要么改变插槽声明的放置位置。
-
-## 结果
-
-这条规则是 tooltip 嵌套的性质，而不是更新蓝点的性质：任何 anchor 内含另一个 tooltip 的 tooltip 现在都会把气泡让给最内层可见的那个。没有嵌套 tooltip 的 tooltip 不受影响——它消费到的是 null context，永远不会上报。
-
-外层 tooltip 仅在子级可见期间收回气泡；它的触发状态得以保留，因此不需要重新进入即可恢复。抑制不改变 anchor 的行为：按钮仍然切换侧边栏，蓝点仍然是非交互标记。
-
-[Tooltip 测试](../../../../packages/client/ui-primitives/tests/tooltip.client.spec.tsx)覆盖收回、用真实 `relatedTarget` 从嵌套 anchor 移到外层 anchor 时的恢复，以及已显示的嵌套 tooltip 卸载时的释放。[侧边栏 shell 测试](../../../../packages/client/ui-sidebar/tests/sidebar-root.client.spec.tsx)覆盖产品接线：在 toggle 自身的 hover 延迟已经过去之后，rail 蓝点气泡仍替换掉 toggle 气泡。
diff --git a/.agents/notes/implemented/bug-fix/2026-09-09-composer-placeholder-whitespace.i18n.yaml b/.agents/notes/implemented/architecture/2026-09-16-size-neutral-product-icon-weights.i18n.yaml
similarity index 54%
rename from .agents/notes/implemented/bug-fix/2026-09-09-composer-placeholder-whitespace.i18n.yaml
rename to .agents/notes/implemented/architecture/2026-09-16-size-neutral-product-icon-weights.i18n.yaml
index c971fb1bfd..758bca04da 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-09-composer-placeholder-whitespace.i18n.yaml
+++ b/.agents/notes/implemented/architecture/2026-09-16-size-neutral-product-icon-weights.i18n.yaml
@@ -1,6 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
-# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-09-09-composer-placeholder-whitespace.md
-2026-09-09-composer-placeholder-whitespace.md: c5d778f8fb1fdfc742636819a9ff27ddeeb0234e
-2026-09-09-composer-placeholder-whitespace.zh.md: b5f82bcd86f8567976bba96095d4de9d42bae9b1
+# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-16-size-neutral-product-icon-weights.md
+2026-09-16-size-neutral-product-icon-weights.md: 3850fcbddfef6d096f648d5b3efa73790f40f8c1
+2026-09-16-size-neutral-product-icon-weights.zh.md: 84031677e9b13b8dbf3b8e5d959359824e0c94fc
diff --git a/.agents/notes/implemented/architecture/2026-09-16-size-neutral-product-icon-weights.md b/.agents/notes/implemented/architecture/2026-09-16-size-neutral-product-icon-weights.md
new file mode 100644
index 0000000000..3850fcbddf
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-16-size-neutral-product-icon-weights.md
@@ -0,0 +1,29 @@
+# Agent Note: Size-neutral product icon weights
+
+Status: implemented
+
+English | [中文](2026-09-16-size-neutral-product-icon-weights.zh.md)
+
+## Problem
+
+Shared product-icon exports encoded one historical render size in each symbol name even though every component accepted a `size` prop. Consumers also thickened selected icons through local CSS or separate drawings, so emphasis had no named library choice and could drift between features.
+
+## Decision
+
+Every shared product glyph exports a size-neutral `Regular` and `Medium` component. `Regular` renders the supplied one-pixel artwork, while `Medium` renders the same paths with a 1.3px inherited stroke; filled regions remain unchanged. The `size` prop controls rendered dimensions, and the former numeric suffix survives only as the default size when a glyph has no 16px source.
+
+`LinkIconRegular` and `LinkIconMedium`, `ReferenceIconRegular` and `ReferenceIconMedium`, and the three `PermissionIcon*Regular`/`PermissionIcon*Medium` pairs follow the same rule. Repository consumers use a named weight instead of a numeric export.
+
+Medium weight is reserved for deliberate emphasis: new-Session controls, Settings trigger and navigation icons, Appearance choices, the composer add button, and clickable artifact-link glyphs. Other existing consumers use Regular. The composer command menu uses `PermissionIconFullAccessRegular` for the permission command because that row names permission elevation rather than the current mode.
+
+## Alternatives considered
+
+**Keep pixel sizes in export names.** Rejected because the suffix duplicated the runtime `size` prop and created separate names for identical geometry.
+
+**Expose one component with a `weight` prop.** Rejected because call sites would hide the chosen weight inside props; explicit component names keep visual emphasis searchable and reviewable.
+
+**Override stroke width in consumer CSS.** Rejected because source SVG elements can carry their own stroke widths, and local overrides would recreate inconsistent weighting outside the library.
+
+## Consequences
+
+The icon API is intentionally breaking while pre-stable: every consumer names `Regular` or `Medium`, and former 14px call sites pass an explicit size when they share geometry with a 16px export. New product glyphs add both weights from one geometry definition. Fill-only artwork exposes both names for API consistency even when stroke weight does not change its appearance. The hierarchy choices above remain explicit at their render sites rather than becoming global size or opacity overrides.
diff --git a/.agents/notes/implemented/architecture/2026-09-16-size-neutral-product-icon-weights.zh.md b/.agents/notes/implemented/architecture/2026-09-16-size-neutral-product-icon-weights.zh.md
new file mode 100644
index 0000000000..84031677e9
--- /dev/null
+++ b/.agents/notes/implemented/architecture/2026-09-16-size-neutral-product-icon-weights.zh.md
@@ -0,0 +1,29 @@
+# Agent Note: 尺寸无关的产品图标线重
+
+Status: implemented
+
+[English](2026-09-16-size-neutral-product-icon-weights.md) | 中文
+
+## 问题
+
+共享产品图标的导出名称包含一个历史渲染尺寸，但每个组件已经接受 `size` prop。消费方还会通过本地 CSS 或独立图稿加粗部分图标，视觉强调没有具名的图标库选项，因而可能在不同功能间漂移。
+
+## 决策
+
+每个共享产品图形都导出尺寸无关的 `Regular` 和 `Medium` 组件。`Regular` 渲染提供的 1px 图稿，`Medium` 使用相同路径并继承 1.3px 描边；填充区域保持不变。`size` prop 控制渲染尺寸；仅当图稿没有 16px 来源时，原数字后缀才作为默认尺寸保留。
+
+`LinkIconRegular` 与 `LinkIconMedium`、`ReferenceIconRegular` 与 `ReferenceIconMedium`，以及三组 `PermissionIcon*Regular`/`PermissionIcon*Medium` 遵循同一规则。仓库内消费方使用具名线重，不再使用带数字的导出名。
+
+Medium 线重只用于明确强调的场景：新建会话控件、设置入口与导航图标、外观选项、输入框加号按钮，以及可点击产物链接的图标。其他既有消费方使用 Regular。编辑器加号菜单中的权限命令使用 `PermissionIconFullAccessRegular`，因为该行表示权限提升，而不是当前权限模式。
+
+## 考虑过的替代方案
+
+**在导出名中保留像素尺寸。** 否决，因为后缀重复了运行时 `size` prop，并为相同几何创建了多个名称。
+
+**只导出一个带 `weight` prop 的组件。** 否决，因为调用点会把线重选择隐藏在 prop 中；显式组件名便于搜索和审查视觉强调。
+
+**在消费方 CSS 中覆盖描边宽度。** 否决，因为源 SVG 元素可能自带描边宽度，本地覆盖会在图标库外重新产生不一致线重。
+
+## 后果
+
+图标 API 在预稳定阶段有意进行破坏性调整：每个消费方明确选择 `Regular` 或 `Medium`；原 14px 调用点与 16px 导出共享几何时会显式传入尺寸。新增产品图形从同一份几何定义同时提供两种线重。仅填充的图稿也为 API 一致性导出两个名称，即使线重不会改变其外观。上述层级选择继续由对应渲染点显式声明，不会变成全局尺寸或透明度覆盖。
diff --git a/.agents/notes/implemented/bug-fix/2026-09-03-resume-headers-do-not-repeat-system-prompts.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-03-resume-headers-do-not-repeat-system-prompts.i18n.yaml
deleted file mode 100644
index d7871098ba..0000000000
--- a/.agents/notes/implemented/bug-fix/2026-09-03-resume-headers-do-not-repeat-system-prompts.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
-# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-09-03-resume-headers-do-not-repeat-system-prompts.md
-2026-09-03-resume-headers-do-not-repeat-system-prompts.md: de5e509c9e57af35bc36c24004457f02b63fd99d
-2026-09-03-resume-headers-do-not-repeat-system-prompts.zh.md: 008e25d8d507aac8fbaec7230bad433732f0efd0
diff --git a/.agents/notes/implemented/bug-fix/2026-09-03-resume-headers-do-not-repeat-system-prompts.md b/.agents/notes/implemented/bug-fix/2026-09-03-resume-headers-do-not-repeat-system-prompts.md
deleted file mode 100644
index de5e509c9e..0000000000
--- a/.agents/notes/implemented/bug-fix/2026-09-03-resume-headers-do-not-repeat-system-prompts.md
+++ /dev/null
@@ -1,31 +0,0 @@
-# Agent Note: Resume headers do not repeat system prompts
-
-Status: implemented
-
-English | [中文](2026-09-03-resume-headers-do-not-repeat-system-prompts.zh.md)
-
-## Problem
-
-Forking a Session copies the source history into the child. The child's first model request then records a `request/header` with reason `resume`, even when its system field is identical to the preceding copied header. Chat treated every resume header as a new display point, so continuing the fork showed a second `System prompt` row and suggested that the system prompt had been injected twice. The provider request still carried the system field once; the duplicate existed only in Chat presentation.
-
-## Decision
-
-The durable resume header records the request boundary needed for exact Session reconstruction. Chat compares that full header with the preceding loaded Request Prompt and displays a non-empty system prompt only for the initial request, an explicit message-series start, or a real system-field change. An unchanged resume does not create a visible repetition.
-
-A partial history window may begin with a non-initial header and lack the predecessor needed for comparison. Chat renders that system prompt conservatively. If prepend later supplies an identical predecessor, the existing request-prompt Node becomes hidden instead of being withdrawn; its key and page-lifetime anchor stay stable. A different system field remains visible.
-
-Trajectory exposes every request header and its classified changes. Chat presentation does not alter provider requests, Session events, or reconstruction.
-
-## Alternatives considered
-
-**Omit unchanged resume headers from the Session log.** Rejected: resume is a real request boundary, and removing it would make exact reconstruction depend on process history that the durable log does not contain.
-
-**Special-case only forked Sessions.** Rejected: an ordinary process resume has the same presentation semantics, and the request headers already contain the system fields needed for a direct comparison.
-
-**Keep the duplicate row as a lifecycle marker.** Rejected: `System prompt` describes model-visible request content, so using it to mark a loop restart incorrectly implies another prompt injection. Request lifecycle evidence remains available in Trajectory.
-
-## Consequences
-
-Continuing a fork or resuming a process with an unchanged system field leaves one visible `System prompt` row for the current message series. Explicit series starts and real system changes still repeat the row. A partial window can initially show a conservative row and hide it after older history loads, while retaining the same materialized Node.
-
-The unit regression covers initial, series, unchanged resume, system-change, and prepend cases. The Web recorded-session scenario contains an unchanged resume header and asserts that the settled Chat renders exactly one `System prompt` control.
diff --git a/.agents/notes/implemented/bug-fix/2026-09-03-resume-headers-do-not-repeat-system-prompts.zh.md b/.agents/notes/implemented/bug-fix/2026-09-03-resume-headers-do-not-repeat-system-prompts.zh.md
deleted file mode 100644
index 008e25d8d5..0000000000
--- a/.agents/notes/implemented/bug-fix/2026-09-03-resume-headers-do-not-repeat-system-prompts.zh.md
+++ /dev/null
@@ -1,31 +0,0 @@
-# Agent Note: Resume header 不重复系统提示词
-
-Status: implemented
-
-[English](2026-09-03-resume-headers-do-not-repeat-system-prompts.md) | 中文
-
-## 问题
-
-fork Session 会把源会话历史复制到子会话。即使 system 字段与前一条被复制的 header 完全相同，子会话的第一个模型请求仍会记录一条 reason 为 `resume` 的 `request/header`。Chat 把每条 resume header 都视作新的展示点，因此继续 fork 会显示第二行`系统提示词`，让人误以为系统提示词被注入了两次。提供方请求实际仍只携带一次 system 字段；重复仅存在于 Chat 展示中。
-
-## 决策
-
-持久化 resume header 记录精确重建 Session 所需的请求边界。Chat 会把完整 header 与前一条已加载 Request Prompt 比较，只在初始请求、显式消息序列起点或真实 system 字段变化时显示非空系统提示词。内容未变的 resume 不创建可见的重复行。
-
-部分历史窗口可能以非初始 header 开头，因缺少前序 header 而无法比较。Chat 会保守渲染该系统提示词。如果 prepend 随后补入相同的前序 header，既有 request-prompt Node 会转为隐藏而不是被撤回；其 key 和页面生命周期内的 anchor 保持稳定。不同的 system 字段仍然可见。
-
-Trajectory 会展示每一条请求 header 及其变化分类。Chat 展示不会改变提供方请求、Session event 或重建行为。
-
-## 考虑过的替代方案
-
-**从 Session log 省略未变化的 resume header。** 否决：resume 是真实的请求边界，移除后精确重建将依赖持久日志未记录的进程历史。
-
-**只对 fork Session 做特殊处理。** 否决：普通进程恢复具有相同的展示语义，请求 header 已经包含可直接比较的 system 字段。
-
-**把重复行保留为生命周期标记。** 否决：`系统提示词`描述模型可见的请求内容，用它标记 loop 重启会错误暗示再次注入提示词。请求生命周期证据仍可在 Trajectory 中查看。
-
-## 后果
-
-继续 fork 或在 system 字段未变时恢复进程，当前消息序列只保留一行可见的`系统提示词`。显式序列起点与真实 system 变化仍会重复该行。部分窗口起初可以显示保守行，并在更早历史加载后将其隐藏，同时保留同一个已物化 Node。
-
-单元回归覆盖初始请求、显式序列、未变化 resume、system 变化与 prepend 场景。Web 录制会话场景包含一条未变化的 resume header，并断言稳定后的 Chat 只渲染一个`系统提示词`控件。
diff --git a/.agents/notes/implemented/bug-fix/2026-09-07-pinned-scroll-delivery-before-layout.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-07-pinned-scroll-delivery-before-layout.i18n.yaml
deleted file mode 100644
index 5df3dbdf86..0000000000
--- a/.agents/notes/implemented/bug-fix/2026-09-07-pinned-scroll-delivery-before-layout.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
-# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-09-07-pinned-scroll-delivery-before-layout.md
-2026-09-07-pinned-scroll-delivery-before-layout.md: f3b428dbe0d2fdc7cbaedf0383d2ab80ea1bfd45
-2026-09-07-pinned-scroll-delivery-before-layout.zh.md: 9b200f45535c67cfbbb75feaf3025c5a3b5c1fa2
diff --git a/.agents/notes/implemented/bug-fix/2026-09-07-pinned-scroll-delivery-before-layout.md b/.agents/notes/implemented/bug-fix/2026-09-07-pinned-scroll-delivery-before-layout.md
deleted file mode 100644
index f3b428dbe0..0000000000
--- a/.agents/notes/implemented/bug-fix/2026-09-07-pinned-scroll-delivery-before-layout.md
+++ /dev/null
@@ -1,23 +0,0 @@
-# Agent Note: Settle pinned scroll deliveries before layout changes
-
-Status: implemented
-
-English | [中文](2026-09-07-pinned-scroll-delivery-before-layout.zh.md)
-
-## Problem
-
-A delayed scroll sample compares positions from different layouts. While Chat is pinned, a composer or transcript shrink can move the browser floor; subsequent growth can move the browser position again before `scrollend` or the sampling timer. Deferring follow during that interval leaves the observed-top ledger stale and can classify browser layout movement as reader input, disabling follow without a reader gesture.
-
-## Decision
-
-[ChatView](../../../../packages/client/ui-chat/src/client/chat/ChatView.tsx) uses the existing observed-top comparison to sample non-reader pinned scroll deliveries synchronously through the same sample operation that clears pending work. This releases layout follow before further growth. Genuine reader movement remains pending until the existing interval or `scrollend`, even within the follow threshold: growth must not erase small gestures before they accumulate into a scroll-away. Immediate pinned samples use scroll metrics, not semantic-row geometry.
-
-## Alternatives considered
-
-**Defer every delivery.** Coalescing reduces geometry work while reading history, but a pinned browser position and its floor must be attributed in the same layout. A longer timeout or retry cannot recover ownership once the stale comparison disarms it.
-
-**Sample every delivery synchronously.** This restores attribution but also repeats semantic-anchor and reading-line measurements throughout an away-reader scroll burst. Only pinned ownership needs the immediate path.
-
-## Consequences
-
-Pinned deliveries incur immediate scroll-metric reads. History reading retains its bounded sampling cadence, and explicit return-to-bottom deliveries clear any pending away sample. [Focused tests](../../../../packages/client/ui-chat/tests/chat-view.client.spec.tsx) cover shrink/regrowth before scrollend, observer growth without row measurements, repinning with a pending sample, timer and scrollend sampling, and unmount cancellation. The [keyless browser scenario](../../../../apps/web/tests/chat-scroll-contract.e2e.ts) covers pinned Send, real scroll-away input, streaming, and tool disclosure across the long transcript.
diff --git a/.agents/notes/implemented/bug-fix/2026-09-07-pinned-scroll-delivery-before-layout.zh.md b/.agents/notes/implemented/bug-fix/2026-09-07-pinned-scroll-delivery-before-layout.zh.md
deleted file mode 100644
index 9b200f4553..0000000000
--- a/.agents/notes/implemented/bug-fix/2026-09-07-pinned-scroll-delivery-before-layout.zh.md
+++ /dev/null
@@ -1,23 +0,0 @@
-# Agent Note: 在布局变化前处理贴底滚动事件
-
-Status: implemented
-
-[English](2026-09-07-pinned-scroll-delivery-before-layout.md) | 中文
-
-## Problem
-
-延迟的滚动采样会比较来自不同布局的位置。Chat 贴底时，输入框或 transcript（文本记录）收缩可能改变浏览器底部位置；随后的增长又可能在 `scrollend` 或采样定时器触发前改变浏览器位置。在此期间推迟跟随会使已观察顶部位置记录过期，把浏览器布局移动误判为读者输入，在没有读者操作时关闭跟随。
-
-## Decision
-
-[ChatView](../../../../packages/client/ui-chat/src/client/chat/ChatView.tsx) 使用现有的已观察顶部位置比较，通过同一个清除待处理工作的采样操作，同步采样非读者引起的贴底滚动事件。这会在后续增长前恢复布局跟随。真实读者移动即使位于跟随阈值内，也保持待处理直到现有周期或 `scrollend`：增长不能在小幅操作累积为离底滚动前将其抵消。立即执行的贴底采样只读取滚动指标，不读取语义行几何。
-
-## Alternatives considered
-
-**延迟所有事件。** 合并采样减少阅读历史时的几何计算，但贴底浏览器位置及其底部必须在同一布局中完成归因。过期比较关闭跟随后，延长超时或重试都无法恢复归属。
-
-**同步采样所有事件。** 这能恢复归因，却也会在离底读者连续滚动时重复测量语义锚点和阅读线。只有贴底归属需要立即处理。
-
-## Consequences
-
-贴底事件会立即读取滚动指标。历史阅读保留有界采样节奏，显式回到底部的滚动事件会清除任何待处理的离底采样。[聚焦测试](../../../../packages/client/ui-chat/tests/chat-view.client.spec.tsx) 覆盖 scrollend 前的收缩与增长、无需行测量的观察器增长、存在待处理采样时重新贴底、定时器与 scrollend 采样，以及卸载取消。[无密钥浏览器场景](../../../../apps/web/tests/chat-scroll-contract.e2e.ts) 覆盖长 transcript 中贴底发送、真实离底输入、流式输出与工具详情展开。
diff --git a/.agents/notes/implemented/bug-fix/2026-09-08-stable-room-reading-under-hidden-split-controls.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-08-stable-room-reading-under-hidden-split-controls.i18n.yaml
deleted file mode 100644
index f6a8425e96..0000000000
--- a/.agents/notes/implemented/bug-fix/2026-09-08-stable-room-reading-under-hidden-split-controls.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
-# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-09-08-stable-room-reading-under-hidden-split-controls.md
-2026-09-08-stable-room-reading-under-hidden-split-controls.md: c89c5328ee896e23ed24454c50223193c2d587ba
-2026-09-08-stable-room-reading-under-hidden-split-controls.zh.md: edf9948e547b79b33165b9c7168238e6cf1d2685
diff --git a/.agents/notes/implemented/bug-fix/2026-09-08-stable-room-reading-under-hidden-split-controls.md b/.agents/notes/implemented/bug-fix/2026-09-08-stable-room-reading-under-hidden-split-controls.md
deleted file mode 100644
index c89c5328ee..0000000000
--- a/.agents/notes/implemented/bug-fix/2026-09-08-stable-room-reading-under-hidden-split-controls.md
+++ /dev/null
@@ -1,25 +0,0 @@
-# Agent Note: Keep the room reading independent of hidden split controls
-
-Status: implemented
-
-English | [中文](2026-09-08-stable-room-reading-under-hidden-split-controls.zh.md)
-
-## Problem
-
-The dockkit room rule measures each pane's tab strip after every commit to decide whether an equal split leaves two working halves. With `hideSplitWhenBlocked`, a width-blocked pane unmounts its split control — and the unmount changes the very strip the rule measured: the strip sheds the control's 28px box plus its 4px gap, the fixed part shrinks, and the same pane reads as fitting again. Remounting the control reverses the reading. Across a roughly 32px band of pane widths the two states alternate inside nested layout effects until React stops the update loop (error #185); the slot runtime catches the crash and unmounts the Sidebar's entry while the column still records itself expanded, so neither the panel nor the header's collapsed-only expand button renders. A grip drag on a squeezed viewport sweeps the panel through that band, which presented as the whole sidebar vanishing with no way back in.
-
-## Decision
-
-When the embedder hides blocked split controls, the room rule leaves the split control's footprint out of the strip's fixed part unconditionally, so the reading is the same whether the control is currently mounted or not. [`measurePaneFits`](../../../../packages/client/ui-dockkit/src/components/measure.ts) takes the embedder's `hideSplitWhenBlocked` choice, measures the rendered control's box plus the strip's column gap (`splitControlFootprint`), and passes it as [`PaneMeasure.splitControlWidth`](../../../../packages/client/ui-dockkit/src/engine/geometry.ts), which `halvesFit` subtracts from the fixed part. Excluding the footprint is also correct on its own terms: a half too narrow to split would hide its own control, so the footprint is not part of what a half must carry. Embedders that render blocked controls disabled pass nothing and keep the control in the fixed part, as before.
-
-## Alternatives considered
-
-**Hide only budget-blocked controls, render width-blocked ones disabled.** This is what the code did before `hideSplitAtCapacity` widened into `hideSplitWhenBlocked`: the budget is state-driven and cannot feed back through the measurement. It avoids the loop but forfeits the Sidebar's requested presentation — no disabled split control on panes that cannot split.
-
-**Debounce or freeze re-measurement during oscillation.** Damping hides the instability instead of removing it: the reading would still depend on the control's visibility, settle on an arbitrary one of the two states, and flip on the next resize.
-
-**Measure the control's footprint from a constant.** A hardcoded 32px drifts from the stylesheet; measuring the rendered control and the strip's real `column-gap` keeps the subtraction equal to what the strip actually sheds, which is the exact condition for a stable reading.
-
-## Consequences
-
-The room reading is a fixed point under control visibility, so `hideSplitWhenBlocked` embedders get hidden controls without feedback. Panes near the boundary now read as splittable slightly earlier than a disabled-control embedder would report, because the half being asked about would not carry the control. A [dockkit regression test](../../../../packages/client/ui-dockkit/tests/components.client.spec.tsx) emulates the strip shedding the control's footprint and fails with React's update-depth error on the unfixed code; a [Sidebar browser case](../../../../apps/web/tests/sidebar-right.e2e.ts) drags the panel grip past both clamps on a squeezed viewport and asserts the panel, its grip, and a clean console survive, because the crash surfaces only as a console error the scaffold tripwire does not watch.
diff --git a/.agents/notes/implemented/bug-fix/2026-09-08-stable-room-reading-under-hidden-split-controls.zh.md b/.agents/notes/implemented/bug-fix/2026-09-08-stable-room-reading-under-hidden-split-controls.zh.md
deleted file mode 100644
index edf9948e54..0000000000
--- a/.agents/notes/implemented/bug-fix/2026-09-08-stable-room-reading-under-hidden-split-controls.zh.md
+++ /dev/null
@@ -1,25 +0,0 @@
-# Agent Note: Keep the room reading independent of hidden split controls
-
-Status: implemented
-
-[English](2026-09-08-stable-room-reading-under-hidden-split-controls.md) | 中文
-
-## Problem
-
-dockkit 的空间规则在每次 commit 后测量各 pane 的标签条，判断等分后的两半是否仍可用。开启 `hideSplitWhenBlocked` 时，宽度不足的 pane 会卸载自己的分屏控件——而这次卸载恰恰改变了规则所测量的标签条：标签条少了控件的 28px 盒子加 4px 间距，固定部分随之变小，同一个 pane 又被读成"够宽"。控件重新挂载后读数再次反转。在约 32px 的 pane 宽度区间内，两种状态在嵌套 layout effect 中来回切换，直到 React 中止更新循环（错误 #185）；slot 运行时捕获崩溃后卸载 Sidebar 的条目，而列状态仍记录为展开，于是面板和 header 上仅折叠时显示的展开按钮都不再渲染。在收窄的视口上拖动把手会让面板扫过该区间，表现为整个侧栏消失且无法再打开。
-
-## Decision
-
-当嵌入方选择隐藏被阻止的分屏控件时，空间规则无条件将分屏控件的占位排除在标签条固定部分之外，使读数与控件当前是否挂载无关。[`measurePaneFits`](../../../../packages/client/ui-dockkit/src/components/measure.ts) 接收嵌入方的 `hideSplitWhenBlocked` 选择，测量已渲染控件的盒子加标签条的列间距（`splitControlFootprint`），并作为 [`PaneMeasure.splitControlWidth`](../../../../packages/client/ui-dockkit/src/engine/geometry.ts) 传入，由 `halvesFit` 从固定部分中减去。排除该占位本身也是正确的：窄到无法分屏的一半会隐藏自己的控件，所以这份占位并不属于一半必须承载的内容。将被阻止控件渲染为禁用态的嵌入方不传该值，控件照旧计入固定部分。
-
-## Alternatives considered
-
-**只隐藏预算受限的控件，宽度受限的渲染为禁用态。** 这是 `hideSplitAtCapacity` 扩展为 `hideSplitWhenBlocked` 之前的做法：预算由状态驱动，不会经测量反馈回来。它避免了循环，但放弃了 Sidebar 想要的呈现——无法分屏的 pane 上不出现禁用的分屏控件。
-
-**在振荡期间对重新测量做防抖或冻结。** 阻尼只是掩盖不稳定而非消除它：读数仍依赖控件的可见性，会任意停在两种状态之一，并在下次 resize 时再次翻转。
-
-**用常量表示控件占位。** 硬编码的 32px 会与样式表漂移；测量实际渲染的控件和标签条真实的 `column-gap`，才能保证减去的量恰好等于标签条实际卸下的量，这正是读数稳定的确切条件。
-
-## Consequences
-
-空间读数在控件可见性变化下是不动点，`hideSplitWhenBlocked` 的嵌入方获得隐藏控件的呈现且无反馈循环。临界宽度附近的 pane 会比禁用态嵌入方的报告稍早读成可分屏，因为被询问的那一半不会承载控件。[dockkit 回归测试](../../../../packages/client/ui-dockkit/tests/components.client.spec.tsx) 模拟标签条卸下控件占位的反馈，在未修复的代码上以 React 更新深度错误失败；[Sidebar 浏览器用例](../../../../apps/web/tests/sidebar-right.e2e.ts) 在收窄视口上把面板把手拖过两侧钳位，断言面板、把手与干净的 console 均存活——崩溃只以 console error 形式出现，而脚手架的 tripwire 不监听它。
diff --git a/.agents/notes/implemented/bug-fix/2026-09-09-composer-placeholder-whitespace.md b/.agents/notes/implemented/bug-fix/2026-09-09-composer-placeholder-whitespace.md
deleted file mode 100644
index c5d778f8fb..0000000000
--- a/.agents/notes/implemented/bug-fix/2026-09-09-composer-placeholder-whitespace.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# Agent Note: Composer placeholder emptiness
-
-Status: implemented
-
-English | [中文](2026-09-09-composer-placeholder-whitespace.zh.md)
-
-## Problem
-
-Sharing the whitespace-trimmed submission check with placeholder rendering leaves guidance drawn over a draft containing spaces.
-
-## Decision
-
-The Composer hides its placeholder whenever the raw draft is nonempty. Submission keeps its trimmed-content check. Attachments and claimed commands retain their existing placeholder suppression.
-
-## Alternatives considered
-
-**Reuse the submission check.** Whitespace has no sendable message content, but it occupies the editor and moves its caret. A shared check conflates these two states.
-
-## Consequences
-
-All placeholder variants, including queued-message steering guidance, disappear after whitespace input and return after deletion. A whitespace-only draft without attachments remains unsendable. [Component tests](../../../../packages/client/ui-conversation/tests/input-bar.client.spec.tsx) cover visibility, composition, rerendering and submission; the [browser regression](../../../../apps/web/tests/composer-placeholder.e2e.ts) checks keyboard and clipboard gestures against built UI.
diff --git a/.agents/notes/implemented/bug-fix/2026-09-09-composer-placeholder-whitespace.zh.md b/.agents/notes/implemented/bug-fix/2026-09-09-composer-placeholder-whitespace.zh.md
deleted file mode 100644
index b5f82bcd86..0000000000
--- a/.agents/notes/implemented/bug-fix/2026-09-09-composer-placeholder-whitespace.zh.md
+++ /dev/null
@@ -1,21 +0,0 @@
-# Agent Note: Composer 占位提示的判空规则
-
-Status: implemented
-
-[English](2026-09-09-composer-placeholder-whitespace.md) | 中文
-
-## Problem
-
-占位提示复用去除首尾空白后的提交判断，会让提示文字覆盖已经包含空格的草稿。
-
-## Decision
-
-原始草稿非空时，Composer 隐藏占位提示。提交仍检查去除首尾空白后的内容。附件和已认领指令沿用现有的占位提示隐藏规则。
-
-## Alternatives considered
-
-**复用提交判断。** 空白字符没有可发送的消息内容，但会占据编辑器并移动光标。共用判断会混淆这两种状态。
-
-## Consequences
-
-所有占位提示，包括排队消息的插话提示，都会在输入空白字符后隐藏，删除后恢复。没有附件的纯空白草稿仍无法发送。[组件测试](../../../../packages/client/ui-conversation/tests/input-bar.client.spec.tsx) 覆盖显示、输入法组合、重新渲染和提交；[浏览器回归](../../../../apps/web/tests/composer-placeholder.e2e.ts) 使用构建后的界面检查键盘和剪贴板操作。
diff --git a/.agents/notes/implemented/bug-fix/2026-09-14-transcript-width-handle-layering.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-14-transcript-width-handle-layering.i18n.yaml
deleted file mode 100644
index 003ab9ba65..0000000000
--- a/.agents/notes/implemented/bug-fix/2026-09-14-transcript-width-handle-layering.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
-# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-09-14-transcript-width-handle-layering.md
-2026-09-14-transcript-width-handle-layering.md: 01d70e646e874d8266633597f1b510ad73fc2287
-2026-09-14-transcript-width-handle-layering.zh.md: c6e03ec5775256f5aac87d2f7c1ed66a12cf0c2a
diff --git a/.agents/notes/implemented/bug-fix/2026-09-14-transcript-width-handle-layering.md b/.agents/notes/implemented/bug-fix/2026-09-14-transcript-width-handle-layering.md
deleted file mode 100644
index 01d70e646e..0000000000
--- a/.agents/notes/implemented/bug-fix/2026-09-14-transcript-width-handle-layering.md
+++ /dev/null
@@ -1,33 +0,0 @@
-# Agent Note: Transcript width handles stay behind chat content
-
-Status: implemented
-
-English | [中文](2026-09-14-transcript-width-handle-layering.zh.md)
-
-## Problem
-
-The Conversation shell renders each content-width handle as a full-height absolute strip beside the reading column. A high stacking level placed that strip above wide Markdown tables that legitimately overflow the column. The handle glow covered their content and its pointer target could replace their interaction target.
-
-## Decision
-
-The Conversation shell keeps width handles at level zero without creating a body-wide stacking context. Chat raises concrete table elements to level one, while the reading column, column-bounded tool cards, and table breakout wrapper create no new stacking level. A table therefore owns the gutter only where its painted box actually reaches it; a fitting four-column table leaves the adjacent gutter draggable. Fixed message tooltips remain outside the table stacking context and can still paint over the sticky composer.
-
-This rule relies on the supported Chromium engine not turning ChatView's inline-size query container into an intermediate stacking context. The same engine behavior already lets the back-to-bottom control outrank the sticky composer. The Chromium hit-test scenario pins that assumption; raising the whole Chat root would instead make its transparent full-width box reclaim the gutter.
-
-A width handle starts resizing only for the primary pointer button. Ordinary wheel input over the handle is normalized from pixel, computed line-height, or page units and forwarded to the direct sibling transcript scrollport, so hovering the gutter does not suspend reading. Ctrl+wheel is not forwarded because it represents browser zoom or a trackpad pinch gesture.
-
-Each side's hit strip is at most 10px wide. Its hover indicator uses the lower-contrast resting scrollbar tint and is a 2px line with a 16px solid center and 28px fades, for a 72px total visible length.
-
-Composer chrome retains its higher layer, so its full sticky footer band intentionally does not start a width resize. A handle whose pointer capture began above that band temporarily rises to level eight, keeping the indicator visible until release. A full-view composer takeover continues to hide the handles entirely.
-
-## Alternatives considered
-
-**Move the handles farther from the reading column.** Wide tables can use the available transcript width, so a fixed larger inset would only reduce the overlap for some window sizes and would make the handles harder to reach.
-
-**Disable the handles whenever a transcript contains wide content.** One wide row would remove resizing from the entire Session, including empty gutter beside unrelated rows.
-
-**Inspect the elements under the pointer in JavaScript.** Dynamic hit testing would duplicate browser stacking and pointer dispatch rules and could still disagree with new plugin renderers.
-
-## Consequences
-
-Visible Chat content owns pointer input only where its painted element extends into a width-handle strip, while bare gutter keeps a quieter resize affordance, primary-button drag, and transcript wheel scrolling. Unit tests pin the declared handle geometry, pointer-button behavior, direct scrollport lookup, zoom exclusion, and every DOM delta mode. Chromium `elementFromPoint` coverage proves an overflowing table wins the hit while a fitting `md-table-wide` wrapper does not, and a message-action test proves fixed tooltips still paint above the sticky composer.
diff --git a/.agents/notes/implemented/bug-fix/2026-09-14-transcript-width-handle-layering.zh.md b/.agents/notes/implemented/bug-fix/2026-09-14-transcript-width-handle-layering.zh.md
deleted file mode 100644
index c6e03ec577..0000000000
--- a/.agents/notes/implemented/bug-fix/2026-09-14-transcript-width-handle-layering.zh.md
+++ /dev/null
@@ -1,33 +0,0 @@
-# Agent Note: 正文宽度拖拽条位于 Chat 内容下方
-
-Status: implemented
-
-[English](2026-09-14-transcript-width-handle-layering.md) | 中文
-
-## 问题
-
-Conversation shell 将每个正文宽度拖拽条渲染为阅读列旁的全高绝对定位区域。较高的堆叠层级使该区域盖在会合理溢出阅读列的宽 Markdown 表格之上。拖拽条的高亮会遮住表格内容，其指针目标也可能取代表格自身的交互目标。
-
-## 决策
-
-Conversation shell 将宽度拖拽条保持在第零层，不创建覆盖整个 body 的堆叠上下文。Chat 只将具体的表格元素提到第一层，阅读列、限定在列内的工具卡片与表格 breakout 包装层都不创建新的堆叠层级。因此只有表格的可见盒子实际延伸进沟槽时才会占有指针；能容纳在正文中的四列表格不会阻断旁边的沟槽拖拽。消息的固定定位 Tooltip 保持在表格堆叠上下文之外，仍可绘制在粘滞 composer 上方。
-
-该规则依赖交付的 Chromium 引擎不会把 ChatView 的 inline-size query container 变成中间堆叠上下文。back-to-bottom 控件能高于粘滞 composer 也已依赖相同的引擎行为。Chromium 命中测试固定这一假设；如果改为提高整个 Chat root，其透明全宽盒子反而会重新占用沟槽。
-
-宽度拖拽条仅使用主指针按键开始调整。拖拽条上的普通滚轮输入会从像素、计算后的行高或页面单位规整为像素，再转发给直接相邻的 transcript scrollport，因此指针悬停在沟槽时不会中断阅读滚动。Ctrl+滚轮表示浏览器缩放或触控板捏合手势，不会被转发。
-
-每侧的命中区域最宽为 10px。悬停指示线使用对比度更低的静止滚动条颜色，线宽 2px，中心实色段长 16px，两端各渐隐 28px，可见总长度为 72px。
-
-Composer chrome 保留更高层级，因此完整的粘滞底部区带刻意不会开始宽度调整。如果拖拽条在进入该区带之前已获得指针捕获，它会临时提到第八层，使指示线在松开前保持可见。占据完整 View 的 composer takeover 仍会完全隐藏拖拽条。
-
-## 考虑过的替代方案
-
-**将拖拽条移到离阅读列更远的位置。** 宽表格可以使用 transcript 的可用宽度，因此固定增加间距只能减少部分窗口尺寸下的重叠，还会让拖拽条更难触达。
-
-**只要 transcript 包含宽内容就禁用拖拽条。** 一行宽内容会让整个 Session 都无法调整宽度，包括与其他行相邻的空白沟槽。
-
-**在 JavaScript 中检查指针下方的元素。** 动态命中测试会重复浏览器的堆叠与指针分发规则，并且仍可能与新的插件 renderer 不一致。
-
-## 后果
-
-可见 Chat 内容只在其可见元素实际延伸进宽度拖拽区域时拥有指针输入，裸露沟槽则保留更轻的宽度调整提示、主按键拖拽和 transcript 滚轮滚动。单元测试固定声明的拖拽条尺寸、指针按键行为、直接 scrollport 查找、缩放排除和每种 DOM delta mode。Chromium `elementFromPoint` 覆盖证明溢出表格获得指针命中，而可容纳的 `md-table-wide` 包装层不会；消息操作测试证明固定定位 Tooltip 仍绘制在粘滞 composer 上方。
diff --git a/.agents/notes/implemented/bug-fix/2026-09-17-thinking-markdown.i18n.yaml b/.agents/notes/implemented/bug-fix/2026-09-17-thinking-markdown.i18n.yaml
index f0a89cb78d..6377a233cb 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-17-thinking-markdown.i18n.yaml
+++ b/.agents/notes/implemented/bug-fix/2026-09-17-thinking-markdown.i18n.yaml
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write .agents/notes/implemented/bug-fix/2026-09-17-thinking-markdown.md
-2026-09-17-thinking-markdown.md: de49cb42ba537700f6584c9f4cef9a57fb2e3605
-2026-09-17-thinking-markdown.zh.md: e403630138f2f39aec0834e550d4d4a8860a67fe
+2026-09-17-thinking-markdown.md: 6990fc6277d7d1c0a088a50cfb88694b2d9c55c7
+2026-09-17-thinking-markdown.zh.md: 963626088e50a44bcf76c7fc7ec3653e93fcd2c9
diff --git a/.agents/notes/implemented/bug-fix/2026-09-17-thinking-markdown.md b/.agents/notes/implemented/bug-fix/2026-09-17-thinking-markdown.md
index de49cb42ba..6990fc6277 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-17-thinking-markdown.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-17-thinking-markdown.md
@@ -10,9 +10,9 @@ Chat Thinking contains model-authored Markdown, but literal rendering exposes he
## Decision
-[MarkdownText](../../../../packages/client/ui-primitives/src/markdown/MarkdownText.tsx) owns a compact presentation variant used by Chat Thinking and Trajectory thinking details. It keeps the secondary content font size, line height, and tertiary color throughout. Heading levels retain semantic elements but share the same 600 weight and size; paragraphs, lists, quotes, and code use compact spacing. Links keep a resting dotted underline with tertiary color as a secondary-content exception to the [shared link styling](../feature/2026-09-04-web-clickable-link-styles.md); code retains its monospace font and background.
+[MarkdownText](../../../../packages/client/ui-primitives/src/markdown/MarkdownText.tsx) owns a compact presentation variant used by Chat Thinking and Trajectory thinking details. It keeps the secondary content font size, line height, and tertiary color throughout. Heading levels retain semantic elements but share the same 600 weight and size; paragraphs, lists, quotes, and code use compact spacing. Links keep a resting dotted underline with tertiary color as a secondary-content exception to the [shared link styling](../../../../docs/web-styling.md); code retains its monospace font and background.
-Tables and formulas remain enabled through the existing parser. Their containers constrain horizontal overflow, and formula text inherits the secondary font size. Inline formulas retain native KaTeX baselines; enclosing text blocks own overflow so short formulas do not create scrollbars. Compact code banners stay in normal flow, keeping the [Thinking disclosure header](../feature/2026-08-03-web-sticky-collapsible-headers.md) above the scrolling content without a second sticky band.
+Tables and formulas remain enabled through the existing parser. Their containers constrain horizontal overflow, and formula text inherits the secondary font size. Inline formulas retain native KaTeX baselines; enclosing text blocks own overflow so short formulas do not create scrollbars. Compact code banners stay in normal flow, keeping the [Thinking disclosure header](../../../../packages/client/ui-chat/src/client/chat/ReasoningRow.module.css) above the scrolling content without a second sticky band.
Chat passes its running state to the existing incremental Markdown renderer. The collapsed summary remains a separate single-line text projection. The parser, frozen-block cache, stored reasoning, and Session format do not change. Trajectory pins Thinking to its inspector’s fixed 13px/20px tier, independent of Chat’s content-size setting. Its answer output retains its existing typography and its [Thinking disclosure behavior](../feature/2026-09-09-ptc-trajectory-code-inspection.md).
diff --git a/.agents/notes/implemented/bug-fix/2026-09-17-thinking-markdown.zh.md b/.agents/notes/implemented/bug-fix/2026-09-17-thinking-markdown.zh.md
index e403630138..963626088e 100644
--- a/.agents/notes/implemented/bug-fix/2026-09-17-thinking-markdown.zh.md
+++ b/.agents/notes/implemented/bug-fix/2026-09-17-thinking-markdown.zh.md
@@ -10,9 +10,9 @@ Chat Thinking 包含模型编写的 Markdown，但纯文本渲染直接显示标
## 决策
-[MarkdownText](../../../../packages/client/ui-primitives/src/markdown/MarkdownText.tsx) 拥有紧凑展示变体，供 Chat Thinking 和 Trajectory 思考详情使用。内容沿用次级字号、行高和 tertiary 颜色。各级标题保留语义元素，但统一使用 600 字重和相同字号；段落、列表、引用和代码采用紧凑间距。链接保留默认点状下划线与 tertiary 颜色，作为[共享链接样式](../feature/2026-09-04-web-clickable-link-styles.zh.md)的次级内容例外；代码保留等宽字体和底色。
+[MarkdownText](../../../../packages/client/ui-primitives/src/markdown/MarkdownText.tsx) 拥有紧凑展示变体，供 Chat Thinking 和 Trajectory 思考详情使用。内容沿用次级字号、行高和 tertiary 颜色。各级标题保留语义元素，但统一使用 600 字重和相同字号；段落、列表、引用和代码采用紧凑间距。链接保留默认点状下划线与 tertiary 颜色，作为[共享链接样式](../../../../docs/web-styling.zh.md)的次级内容例外；代码保留等宽字体和底色。
-表格和公式继续通过既有解析器启用。其容器限制横向溢出，公式文本继承次级字号。行内公式保留 KaTeX 原生基线，由外层文本块承担溢出处理，短公式不会产生滚动条。紧凑代码栏保持正常文档流，让 [Thinking 折叠标题](../feature/2026-08-03-web-sticky-collapsible-headers.zh.md) 位于滚动内容上方，无需第二条 sticky 栏。
+表格和公式继续通过既有解析器启用。其容器限制横向溢出，公式文本继承次级字号。行内公式保留 KaTeX 原生基线，由外层文本块承担溢出处理，短公式不会产生滚动条。紧凑代码栏保持正常文档流，让 [Thinking 折叠标题](../../../../packages/client/ui-chat/src/client/chat/ReasoningRow.module.css) 位于滚动内容上方，无需第二条 sticky 栏。
Chat 将运行状态传给既有增量 Markdown 渲染器。折叠摘要仍是独立的单行文本投影。解析器、冻结块缓存、存储的推理内容和 Session 格式均保持不变。Trajectory 将 Thinking 固定在检查器的 13px/20px 层级，与 Chat 的内容字号设置无关。其回答输出保留既有排版及其 [Thinking 折叠行为](../feature/2026-09-09-ptc-trajectory-code-inspection.zh.md)。
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
index ad0bf724cd..21f75ab4b4 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.i18n.yaml
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
-2026-07-27-web-subagent-conversations.md: f4c323866f0ce11aecab9c6a0e2a017430df33bc
-2026-07-27-web-subagent-conversations.zh.md: c575cffe4afd95e66868ba22138b69f37fdd1786
+2026-07-27-web-subagent-conversations.md: 3798a5a2e5deb8b3801298def31c3a1890877796
+2026-07-27-web-subagent-conversations.zh.md: 4531528dd2a58baff3aaeaf53f20e037fce6cec4
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
index f4c323866f..3798a5a2e5 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.md
@@ -39,7 +39,7 @@ The Figma [subagent list](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5J8/Ha
## Product contract
-The child-count control appears when the direct catalog contains entries or its read fails; it stays hidden while an empty catalog is absent or loading, and after a successful empty read. On an ordinary session, a slash separates the current title from that control. Every subagent breadcrumb combines its compact 12px title with a fixed double chevron: the current breadcrumb uses primary color and weight 500, while ancestors use tertiary color and weight 400. Hovering a combined control for 150ms opens its direct-parent catalog, with a short crossing grace for the portaled menu; ArrowDown remains the keyboard entry path. Clicking an ancestor cancels pending hover, closes an open catalog, and only navigates upward. Each direct-parent catalog enables sibling switching and bolds its selected row; its label overrides the optional session-summary title, and a missing switcher catalog loads on interaction. Only the current subagent appends its own direct-child count control. Long titles truncate before the fixed chevron. The trigger reports the direct catalog's total and running counts. Ordinary sidebar rows hide subagent-origin Sessions and read their direct running-child count from the same loaded catalog map; Session summaries supply activity but never create membership. Pending interaction outranks parent running; either remains primary while direct-child activity becomes a second hover and assistive status. With neither present, direct-child activity outranks an unviewed completion reminder, which returns after the last running direct child stops. A tree row remains expandable while its child catalog is absent, loading, or failed, and becomes a known leaf only after that catalog loads empty. Loading shows a generic notice rather than summary-derived placeholder rows. The tree presents continuable and one-shot rows, falling back to the Session id when an optional one-shot label is absent.
+The child-count control appears when the direct catalog contains entries or its read fails; it stays hidden while an empty catalog is absent or loading, and after a successful empty read. On an ordinary session, a slash separates the current title from that control. Every subagent breadcrumb combines its compact 12px title with a fixed double chevron: the current breadcrumb uses primary color and weight 500, while ancestors use tertiary color and weight 400. Hovering a combined control for 150ms opens its direct-parent catalog, with a short crossing grace for the portaled menu; ArrowDown remains the keyboard entry path. Clicking an ancestor cancels pending hover, closes an open catalog, and only navigates upward. Each direct-parent catalog enables sibling switching and bolds its selected row; its label overrides the optional session-summary title, and a missing switcher catalog loads on interaction. Only the current subagent appends its own direct-child count control. Long titles truncate before the fixed chevron. The trigger reports the direct catalog's total and running counts. Ordinary sidebar rows hide subagent-origin Sessions and read their direct running-child count from the same loaded catalog map; Session summaries supply activity but never create membership. Running direct children use the shared tertiary-grey ongoing loader. Pending interaction outranks parent running; either remains primary while direct-child activity becomes a second hover and assistive status. An ordinary Workspace row with a pending approval, plan review, or question replaces its relative time with the compact label `Approval`, `Plan review`, or `Answer`; hover and assistive details retain the full status and relative time. With neither primary state present, direct-child activity outranks an unviewed completion reminder, which returns after the last running direct child stops. A tree row remains expandable while its child catalog is absent, loading, or failed, and becomes a known leaf only after that catalog loads empty. Loading shows a generic notice rather than summary-derived placeholder rows. The tree presents continuable and one-shot rows, falling back to the Session id when an optional one-shot label is absent.
`running` means the child Agent driver is draining work; `inactive` means that driver is idle or absent. Session-list baselines and status events supply activity, and removal marks completed subagents inactive while retaining their display projections. The shared parent `subagentCatalog` projection supplies membership. Initial reads and pushed values meet in one projection store; a newer sequence wins. [The projection-consumer decision](../simplification/2026-09-08-web-subagent-catalog-projections.md) owns loading, reconnect, and synchronization tradeoffs. A prompt response remains delivery-time authority.
diff --git a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
index c575cffe4a..4531528dd2 100644
--- a/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
+++ b/.agents/notes/implemented/feature/2026-07-27-web-subagent-conversations.zh.md
@@ -39,7 +39,7 @@ Figma 中的 [subagent 列表](https://www.figma.com/design/jRBBK7zBgcszdVWQ0Fh5
## 产品约定
-直接 catalog 有子项或读取失败时显示 child 数量控件；空目录缺席、加载中或成功读取为空时均隐藏该控件。普通会话会用斜杠分隔当前 title 和该控件。每一级 subagent 面包屑都将紧凑的 12px title 与固定显示的双向箭头组合成一个控件：当前面包屑使用主标签颜色和 500 字重，祖先则使用三级标签颜色和 400 字重。悬停组合控件 150ms 后会打开其直接 parent 目录；浮层菜单具有短暂的跨越宽限时间，ArrowDown 保留为键盘入口。点击祖先会取消待触发的悬停、关闭已打开的目录，并且只向上导航。每个直接 parent 目录都可切换 sibling，并会加粗其选中行；目录 label 优先于可选的会话摘要 title，缺失的切换器目录在交互时加载。只有当前 subagent 会追加自己的直接 child 数量控件。过长的 title 会在固定箭头之前截断。触发器报告直接 catalog 的总数与运行数。普通侧边栏 row 隐藏 origin 为 subagent 的 Session，并从同一份已加载 catalog map 读取直接运行 child 数；Session summary 提供 activity，但绝不创建 membership。待处理交互优先于 parent 的运行中状态；二者无论哪一项存在都会保持为主要状态，而直接 child activity 则成为悬停与无障碍状态中的第二项。两者均不存在时，直接 child activity 优先于未查看的完成提醒；最后一个运行中的直接 child 停止后，该提醒会恢复。tree row 在 child catalog 缺席、加载中或失败时保持可展开，只有 catalog 成功加载为空后才成为已知叶子。加载时显示通用提示，不会从 summary 生成占位 row。tree 会呈现 continuable 与 one-shot row；one-shot 的可选 label 缺失时，回退到其 Session id。
+直接 catalog 有子项或读取失败时显示 child 数量控件；空目录缺席、加载中或成功读取为空时均隐藏该控件。普通会话会用斜杠分隔当前 title 和该控件。每一级 subagent 面包屑都将紧凑的 12px title 与固定显示的双向箭头组合成一个控件：当前面包屑使用主标签颜色和 500 字重，祖先则使用三级标签颜色和 400 字重。悬停组合控件 150ms 后会打开其直接 parent 目录；浮层菜单具有短暂的跨越宽限时间，ArrowDown 保留为键盘入口。点击祖先会取消待触发的悬停、关闭已打开的目录，并且只向上导航。每个直接 parent 目录都可切换 sibling，并会加粗其选中行；目录 label 优先于可选的会话摘要 title，缺失的切换器目录在交互时加载。只有当前 subagent 会追加自己的直接 child 数量控件。过长的 title 会在固定箭头之前截断。触发器报告直接 catalog 的总数与运行数。普通侧边栏 row 隐藏 origin 为 subagent 的 Session，并从同一份已加载 catalog map 读取直接运行 child 数；Session summary 提供 activity，但绝不创建 membership。运行中的直接 child 使用共享的三级灰色 ongoing loading。待处理交互优先于 parent 的运行中状态；二者无论哪一项存在都会保持为主要状态，而直接 child activity 则成为悬停与无障碍状态中的第二项。普通 Workspace 行存在待处理的审批、计划审阅或问题时，会用紧凑的「待批准」「计划待审」或「待回答」替换相对时间；悬停与无障碍详情仍保留完整状态和相对时间。两种主要状态均不存在时，直接 child activity 优先于未查看的完成提醒；最后一个运行中的直接 child 停止后，该提醒会恢复。tree row 在 child catalog 缺席、加载中或失败时保持可展开，只有 catalog 成功加载为空后才成为已知叶子。加载时显示通用提示，不会从 summary 生成占位 row。tree 会呈现 continuable 与 one-shot row；one-shot 的可选 label 缺失时，回退到其 Session id。
`running` 表示子 Agent driver 正在处理工作；`inactive` 表示该 driver 空闲或不存在。Session 列表基线与状态事件提供活动状态，移除事件将完成的子代理标为 inactive 并保留其展示 projection。共享的父 `subagentCatalog` projection 提供成员关系。初始读取与推送值进入同一个 projection store，较新序号优先。[projection 消费决策](../simplification/2026-09-08-web-subagent-catalog-projections.zh.md) 说明加载、重连与同步取舍。提示词响应仍是投递时的权威依据。
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-sticky-collapsible-headers.i18n.yaml b/.agents/notes/implemented/feature/2026-08-03-web-sticky-collapsible-headers.i18n.yaml
deleted file mode 100644
index 9ae953b44a..0000000000
--- a/.agents/notes/implemented/feature/2026-08-03-web-sticky-collapsible-headers.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
-# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-08-03-web-sticky-collapsible-headers.md
-2026-08-03-web-sticky-collapsible-headers.md: 5bbe91681e656a8278b9d65f12e20a4d9dc779d0
-2026-08-03-web-sticky-collapsible-headers.zh.md: c75846fa7f5ca1088dab530b63243553e50f9579
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-sticky-collapsible-headers.md b/.agents/notes/implemented/feature/2026-08-03-web-sticky-collapsible-headers.md
deleted file mode 100644
index 5bbe91681e..0000000000
--- a/.agents/notes/implemented/feature/2026-08-03-web-sticky-collapsible-headers.md
+++ /dev/null
@@ -1,41 +0,0 @@
-# Agent Note: Web sticky collapsible headers — Think and compaction toggles pin while scrolling
-
-Status: implemented
-
-English | [中文](2026-08-03-web-sticky-collapsible-headers.zh.md)
-
-## Problem
-
-Two conversation blocks render their expanded body uncapped, flowing with the page instead of scrolling inside a bounded surface: the Web Think row (`.thinkBody`) and the compaction marker (`.compactionBody`). Every other tool row caps its body and scrolls it inside its own card, so its disclosure header stays visible. The two uncapped blocks do not. A long chain of thought or a long compaction summary carries its own disclosure header off the top of the viewport, so a reader who wants to collapse the block again must scroll the full body back up to reach the toggle.
-
-## Decision
-
-The disclosure header of each uncapped block sticks to the conversation scroll container's top while the block is open. The header remains in normal flow when collapsed, so a collapsed block scrolls away like any other row.
-
-Both blocks already scroll against the shared conversation scroll container (`[data-conversation-scroll]`), not an inner box, so `position: sticky; top: 0` on the header pins it against that container. A base-token background masks the prose that scrolls under the pinned header.
-
-The pinned header's stacking rank differs by block, because their bodies differ. The Think body uses [compact Markdown](../bug-fix/2026-09-17-thinking-markdown.md) with code banners in normal flow, so `z-index: 1` suffices. The compaction body renders markdown, and a fenced code block in the summary pins its own banner at `z-index: 6` (`packages/client/ui-primitives/src/markdown/CodeBlock.module.css`) with a Copy control inside it; the compaction header therefore uses `z-index: 7` and holds that banner below its own band, so the header never covers the Copy control and the banner never covers the toggle. The band's height is one component-local measurement (`--dsh-compaction-header-height` on `.compactionRow`) shared by the toggle's `height` and the banner's `top`; the banner rule wins over CodeBlock's `top: 0` by specificity, because the two sheets load in their own packages. The pinned header also overrides its hover fill to the opaque `--dsw-alias-interactive-bg-hover-solid` token and squares its corners for as long as the row is open: the default translucent hover token would let the scrolling prose show through the moment the pointer lands on the toggle, and the base 6px radius would leave the same prose visible at the corners. `:hover` raises the rule's specificity above the later base hover rule, so declaration order does not decide the winner. Two other elements take `z-index: 7` to clear the same code banners: the composer seat and the turn-navigation rail slot (`TurnNavigator.module.css`, ui-chat). Their order among equal ranks is stated once, in the composer seat's comment (`packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css`).
-
-The rules are scoped so only the two uncapped blocks are affected; the capped tool rows keep their existing behavior, since stacking sticky headers across a run of tool rows would pile them at the top. The Think rule is `packages/client/ui-chat/src/client/chat/ReasoningRow.module.css` `.root[data-expanded] [data-open] [data-disclosure-row]` — gated on `DisclosureRow`'s `data-open` so a collapsed Think row never sticks, and scoped under the Think row's own root so no tool-call variant is touched. The compaction rule is `packages/client/ui-chat/src/client/chat/MessageItem.module.css` `.compactionRow:has(.compactionBody) .compactionButton` — the body sibling exists in the DOM only while open, so `:has()` gates the stick on the open state.
-
-No session, wire, durable event, or model-visible contract changes; this is a presentation-only CSS change owned by the existing components.
-
-## Alternatives considered
-
-**Cap the two bodies with `max-height` + internal scroll, matching the tool cards.** Rejected: the Think body is deliberately uncapped so reasoning reads as ordinary message prose ([web-thinking-tail-scroll](../../archived/feature/2026-08-02-web-thinking-tail-scroll.md) and the `.thinkBody` comment own that intent), and the compaction summary is a reading surface. An inner scrollport introduces nested scrolling — the wheel switches from page to box under the cursor — and compresses long technical prose into a small window that is worse to read. Sticky headers keep the flowing-prose reading model and still keep the toggle reachable.
-
-**Add sticky headers to every collapsible row for consistency.** Rejected: the capped tool rows already keep their header visible because their body scrolls internally, so they have no problem to solve. Making their headers sticky against the page would stack one pinned header per open row at the top of the viewport during a scroll through a run of tool calls, which is visual noise, not consistency.
-
-**Offset the summary's code banner from `CodeBlock` rather than from the compaction rule.** Rejected: `CodeBlock` could read a property such as `--dsl-code-block-banner-top` that this consumer sets, which would leave the code block the owner of its own geometry and avoid a `:has()` selector reaching into another package's DOM. It also routes every consumer's layout through a property only this block sets, and the offset is this block's presentation concern rather than the code block's: the local rule states the offset beside the toggle that creates it, and `[data-code-block-banner]` is the hook `CodeBlock` already publishes for owner styling.
-
-**A shared sticky rule on the `DisclosureRow` primitive.** Rejected: `DisclosureRow` backs Think, every tool-call variant, and the context-injection row; a rule there would hit the capped rows too. The behavior belongs only to the uncapped consumers, so each scopes the rule to its own block.
-
-## Consequences
-
-The collapse toggle for a long Think block or compaction summary stays reachable without scrolling the body back to its start, while both bodies keep flowing as page prose. The change is CSS-only: no timer, subscription, durable state, DOM structure change, or transport traffic. The compaction rule uses the CSS `:has()` selector, supported across the browsers the Web UI targets.
-
-## Testing
-
-The unit specs pin the DOM anchors the selectors key on: `packages/client/ui-chat/tests/reasoning-row.client.spec.tsx` asserts an open Think row nests `[data-disclosure-row]` under `[data-variant='think'][data-expanded] [data-open]` and that a collapsed row has no `[data-open]`; `packages/client/ui-chat/tests/chat-branch-tails.client.spec.tsx` asserts the compaction body appears under `.compactionRow` only while open. `packages/client/ui-chat/tests/sticky-header-styles.client.spec.ts` reads the rules as CSS text and pins the declarations the pinning depends on: `position: sticky`, `top: 0`, the square corners, the `z-index` rank of each side, the single measurement shared by the toggle's height and the code banner's offset, and the opaque hover token, because jsdom computes no sticky layout and the render specs cannot fail on a changed declaration.
-
-The real-browser evidence is two keyless Chromium e2e paths. `apps/web/tests/lifecycle-chrome.e2e.ts` expands the settled turn's process row, opens the Think row, and asserts its header computes `position: sticky`, `top: 0px` (and is not sticky while collapsed); that fixture's recorded reasoning is a single line, too short to overflow, so it proves only that the CSS resolves onto the Think header. `apps/web/tests/seeded-history.e2e.ts` carries the pinned-while-scrolling evidence: it seeds a compaction whose summary length this suite controls (a fenced code block plus 40 list items), shrinks the viewport to force overflow, scrolls the marker into its pinned state, and asserts the header computes `position: sticky`, `top: 0px`, a `z-index` greater than the code block banner's, that it holds at the scrollport top after the scroll, that its own center is the topmost hit-tested element (the toggle stays clickable), and that its hover fill stays fully opaque (alpha 1). The same case scrolls the summary's code banner into its own stuck position and asserts the banner stops below the toggle's band and that the banner's Copy control owns its center, so the offset cannot regress into a covered control. The case also writes a keyless geometry golden (`snapshots/web/seeded-history/sticky-geometry.expected.md`) fixing these platform-independent semantic facts, since this is a user-visible CSS behavior that changes no DOM and no accessible name, so the aria goldens cannot capture it. The PR demo GIF, recorded against a real server and a real model round, carries the visual evidence that the pinned header stays at the top while the body scrolls.
diff --git a/.agents/notes/implemented/feature/2026-08-03-web-sticky-collapsible-headers.zh.md b/.agents/notes/implemented/feature/2026-08-03-web-sticky-collapsible-headers.zh.md
deleted file mode 100644
index c75846fa7f..0000000000
--- a/.agents/notes/implemented/feature/2026-08-03-web-sticky-collapsible-headers.zh.md
+++ /dev/null
@@ -1,41 +0,0 @@
-# Agent Note：Web 可折叠块的钉住标题 —— Think 与压缩标记的折叠按钮在滚动时钉住
-
-Status: implemented
-
-[English](2026-08-03-web-sticky-collapsible-headers.md) | 中文
-
-## 问题
-
-会话里有两个块的展开正文不封顶，随整页滚动，而不是在有界的表面内部滚动：Web Think 行（`.thinkBody`）和压缩标记（`.compactionBody`）。其他每个工具行都给正文封顶并在自己的卡片内部滚动，所以折叠标题始终可见。这两个不封顶的块做不到。一段很长的思维链或很长的压缩摘要会把自己的折叠标题顶出视口上方，想再次折叠该块的读者必须把整段正文滚回顶部才能够到折叠按钮。
-
-## 决策
-
-每个不封顶块的折叠标题在块展开时钉在会话滚动容器的顶部。折叠时标题保持在正常文档流中，所以折叠的块会像其他行一样滚走。
-
-这两个块本来就是相对共享的会话滚动容器（`[data-conversation-scroll]`）滚动，而非某个内层框，所以在标题上加 `position: sticky; top: 0` 就把它钉在该容器上。一个 base token 背景遮住在钉住的标题下方滚过的正文。
-
-钉住的标题的层叠级别按块而异，因为两者正文不同。Think 正文使用[紧凑 Markdown](../bug-fix/2026-09-17-thinking-markdown.zh.md)，代码栏处于正常文档流中，`z-index: 1` 就够。压缩正文渲染 markdown，摘要里的围栏代码块会把自己的 banner 钉在 `z-index: 6`（`packages/client/ui-primitives/src/markdown/CodeBlock.module.css`），banner 里带一个 Copy 控件；因此压缩标题用 `z-index: 7`，并让那个 banner 停在自己的标题带下方，这样标题永远不会盖住 Copy 控件，banner 也不会盖住折叠按钮。标题带高度是一个组件局部量（`.compactionRow` 上的 `--dsh-compaction-header-height`），由折叠按钮的 `height` 与 banner 的 `top` 共用；banner 规则靠特异性压过 CodeBlock 的 `top: 0`，因为两张样式表分属不同的包。钉住的标题还把 hover 底覆盖为不透明的 `--dsw-alias-interactive-bg-hover-solid` token，并在整行展开期间都保持直角：默认的半透明 hover token 会在指针落到折叠按钮准备折叠的瞬间让滚动的正文透出，而基础的 6px 圆角会让同样的正文在四角露出来。`:hover` 把该规则的特异性抬到文件更靠后的 hover 基础规则之上，所以胜负不由声明顺序决定。另外还有两个元素为了避开同一批代码 banner 取 `z-index: 7`：输入框座与轮次导航轨道槽（`TurnNavigator.module.css`，ui-chat）。同级之间的先后顺序只写在一处：`packages/client/ui-conversation/src/client/skeleton/ConversationRoot.module.css` 中输入框座的注释。
-
-规则被限定作用域，只影响这两个不封顶的块；封顶的工具行保持原有行为，因为让一连串工具行的 sticky 标题层层堆叠会把它们全挤在顶部。Think 规则是 `packages/client/ui-chat/src/client/chat/ReasoningRow.module.css` 的 `.root[data-expanded] [data-open] [data-disclosure-row]`，用 `DisclosureRow` 的 `data-open` 门控，折叠的 Think 行绝不钉住，并限定在 Think 行自己的 root 之下，不触及任何工具调用 variant。压缩规则是 `packages/client/ui-chat/src/client/chat/MessageItem.module.css` 的 `.compactionRow:has(.compactionBody) .compactionButton`，正文兄弟节点只在展开时存在于 DOM，所以 `:has()` 就以展开状态门控钉住。
-
-不改动任何 session、wire、durable event 或 model-visible 契约；这是一处纯展示层的 CSS 改动，由既有组件拥有。
-
-## 曾考虑的替代方案
-
-**用 `max-height` 加内部滚动给这两个正文封顶，与工具卡片一致。** 否决：Think 正文是刻意不封顶的，好让推理读起来像普通消息正文（[web-thinking-tail-scroll](../../archived/feature/2026-08-02-web-thinking-tail-scroll.md) 和 `.thinkBody` 注释拥有这一意图），压缩摘要是一个阅读表面。内层滚动框会引入嵌套滚动，滚轮在光标下从整页切换到框内，并把很长的技术性正文压进一个更难读的小窗口。钉住标题保留了流式正文的阅读模型，同时让折叠按钮依然够得着。
-
-**为一致性给每个可折叠行都加钉住标题。** 否决：封顶的工具行因为正文在内部滚动，标题本来就一直可见，没有需要解决的问题。让它们的标题相对整页钉住，会在滚过一连串工具调用时把每个展开行各自钉住的标题堆叠在视口顶部，这是视觉噪音，不是一致性。
-
-**把摘要内代码栏的偏移交给 `CodeBlock` 承担。** 否决：可以让 `CodeBlock` 读取使用方设置的 `--dsl-code-block-banner-top` 之类的属性，这样代码块继续拥有自己的几何，也避免用 `:has()` 选择器伸进另一个包的 DOM。代价是把所有使用方的布局都接到一个只有这个块会设置的属性上，而这段偏移是这个块的呈现问题、不是代码块的：局部规则把偏移写在造成它的折叠按钮旁边，而 `[data-code-block-banner]` 本来就是 `CodeBlock` 为使用者样式发布的钩子。
-
-**在 `DisclosureRow` 基元上加一条共享的 sticky 规则。** 否决：`DisclosureRow` 支撑 Think、每个工具调用 variant 以及 context-injection 行；在那里加规则会一并命中封顶行。该行为只属于不封顶的消费者，所以各自把规则限定在自己的块上。
-
-## 后果
-
-很长的 Think 块或压缩摘要的折叠按钮无需把正文滚回起点就能够到，同时两个正文都保持作为整页正文流动。改动是纯 CSS：没有计时器、订阅、durable state、DOM 结构改动或传输流量。压缩规则使用 CSS `:has()` 选择器，Web UI 所面向的各浏览器均支持。
-
-## 测试
-
-单元测试钉住选择器所依赖的 DOM 锚点：`packages/client/ui-chat/tests/reasoning-row.client.spec.tsx` 断言展开的 Think 行在 `[data-variant='think'][data-expanded] [data-open]` 之下嵌套了 `[data-disclosure-row]`，且折叠行没有 `[data-open]`；`packages/client/ui-chat/tests/chat-branch-tails.client.spec.tsx` 断言压缩正文只在展开时出现在 `.compactionRow` 之下。`packages/client/ui-chat/tests/sticky-header-styles.client.spec.ts` 把这两条规则当作 CSS 文本读取，逐条固定钉住所依赖的声明：`position: sticky`、`top: 0`、直角圆角、两侧各自的 `z-index` 级别、折叠按钮高度与代码 banner 偏移共用的那一个量，以及不透明的 hover token——因为 jsdom 不计算 sticky 布局，渲染类测试也无法在某条声明被改动时变红。
-
-真实浏览器证据由两条 keyless Chromium e2e 路径承载。`apps/web/tests/lifecycle-chrome.e2e.ts` 展开已结束轮次的 process 行、展开 Think 行，并断言其标题计算出 `position: sticky`、`top: 0px`（折叠时非 sticky）；该 fixture 录制的 reasoning 只有一行，太短不足以溢出，所以它只证明 CSS 解析到了 Think 标题。`apps/web/tests/seeded-history.e2e.ts` 承载「钉住态随滚动」的证据：它种入一个摘要长度由本套件控制的压缩（一个围栏代码块加 40 个列表项），把视口压小以强制溢出，滚动到 marker 的钉住态，断言标题计算出 `position: sticky`、`top: 0px`、`z-index` 大于代码块 banner、滚动后仍停在滚动口顶边、其自身中心是命中测试命中的最上层元素（折叠按钮保持可点击），以及其 hover 底保持完全不透明（alpha 1）。同一用例还把摘要里的代码 banner 滚到它自己的钉住位置，断言 banner 停在标题带下方、且 banner 的 Copy 控件在它的中心点命中自身，使这条偏移不会退化成控件被盖住。同一用例还写出一份 keyless 几何 golden（`snapshots/web/seeded-history/sticky-geometry.expected.md`），把这些与平台无关的语义事实固定下来，因为这是一处用户可见、但不改动 DOM 与无障碍名称的 CSS 行为，无障碍 golden 捕获不到它。PR demo GIF 用真实服务器加真实模型轮次录制，承载视觉证据：钉住的标题在正文滚动时停留在顶部。
diff --git a/.agents/notes/implemented/feature/2026-09-04-web-clickable-link-styles.md b/.agents/notes/implemented/feature/2026-09-04-web-clickable-link-styles.md
deleted file mode 100644
index c4e506294c..0000000000
--- a/.agents/notes/implemented/feature/2026-09-04-web-clickable-link-styles.md
+++ /dev/null
@@ -1,35 +0,0 @@
-# Agent Note: Web clickable-link language — link alias, dotted hover underline, category glyphs
-
-Status: implemented
-
-English | [中文](2026-09-04-web-clickable-link-styles.zh.md)
-
-## Problem
-
-Clickable artifact links in the chat transcript wore four different costumes: markdown anchors and prose file mentions were business-primary blue with a solid hover underline, web search/fetch links matched that pair, produced-file chips were grey pills (label-secondary text on interactive-bg-hover, 96px max width), and workflow member links carried a resting solid underline. Nothing marked what a link opens (browser, host app, Finder, in-app view), and link color was coupled to `--dsw-alias-state-business-primary`, which also drives focus rings and state dots, so tuning link color risked unrelated surfaces.
-
-## Decision
-
-One link language across the transcript's clickable-link surfaces — markdown anchors (including reference links, mailto, and URL-promoted inline code), prose file mentions, web search source links and the fetch URL, produced-file chips, and workflow member links:
-
-- Color comes through a dedicated `--dsw-alias-link` alias in `design-platform.css` (light `deepseek-500`, dark `deepseek-400`), decoupled from `state-business-primary`; links render at `font-weight: 500` with no underline at rest and `underline dotted` at 3px offset on hover/focus.
-- A leading category glyph — the new `LinkIcon` in ui-primitives with kinds `url`, `folder`, `code`, `image`, `document`, and `other` (paper) — renders `currentColor` only; the `url` glyph is the globe, or the destination site's own mark when its host is a known site ([known-site link marks](2026-09-16-known-site-link-marks.md)); `classifyLinkPath` folds the [shared detailed file-type classification](2026-09-08-shared-file-type-icons.md) into those six link categories, and code, web, and data extensions share the code glyph by design. Two anchor shapes carry no glyph: workflow member links (an in-app member view fits no file or URL category) and anchors wrapping only images (a badge or thumbnail — a dangling globe beside the picture leads no text). Inline glyphs sit at 1.1em with a −0.25em baseline offset; the flex-centered produced-file glyphs instead nudge 1.2px down because the 22px text box carries its glyphs below box center.
-- Produced-file chips drop the grey pill and the 96px cap: plain link-blue text at natural width that shrinks with ellipsis only when the row overflows; the container-query bands still budget 96px per chip when choosing how many chips to show.
-- [Compact Thinking Markdown](../bug-fix/2026-09-17-thinking-markdown.md) retains tertiary text color and a resting dotted underline to preserve secondary emphasis.
-- Deliberately untouched: ToolRow's grey dotted file links, and the grey "Show in folder" action (it gains the folder glyph but keeps its grey style).
-- In the same pass, the inline-code chip tint moved from `neutral-bluish-100` to `neutral-50` (dark: `neutral-800`) and gained a 0.5px l1 border.
-
-Coverage: a LinkIcon unit spec (one distinct glyph per kind, classification table), refreshed markdown-dom fixtures, and the `clickable-links-gallery` web e2e — one settled keyless turn rendering every clickable link form — registered in the host compiler face (`tsconfig.host.json`) like its other scaffold-importing siblings.
-
-## Alternatives considered
-
-- **Colored Word/Excel/PPT/PDF link glyphs.** Rejected: fixed brand fills break the icon set's currentColor-only rule, so those extensions fold into the single outline `document` glyph. The larger file-card primitive uses distinct current-color silhouettes instead.
-- **Per-extension link icons.** Collapsed to six categories: more glyphs than the eye can parse at 14px adds noise. The 28px `FileTypeIcon` owns the more detailed file identities, and per-site marks live behind the same `url` category ([known-site link marks](2026-09-16-known-site-link-marks.md)).
-- **Keeping links on `state-business-primary`.** Darker link blues (blue-600/650/700 were auditioned and reverted) would have dragged focus rings and state dots along; the dedicated alias localizes any future tuning to one line.
-- **Glyphs on ToolRow path links.** Rejected: tool rows keep their quieter grey dotted affordance, and leading glyphs there would stack icons in already dense rows.
-
-## Consequences
-
-- A new clickable artifact surface should consume `--dsw-alias-link` and the LinkIcon vocabulary rather than introduce another color or underline form; the rule lives in [docs/web-styling.md](../../../../docs/web-styling.md).
-- Long produced-file names take their natural width; when a row overflows, flex shrinks all chips proportionally, so several long names shrink together instead of the last one yielding first.
-- mailto links currently share the `url` globe; a distinct mail category is a one-line addition if ever wanted.
diff --git a/.agents/notes/implemented/feature/2026-09-04-web-clickable-link-styles.zh.md b/.agents/notes/implemented/feature/2026-09-04-web-clickable-link-styles.zh.md
deleted file mode 100644
index 01258674b4..0000000000
--- a/.agents/notes/implemented/feature/2026-09-04-web-clickable-link-styles.zh.md
+++ /dev/null
@@ -1,35 +0,0 @@
-# Agent Note: Web 可点击链接语言——链接别名、hover 点状下划线、分类图标
-
-Status: implemented
-
-[English](2026-09-04-web-clickable-link-styles.md) | 中文
-
-## 问题
-
-会话记录里的可点击产物链接有四套互不一致的样式：Markdown 锚点和正文文件引用是 business-primary 蓝加 hover 实线下划线，网页搜索/抓取链接与之相同，产物 chips 是灰色药丸（interactive-bg-hover 底上的 label-secondary 文字，96px 最大宽度），workflow 成员链接则带常驻实线下划线。没有任何标记说明链接点开后去哪儿（浏览器、宿主应用、Finder、应用内视图），而且链接颜色耦合在 `--dsw-alias-state-business-primary` 上——它同时驱动焦点环和状态点，调链接色会波及无关表面。
-
-## 决策
-
-会话记录的可点击链接表面——Markdown 锚点（含引用式链接、mailto、被提升为链接的 inline code）、正文文件引用、网页搜索来源链接与抓取 URL、产物 chips、workflow 成员链接——统一为一套链接语言：
-
-- 颜色经由 `design-platform.css` 中专用的 `--dsw-alias-link` 别名（亮色 `deepseek-500`，暗色 `deepseek-400`），与 `state-business-primary` 解耦；链接以 `font-weight: 500` 呈现，默认无下划线，hover/focus 时为 3px offset 的 `underline dotted`。
-- 前置分类图标——ui-primitives 新增的 `LinkIcon`，kind 为 `url`、`folder`、`code`、`image`、`document`、`other`（纸张）——只渲染 `currentColor`；`url` 图形为地球，目的地主机属于已知站点时则为该站点自己的标记（[已知站点链接标记](2026-09-16-known-site-link-marks.zh.md)）；`classifyLinkPath` 把[共享精细文件类型分类](2026-09-08-shared-file-type-icons.zh.md)折叠进这六种链接类别，代码、网页、数据扩展名按设计共用 code 图形。两类锚点不带图标：workflow 成员链接（应用内成员视图不属于任何文件或 URL 类别）和只包图片的锚点（徽章或缩略图——图片旁悬着的地球没有可引导的文字）。行内图标为 1.1em、基线偏移 −0.25em；flex 居中的产物图标则下移 1.2px，因为 22px 文字盒的字形低于盒中心。
-- 产物 chips 去掉灰色药丸和 96px 上限：纯链接蓝文字按自然宽度展示，仅当整行溢出时才收缩出省略号；容器查询档位在决定展示几个 chip 时仍按每个 96px 预算。
-- [紧凑 Thinking Markdown](../bug-fix/2026-09-17-thinking-markdown.zh.md) 保留 tertiary 文字色和默认点状下划线，以保持次级强调。
-- 刻意不动：ToolRow 的灰色点线文件链接，以及灰色的「在文件夹中显示」操作（它获得文件夹图标但保持灰色样式）。
-- 同一批次中，inline code 底色从 `neutral-bluish-100` 换到 `neutral-50`（暗色：`neutral-800`），并新增 0.5px l1 描边。
-
-覆盖：LinkIcon 单测（每个 kind 一个独立图形、分类表）、刷新后的 markdown-dom 夹具，以及 `clickable-links-gallery` web e2e——一个 settled 的 keyless 回合渲染全部可点击链接形态——像其他引 scaffold 的同类一样注册进 host 编译面（`tsconfig.host.json`）。
-
-## 备选方案
-
-- **彩色 Word/Excel/PPT/PDF 链接图形。** 否决：固定品牌填充违反图标集 currentColor-only 规则，因此这些扩展名并入单一的 outline `document` 图形。较大的文件卡片 primitive 改用各自不同的 current-color 轮廓。
-- **每个扩展名一个链接图标。** 收敛为六个类别：14px 下超出肉眼可分辨数量的图形只会增加噪音。28px 的 `FileTypeIcon` 拥有更精细的文件身份；按站点标记位于同一 `url` 类别之下（[已知站点链接标记](2026-09-16-known-site-link-marks.zh.md)）。
-- **链接继续用 `state-business-primary`。** 更深的链接蓝（试过 blue-600/650/700 又回退）会连带焦点环和状态点；专用别名把未来的调色收敛到一行。
-- **给 ToolRow 路径链接加图形。** 否决：工具行保持更安静的灰色点线示能，在已经很密的行里加前置图形会造成图标堆叠。
-
-## 后果
-
-- 新的可点击产物表面应消费 `--dsw-alias-link` 和 LinkIcon 词汇，而不是引入另一种颜色或下划线形态；规则记录在 [docs/web-styling.md](../../../../docs/web-styling.zh.md)。
-- 长产物文件名按自然宽度展示；整行溢出时 flex 按比例收缩所有 chip，几个长名字一起收缩，而不是最后一个先让位。
-- mailto 链接目前共用 `url` 地球图形；若将来需要独立的邮件类别，一行即可加上。
diff --git a/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.i18n.yaml b/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.i18n.yaml
index a2f18c11cb..702e3bf1fc 100644
--- a/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.i18n.yaml
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.md
-2026-09-05-sidebar-text-preview-and-file-tree.md: 0142b325004a1fc018e944ed908d600e75f0ab0d
-2026-09-05-sidebar-text-preview-and-file-tree.zh.md: d40ca8c790c9a7208a2243422c0973fc293a5915
+2026-09-05-sidebar-text-preview-and-file-tree.md: 8ddb1a336307011d8f6ce9bbe927f00642a83e60
+2026-09-05-sidebar-text-preview-and-file-tree.zh.md: 294a2b456008837882f7f82e55e8e9e435254554
diff --git a/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.md b/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.md
index 0142b32500..8ddb1a3363 100644
--- a/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.md
+++ b/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.md
@@ -20,7 +20,7 @@ Three tab types ship with the Sidebar: the **guide** (`ui-sidebar-right`), the *
The guide is what a pane shows before it holds content. Its registration is `{ id: '@deepseek-ai/dsh-client-ui-sidebar-right/guide', kind: 'guide', priority: 'builtin', title }` with no `patterns`: a guide views nothing, so it is opened by kind through `openTab` and recorded under the page address `sidebar://guide`, which is the registry's bookkeeping and never composed by a caller. The tab's title is `开始` / `Start`, captured into the layout record when the pane is seeded, so a later language change relabels the type and not tabs already open.
-The body projects every registered type's `guide[]` in `order` through the registry's observable `guide()` list, so a type registering later appears without the guide knowing it. [Guide start page and stat pill refinements](2026-09-10-guide-start-page-and-stat-pill-refinements.md) owns the compass, optional descriptions, fallback glyph, and current capsule layout. Picking a capsule calls `tabActions.openTab(entry.kind, { replaceTab: true })`: the picked type opens in the guide's own tab, and the guide is gone. The guide is a doorway, not a page that stays open beside what it opened.
+The body projects every registered type's `guide[]` in `order` through the registry's observable `guide()` list, so a type registering later appears without the guide knowing it. The [Sidebar README](../../../../packages/client/ui-sidebar-right/README.md#the-guide) describes the compass, optional descriptions, fallback glyph, and current capsule layout. Picking a capsule calls `tabActions.openTab(entry.kind, { replaceTab: true })`: the picked type opens in the guide's own tab, and the guide is gone. The guide is a doorway, not a page that stays open beside what it opened.
The body is also the replacement seam. It renders the `sidebar.right.tab.guide` chain with the shipped guide as the chain's fallback, so a product that registers its own entry takes the whole body, and with no entry, or every entry declining, the shipped guide draws. Because the shipped guide is the fallback and not a chain entry, there is always exactly one body and it cannot be outvoted by accident.
@@ -48,7 +48,7 @@ A failed read keeps content already shown and adds a localized failure with a re
### The file tree
-`files` is a page type, not a viewer: it claims no address. Its registration is `{ kind: 'files', id: '@deepseek-ai/dsh-client-ui-sidebar-files', priority: 'builtin', title, guide: [{ order: 10, title, description, icon: FolderSheetGlyph }] }` — no `patterns`, because nothing navigates *to* a file tree by address; the guide's entry box opens the type itself. `FolderSheetGlyph` adapts the shared coloured folder sheet to the guide's requested glyph size; the [guide refinement](2026-09-10-guide-start-page-and-stat-pill-refinements.md) owns that presentation choice. `id` is the implementation's identity in the Tab system and doubles as the `key` of the body seat `sidebar.right.pane.tab`, so the same string names the type and the component that draws it. `register()` returns a disposer and goes through `ctx.effect`, as every registration does.
+`files` is a page type, not a viewer: it claims no address. Its registration is `{ kind: 'files', id: '@deepseek-ai/dsh-client-ui-sidebar-files', priority: 'builtin', title, guide: [{ order: 10, title, description, icon: FolderSheetGlyph }] }` — no `patterns`, because nothing navigates *to* a file tree by address; the guide's entry box opens the type itself. `FolderSheetGlyph` adapts the shared coloured folder sheet to the guide's requested glyph size; the [Sidebar README](../../../../packages/client/ui-sidebar-right/README.md#the-guide) describes that presentation rule. `id` is the implementation's identity in the Tab system and doubles as the `key` of the body seat `sidebar.right.pane.tab`, so the same string names the type and the component that draws it. `register()` returns a disposer and goes through `ctx.effect`, as every registration does.
The root is the session's working directory as the Host reports it in the session list (`useSessions().byId[sessionId].cwd`), labelled by `workspaceTitleOf` from `dsh-util-workspace-path` — the final non-empty path segment — with the root string itself as the label when the path is separator-only. A session without a working directory shows one line (`noWorkspace`) and issues no request. There is no root chooser and no way to browse upward: the Host's `list` refuses paths outside the Session's workspace root, so the one directory the client can list is the one it shows.
diff --git a/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.zh.md b/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.zh.md
index d40ca8c790..294a2b4560 100644
--- a/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.zh.md
@@ -20,7 +20,7 @@ Sidebar 随包交付三个 tab 类型：**引导页**（`ui-sidebar-right`）、
引导页是 pane 承载内容之前显示的东西。它的注册定义是 `{ id: '@deepseek-ai/dsh-client-ui-sidebar-right/guide', kind: 'guide', priority: 'builtin', title }`，没有 `patterns`：引导页不查看任何东西，所以经 `openTab` 按 kind 打开，并记在页地址 `sidebar://guide` 之下——那是注册表自己的记账，调用方从不拼它。tab 标题是 `开始` / `Start`，在 pane 播种时捕获进布局记录，于是之后切换语言只重标类型，不改已开着的 tab。
-正文按 `order` 从每个已注册类型的 `guide[]` 投影入口，并通过注册表可观察的 `guide()` 列表更新，因此后注册的类型无需引导页感知即可出现。[引导起始页与统计 pill 的细化](2026-09-10-guide-start-page-and-stat-pill-refinements.zh.md)负责罗盘、可选描述、兜底图标和当前胶囊布局。点选胶囊会调用 `tabActions.openTab(entry.kind, { replaceTab: true })`：被选的类型在引导页自己的 tab 里打开，引导页随之消失。引导页是一扇门，不是留在被打开者旁边的一页。
+正文按 `order` 从每个已注册类型的 `guide[]` 投影入口，并通过注册表可观察的 `guide()` 列表更新，因此后注册的类型无需引导页感知即可出现。[Sidebar README](../../../../packages/client/ui-sidebar-right/README.zh.md#the-guide)说明罗盘、可选描述、兜底图标和当前胶囊布局。点选胶囊会调用 `tabActions.openTab(entry.kind, { replaceTab: true })`：被选的类型在引导页自己的 tab 里打开，引导页随之消失。引导页是一扇门，不是留在被打开者旁边的一页。
体同时也是替换接缝。它渲染 `sidebar.right.tab.guide` 链，并以随包交付的引导页作为链的 fallback，于是注册了自己入口的产品接管整个体，而没有入口、或每个入口都拒绝时，随包交付的引导页照常绘制。因为随包交付的引导页是 fallback 而不是链上的一个入口，所以永远恰有一个体，也不可能被意外投掉。
@@ -48,7 +48,7 @@ store 是 Slot 标准件：每会话一个独占实例，按 tab id 分桶，持
### 文件树
-`files` 是页类型，不是查看器：它不认领任何地址。注册定义是 `{ kind: 'files', id: '@deepseek-ai/dsh-client-ui-sidebar-files', priority: 'builtin', title, guide: [{ order: 10, title, description, icon: FolderSheetGlyph }] }`——没有 `patterns`，因为没有谁按地址导航*到*一棵文件树；引导页的入口框打开的是类型本身。`FolderSheetGlyph` 把共享的彩色文件夹页适配到引导页请求的图标尺寸；[引导页细化记录](2026-09-10-guide-start-page-and-stat-pill-refinements.zh.md)负责这项展示选择。`id` 是这个实现在 Tab 系统里的唯一键，同时也是体坑位 `sidebar.right.pane.tab` 的 `key`，于是同一个串既命名类型也命名画它的组件。`register()` 返回 disposer 并经 `ctx.effect` 注册，与所有注册一致。
+`files` 是页类型，不是查看器：它不认领任何地址。注册定义是 `{ kind: 'files', id: '@deepseek-ai/dsh-client-ui-sidebar-files', priority: 'builtin', title, guide: [{ order: 10, title, description, icon: FolderSheetGlyph }] }`——没有 `patterns`，因为没有谁按地址导航*到*一棵文件树；引导页的入口框打开的是类型本身。`FolderSheetGlyph` 把共享的彩色文件夹页适配到引导页请求的图标尺寸；[Sidebar README](../../../../packages/client/ui-sidebar-right/README.zh.md#the-guide)说明这项展示规则。`id` 是这个实现在 Tab 系统里的唯一键，同时也是体坑位 `sidebar.right.pane.tab` 的 `key`，于是同一个串既命名类型也命名画它的组件。`register()` 返回 disposer 并经 `ctx.effect` 注册，与所有注册一致。
根是 Host 在会话列表里上报的会话工作目录（`useSessions().byId[sessionId].cwd`），标签由 `dsh-util-workspace-path` 的 `workspaceTitleOf` 给出——路径最后一个非空段——路径只有分隔符时用根串本身作标签。没有工作目录的会话只显示一行（`noWorkspace`），不发请求。没有根选择器，也不能往上浏览：Host 的 `list` 拒绝会话工作区根之外的路径，所以客户端能列的那一个目录就是它显示的目录。
diff --git a/.agents/notes/implemented/feature/2026-09-07-composer-session-stats-pills.i18n.yaml b/.agents/notes/implemented/feature/2026-09-07-composer-session-stats-pills.i18n.yaml
index a84c4d396a..0c2c513623 100644
--- a/.agents/notes/implemented/feature/2026-09-07-composer-session-stats-pills.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-07-composer-session-stats-pills.i18n.yaml
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-07-composer-session-stats-pills.md
-2026-09-07-composer-session-stats-pills.md: 22f78dfdde854baaf1ced8c20c55042952df8c26
-2026-09-07-composer-session-stats-pills.zh.md: 6b71c6e7cf03cbd32fa4da9edf38f6aa4814310c
+2026-09-07-composer-session-stats-pills.md: d165aab471bc5958cb7a0b287d278a0ae48485ee
+2026-09-07-composer-session-stats-pills.zh.md: dac136d4e60e50b026ed082eb7a006a80059c328
diff --git a/.agents/notes/implemented/feature/2026-09-07-composer-session-stats-pills.md b/.agents/notes/implemented/feature/2026-09-07-composer-session-stats-pills.md
index 22f78dfdde..d165aab471 100644
--- a/.agents/notes/implemented/feature/2026-09-07-composer-session-stats-pills.md
+++ b/.agents/notes/implemented/feature/2026-09-07-composer-session-stats-pills.md
@@ -12,7 +12,8 @@ The session stats strip under the composer (`StatsLine`, ui-chat, mounted on `co
`StatsPills` (packages/client/ui-chat/src/client/chat/StatsPills.tsx) replaces `StatsLine` on the same `conversation.composer.dock` slot; the losing variant is deleted, its shared helpers (`deriveStats`, `formatDuration`, `cacheHitPercent`, `billedInputTokens`) absorbed into the new module, and the dead `stats.llm`, `stats.toolCall`, `stats.ttftAverage`, `stats.tokensPerSecond`, and `stats.tokens` locale keys removed.
-- **Two icon pills, two dialogs.** A gauge pill (new `IconGaugeOutline16`, dial center optically dropped to y=8.75 because the bottom-open arc reads high) shows `{turns} 轮 {steps} 步` plus output TPS and click-opens the 会话统计 dialog (LLM time, tool time, average TTFT, TPS); a log with no timed figure would open an empty dialog, so that pill renders as a static reading instead of a button. A database pill (`IconDatabaseOutline16`) shows the compact billed total plus cache-hit share and click-opens the Token 用量 dialog (cache hit, uncached input, cache read, output, and cache write when non-zero — exact counts). Both dialogs wear the shared `stat-dialog` module (portal panel, anchored placement, outside-dismiss, optionally externally owned open state) extracted for exactly this two-consumer split; the pills row owns one exclusive open slot, so opening either dialog closes the other, and each button carries an explicit `aria-label` that separates with ` · ` the segments the aria-hidden sep glyph joins visually. [Guide start page and stat pill refinements](2026-09-10-guide-start-page-and-stat-pill-refinements.md) owns the zero cache-write omission.
+- **Two icon pills, two dialogs.** A gauge pill (new `IconGaugeOutlineRegular`, dial center optically dropped to y=8.75 because the bottom-open arc reads high) shows `{turns} 轮 {steps} 步` plus output TPS and click-opens the 会话统计 dialog (LLM time, tool time, average TTFT, TPS); a log with no timed figure would open an empty dialog, so that pill renders as a static reading instead of a button. A database pill (`IconDatabaseOutlineRegular`) shows the compact billed total plus cache-hit share and click-opens the Token 用量 dialog (cache hit, uncached input, cache read, output, and cache write when non-zero — exact counts). Both dialogs wear the shared `stat-dialog` module (portal panel, anchored placement, outside-dismiss, optionally externally owned open state) extracted for exactly this two-consumer split; the pills row owns one exclusive open slot, so opening either dialog closes the other, and each button carries an explicit `aria-label` that separates with ` · ` the segments the aria-hidden sep glyph joins visually. [StatsPills](../../../../packages/client/ui-chat/src/client/chat/StatsPills.tsx) owns the zero cache-write omission.
+- **Shared information tier.** Composer stats and per-turn tail metadata use the secondary font size minus one pixel. Assistant-tail metadata uses the action icons' tertiary label color and starts after an extra 8px separation from the action cluster.
- **Data sourcing is unchanged in architecture.** Counts and times prefer the durable `sessionStats` projection with the window fold as the assembly-without-the-unit fallback ([whole-session counts](../../archived/bug-fix/2026-08-12-full-session-turn-step-counts.md)); token figures ride `tokenUsage` only, so an absent projection drops the usage pill rather than showing window-derived billing. Cache writes stay in the billed total and the cache-hit denominator ([projection decision](../architecture/2026-07-29-projected-token-usage-and-request-context.md)). Context occupancy remains owned by ui-conversation's `ContextMeter`, with its ring and percentage after the two stats pills below the input card. The common dock groups statistics together and leaves the toolbar for input actions; ui-chat does not import the context component. The context panel renders through a portal and uses ui-primitives for viewport-clamped positioning and outside-pointer dismissal, including when the statistics contribution is absent.
- **Render discipline.** The row folds settled nodes only (`chat.legacy.nodes` identity), so streaming chunk frames cause zero rerenders — pinned by a render-count unit test. A session with no closed step and no billed tokens renders nothing.
- **The composer owns dock spacing.** `InputBar` places slot contributions and `ContextMeter` in one centered flex row, supplies 4px above the dock and 4px below it even when the slot has no visible contribution. The hero keeps no bottom padding and hides its empty dock. `StatsPills` supplies shrinkable time and billing content; it does not claim the full row width or add outer padding.
diff --git a/.agents/notes/implemented/feature/2026-09-07-composer-session-stats-pills.zh.md b/.agents/notes/implemented/feature/2026-09-07-composer-session-stats-pills.zh.md
index 6b71c6e7cf..dac136d4e6 100644
--- a/.agents/notes/implemented/feature/2026-09-07-composer-session-stats-pills.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-07-composer-session-stats-pills.zh.md
@@ -12,7 +12,8 @@ Status: implemented
`StatsPills`（packages/client/ui-chat/src/client/chat/StatsPills.tsx）在同一 `conversation.composer.dock` 插槽上取代 `StatsLine`；落选变体已删除，其共享工具函数（`deriveStats`、`formatDuration`、`cacheHitPercent`、`billedInputTokens`）并入新模块，废弃的 `stats.llm`、`stats.toolCall`、`stats.ttftAverage`、`stats.tokensPerSecond`、`stats.tokens` 文案键一并移除。
-- **两个图标 pill、两个弹层。** 仪表盘 pill（新增 `IconGaugeOutline16`，因下开口圆弧视觉偏高而把表盘中心光学下移到 y=8.75）展示 `{turns} 轮 {steps} 步` 加输出 TPS，点击打开「会话统计」弹层（模型用时、工具调用用时、首 token 平均、输出速度）；日志里没有任何计时数字时弹层会是空的，此时该 pill 渲染为静态读数而非按钮。数据库 pill（`IconDatabaseOutline16`）展示紧凑计费总量加缓存命中率，点击打开「Token 用量」弹层（缓存命中、未缓存输入、缓存读取、输出，以及非零时的缓存写入——精确计数）。两个弹层共用为这两处消费者抽出的 `stat-dialog` 模块（portal 面板、锚定定位、点击外部关闭、可选的外部持有开合状态）；pill 行持有唯一的互斥开合槽位，打开任一弹层即关闭另一个，且每个按钮携带显式 `aria-label`，用 ` · ` 分隔 aria-hidden 分隔符在视觉上连接的两段文本。[引导起始页与统计 pill 的细化](2026-09-10-guide-start-page-and-stat-pill-refinements.zh.md)负责缓存写入为零时省略该行的规则。
+- **两个图标 pill、两个弹层。** 仪表盘 pill（新增 `IconGaugeOutlineRegular`，因下开口圆弧视觉偏高而把表盘中心光学下移到 y=8.75）展示 `{turns} 轮 {steps} 步` 加输出 TPS，点击打开「会话统计」弹层（模型用时、工具调用用时、首 token 平均、输出速度）；日志里没有任何计时数字时弹层会是空的，此时该 pill 渲染为静态读数而非按钮。数据库 pill（`IconDatabaseOutlineRegular`）展示紧凑计费总量加缓存命中率，点击打开「Token 用量」弹层（缓存命中、未缓存输入、缓存读取、输出，以及非零时的缓存写入——精确计数）。两个弹层共用为这两处消费者抽出的 `stat-dialog` 模块（portal 面板、锚定定位、点击外部关闭、可选的外部持有开合状态）；pill 行持有唯一的互斥开合槽位，打开任一弹层即关闭另一个，且每个按钮携带显式 `aria-label`，用 ` · ` 分隔 aria-hidden 分隔符在视觉上连接的两段文本。[StatsPills](../../../../packages/client/ui-chat/src/client/chat/StatsPills.tsx)负责缓存写入为零时省略该行的规则。
+- **统一信息层级。** 输入框底部统计与单轮回答末尾信息都使用次级字号减 1px。回答末尾信息使用与操作图标一致的 tertiary 文字颜色，并与操作图标组额外拉开 8px。
- **数据来源架构不变。** 计数与用时优先读取持久的 `sessionStats` 投影，窗口折叠仅作无该单元装配时的回退（[全会话计数](../../archived/bug-fix/2026-08-12-full-session-turn-step-counts.md)）；token 数字只走 `tokenUsage`，投影缺席时直接不渲染用量 pill，而非展示窗口推算的计费。缓存写入仍计入计费总量与缓存命中分母（[投影决定](../architecture/2026-07-29-projected-token-usage-and-request-context.zh.md)）。上下文占用仍归 ui-conversation 的 `ContextMeter` 所有，在输入卡片下方、两个统计 pill 之后显示圆环和百分比。共用 dock 将统计信息放在一起，工具栏保留给输入操作；ui-chat 不导入上下文组件。上下文面板通过 portal 渲染，复用 ui-primitives 的视口内定位与外部指针关闭工具，统计贡献项缺席时也不会越界。
- **渲染纪律。** 该行只折叠已定稿节点（`chat.legacy.nodes` 身份），流式 chunk 帧零重渲染——由渲染计数单测钉住。无已完成步且无计费 token 的会话什么都不渲染。
- **输入框负责 dock 间距。** `InputBar` 将 slot 贡献项和 `ContextMeter` 放在同一个居中的 flex 行中，在 dock 上下各提供 4px 留白，即使 slot 没有可见贡献项也保持该间距。hero 保持无底部留白，并隐藏空 dock。`StatsPills` 提供可收缩的时间与计费内容，不占满整行宽度，也不添加外部 padding。
diff --git a/.agents/notes/implemented/feature/2026-09-08-composer-menu-sections-and-localized-rows.i18n.yaml b/.agents/notes/implemented/feature/2026-09-08-composer-menu-sections-and-localized-rows.i18n.yaml
index a42e0ee0bd..93a617d08b 100644
--- a/.agents/notes/implemented/feature/2026-09-08-composer-menu-sections-and-localized-rows.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-08-composer-menu-sections-and-localized-rows.i18n.yaml
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-08-composer-menu-sections-and-localized-rows.md
-2026-09-08-composer-menu-sections-and-localized-rows.md: 3cccb3c038ae4c358860f09533e966e9121b987e
-2026-09-08-composer-menu-sections-and-localized-rows.zh.md: 31c879b17ac6788bfade50a3245903c3e2e56224
+2026-09-08-composer-menu-sections-and-localized-rows.md: 50b97ce2c7e59d53bf5607fef74a799a359d27c8
+2026-09-08-composer-menu-sections-and-localized-rows.zh.md: 92bcb04bfe9b4f7b5581c80d7c0b843f98096e52
diff --git a/.agents/notes/implemented/feature/2026-09-08-composer-menu-sections-and-localized-rows.md b/.agents/notes/implemented/feature/2026-09-08-composer-menu-sections-and-localized-rows.md
index 3cccb3c038..50b97ce2c7 100644
--- a/.agents/notes/implemented/feature/2026-09-08-composer-menu-sections-and-localized-rows.md
+++ b/.agents/notes/implemented/feature/2026-09-08-composer-menu-sections-and-localized-rows.md
@@ -18,9 +18,9 @@ A menu pick fills the locale's claim token: under Chinese, picking Plan fills `/
The File row is an `action` contribution: a bare invocation consumes the trigger token and runs a client callback without submitting a message. Conversation owns that registration, its live availability, and the hidden file input. The menu replaces the separate paperclip button; the `+` button's accessible name and tooltip read "Add files or run commands".
-`ui-input-trigger` renders the new row anatomy: `InputTriggerCandidate.label` is the title and a second search key of the shared `rankByName`, the name renders as a trailing alias when the label differs from it, `icon` accepts an icon component beside the reference glyph tokens, and the description is right-aligned. `ui-primitives` gains the Plan glyph from the design doc, a static ring for Compact, and the permission shield contour.
+`ui-input-trigger` renders the new row anatomy: `InputTriggerCandidate.label` is the title and a second search key of the shared `rankByName`, the name renders as a trailing alias when the label differs from it, `icon` accepts an icon component beside the reference glyph tokens, and the description is right-aligned. Aliases and descriptions use a font one pixel below the primary labels. `ui-primitives` gains the Plan glyph from the design doc, a static ring for Compact, and the permission shield contour.
-The menu uses a 400 px border-box height cap, which fits both headings and the eight built-in rows before the viewport clamp reduces it. A real overflow keeps a 10 px draggable WebKit rail around a 4 px visible thumb, insets the track from the rounded ends, and shows a bottom fade until the viewport reaches the final row; Firefox keeps its standard thin scrollbar.
+The menu uses a 400 px border-box height cap, which fits both headings and the eight built-in rows before the viewport clamp reduces it. A real overflow keeps a 6 px draggable WebKit rail around a 2 px visible thumb, insets the track from the rounded ends, and shows a bottom fade until the viewport reaches the final row; Firefox keeps its standard thin scrollbar.
## Alternatives considered
diff --git a/.agents/notes/implemented/feature/2026-09-08-composer-menu-sections-and-localized-rows.zh.md b/.agents/notes/implemented/feature/2026-09-08-composer-menu-sections-and-localized-rows.zh.md
index 31c879b17a..92bcb04bfe 100644
--- a/.agents/notes/implemented/feature/2026-09-08-composer-menu-sections-and-localized-rows.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-08-composer-menu-sections-and-localized-rows.zh.md
@@ -18,9 +18,9 @@ composer 的 `+` 按钮与键入的 `/` 按宿主注册顺序把每个命令列
「文件」行是一个 `action` 贡献项：裸调用消费触发 token 后运行客户端回调，不提交消息。Conversation 负责该注册、实时可用性和隐藏文件输入框。菜单取代单独的回形针按钮，`+` 按钮的无障碍名称与提示为「添加文件或调用指令」。
-`ui-input-trigger` 渲染新的行结构：`InputTriggerCandidate.label` 是标题，也是共享 `rankByName` 的第二个搜索键；label 与名字不同时名字渲染为尾随别名；`icon` 在引用图标 token 之外接受图标组件；说明右对齐。`ui-primitives` 新增设计稿给出的计划图标、压缩用的静态环形，以及权限盾形轮廓。
+`ui-input-trigger` 渲染新的行结构：`InputTriggerCandidate.label` 是标题，也是共享 `rankByName` 的第二个搜索键；label 与名字不同时名字渲染为尾随别名；`icon` 在引用图标 token 之外接受图标组件；说明右对齐。别名与说明使用比主标签小 1px 的字号。`ui-primitives` 新增设计稿给出的计划图标、压缩用的静态环形，以及权限盾形轮廓。
-菜单采用 400 px 的 border-box 高度上限，在视口限制缩小高度前可容纳两个小节标题与八个内置入口。内容确实溢出时，WebKit 系浏览器用 10 px 的可拖动区域承载 4 px 的可见滑块，轨道避开圆角两端，视口抵达最后一行前显示底部渐隐；Firefox 保留标准细滚动条。
+菜单采用 400 px 的 border-box 高度上限，在视口限制缩小高度前可容纳两个小节标题与八个内置入口。内容确实溢出时，WebKit 系浏览器用 6 px 的可拖动区域承载 2 px 的可见滑块，轨道避开圆角两端，视口抵达最后一行前显示底部渐隐；Firefox 保留标准细滚动条。
## 考虑过的替代方案
diff --git a/.agents/notes/implemented/feature/2026-09-08-shared-file-type-icons.i18n.yaml b/.agents/notes/implemented/feature/2026-09-08-shared-file-type-icons.i18n.yaml
index bf3876efca..35f8f4dc56 100644
--- a/.agents/notes/implemented/feature/2026-09-08-shared-file-type-icons.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-08-shared-file-type-icons.i18n.yaml
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-08-shared-file-type-icons.md
-2026-09-08-shared-file-type-icons.md: 1e3fe7267961a8525bbcdf946eacaa933bcf3e4f
-2026-09-08-shared-file-type-icons.zh.md: fd1f38ebb33f80c73d17cc48f6f9640c309f97f2
+2026-09-08-shared-file-type-icons.md: 5dbe0ade14c15e1d509f56eba6e0266c61089c46
+2026-09-08-shared-file-type-icons.zh.md: 9dbccdf10f188b30dcbbbe11d45b238af42ca112
diff --git a/.agents/notes/implemented/feature/2026-09-08-shared-file-type-icons.md b/.agents/notes/implemented/feature/2026-09-08-shared-file-type-icons.md
index 1e3fe72679..5dbe0ade14 100644
--- a/.agents/notes/implemented/feature/2026-09-08-shared-file-type-icons.md
+++ b/.agents/notes/implemented/feature/2026-09-08-shared-file-type-icons.md
@@ -6,25 +6,25 @@ English | [中文](2026-09-08-shared-file-type-icons.zh.md)
## Problem
-Client feature plugins can share React components only through `@deepseek-ai/dsh-client-ui-primitives`, but file cards had no shared file-type presentation. `LinkIcon` owned the only extension table and deliberately collapsed paths into six link categories, while attachment cards, sent-message attachments, queued files, and workspace file rows used one generic document glyph. Two of those consumers also carried separate extension-display helpers. Adding a precise file icon anywhere else would have required another extension table or a runtime import between feature plugins.
+Client feature plugins can share React components only through `@deepseek-ai/dsh-client-ui-primitives`, but file cards had no shared file-type presentation. The package-owned classifier provides the only extension table and deliberately folds detailed file types into six link categories for `LinkIconMedium`, while attachment cards, sent-message attachments, queued files, and workspace file rows use detailed file glyphs. Adding a precise file icon anywhere else would require another extension table or a runtime import between feature plugins.
## Decision
`ui-primitives` owns one Cordis-free file classification and rendering API. `fileExtension(path)` applies the shared basename and final-dot semantics to either path separator. `classifyFileType(path)` matches without case sensitivity and returns the closed `FileType` union: the traditional `code`, `excel`, `folder`, `html`, `image`, `markdown`, `other`, `pdf`, `ppt`, `video`, and `word` categories plus the detailed `CodeFileType` categories rendered by `CodeFileIcon`. Exact filenames, filename prefixes, filename suffixes, optional project context, and extensions run in that order. The path classifier returns every member except `folder`; callers use the explicit `FileTypeIcon` `kind` override when they know an entry is a directory. Unknown extensions, missing extensions, and trailing dots resolve to `other`, except the shared table recognizes named files such as `Dockerfile`, `Makefile`, `package.json`, `.gitignore`, `README`, and `CHANGELOG`.
-`FileTypeIcon` accepts a path, shared `IconProps`, the explicit `kind`, and an optional project-file snapshot. Traditional file types render the supplied 28px document and folder contours as inline SVG. Excel, Markdown, PDF, PPT, and Word foreground marks scale to 122% around their visual center; the remaining marked traditional glyphs use 112%, while the file body and folded corner retain their source geometry and the generic file has no invented center mark. The sheet is a solid category color, the foreground mark and ordinary folded corner are white, and the generic file has a darker grey corner. CSS assigns the supplied category palette through static design tokens: DeepSeek blue for code/HTML/Markdown, the lighter DeepSeek blue for Word, green for Excel, two amber steps for folder/PPT, red for PDF, and neutral grey for unknown files. Image and video share the supplied violet through a component-local variable because the design platform has no matching violet token. A caller may override a traditional sheet through `--dsh-file-type-icon-color`.
+`FileTypeIcon` accepts a path, shared `IconProps`, the explicit `kind`, and an optional project-file snapshot. Traditional file types render the supplied 28px document and folder contours as inline SVG. The spreadsheet glyph uses the supplied unscaled 1.2px table grid; Markdown, PDF, PPT, and Word foreground marks scale to 122% around their visual center, and the remaining marked traditional glyphs use 112%. The file body and folded corner retain their source geometry, and the generic file has no invented center mark. The sheet is a solid category color, the foreground mark and ordinary folded corner are white, and the generic file has a darker grey corner. CSS assigns the supplied category palette through static design tokens: DeepSeek blue for code/HTML/Markdown, the lighter DeepSeek blue for Word, green for spreadsheets, two amber steps for folder/PPT, red for PDF, and neutral grey for unknown files. Image and video share the supplied violet through a component-local variable because the design platform has no matching violet token. A caller may override a traditional sheet through `--dsh-file-type-icon-color`.
-Recognized code and configuration files render the corresponding 20px square artwork scaled to the requested icon size. The embedded static table contains exactly the 48 established `CodeFileType` entries; archive-only artwork does not add a category, and an adjacent manifest records the responsible design owner and source digests. Tests reject scripts, event attributes, external references, and duplicate ids in that table. `CodeFileIcon` replaces local SVG ids with a per-component prefix before insertion so repeated gradients and clip paths remain independent. These technology marks retain their embedded multicolor fills and are the explicit exception to the ordinary current-color icon rule. The map selects React before TypeScript/JavaScript, Angular filename suffixes before their base extension, Docker/Node/Git/Make/CMake by filename rules, and Flutter only when the optional project snapshot contains a `pubspec.yaml` whose text includes `flutter:`. Markdown and SVG remain owned by the traditional Markdown and image categories. CSV and TSV use the code glyph in file cards, rows, and preview titles; their clickable links also use code. Both `.env` and names ending in `.env` use the environment glyph. Every traditional and technology SVG is `aria-hidden`, and the card, row, or button that owns the file identity supplies the accessible name.
+Recognized code and configuration files render the corresponding 20px square artwork scaled to the requested icon size. The embedded static table contains exactly the 48 established `CodeFileType` entries; archive-only artwork does not add a category, and an adjacent manifest records the responsible design owner and source digests. Tests reject scripts, event attributes, external references, and duplicate ids in that table. `CodeFileIcon` replaces local SVG ids with a per-component prefix before insertion so repeated gradients and clip paths remain independent. These technology marks retain their embedded multicolor fills and are the explicit exception to the ordinary current-color icon rule. The map selects React before TypeScript/JavaScript, Angular filename suffixes before their base extension, Docker/Node/Git/Make/CMake by filename rules, and Flutter only when the optional project snapshot contains a `pubspec.yaml` whose text includes `flutter:`. Markdown and SVG remain owned by the traditional Markdown and image categories. CSV, TSV, Excel workbooks and templates, OpenDocument spreadsheets, and Numbers use the spreadsheet glyph in file cards, rows, and preview titles; their clickable links use the document category. Both `.env` and names ending in `.env` use the environment glyph. Every traditional and technology SVG is `aria-hidden`, and the card, row, or button that owns the file identity supplies the accessible name.
-`LinkIcon` delegates extension classification to `classifyFileType` and folds the detailed result into its existing link vocabulary: code and HTML use `code`, images use `image`, PDF/Word/Excel/PPT use `document`, and Markdown/video/unknown files use `other`. Extensionless names remain `other` in link contexts, so the 14px clickable-link appearance defined by the [clickable-link decision](2026-09-04-web-clickable-link-styles.md) does not change.
+`LinkIconMedium` delegates extension classification to `classifyFileType` and folds the detailed result into its existing link vocabulary: code and HTML use `code`, images use `image`, PDF/Word/Excel/PPT use `document`, and Markdown/video/unknown files use `other`. Extensionless names remain `other` in link contexts, so the 14px clickable-link appearance defined by the [link styling rules](../../../../docs/web-styling.md) does not change.
-Attachment upload cards, sent-message file cards, queued-file rows, and workspace file rows render `FileTypeIcon`. The Files tab title renders its explicit `folder` kind at 16px. Explicit delivery cards use `FileTypeIcon` at 20px and `fileExtension` for their fallback metadata. The two metadata rows use `fileExtension` rather than local parsers; a leading-dot basename such as `.env` therefore displays `ENV`, while an absent or trailing suffix displays no extension label. Image content continues to render as a preview rather than a file-type glyph, and produced-file links and Markdown file mentions continue to use `LinkIcon` because they are link surfaces.
+Attachment upload cards, sent-message file cards, queued-file rows, and workspace file rows render `FileTypeIcon`. The Files tab title renders its explicit `folder` kind at 16px. Explicit delivery cards use `FileTypeIcon` at 20px and `fileExtension` for their fallback metadata. The two metadata rows use `fileExtension` rather than local parsers; a leading-dot basename such as `.env` therefore displays `ENV`, while an absent or trailing suffix displays no extension label. Image content continues to render as a preview rather than a file-type glyph, and produced-file links and Markdown file mentions continue to use `LinkIconMedium` because they are link surfaces.
## Alternatives considered
-**Use `LinkIcon` for every file surface.** Rejected. Its six categories and 14px outline drawings communicate link destinations at text size; a 28px file card has room for the supplied HTML, Markdown, PDF, Word, Excel, PPT, and video identities.
+**Use `LinkIconMedium` for every file surface.** Rejected. Its six categories and 14px outline drawings communicate link destinations at text size; a 28px file card has room for the supplied HTML, Markdown, PDF, Word, Excel, PPT, and video identities.
-**Keep a second extension table beside `LinkIcon`.** Rejected. The same path could drift to different categories as either list grows. One detailed table plus an explicit detailed-to-link adapter preserves both consumers' semantics.
+**Keep a second extension table beside `LinkIconMedium`.** Rejected. The same path could drift to different categories as either list grows. One detailed table plus an explicit detailed-to-link adapter preserves both consumers' semantics.
**Put the supplied traditional-file colors directly in each SVG path.** Rejected. Traditional SVG geometry stays reusable and follows the icon set's `currentColor` rule; the component stylesheet owns the default category palette, and render sites retain one CSS-variable override instead of rewriting path fills. The technology artwork is exempt because its embedded multicolor marks identify the language or tool rather than decorating a generic file silhouette.
@@ -32,7 +32,7 @@ Attachment upload cards, sent-message file cards, queued-file rows, and workspac
## Testing
-The `ui-primitives` specs cover case-insensitive suffixes, both path separators, leading-dot files, missing and trailing suffixes, common named files, unknown fallback, all detailed code mappings, rule priority, Flutter context, the exact 48-key artwork set, rejected archive-only categories, static-markup safety, instance-safe SVG ids and references, `aria-hidden`, sizing/class forwarding, distinct artwork, the 112% and 122% foreground-mark transforms, and the traditional solid-sheet/contrast-mark layers without literal SVG colors. A stylesheet spec pins every traditional category-to-color mapping, the caller override, and the local violet value. The existing `LinkIcon` classification table pins its coarse output, including `Makefile` remaining `other`. Attachment, chat, queue, and sidebar component suites exercise the migrated render paths; their accessibility output does not change because the glyphs remain decorative.
+The `ui-primitives` specs cover case-insensitive suffixes, both path separators, leading-dot files, missing and trailing suffixes, common named files, unknown fallback, all detailed code mappings, rule priority, Flutter context, the exact 48-key artwork set, rejected archive-only categories, static-markup safety, instance-safe SVG ids and references, `aria-hidden`, sizing/class forwarding, distinct artwork, the supplied spreadsheet grid, the 112% and 122% foreground-mark transforms, and the traditional solid-sheet/contrast-mark layers without literal SVG colors. A stylesheet spec pins every traditional category-to-color mapping, the caller override, and the local violet value. The `LinkIconMedium` classification table pins its coarse output, including `Makefile` remaining `other`. Attachment, chat, queue, and sidebar component suites exercise the migrated render paths; their accessibility output does not change because the glyphs remain decorative.
## Consequences
diff --git a/.agents/notes/implemented/feature/2026-09-08-shared-file-type-icons.zh.md b/.agents/notes/implemented/feature/2026-09-08-shared-file-type-icons.zh.md
index fd1f38ebb3..9dbccdf10f 100644
--- a/.agents/notes/implemented/feature/2026-09-08-shared-file-type-icons.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-08-shared-file-type-icons.zh.md
@@ -6,25 +6,25 @@ Status: implemented
## 问题
-客户端功能插件只能通过 `@deepseek-ai/dsh-client-ui-primitives` 共享 React 组件，但文件卡片没有共享的文件类型呈现。`LinkIcon` 拥有唯一一份扩展名表，并有意把路径折叠为六种链接类别；附件卡片、已发送消息附件、排队文件和工作区文件行则统一使用一个通用文档图形。其中两个消费方还各自带着一份扩展名展示辅助函数。在其他位置增加精细文件图标，需要再复制一份扩展名表或让功能插件之间产生运行时 import。
+客户端功能插件只能通过 `@deepseek-ai/dsh-client-ui-primitives` 共享 React 组件，但文件卡片没有共享的文件类型呈现。本包拥有唯一一份扩展名分类表，并为 `LinkIconMedium` 将细分文件类型有意折叠为六种链接类别；附件卡片、已发送消息附件、排队文件和工作区文件行使用细分文件图形。在其他位置增加精细文件图标，需要再复制一份扩展名表或让功能插件之间产生运行时 import。
## 决策
`ui-primitives` 统一拥有一套 Cordis-free 的文件分类与渲染 API。`fileExtension(path)` 对两种路径分隔符采用共享的 basename 与最终点号语义。`classifyFileType(path)` 不区分大小写，并返回闭合的 `FileType` 联合：传统的 `code`、`excel`、`folder`、`html`、`image`、`markdown`、`other`、`pdf`、`ppt`、`video`、`word` 类别，以及由 `CodeFileIcon` 渲染的细分 `CodeFileType` 集合。解析按完整文件名、文件名前缀、文件名后缀、可选项目上下文、扩展名的顺序执行。路径分类器返回 `folder` 之外的全部成员；调用方确认条目是目录时，通过 `FileTypeIcon` 的显式 `kind` 覆盖指定目录。未知扩展名、无扩展名和末尾点号回退到 `other`，但共享表识别 `Dockerfile`、`Makefile`、`package.json`、`.gitignore`、`README`、`CHANGELOG` 等具名文件。
-`FileTypeIcon` 接受路径、共享 `IconProps`、显式 `kind`和可选的项目文件快照。传统文件类型把所提供的 28px 文档与文件夹轮廓渲染为 inline SVG。Excel、Markdown、PDF、PPT、Word 的前景标记围绕自身视觉中心缩放至 122%，其余带标记的传统图形使用 112%；文件底板与折角保持源图几何，通用文件不凭空增加中心标记。底板使用实色分类颜色，前景标记与普通折角使用白色，通用文件使用较深的灰色折角。CSS 通过静态设计 token 分配所提供的分类调色板：code/HTML/Markdown 使用 DeepSeek 蓝，Word 使用较浅的 DeepSeek 蓝，Excel 使用绿色，folder/PPT 使用两档琥珀色，PDF 使用红色，未知文件使用中性灰。image 与 video 通过组件本地变量共用所提供的紫色，因为设计平台没有匹配的紫色 token。调用方可通过 `--dsh-file-type-icon-color` 覆盖传统底板颜色。
+`FileTypeIcon` 接受路径、共享 `IconProps`、显式 `kind`和可选的项目文件快照。传统文件类型把所提供的 28px 文档与文件夹轮廓渲染为 inline SVG。表格图形使用所提供的未缩放 1.2px 表格网格；Markdown、PDF、PPT、Word 的前景标记围绕自身视觉中心缩放至 122%，其余带标记的传统图形使用 112%。文件底板与折角保持源图几何，通用文件不凭空增加中心标记。底板使用实色分类颜色，前景标记与普通折角使用白色，通用文件使用较深的灰色折角。CSS 通过静态设计 token 分配所提供的分类调色板：code/HTML/Markdown 使用 DeepSeek 蓝，Word 使用较浅的 DeepSeek 蓝，表格使用绿色，folder/PPT 使用两档琥珀色，PDF 使用红色，未知文件使用中性灰。image 与 video 通过组件本地变量共用所提供的紫色，因为设计平台没有匹配的紫色 token。调用方可通过 `--dsh-file-type-icon-color` 覆盖传统底板颜色。
-已识别的代码与配置文件把对应的 20px 方形图稿缩放到请求的图标尺寸。内嵌静态表只包含现有 48 个 `CodeFileType` 条目；资源包中额外的图稿不会新增类别，相邻 manifest 记录负责的设计归属方与来源摘要。测试会拒绝该表中的脚本、事件属性、外部引用与重复 id。`CodeFileIcon` 在插入前为本地 SVG id 加上组件实例前缀，使重复渐变与裁剪路径互不干扰。这些技术标记保留自身内嵌的多色填充，是普通 current-color 图标规则的明确例外。映射让 React 优先于 TypeScript/JavaScript、Angular 文件名后缀优先于基础扩展名，并按文件名识别 Docker/Node/Git/Make/CMake；只有可选项目快照包含内容带 `flutter:` 的 `pubspec.yaml` 时才选择 Flutter。Markdown 与 SVG 仍由传统 Markdown 和图片类别拥有。CSV 和 TSV 在文件卡片、文件行及预览标题中使用 code 图标，其可点击链接也使用 code。`.env` 和以 `.env` 结尾的文件名均使用环境配置图标。所有传统与技术 SVG 都是 `aria-hidden` 的，拥有文件身份的卡片、行或按钮提供无障碍名称。
+已识别的代码与配置文件把对应的 20px 方形图稿缩放到请求的图标尺寸。内嵌静态表只包含现有 48 个 `CodeFileType` 条目；资源包中额外的图稿不会新增类别，相邻 manifest 记录负责的设计归属方与来源摘要。测试会拒绝该表中的脚本、事件属性、外部引用与重复 id。`CodeFileIcon` 在插入前为本地 SVG id 加上组件实例前缀，使重复渐变与裁剪路径互不干扰。这些技术标记保留自身内嵌的多色填充，是普通 current-color 图标规则的明确例外。映射让 React 优先于 TypeScript/JavaScript、Angular 文件名后缀优先于基础扩展名，并按文件名识别 Docker/Node/Git/Make/CMake；只有可选项目快照包含内容带 `flutter:` 的 `pubspec.yaml` 时才选择 Flutter。Markdown 与 SVG 仍由传统 Markdown 和图片类别拥有。CSV、TSV、Excel 工作簿与模板、OpenDocument 表格和 Numbers 在文件卡片、文件行及预览标题中使用表格图标，其可点击链接使用文档类别。`.env` 和以 `.env` 结尾的文件名均使用环境配置图标。所有传统与技术 SVG 都是 `aria-hidden` 的，拥有文件身份的卡片、行或按钮提供无障碍名称。
-`LinkIcon` 委托 `classifyFileType` 做扩展名分类，再把精细结果折叠进原有链接词汇：code 与 HTML 使用 `code`，图片使用 `image`，PDF/Word/Excel/PPT 使用 `document`，Markdown、video 与未知文件使用 `other`。无扩展名文件在链接语境中仍是 `other`，因此[可点击链接决策](2026-09-04-web-clickable-link-styles.zh.md)定义的 14px 外观不变。
+`LinkIconMedium` 委托 `classifyFileType` 做扩展名分类，再把精细结果折叠进原有链接词汇：code 与 HTML 使用 `code`，图片使用 `image`，PDF/Word/Excel/PPT 使用 `document`，Markdown、video 与未知文件使用 `other`。无扩展名文件在链接语境中仍是 `other`，因此[链接样式规则](../../../../docs/web-styling.zh.md)定义的 14px 外观不变。
-附件上传卡片、已发送消息文件卡片、排队文件行和工作区文件行渲染 `FileTypeIcon`。Files 标签页标题使用显式的 `folder` 类别，尺寸为 16px。显式交付卡片使用 20px 的 `FileTypeIcon`，并通过 `fileExtension` 提供默认元数据。两处元数据行使用 `fileExtension`，不再保留本地解析器；`.env` 这样的前导点 basename 会显示 `ENV`，无后缀或末尾点号则不显示扩展名 label。图片内容继续渲染为预览而不是文件类型图形，产物文件链接与 Markdown 文件提及继续使用 `LinkIcon`，因为它们属于链接表面。
+附件上传卡片、已发送消息文件卡片、排队文件行和工作区文件行渲染 `FileTypeIcon`。Files 标签页标题使用显式的 `folder` 类别，尺寸为 16px。显式交付卡片使用 20px 的 `FileTypeIcon`，并通过 `fileExtension` 提供默认元数据。两处元数据行统一使用 `fileExtension`；`.env` 这样的前导点 basename 会显示 `ENV`，无后缀或末尾点号则不显示扩展名 label。图片内容继续渲染为预览而不是文件类型图形，产物文件链接与 Markdown 文件提及继续使用 `LinkIconMedium`，因为它们属于链接表面。
## 备选方案
-**所有文件表面都使用 `LinkIcon`。** 否决。它的六种类别和 14px outline 图形用于在文字尺寸下表达链接目标；28px 文件卡片有空间表达所提供的 HTML、Markdown、PDF、Word、Excel、PPT 与 video 身份。
+**所有文件表面都使用 `LinkIconMedium`。** 否决。它的六种类别和 14px outline 图形用于在文字尺寸下表达链接目标；28px 文件卡片有空间表达所提供的 HTML、Markdown、PDF、Word、Excel、PPT 与 video 身份。
-**在 `LinkIcon` 旁保留第二份扩展名表。** 否决。任一列表增长后，同一路径可能漂移到不同类别。一份精细表加一个显式的精细到链接适配，能同时保住两类消费方的语义。
+**在 `LinkIconMedium` 旁保留第二份扩展名表。** 否决。任一列表增长后，同一路径可能漂移到不同类别。一份精细表加一个显式的精细到链接适配，能同时保住两类消费方的语义。
**把所提供的传统文件颜色直接写入每一条 SVG path。** 否决。传统 SVG 几何保持可复用，并遵守图标集的 `currentColor` 规则；组件样式表拥有默认分类调色板，渲染点只需一个 CSS 变量即可覆盖颜色，不需要重写 path 填充。技术图稿是例外，因为其内嵌的多色标记用于识别语言或工具，而不是装饰通用文件轮廓。
@@ -32,7 +32,7 @@ Status: implemented
## 测试
-`ui-primitives` 测试覆盖不区分大小写的后缀、两种路径分隔符、前导点文件、无后缀与末尾点号、常见具名文件、未知回退、全部细分代码映射、规则优先级、Flutter 上下文、精确的 48 键图稿集、被拒绝的资源包额外类别、静态 markup 安全性、实例安全的 SVG id 与引用、`aria-hidden`、尺寸/class 转发、不同图稿、112% 与 122% 前景标记变换，以及不含 SVG 字面颜色的传统实色底板/对比标记层。样式表测试钉住每一项传统类别到颜色的映射、调用方覆盖变量与本地紫色值。既有 `LinkIcon` 分类表钉住它的粗粒度输出，包括 `Makefile` 仍为 `other`。附件、聊天、队列和侧边栏组件测试覆盖迁移后的渲染路径；由于图形仍是装饰性的，其无障碍输出不变。
+`ui-primitives` 测试覆盖不区分大小写的后缀、两种路径分隔符、前导点文件、无后缀与末尾点号、常见具名文件、未知回退、全部细分代码映射、规则优先级、Flutter 上下文、精确的 48 键图稿集、被拒绝的资源包额外类别、静态 markup 安全性、实例安全的 SVG id 与引用、`aria-hidden`、尺寸/class 转发、不同图稿、所提供的表格网格、112% 与 122% 前景标记变换，以及不含 SVG 字面颜色的传统实色底板/对比标记层。样式表测试钉住每一项传统类别到颜色的映射、调用方覆盖变量与本地紫色值。`LinkIconMedium` 分类表钉住它的粗粒度输出，包括 `Makefile` 仍为 `other`。附件、聊天、队列和侧边栏组件测试覆盖迁移后的渲染路径；由于图形仍是装饰性的，其无障碍输出不变。
## 后果
diff --git a/.agents/notes/implemented/feature/2026-09-09-turn-duration-hour-unit.md b/.agents/notes/implemented/feature/2026-09-09-turn-duration-hour-unit.md
deleted file mode 100644
index f0f5cb478d..0000000000
--- a/.agents/notes/implemented/feature/2026-09-09-turn-duration-hour-unit.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# Agent Note: Turn duration labels gain an hour unit
-
-Status: implemented
-
-English | [中文](2026-09-09-turn-duration-hour-unit.zh.md)
-
-## Problem
-
-The Web chat's turn duration labels counted minutes without bound. `formatRunDuration` in [message-chrome.ts](../../../../packages/client/ui-chat/src/client/chat/message-chrome.ts) split elapsed milliseconds into seconds and minutes only, so a turn that ran for 90 minutes read `90分05秒` / `90m 05s` in all three places sharing the formatter: the `Deep diving...` running clock, the settled `Ran for {duration}` footer, and the turn-time dialog's total. The archived [turn run time decision](../../archived/feature/2026-08-03-web-turn-run-time.md) fixed the clock's anchor and the shared whole-second floor; it left the formatter at two units, which stops reading correctly once a turn crosses an hour.
-
-## Decision
-
-`formatRunDuration` carries an hour branch: elapsed time at or above 3600 seconds renders through `duration.hours` with zero-padded minutes and seconds — `1小时05分03秒` / `1h 05m 03s` — while everything below an hour keeps the existing second and minute branches unchanged. Hours appear only at or above 3600 seconds, so 3599 seconds still reads `59分59秒` and `60分00秒` never appears. Seconds are retained rather than dropped once hours appear, because the running clock ticks every second and a `1小时05分` label would sit still for a minute at a time. Negatives still clamp to zero and partial seconds still floor. `duration.hours` joins both dictionaries in [locale.ts](../../../../packages/client/ui-chat/src/client/locale.ts), and `RunDurationTranslate` widens to three keys.
-
-The change is confined to the turn formatter. `StatsPills.formatDuration` — the session-wide aggregate pill reading `45.2s` / `2m42s` — keeps its own two-unit format.
-
-## Alternatives considered
-
-**Pair hours with minutes only.** Dropping seconds at the hour boundary matches the `ui-jobs` job-duration format and keeps the label short. It loses the second-level figure from the settled footer, and it makes the live clock look frozen: the label would change once a minute while the turn is still running.
-
-**Three units while running, two once settled.** Rejected because both readings come from one function by design — the archived decision pins that — so the same turn would report different precision before and after it settles.
-
-**Change the aggregate pill in the same change.** `StatsPills.formatDuration` measures session-wide aggregates — LLM time, tool time, and average TTFT — from projections rather than one turn's boundaries. It can exceed an hour too, but folding it in would mix two independent formatters and their tests into one change.
-
-**Leave minutes unbounded.** `90分05秒` is technically correct and costs nothing to keep, but it is the reading that prompted this change and grows harder to parse the longer a turn runs.
-
-## Consequences
-
-Long turns now read in hours without new session events or new timing state; the labels remain derived from the logged `turn/start` and `turn/end` boundaries and keep the 15-second clock delay. The unit spec covers the 3599-second and 3600-second boundary plus the English template. No recorded-session snapshot changes: every shipped `Deep diving...` expectation is captured before the clock appears.
diff --git a/.agents/notes/implemented/feature/2026-09-09-turn-duration-hour-unit.zh.md b/.agents/notes/implemented/feature/2026-09-09-turn-duration-hour-unit.zh.md
deleted file mode 100644
index c9c94eef2a..0000000000
--- a/.agents/notes/implemented/feature/2026-09-09-turn-duration-hour-unit.zh.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# Agent Note: 回合耗时标签增加小时单位
-
-Status: implemented
-
-[English](2026-09-09-turn-duration-hour-unit.md) | 中文
-
-## 问题
-
-Web 聊天的回合耗时标签分钟数无界增长。[message-chrome.ts](../../../../packages/client/ui-chat/src/client/chat/message-chrome.ts) 里的 `formatRunDuration` 只把毫秒拆成秒和分两级，于是一个跑了 90 分钟的回合在共用一个格式化器的三处都读作 `90分05秒` / `90m 05s`：`Deep diving...` 后的实时计时、收尾的 `Ran for {duration}` 页脚，以及耗时详情弹窗里的总用时。已归档的[回合运行时长决策](../../archived/feature/2026-08-03-web-turn-run-time.md)确定了计时锚点和共用的整秒向下取整；它把格式化器留在两级单位，一旦回合跨过一小时就不再正确。
-
-## 决定
-
-`formatRunDuration` 增加小时分支：总时长达到或超过 3600 秒时经 `duration.hours` 渲染，分和秒补零——`1小时05分03秒` / `1h 05m 03s`——不足一小时的时长保持原有的秒、分两级不变。小时只在达到或超过 3600 秒时出现，因此 3599 秒仍读作 `59分59秒`，不会出现 `60分00秒`。出现小时后保留秒而不丢弃，因为实时计时每秒都在走，`1小时05分` 这样的标签会整整一分钟静止不动。负值仍然钳到 0，不足一秒仍然向下取整。[locale.ts](../../../../packages/client/ui-chat/src/client/locale.ts) 的两套字典都新增 `duration.hours`，`RunDurationTranslate` 扩为三个键。
-
-改动只限于回合计时器。`StatsPills.formatDuration`——会话级聚合胶囊，读作 `45.2s` / `2m42s`——保留自己的两级格式。
-
-## 考虑过的替代方案
-
-**小时只与分配对。** 在小时边界丢掉秒与 `ui-jobs` 的任务时长格式一致，标签也更短。代价是收尾页脚失去秒级数字，并且实时计时看起来像卡住了：回合还在跑，标签却每分钟才变一次。
-
-**运行中三单位、收尾两单位。** 拒绝，因为两处读数按设计来自同一个函数——归档决策锁定了这一点——同一个回合会在结束前后报告不同的精度。
-
-**在同一次改动里改聚合胶囊。** `StatsPills.formatDuration` 统计的是来自投影的会话级聚合值——LLM 耗时、工具耗时与平均 TTFT——而不是单个回合的边界。它同样可能超过一小时，但把它折进来会让两个独立的格式化器及其测试混进同一次改动。
-
-**保留分钟无界。** `90分05秒` 在技术上没错，保留也不花成本，但它正是引发这次改动的读数，而且回合跑得越久越难解析。
-
-## 后果
-
-长回合现在按小时展示，没有新增会话事件或计时状态；标签仍由日志中的 `turn/start` 与 `turn/end` 边界派生，并保留 15 秒后才出现计时的延迟。单元 spec 覆盖 3599 秒与 3600 秒的边界以及英文模板。录制会话快照没有变化：所有已发布的 `Deep diving...` 期望都在计时出现之前就被捕获。
diff --git a/.agents/notes/implemented/feature/2026-09-10-connection-indicator-refinements.i18n.yaml b/.agents/notes/implemented/feature/2026-09-10-connection-indicator-refinements.i18n.yaml
deleted file mode 100644
index 7d4eb35fa1..0000000000
--- a/.agents/notes/implemented/feature/2026-09-10-connection-indicator-refinements.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
-# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-10-connection-indicator-refinements.md
-2026-09-10-connection-indicator-refinements.md: 3b6b4c7fd0962edbb87be17c2fa45eded46ee86b
-2026-09-10-connection-indicator-refinements.zh.md: 0bd5dc3e0b5b69cf2d9491e2d3ce5711c96898f5
diff --git a/.agents/notes/implemented/feature/2026-09-10-connection-indicator-refinements.md b/.agents/notes/implemented/feature/2026-09-10-connection-indicator-refinements.md
deleted file mode 100644
index 3b6b4c7fd0..0000000000
--- a/.agents/notes/implemented/feature/2026-09-10-connection-indicator-refinements.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# Agent Note: Connection indicator state and interaction refinements
-
-Status: implemented
-
-English | [中文](2026-09-10-connection-indicator-refinements.zh.md)
-
-## Problem
-
-The sidebar connection pill hid its affordance behind a hover swap: outage and retry-attempt states replaced their label with **Reconnect now** on hover or focus, so every state had to reserve the widest supplied label to keep the control from resizing. A retry that resolved in under a second flickered the connecting pill in and out, and state changes and unmounts jumped with no transition.
-
-## Decision
-
-**The disconnected pill shows its action statically.** [ConnectionIndicator.tsx](../../../../packages/client/ui-primitives/src/ConnectionIndicator.tsx) renders a permanent retry glyph (`IconRefreshOutline14`) beside the outage copy (`连接异常，刷新重试` / `Disconnected`; the Chinese copy also names the retry action); clicking the pill still reconnects immediately. The hover label swap and the hidden widest-label size-reservation spans are gone, so the pill sizes to its current label. The connecting state shows a rotating-arc spinner instead of the exclamation glyph. Appearance and removal fade over 150ms — swaps between visible states replace content in place: `EXIT_MS` delays unmount to match the stylesheet's `.leaving` transition, and `prefers-reduced-motion` disables every animation and transition. Chrome settles at 28px height, 8px horizontal padding, 4px icon gap, 13px radius, and a 1px border of the label color at 20% alpha.
-
-**The shell owns attempt pacing.** [SettingsRoot.tsx](../../../../packages/client/ui-settings-general/src/client/SettingsRoot.tsx) keeps the connecting pill visible for at least `CONNECTING_MIN_VISIBLE_MS` (800ms) so sub-second retries do not flicker; every attempt, manual or automatic, reads the one label `重新连接中` (`connection.connecting`). The two-second recovery confirmation (`RECOVERY_CONFIRMATION_MS`) starts when the recovered pill becomes visible, so a hold that delays its appearance never shortens the confirmation. Both timings are built-in presentation constants of their owners, not configuration.
-
-## Alternatives considered
-
-**Animating width changes.** A FLIP-style measured pixel transition (remember the old width, pin it, transition to the new measurement) needs a layout effect and imperative style writes; the fade-only change reads calm enough without them.
-
-**Swapping to the retry glyph only on hover.** Showing the retry glyph permanently states the affordance without requiring any pointer interaction, matching the static label; a hover cross-fade adds interaction-dependent state and conveys nothing extra.
-
-**Scaling on enter/exit.** A 0.98 scale beside the opacity fades reads as jitter at 12px text, so only opacity animates.
-
-**Naming manual and automatic attempts differently.** `ConnectionController.emitState` deduplicates repeated `connecting` states across backoff attempts, so the shell cannot observe attempt boundaries: a shell-held manual-retry flag either flips the label mid-hold or sticks across later automatic attempts. Distinguishing the copy correctly requires the connection layer to expose the attempt origin, which this change does not need — both attempt kinds read the same label.
-
-## Consequences
-
-`ConnectionIndicator`'s `reconnectLabel` prop and its size-reservation spans are removed from the pre-stable API; the sole consumer (`ui-settings-general`) is updated in the same change. `settings-root.client.spec.tsx` pins the 800ms hold, the single attempt label held steady through the hold, and the visibility-based confirmation window; `atoms.client.spec.tsx` pins the exit-duration unmount; `lifecycle-chrome.e2e.ts` and its ARIA golden replay the recovery flow in a real browser. Both packages' READMEs restate the interaction.
diff --git a/.agents/notes/implemented/feature/2026-09-10-connection-indicator-refinements.zh.md b/.agents/notes/implemented/feature/2026-09-10-connection-indicator-refinements.zh.md
deleted file mode 100644
index 0bd5dc3e0b..0000000000
--- a/.agents/notes/implemented/feature/2026-09-10-connection-indicator-refinements.zh.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# Agent Note: 连接指示器状态与交互细化
-
-Status: implemented
-
-[English](2026-09-10-connection-indicator-refinements.md) | 中文
-
-## Problem
-
-侧边栏连接药丸把操作提示藏在悬停切换里：断连与重试状态在悬停或聚焦时把文案替换为**立即重连**，因此每个状态都要为最宽的 label 预留空间以避免控件变形。一次不到一秒就恢复的重试会让连接中药丸闪现闪没，状态切换和消失也没有任何过渡、十分突兀。
-
-## Decision
-
-**断连药丸静态地展示其动作。** [ConnectionIndicator.tsx](../../../../packages/client/ui-primitives/src/ConnectionIndicator.tsx) 在断连文案旁常驻渲染重试图形（`IconRefreshOutline14`），文案为 `连接异常，刷新重试` / `Disconnected`（中文文案同时点明重试动作）；点击药丸仍会立即重连。悬停换文案和隐藏的最宽 label 占位 span 全部移除，药丸宽度随当前 label 自适应。连接中状态改用旋转圆弧 spinner 取代感叹号图形。出现与移除以 150ms 淡入淡出——可见状态之间的切换则原地替换内容：`EXIT_MS` 延迟卸载以匹配样式表的 `.leaving` 过渡，`prefers-reduced-motion` 会禁用全部动画与过渡。外观定为高 28px、水平内边距 8px、图标间距 4px、圆角 13px，以及 label 颜色 20% 透明度的 1px 边框。
-
-**外壳拥有尝试节奏。** [SettingsRoot.tsx](../../../../packages/client/ui-settings-general/src/client/SettingsRoot.tsx) 让连接中药丸至少可见 `CONNECTING_MIN_VISIBLE_MS`（800ms），亚秒级重试不再闪动；无论手动还是自动，每次尝试都显示同一个文案`重新连接中`（`connection.connecting`）。2 秒恢复确认（`RECOVERY_CONFIRMATION_MS`）从恢复药丸实际可见时起算，驻留推迟其出现也不会缩短确认时长。两个时长是各自持有方的内置展示常量，不是配置。
-
-## Alternatives considered
-
-**给宽度变化加动画。** FLIP 式的像素测量过渡（记住旧宽度、钉住、过渡到新测量值）需要一个 layout effect 和命令式样式写入；纯淡入淡出已足够平静，无需这些。
-
-**仅在悬停时切换为重试图形。** 常驻显示重试图形无需任何指针交互就说明了操作，与静态文案一致；悬停交叉渐变引入依赖交互的状态却不传达更多信息。
-
-**进出场缩放。** 0.98 的缩放叠加在透明度淡入淡出上，在 12px 文字上读起来像抖动，因此只保留透明度。
-
-**手动与自动尝试使用不同命名。** `ConnectionController.emitState` 会去重退避尝试之间重复的 `connecting` 状态，外壳观察不到尝试边界：外壳自持的手动重试标志要么在驻留中途翻转文案，要么在后续自动尝试中一直滞留。要正确区分文案需要连接层暴露尝试来源，而本次变更并不需要——两种尝试显示同一文案。
-
-## Consequences
-
-`ConnectionIndicator` 的 `reconnectLabel` prop 及其占位 span 从 pre-stable API 中移除；唯一消费者（`ui-settings-general`）在同一变更中更新。`settings-root.client.spec.tsx` 固定 800ms 驻留、驻留期间保持不变的单一尝试文案，以及按可见时刻起算的确认窗口；`atoms.client.spec.tsx` 固定退出时长后的卸载；`lifecycle-chrome.e2e.ts` 及其 ARIA golden 在真实浏览器中回放恢复流程。两个包的 README 重述了该交互。
diff --git a/.agents/notes/implemented/feature/2026-09-10-guide-start-page-and-stat-pill-refinements.i18n.yaml b/.agents/notes/implemented/feature/2026-09-10-guide-start-page-and-stat-pill-refinements.i18n.yaml
deleted file mode 100644
index dd2b16d82c..0000000000
--- a/.agents/notes/implemented/feature/2026-09-10-guide-start-page-and-stat-pill-refinements.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
-# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-10-guide-start-page-and-stat-pill-refinements.md
-2026-09-10-guide-start-page-and-stat-pill-refinements.md: 987e46fd597b11046843a943c60187fdb1a769d0
-2026-09-10-guide-start-page-and-stat-pill-refinements.zh.md: 590f18a2963507a8918a0aca30997aac23c6e477
diff --git a/.agents/notes/implemented/feature/2026-09-10-guide-start-page-and-stat-pill-refinements.md b/.agents/notes/implemented/feature/2026-09-10-guide-start-page-and-stat-pill-refinements.md
deleted file mode 100644
index 987e46fd59..0000000000
--- a/.agents/notes/implemented/feature/2026-09-10-guide-start-page-and-stat-pill-refinements.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# Agent Note: Guide start page and stat pill refinements
-
-Status: implemented
-
-English | [中文](2026-09-10-guide-start-page-and-stat-pill-refinements.zh.md)
-
-## Problem
-
-The right Sidebar's guide tab was a bare list of entry capsules: no visual anchor above them, a capsule could only say its title, and an entry whose type registered no glyph rendered with no icon at all, so a mixed list read as broken rather than sparse. Separately, the session token-usage dialog under the composer printed a `Cache write 0 tok` row for sessions that never wrote cache.
-
-## Decision
-
-**The guide is a compass over self-describing capsules.** This refines the guide contracts in [Right Sidebar tab types and navigation](../architecture/2026-09-05-sidebar-tab-types-and-navigation.md) and [Sidebar text preview and file tree](2026-09-05-sidebar-text-preview-and-file-tree.md). [GuideBody.tsx](../../../../packages/client/ui-sidebar-right/src/client/tabs/guide/GuideBody.tsx) draws a muted 56px compass hero over the entry capsules and no heading, as a browser start page shows its doors without a caption. [`SidebarRightGuideEntry`](../../../../packages/client/ui-sidebar-right/src/client/tab-registry.ts) gains an optional thunked `description` — read fresh on every render like `title`, so language changes need no re-registration. A capsule shows its description under the title only while the guide lists at most `MAX_DESCRIBED_ENTRIES` (4) entries; a longer list drops every description to stay light, so a type must stand on its title. The glyph rides the capsule's height: 22px beside a bare title, 26px beside two lines.
-
-**Icon-less entries fall back to a shipped cube placeholder.** The fallback is decided at the render site (`entry.icon ?? CubeGlyph`), not at registration, so every contributor — builtin or extension — gets it uniformly and a chain replacement of the body replaces the rule with it. `CubeGlyph` lives beside `CompassGlyph` in [GuideTitle.tsx](../../../../packages/client/ui-sidebar-right/src/client/tabs/guide/GuideTitle.tsx): an isometric box in 1.1px straight strokes with rounded joins on `currentColor`, drawn on `--dsw-alias-label-tertiary` — one step quieter than a registered glyph's ink — to mark the slot as unclaimed. The files type registers a description and the shared folder glyph in [definition.tsx](../../../../packages/client/ui-sidebar-files/src/client/definition.tsx).
-
-**The session usage dialog drops the zero cache-write row.** This refines [Composer session stats](2026-09-07-composer-session-stats-pills.md). [StatsPills.tsx](../../../../packages/client/ui-chat/src/client/chat/StatsPills.tsx) renders the `Cache write` row only when `cacheWriteTokens !== 0`, as the per-turn panel already drops its absent optional fields; the always-present buckets (input, cache read, output) keep their rows.
-
-## Alternatives considered
-
-**Register the cube in `ui-primitives`.** Its `icons/index.tsx` is the imported figma `ic_ds_*` set, and the cube has a single consumer; `CompassGlyph` set the precedent of package-local guide glyphs.
-
-**Default the icon at registration time.** A `?? default` inside the registry would hide the fallback from the body and make "registered no glyph" undetectable, losing the quieter placeholder ink; explicit render-site fallback keeps registrations honest.
-
-**Show `Cache write 0`.** A session on a provider that never writes cache would carry the row forever; zero here means "not a thing", not a measurement.
-
-## Consequences
-
-`description` is new pre-stable registry API; every consumer was updated (the files entry registers one). The 4-entry threshold is a shipped constant of the guide body, not configuration. Guide-body specs cover the placeholder (size and ink), the description threshold on both sides, and the registered-glyph path; chat-stats specs cover the dropped and present cache-write row. The `ui-sidebar-right` and `ui-sidebar-files` READMEs restate the guide rules.
diff --git a/.agents/notes/implemented/feature/2026-09-10-guide-start-page-and-stat-pill-refinements.zh.md b/.agents/notes/implemented/feature/2026-09-10-guide-start-page-and-stat-pill-refinements.zh.md
deleted file mode 100644
index 590f18a296..0000000000
--- a/.agents/notes/implemented/feature/2026-09-10-guide-start-page-and-stat-pill-refinements.zh.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# Agent Note: 引导起始页与统计 pill 的细化
-
-Status: implemented
-
-[English](2026-09-10-guide-start-page-and-stat-pill-refinements.md) | 中文
-
-## Problem
-
-右侧边栏的引导 tab 只是一列光秃秃的入口胶囊：上方没有视觉锚点，胶囊只能显示标题，而类型没注册图标的入口干脆不画图标，混合列表看起来像坏了而不是稀疏。另外，输入框下方的会话 token 用量弹窗会给从未写入缓存的会话打印一行 `Cache write 0 tok`。
-
-## Decision
-
-**引导页是罗盘压着能自我说明的胶囊。** 本决议细化[右侧 Sidebar tab 类型与导航](../architecture/2026-09-05-sidebar-tab-types-and-navigation.zh.md)和 [Sidebar 文本预览与文件树](2026-09-05-sidebar-text-preview-and-file-tree.zh.md)中的引导页约定。[GuideBody.tsx](../../../../packages/client/ui-sidebar-right/src/client/tabs/guide/GuideBody.tsx) 在入口胶囊上方画一枚弱化的 56px 罗盘，不加标题，如同浏览器起始页不给它的入口配说明文字。[`SidebarRightGuideEntry`](../../../../packages/client/ui-sidebar-right/src/client/tab-registry.ts) 新增可选的 thunk 化 `description`——与 `title` 一样每次渲染重新读取，语言切换无需重新注册。仅当引导页列出的入口不超过 `MAX_DESCRIBED_ENTRIES`（4）个时，胶囊才在标题下显示描述；更长的列表去掉所有描述以保持轻盈，所以类型必须靠标题立得住。图标随胶囊高度变化：单行标题旁 22px，两行旁 26px。
-
-**没有图标的入口回退到内置的立方体占位符。** 回退在渲染点决定（`entry.icon ?? CubeGlyph`）而不在注册时，因此每个贡献者——内置或扩展——得到统一的占位符，链式替换 body 时规则随之整体替换。`CubeGlyph` 与 `CompassGlyph` 一起放在 [GuideTitle.tsx](../../../../packages/client/ui-sidebar-right/src/client/tabs/guide/GuideTitle.tsx)：一只等距视角的盒子，1.1px 直线描边、圆角拼接、走 `currentColor`，用 `--dsw-alias-label-tertiary` 着色——比注册图标的墨色浅一档——标记这个槽位无人认领。files 类型在 [definition.tsx](../../../../packages/client/ui-sidebar-files/src/client/definition.tsx) 注册了描述和共享的文件夹图标。
-
-**会话用量弹窗去掉为零的缓存写入行。** 本决议细化[输入框下的会话统计](2026-09-07-composer-session-stats-pills.zh.md)。[StatsPills.tsx](../../../../packages/client/ui-chat/src/client/chat/StatsPills.tsx) 仅当 `cacheWriteTokens !== 0` 时渲染 `Cache write` 行，与 per-turn 面板去掉缺失可选字段的做法一致；始终存在的桶（输入、缓存读取、输出）保留各自的行。
-
-## Alternatives considered
-
-**把立方体注册进 `ui-primitives`。** 其 `icons/index.tsx` 是导入的 figma `ic_ds_*` 集合，而立方体只有一个消费者；`CompassGlyph` 已开了引导图标包内自持的先例。
-
-**在注册时默认图标。** 注册表内部的 `?? default` 会对 body 隐藏回退，让"没注册图标"无法辨认，浅色占位墨色随之丢失；显式的渲染点回退让注册保持诚实。
-
-**显示 `Cache write 0`。** 用不写缓存的 provider 的会话会永远挂着这一行；这里的零意味着"没有这回事"，不是一次测量。
-
-## Consequences
-
-`description` 是新的 pre-stable 注册表 API；所有消费者已同步更新（files 入口注册了一个）。4 个入口的阈值是引导 body 的内置常量，不是配置。guide-body 用例覆盖占位符（尺寸与墨色）、描述阈值两侧和已注册图标路径；chat-stats 用例覆盖缓存写入行的去除与保留。`ui-sidebar-right` 与 `ui-sidebar-files` 的 README 重述了引导页规则。
diff --git a/.agents/notes/implemented/feature/2026-09-14-desktop-primary-runtime.i18n.yaml b/.agents/notes/implemented/feature/2026-09-14-desktop-primary-runtime.i18n.yaml
index 4ed53fa01a..50233385bf 100644
--- a/.agents/notes/implemented/feature/2026-09-14-desktop-primary-runtime.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-14-desktop-primary-runtime.i18n.yaml
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-14-desktop-primary-runtime.md
-2026-09-14-desktop-primary-runtime.md: d3bb7d173450d4c27af4b5b65e16f33cc285605a
-2026-09-14-desktop-primary-runtime.zh.md: 2df6effdccc09a488e322bfe6f144e18b101369c
+2026-09-14-desktop-primary-runtime.md: 51bbaac89c5c2ec9a3a016030e7b320d2b5566b8
+2026-09-14-desktop-primary-runtime.zh.md: 4f27d61b5e713f66e2f478894dbd547cd7ecfff4
diff --git a/.agents/notes/implemented/feature/2026-09-14-desktop-primary-runtime.md b/.agents/notes/implemented/feature/2026-09-14-desktop-primary-runtime.md
index d3bb7d1734..51bbaac89c 100644
--- a/.agents/notes/implemented/feature/2026-09-14-desktop-primary-runtime.md
+++ b/.agents/notes/implemented/feature/2026-09-14-desktop-primary-runtime.md
@@ -18,7 +18,7 @@ Node downloads and hash-verifies the complete locked wheel set and unpacks libra
macOS grants `com.apple.security.cs.allow-jit` only to the standalone Node executable. Hardened-runtime signing without that entitlement prevents V8 from allocating its code region. Interpreter and library smoke checks run after signing as well as after staging cleanup; a valid signature alone does not establish executable behavior.
-Windows signed packaging separates materialization from execution with a supervised primary-runtime signing stage. PE inspection excludes foreign-platform Node addons and refuses directory links. Valid vendor signatures remain intact; only unsigned files receive the configured EV signature. Invalid existing signatures fail before hardware access, and each new signature is checked for validity, timestamp and certificate identity before the next file. Electron-builder's copy-time signing hook preserves runtime executables only after exact-byte and signature verification; the same serial queue rejects later tasks if preservation fails. The existing per-user interlock, serialized signer and redacted journal own hardware calls; no failure permits a retry or later stage. Runtime execution receives no signing credentials and follows complete verification. Development and unsigned preparation retain native smoke without automatic hardware access.
+Windows signed packaging separates materialization from execution with supervised signing stages for the primary runtime and application production dependencies. PE inspection identifies content independently of extensions, excludes non-PE foreign-platform Node addons and refuses directory links. Public-key verification uses batches of 32 files with at most four processes and drains each batch before returning failure; hardware operations remain serial. Valid vendor signatures remain intact; only unsigned files receive the configured EV signature. Invalid existing signatures fail before hardware access, and each new signature is checked for validity, timestamp and certificate identity before the next file. Electron-builder's copy-time signing hook preserves runtime executables only after exact-byte and signature verification; the same serial queue rejects later tasks if preservation fails. The existing per-user interlock, serialized signer and redacted journal own hardware calls; hardware failures prohibit retries and later stages. Public timestamp attempts follow the [signature completion policy](../process/2026-09-17-windows-signature-completion.md). Runtime execution receives no signing credentials and follows complete verification. Development and unsigned preparation retain native smoke without automatic hardware access. Runtime inventories record signed bytes. Electron-builder unpacks detected dependency PE files and preserves signed copies. Final signature verification and ASAR payload and Host smoke use a private native cache before release completion.
Desktop ZIP extraction pins `extract-zip` to `yauzl` 3.4.0 through a scoped dependency override. The 2.x reader can leave large deflate entries unfinished on Node 26 ([upstream issue](https://github.com/thejoshwolfe/yauzl/issues/176)); retaining the existing extractor preserves its path validation and wheel-entry checks. The development launcher uses top-level await so unfinished preparation cannot exit successfully. A large compressed wheel regression checks the complete extracted bytes.
@@ -30,8 +30,12 @@ Desktop ZIP extraction pins `extract-zip` to `yauzl` 3.4.0 through a scoped depe
**Independent updates and version-named directories.** Runtime releases are coupled to Desktop, and the requested installation location is stable.
+**Multi-file SignTool requests.** A software-certificate probe with a missing first file still signs the second file before returning an error. One process cannot guarantee stopping hardware operations at the first failure; token signing remains one file per supervised request.
+
**Signing only the interpreter or bypassing native smoke.** Windows code integrity also evaluates DLLs and Python extensions. A signed launcher cannot make an unsigned extension load, and skipping execution would hide unusable installed dependencies. Preserving valid upstream signatures avoids unnecessary hardware operations and retains upstream attribution.
+Dependency manifests use electron-builder's own cleanup before inventory sealing. Its archive writer otherwise changes package metadata after signing; pre-applying that transformation keeps the final archive verifiable without replacing the sealed inventory after packaging.
+
## Consequences
The application carries additional native files and replaces the complete managed payload on upgrade. Running interpreters can prevent replacement on Windows. Native build smoke, install/reuse/recovery tests and a keyless tool-error session cover distinct installation and model-output paths; macOS signing uses the existing native-runtime signer. Interpreter archives and Python wheels are hash-pinned, and licenses remain with their distributions.
diff --git a/.agents/notes/implemented/feature/2026-09-14-desktop-primary-runtime.zh.md b/.agents/notes/implemented/feature/2026-09-14-desktop-primary-runtime.zh.md
index 2df6effdcc..4f27d61b5e 100644
--- a/.agents/notes/implemented/feature/2026-09-14-desktop-primary-runtime.zh.md
+++ b/.agents/notes/implemented/feature/2026-09-14-desktop-primary-runtime.zh.md
@@ -18,7 +18,7 @@ Node 下载并校验完整锁定 wheel 集的哈希，将库文件解压到 site
macOS 仅向独立 Node 可执行文件授予 `com.apple.security.cs.allow-jit`。缺少此权限的强化运行时签名会阻止 V8 分配代码区域。解释器和库的 smoke 检查在签名后以及暂存清理后执行；签名有效本身不能证明程序可运行。
-Windows 签名打包通过受监督的第一方运行时签名阶段，将文件准备与执行分开。PE 检查排除其他平台的 Node 插件，并拒绝目录链接。有效的上游签名保持不变；仅未签名文件使用配置的 EV 证书签名。已有签名无效时，在访问硬件前失败；每个新签名通过有效性、时间戳和证书身份检查后，才处理下一个文件。electron-builder 复制阶段的签名钩子仅在逐字节比对和验签通过后保留运行时可执行文件；保留验证失败时，同一串行队列拒绝后续任务。硬件调用复用现有的用户级互锁、串行签名器和脱敏日志；任何失败都不允许重试或继续后续阶段。运行时执行不接收签名凭据，并在完整验签后进行。开发和未签名准备保留本机 smoke，不自动访问硬件。
+Windows 签名打包通过受监督的签名阶段覆盖第一方运行时和应用生产依赖，将文件准备与执行分开。PE 检查独立于扩展名识别文件内容，排除其他平台的非 PE Node 原生插件，并拒绝目录链接。公钥验签每个进程处理最多 32 个文件，同时最多运行四个进程，返回失败前等待当前批次全部结束；硬件操作仍串行执行。有效的上游签名保持不变；仅未签名文件使用配置的 EV 证书签名。已有签名无效时，在访问硬件前失败；每个新签名通过有效性、时间戳和证书身份检查后，才处理下一个文件。electron-builder 复制阶段的签名钩子仅在逐字节比对和验签通过后保留运行时可执行文件；保留验证失败时，同一串行队列拒绝后续任务。硬件调用复用现有的用户级互锁、串行签名器和脱敏日志；硬件失败不允许重试或继续后续阶段。公开时间戳尝试遵循[签名完成规则](../process/2026-09-17-windows-signature-completion.zh.md)。运行时执行不接收签名凭据，并在完整验签后进行。开发和未签名准备保留本机 smoke，不自动访问硬件。运行时清单记录签名后的字节。electron-builder 将检测到的依赖 PE 文件放在归档外，并保留已签名的副本。发布完成前，最终签名检查以及 ASAR 载荷和 Host 冒烟检查使用私有原生缓存。
Desktop ZIP 解压通过定向依赖覆盖为 `extract-zip` 固定 `yauzl` 3.4.0。2.x 读取器在 Node 26 上可能无法完成较大 deflate 条目的读取（[上游问题](https://github.com/thejoshwolfe/yauzl/issues/176)）；保留现有解压器可保留其路径校验和 wheel 条目检查。开发启动器使用顶层 await，避免准备未完成却成功退出。大压缩 wheel 回归测试检查完整的解压字节。
@@ -30,8 +30,12 @@ Desktop ZIP 解压通过定向依赖覆盖为 `extract-zip` 固定 `yauzl` 3.4.0
**独立更新和版本目录。** Runtime 发布与 Desktop 绑定，且请求的安装位置固定。
+**多文件 SignTool 请求。** 软件证书探针在第一个文件不存在时，仍会先给第二个文件签名，再返回错误。单个进程无法保证首个失败后停止硬件操作；令牌签名仍按每个受监督请求处理一个文件。
+
**仅签名解释器或跳过本机 smoke。** Windows 代码完整性也检查 DLL 和 Python 扩展。启动程序有签名不能让未签名扩展被加载，跳过执行会隐藏安装后不可用的依赖。保留有效上游签名既减少硬件操作，也保留上游归属信息。
+依赖清单在记录完整性清单前使用 electron-builder 自身的清理逻辑。否则其归档写入器会在签名后修改包元数据；提前应用该转换可让最终归档通过校验，无需在打包后替换已封装的完整性清单。
+
## Consequences
应用携带额外的原生文件，并在升级时替换完整受管产物。Windows 上运行中的解释器可能阻止替换。本机构建 smoke、安装与复用及恢复测试、无密钥工具错误会话分别覆盖安装和模型输出路径；macOS 签名复用现有原生 Runtime 签名器。解释器压缩包和 Python wheel 固定哈希，许可证随各分发包保留。
diff --git a/.agents/notes/implemented/feature/2026-09-16-known-site-link-marks.md b/.agents/notes/implemented/feature/2026-09-16-known-site-link-marks.md
deleted file mode 100644
index 9d029af06f..0000000000
--- a/.agents/notes/implemented/feature/2026-09-16-known-site-link-marks.md
+++ /dev/null
@@ -1,38 +0,0 @@
-# Agent Note: Known-site link marks
-
-Status: implemented
-
-English | [中文](2026-09-16-known-site-link-marks.zh.md)
-
-## Problem
-
-Every transcribed anchor led with the same globe, so a transcript full of GitHub, npm, and documentation links gave no signal about where a link goes until the reader parsed its label. The [clickable-link vocabulary](2026-09-04-web-clickable-link-styles.md) reserved that leading seat for one category glyph and left per-site marks as a possible later extension of the `url` category.
-
-## Decision
-
-`LinkIcon` takes an optional `href`. For the `url` category, a destination whose host is a well-known site draws that site's own mark; every other `url` destination keeps the globe, and the file categories ignore `href` because their destination is a path, not a site.
-
-`SiteGlyph.tsx` in ui-primitives owns the mapping: forty host suffixes resolve to thirty-four marks. The developer sites a transcript usually cites: GitHub (`github.com`, `github.io`, `raw.githubusercontent.com`), GitLab, npm, PyPI, Stack Overflow, MDN, Wikipedia, Hacker News (`news.ycombinator.com`), YouTube (`youtube.com`, `youtu.be`), X (`x.com`, `twitter.com`), Bilibili, Zhihu, Juejin, CSDN. The mainstream sites a general audience links: search (Google, Baidu, DuckDuckGo), video and audio (TikTok, Netflix, Spotify), social and messaging (Facebook, Instagram, Reddit, Telegram with its `t.me` short links, WhatsApp with `wa.me`, WeChat via `weixin.qq.com`, QQ, Weibo), shopping (Taobao, AliExpress, eBay), reference and community (Quora, V2EX), and Apple. A host matches a suffix when it equals it or is a subdomain of it, and the longest matching suffix wins, so `gist.github.com` and `en.wikipedia.org` need no entry while `weixin.qq.com` keeps WeChat rather than the QQ mark its `qq.com` suffix would also select. Only absolute `http:` and `https:` destinations can match; anything else falls back to the globe.
-
-The artwork is the [Simple Icons](https://simpleicons.org) set (CC0-1.0) consumed as a devDependency of ui-primitives, so adding a site is one host-map entry and the artwork version comes from the lockfile rather than a copied path. Each mark renders as that set's single path on its 24-unit viewBox, inset to a 28-unit box so it keeps the ~8% margin the 20-unit `ic_ds_*` glyphs draw inside their own box, and takes the link's `currentColor` rather than the brand fill the set records. Every mark is `aria-hidden`; the anchor's own text remains the accessible name.
-
-Taking `currentColor` is deliberate for a functional link glyph rather than brand presentation: YouTube, X, Instagram, and other brands publish guidelines against recoloring their marks, and the first alternative below weighs the fixed-brand-fill option. CC0-1.0 covers the path data; every mark remains its owner's trademark, and the generated third-party notices cover the package rather than this artwork.
-
-Two consumers pass their destination: the markdown renderer's `renderSafeLink`, which covers authored anchors, reference links, and URL-promoted inline code, and the web card's source and fetch links. Both already hold the sanitized destination.
-
-## Alternatives considered
-
-- **Fetching each site's favicon** from the site itself or a favicon service. This covers arbitrary sites, but rendering a transcript would issue network requests to every linked host, which discloses reading activity and turns a text render into a network operation; it also fails offline and behind a strict `img-src` policy. Rejected: a fixed local vocabulary keeps rendering deterministic and private, and the globe remains the honest fallback.
-- **Filling the mark with the site's brand color.** Rejected: the link glyphs are `currentColor`-only so they follow the link alias, dark mode, and hover; a fixed fill would be the first exception and would fight the link's own hover color.
-- **Copying the path data into this module.** Rejected: a third-party artwork set that changes upstream is exactly what a pinned dependency tracks; fourteen embedded copies would leave no update path.
-- **Adding site values to `LinkIconKind`.** Rejected: the kind is the category the consumer states, while the site is derived from the destination; folding both into one union would make every consumer spell out a site it does not know.
-- **A monogram tile for every unmapped host.** Rejected as noise: a generated letter capsule claims a site identity without carrying one, and 14px leaves no room for readable initials.
-
-## Consequences
-
-- Adding a site needs a host-map entry in `SiteGlyph.tsx` and, to be checked, a URL in the `link-icon` spec: that spec lists a representative URL per mapped site, requires thirty-four distinct marks across them, and pins the GitHub, npm, YouTube, Wikipedia, X, Telegram, and WhatsApp aliases. A dropped or duplicated entry fails the count, while a site added to the map alone stays uncovered by the spec.
-- The vocabulary stays bounded by category rather than by demand: each site costs one map entry, one upstream mark, and one spec URL, and the thirty-four marks add roughly 23 KB of path data to the source, which the shell build reduces to a few KB in the entry chunk after tree-shaking, minification, and compression.
-- `simple-icons` enters the browser build graph as a development dependency of ui-primitives; the shell build tree-shakes the imported marks instead of the complete set.
-- Unknown hosts, non-http schemes, unparseable destinations, and file categories keep the existing globe or category glyph; the `mailto` link in a transcript still shows the globe.
-- The vocabulary is deliberately finite. Sites such as `example.com` never get a mark from this mechanism; recognizing them would require the network fetching the alternatives reject.
-- Coverage: the LinkIcon spec covers the aliases, the fallback branches, and the sizing seat; the markdown spec pins one known and one unknown anchor; the web-card spec pins a source and a fetch link against the same marks.
diff --git a/.agents/notes/implemented/feature/2026-09-16-known-site-link-marks.zh.md b/.agents/notes/implemented/feature/2026-09-16-known-site-link-marks.zh.md
deleted file mode 100644
index 2c7630d122..0000000000
--- a/.agents/notes/implemented/feature/2026-09-16-known-site-link-marks.zh.md
+++ /dev/null
@@ -1,38 +0,0 @@
-# Agent Note: 已知站点链接标记
-
-Status: implemented
-
-[English](2026-09-16-known-site-link-marks.md) | 中文
-
-## Problem
-
-转写内容中的每个锚点都以同一个地球图形开头，因此满是 GitHub、npm 与文档链接的对话在读者解析标签之前，无法从图形看出链接去向。[可点击链接词汇](2026-09-04-web-clickable-link-styles.zh.md) 把该前置位置留给一个分类图形，并把按站点区分的标记留作 `url` 类别日后可能的扩展。
-
-## Decision
-
-`LinkIcon` 接受可选的 `href`。对于 `url` 类别，目的地主机属于已知站点时改画该站点自己的标记；其余 `url` 目的地仍使用地球，文件类别忽略 `href`，因为它们的目的地是路径而不是站点。
-
-ui-primitives 的 `SiteGlyph.tsx` 持有该映射：四十个主机后缀解析为三十四个标记。转写内容常引用的开发者站点：GitHub（`github.com`、`github.io`、`raw.githubusercontent.com`）、GitLab、npm、PyPI、Stack Overflow、MDN、Wikipedia、Hacker News（`news.ycombinator.com`）、YouTube（`youtube.com`、`youtu.be`）、X（`x.com`、`twitter.com`）、Bilibili、知乎、掘金与 CSDN。普通用户常访问的主流站点：搜索（Google、百度、DuckDuckGo）、视频与音频（TikTok、Netflix、Spotify）、社交与通讯（Facebook、Instagram、Reddit、Telegram 及 `t.me` 短链、WhatsApp 及 `wa.me`、`weixin.qq.com` 上的微信、QQ、微博）、购物（淘宝、速卖通、eBay）、参考资料与社区（Quora、V2EX）以及 Apple。主机等于某后缀或为其子域即匹配，且最长匹配后缀优先，因此 `gist.github.com` 与 `en.wikipedia.org` 无需单独登记，而 `weixin.qq.com` 得到微信标记而不是其 `qq.com` 后缀同样会选中的 QQ 标记。只有绝对 `http:` 与 `https:` 目的地能够匹配，其余一律回退到地球。
-
-图形取自 [Simple Icons](https://simpleicons.org) 图标集（CC0-1.0），以 ui-primitives 的 devDependency 形式引入，因此新增站点只是主机映射中的一条记录，图形版本由 lockfile 固定，而不是复制路径数据。每个标记以该图标集的单条 path 绘制在其 24 单位 viewBox 上，并内缩到 28 单位盒中，以保留 20 单位 `ic_ds_*` 图形在自身盒内约 8% 的留白；填充使用链接的 `currentColor`，而不是图标集记录的品牌填充色。所有标记均为 `aria-hidden`，锚点自身文本仍是可访问名称。
-
-对功能性链接图形采用 `currentColor` 是刻意的取舍，而非品牌呈现：YouTube、X、Instagram 等品牌公布的规范禁止为其标记改色，下方第一个备选方案比较了固定品牌填充的做法。CC0-1.0 覆盖路径数据；每个标记仍属其所有者的商标，生成的第三方声明覆盖该 npm 包本身，而不是这份图形。
-
-两处消费者传入自己的目的地：markdown 渲染器的 `renderSafeLink`（覆盖作者书写的锚点、引用式链接与提升为链接的行内代码）以及 web 卡片的来源与抓取链接。两者本已持有经安全校验的目的地。
-
-## Alternatives considered
-
-- **抓取各站点的 favicon**，无论取自站点本身还是 favicon 服务。这能覆盖任意站点，但渲染一份转写内容会向每个被链接的主机发起网络请求，泄露阅读行为并把文本渲染变成网络操作；它在离线与严格 `img-src` 策略下同样失败。拒绝：固定的本地词汇表让渲染保持确定与私密，地球仍是诚实的回退。
-- **以站点品牌色填充标记。** 拒绝：链接图形只使用 `currentColor`，以跟随链接 alias、暗色模式与 hover；固定填充会成为首个例外，并与链接自身的 hover 颜色冲突。
-- **把路径数据复制进本模块。** 拒绝：上游会持续更新的第三方图形集正是需要固定版本依赖来跟踪的内容；十四个内嵌副本没有更新路径。
-- **把站点值加进 `LinkIconKind`。** 拒绝：kind 是消费者陈述的分类，而站点由目的地推导；把两者折进同一联合类型会迫使每个消费者写出自己并不知晓的站点。
-- **为每个未映射主机生成首字母方块。** 以噪音为由拒绝：自动生成的字母胶囊宣称了一种站点身份却没有承载它，14px 也没有留下可读字母的空间。
-
-## Consequences
-
-- 新增站点需要在 `SiteGlyph.tsx` 的主机映射中加一条记录，并在 `link-icon` spec 中补一个 URL 才会被检查：该 spec 为每个已映射站点列出一个代表 URL、要求它们共产生三十四个互不相同的标记，并固定 GitHub、npm、YouTube、Wikipedia、X、Telegram 与 WhatsApp 的别名。记录丢失或重复会让数量断言失败，而只改主机映射、不补 spec URL 的新站点仍未被 spec 覆盖。
-- 词汇表按类别而非按需求增长：每个站点需要一条主机映射、一个上游标记与一个 spec URL；这三十四个标记在源码中增加约 23 KB 路径数据，经 shell 构建的 tree-shake、压缩与 gzip 后进入入口 chunk 的只有几 KB。
-- `simple-icons` 作为 ui-primitives 的开发依赖进入浏览器构建图；shell 构建会 tree-shake 所导入的标记，而不是整套图标。
-- 未收录主机、非 http scheme、无法解析的目的地与文件类别都保留原有的地球或分类图形；转写内容中的 `mailto` 链接仍显示地球。
-- 该词汇表刻意有限。像 `example.com` 这样的站点不会由此机制获得标记；要识别它们就需要被上述备选方案拒绝的网络抓取。
-- 覆盖：LinkIcon spec 覆盖别名、各回退分支与尺寸座位；markdown spec 固定一个已知锚点与一个未知锚点；web 卡片 spec 用同一批标记固定一个来源链接与一个抓取链接。
diff --git a/.agents/notes/implemented/simplification/2026-09-17-plugin-inventory-phase-dot.i18n.yaml b/.agents/notes/implemented/feature/2026-09-17-compact-translucent-menu-surfaces.i18n.yaml
similarity index 55%
rename from .agents/notes/implemented/simplification/2026-09-17-plugin-inventory-phase-dot.i18n.yaml
rename to .agents/notes/implemented/feature/2026-09-17-compact-translucent-menu-surfaces.i18n.yaml
index 5c2380b3d6..cf44de1cb6 100644
--- a/.agents/notes/implemented/simplification/2026-09-17-plugin-inventory-phase-dot.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-17-compact-translucent-menu-surfaces.i18n.yaml
@@ -1,6 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
-# pnpm run verify-translation-pairing --write .agents/notes/implemented/simplification/2026-09-17-plugin-inventory-phase-dot.md
-2026-09-17-plugin-inventory-phase-dot.md: e90d49b6a3d2d8e03f662b3de531ef180d350cad
-2026-09-17-plugin-inventory-phase-dot.zh.md: d344ede75c7e0dd77a0d57720e0c1366f22e75b8
+# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-17-compact-translucent-menu-surfaces.md
+2026-09-17-compact-translucent-menu-surfaces.md: 08fcb2d851e4c75ce9069fc797e8dbcb070acc5b
+2026-09-17-compact-translucent-menu-surfaces.zh.md: 8e13634995d46b7414f17bbb51443df85cb3ac3c
diff --git a/.agents/notes/implemented/feature/2026-09-17-compact-translucent-menu-surfaces.md b/.agents/notes/implemented/feature/2026-09-17-compact-translucent-menu-surfaces.md
new file mode 100644
index 0000000000..08fcb2d851
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-17-compact-translucent-menu-surfaces.md
@@ -0,0 +1,29 @@
+# Agent Note: Compact translucent menu surfaces
+
+Status: implemented
+
+English | [中文](2026-09-17-compact-translucent-menu-surfaces.zh.md)
+
+## Problem
+
+Shared dropdowns and feature-owned menu panels used the same elevated color token but retained unrelated padding, row height, corner radius, and scrollbar geometry. The opaque menu fill also made nested and portalled surfaces read as solid cards rather than one elevation family, while narrowing individual menus locally would keep those differences distributed across packages.
+
+## Decision
+
+`ui-theme` defines `--dsw-specific-menu` as a translucent light or dark fill and defines `--dsw-menu-backdrop-filter` as `blur(40px) saturate(150%)`. Every elevated package surface that paints the menu fill also applies that backdrop filter, uses `border: 0`, and takes an elevation shadow with its rebindable hairline stroke. A surface containing fixed-position overlays paints the fill and filter on an isolated background pseudo-element, because a filtered ancestor would otherwise change those overlays' containing block. Descendant sticky rows may repaint the inherited fill without another filter. Browsers without backdrop filtering still render the theme-owned translucent fill.
+
+The shared `Menu` and the composer input-trigger menu use the same compact baseline: a 16px outer radius, 3px frame padding, 34px ordinary rows, 13px primary text on a 20px line, 6px icon/text gaps, and 8px row radii. Dense and compact variants reduce from that baseline instead of retaining the former ordinary geometry. The composer menu keeps its feature-owned grouping and 400px height cap; its aliases and descriptions use 12px text on an 18px line.
+
+The global WebKit scrollbar width is 5px. The composer menu overrides it with a 6px draggable rail and a 2px visible thumb through the existing scrollbar geometry variables; Firefox continues to use its standard thin scrollbar path. Track insets and elevated l2 thumb colors remain surface-owned rebindings.
+
+## Alternatives considered
+
+**Keep an opaque shared menu fill.** Rejected because every consumer would need a separate translucent override to share one material, recreating the theme branch outside `ui-theme`.
+
+**Compact only the composer command menu.** Rejected because the shared `Menu` renders the same action, settings, and navigation vocabulary; keeping its former 40px rows would preserve two densities for the same control family.
+
+**Use the 6px padded rail for every scrollbar.** Rejected because ordinary scroll regions need the direct 5px thumb, while the command menu needs a wider hit area around a visually quieter thumb. The existing geometry variables express that difference without another scrollbar implementation.
+
+## Consequences
+
+Elevated menu-fill consumers must pair the fill and backdrop-filter tokens in the same rule, either on the surface or on its isolated background pseudo-element; the stylesheet gate rejects a material layer that omits the filter. Shared menu geometry changes affect every `Menu` render site, while the composer menu retains its own content and interaction rules. Browser and component snapshots cover assembled structure, and theme specs pin the tokens, compact metrics, scrollbar geometry, and complete menu-filter pairing.
diff --git a/.agents/notes/implemented/feature/2026-09-17-compact-translucent-menu-surfaces.zh.md b/.agents/notes/implemented/feature/2026-09-17-compact-translucent-menu-surfaces.zh.md
new file mode 100644
index 0000000000..8e13634995
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-17-compact-translucent-menu-surfaces.zh.md
@@ -0,0 +1,29 @@
+# Agent Note: 紧凑半透明菜单表面
+
+Status: implemented
+
+[English](2026-09-17-compact-translucent-menu-surfaces.md) | 中文
+
+## Problem
+
+共享下拉菜单与功能包自有菜单面板使用同一个高层级颜色 token，却保留了不同的内边距、行高、圆角和滚动条几何。不透明菜单填充也让嵌套与 portal 表面像彼此独立的实色卡片；如果只在各功能菜单中局部收紧尺寸，这些差异仍会分散在多个包中。
+
+## Decision
+
+`ui-theme` 将 `--dsw-specific-menu` 定义为明暗主题各自的半透明填充，并将 `--dsw-menu-backdrop-filter` 定义为 `blur(40px) saturate(150%)`。每个绘制菜单填充的包级高层级表面同时应用该 backdrop filter、设置 `border: 0`，并使用带可重绑发丝描边的 elevation 投影。包含 fixed 定位浮层的表面把填充与滤镜绘制在隔离的背景伪元素上，因为带滤镜的祖先会改变这些浮层的包含块。后代 sticky 行可以再次绘制继承的填充，无需重复 filter。不支持 backdrop filtering 的浏览器仍渲染主题持有的半透明填充。
+
+共享 `Menu` 与 composer 输入触发菜单使用同一套紧凑基准：16px 外圆角、3px 边框内距、34px 普通行、13px 主文字配 20px 行高、6px 图文间距，以及 8px 行圆角。dense 与 compact 变体在该基准上继续缩小，不再保留旧的普通几何。composer 菜单保留其功能包持有的分组与 400px 高度上限；别名和说明使用 12px 字号与 18px 行高。
+
+WebKit 系全局滚动条宽度为 5px。composer 菜单通过既有滚动条几何变量覆盖为 6px 可拖动轨道与 2px 可见滑块；Firefox 继续走标准 thin scrollbar 路径。轨道内缩与高层级 l2 滑块颜色仍由表面自行重绑。
+
+## Alternatives considered
+
+**保留不透明的共享菜单填充。** 否决，因为每个消费方都需要单独覆盖成半透明，导致同一种材质再次在 `ui-theme` 之外分叉。
+
+**只收紧 composer 指令菜单。** 否决，因为共享 `Menu` 渲染的是同一套操作、设置与导航词汇；保留原 40px 行会让同一个控件家族继续存在两种密度。
+
+**所有滚动条都使用 6px 带内边距轨道。** 否决，因为普通滚动区域需要直接的 5px 滑块，而指令菜单需要在更安静的可见滑块外保留更宽点击区域。现有几何变量可以表达该差异，无需第二套滚动条实现。
+
+## Consequences
+
+高层级菜单填充消费方必须在同一规则中同时使用填充与 backdrop-filter token，规则可以属于表面本身，也可以属于其隔离的背景伪元素；样式表门禁会拒绝漏掉 filter 的材质层。共享菜单几何影响每个 `Menu` 渲染点，composer 菜单仍保留自身内容与交互规则。浏览器与组件快照覆盖装配结构，主题测试固定 token、紧凑尺寸、滚动条几何与完整的菜单 filter 配对。
diff --git a/.agents/notes/implemented/feature/2026-09-16-known-site-link-marks.i18n.yaml b/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.i18n.yaml
similarity index 58%
rename from .agents/notes/implemented/feature/2026-09-16-known-site-link-marks.i18n.yaml
rename to .agents/notes/implemented/feature/2026-09-17-developer-tools-settings.i18n.yaml
index 513a59328a..69db5487b8 100644
--- a/.agents/notes/implemented/feature/2026-09-16-known-site-link-marks.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.i18n.yaml
@@ -1,6 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
-# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-16-known-site-link-marks.md
-2026-09-16-known-site-link-marks.md: 9d029af06f9ca0f3fa8290112c7023ec1b9e0b84
-2026-09-16-known-site-link-marks.zh.md: 2c7630d122d1576ba41cb653cf0b86e9c5a2ddb4
+# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-17-developer-tools-settings.md
+2026-09-17-developer-tools-settings.md: e76cb7f367faff71ef916d8a263dc523583f1cd2
+2026-09-17-developer-tools-settings.zh.md: 5a7d6d59db686f57ef4945b572ea65ffe54b7f9c
diff --git a/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.md b/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.md
new file mode 100644
index 0000000000..e76cb7f367
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.md
@@ -0,0 +1,29 @@
+# Agent Note: Shared developer-tool settings
+
+Status: implemented
+
+English | [中文](2026-09-17-developer-tools-settings.zh.md)
+
+## Problem
+
+Diagnostic views, preset selection and changed-file summaries add complexity to routine tasks. Scripted HTML also grants capabilities that a basic document preview does not need. Desktop and Web share these renderers, so independent switches would let the same setting produce different results across clients.
+
+## Decision
+
+The settings-owned `ctx.settingsScope.developerTools` preference binds a namespace scope and exposes one accepted `ui-developer-tools.enabled` preference, defaulting off. General Settings offers the same switch on Web and desktop. The existing settings transport owns validation, ordered writes, persistence and recovery; loopback Web and desktop follow Host acceptance. Remote Web owns one browser-local observable shared by all consumers until reload, with no Host writes.
+
+Off exposes only Chat, hides tool Inspect actions when no visible View declares tool-call inspection, removes the conversation View tab bar, hides the new-session preset chip, and omits the changed-files card and its summary read. Turning it off from another View activates Chat. The preset composition, saved default, Session events and explicit delivery cards remain unchanged. This preference is presentation policy, not Host authorization.
+
+Plugin assembly translates the shared preference into component-specific capabilities (`showCodeDiff`, `showPresetPicker`, and `interactivePreview`). Conversation supplies the inspection callback using the visible target's `toolCallFocus`; Chat does not name the target. The builtin HTML renderer uses DOMPurify for complete-document sanitization and parser-mutation defenses. Off preserves root styling, removes active documents, resource hints, SVG animation and all `href` attributes, and mounts an iframe with no sandbox permissions and a CSP denying scripts and external resources. It reads no related files. On retains the opaque scripted Blob renderer and its bounded related-file reads. Switching modes replaces the browsing context and disposes pending reads. The [document-preview decision](../architecture/2026-09-08-document-preview-operations.md) and [filesystem-read authority](../architecture/2026-09-09-workspace-file-read-authority.md) remain authoritative for advanced rendering and Host read access.
+
+## Alternatives considered
+
+**Limit the switch to desktop.** The selected requirement contains no desktop-only restriction, and the affected UI is shared. A desktop check would leave the Web renderer with inconsistent visibility and preview behavior.
+
+**Hide controls without changing the active View or iframe.** Previously selected diagnostic content and already-running scripts would survive the toggle. Filtering the available View roster and remounting the HTML context enforce the selected presentation immediately.
+
+## Consequences
+
+Basic HTML sacrifices JavaScript, external and related resources, and link navigation; inline styles and data images remain available. Advanced mode retains normal browser networking and does not gain parent-origin, popup, form or top-navigation privileges. The setting does not constrain third-party preview implementations or revoke Host filesystem authority.
+
+Component and settings tests cover defaulting, schema rejection, accepted-state updates, chip disclosure, changed-file visibility and iframe disposal. The recorded-session [document preview](../../../../apps/web/tests/document-preview.e2e.ts) and [changed-files](../../../../apps/web/tests/changed-files-turn.e2e.ts) scenarios exercise the real settings control and the shared renderer. The browser scaffold enables developer tools by default. Only settings chrome, document preview, changed-files and developer-tools scenarios explicitly retain the shipped default; together they cover hidden diagnostic controls, static previews, and switching back to Chat. Refused Host writes recover accepted state and show the localized retry message. Native Electron execution remains unverified.
diff --git a/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.zh.md b/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.zh.md
new file mode 100644
index 0000000000..5a7d6d59db
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-17-developer-tools-settings.zh.md
@@ -0,0 +1,29 @@
+# Agent Note: 共享开发者工具设置
+
+Status: implemented
+
+[English](2026-09-17-developer-tools-settings.md) | 中文
+
+## Problem
+
+诊断视图、预设选择和改动文件摘要增加了日常任务的复杂度。支持脚本的 HTML 还授予了基础文档预览不需要的能力。桌面端和 Web 共享这些渲染器，分别设置开关会让同一设置在不同客户端产生不同结果。
+
+## Decision
+
+设置域内的 `ctx.settingsScope.developerTools` 偏好对象绑定命名空间 scope，提供一个已接受的 `ui-developer-tools.enabled` 偏好，默认关闭。Web 和桌面端的通用设置提供同一个开关。现有设置传输负责验证、有序写入、持久化和恢复；回环 Web 和桌面端跟随 Host 接受的状态。远程 Web 持有一个所有消费者共享的浏览器本地可观察值，刷新后重置，不发送 Host 写入。
+
+关闭时仅展示 Chat，在没有可见 View 声明工具调用检查能力时隐藏 Inspect 操作，移除会话 View 标签栏，隐藏新会话预设入口，并省略改动文件卡片及其摘要读取。在其他 View 中关闭开关会激活 Chat。预设组合、保存的默认值、Session 事件和显式交付卡片保持不变。此偏好是展示策略，不是 Host 授权。
+
+插件组装层将共享偏好转换为组件自身的能力（`showCodeDiff`、`showPresetPicker` 和 `interactivePreview`）。Conversation 根据可见目标的 `toolCallFocus` 提供检查回调；Chat 不再指定目标名称。内置 HTML 渲染器使用 DOMPurify 清理完整文档并防护解析变异。关闭时保留根节点样式，移除主动文档、资源提示、SVG 动画及所有 `href` 属性，再放入不授予沙箱权限的 iframe，并通过 CSP 禁止脚本和外部资源。不读取关联文件。开启时保留不透明源的脚本 Blob 渲染器及其有界关联文件读取。切换模式会替换浏览上下文并清理待处理读取。[文档预览决策](../architecture/2026-09-08-document-preview-operations.zh.md)和[文件系统读取权限](../architecture/2026-09-09-workspace-file-read-authority.zh.md)继续定义高级渲染与 Host 读取访问。
+
+## Alternatives considered
+
+**仅在桌面端提供开关。** 所选需求没有仅限桌面的约束，相关 UI 也是共享的。桌面端条件判断会让 Web 渲染器的展示和预览行为不一致。
+
+**隐藏控件但不改变激活的 View 或 iframe。** 之前选择的诊断内容和已经运行的脚本会在切换后继续存在。过滤可用 View 并重新挂载 HTML 上下文，可以立即执行所选展示策略。
+
+## Consequences
+
+基础 HTML 放弃 JavaScript、外部与关联资源和链接导航；行内样式与 data 图片仍可用。高级模式保留正常浏览器网络能力，不增加父源、弹窗、表单或顶层导航权限。此设置不约束第三方预览实现，也不撤销 Host 文件系统读取权限。
+
+组件和设置测试覆盖默认值、schema 拒绝、已接受状态更新、入口折叠、改动文件展示和 iframe 清理。基于已记录 Session 的[文档预览](../../../../apps/web/tests/document-preview.e2e.ts)与[改动文件](../../../../apps/web/tests/changed-files-turn.e2e.ts)场景验证真实设置控件及共用渲染器。浏览器脚手架默认开启开发者工具，仅设置外壳、文档预览、改动文件和开发者工具场景显式保留产品默认值；这些场景共同覆盖诊断控件隐藏、静态预览和切回 Chat。Host 拒绝写入后会恢复已接受状态，并显示本地化重试提示。原生 Electron 执行尚未验证。
diff --git a/.agents/notes/implemented/feature/2026-09-04-web-clickable-link-styles.i18n.yaml b/.agents/notes/implemented/feature/2026-09-17-state-dot-visual-language.i18n.yaml
similarity index 57%
rename from .agents/notes/implemented/feature/2026-09-04-web-clickable-link-styles.i18n.yaml
rename to .agents/notes/implemented/feature/2026-09-17-state-dot-visual-language.i18n.yaml
index 6009b3c1ad..d86602a99e 100644
--- a/.agents/notes/implemented/feature/2026-09-04-web-clickable-link-styles.i18n.yaml
+++ b/.agents/notes/implemented/feature/2026-09-17-state-dot-visual-language.i18n.yaml
@@ -1,6 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
-# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-04-web-clickable-link-styles.md
-2026-09-04-web-clickable-link-styles.md: c4e506294c87c6b959cb449403edce09daa11062
-2026-09-04-web-clickable-link-styles.zh.md: 01258674b4b8194ad5e0597cde61cc2186406d49
+# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-17-state-dot-visual-language.md
+2026-09-17-state-dot-visual-language.md: 751abbaa33919721c7e71738ad9b6bed744fcad7
+2026-09-17-state-dot-visual-language.zh.md: 9746ec9af79e15fc41ea8e6601cc52c1cfafba02
diff --git a/.agents/notes/implemented/feature/2026-09-17-state-dot-visual-language.md b/.agents/notes/implemented/feature/2026-09-17-state-dot-visual-language.md
new file mode 100644
index 0000000000..751abbaa33
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-17-state-dot-visual-language.md
@@ -0,0 +1,31 @@
+# Agent Note: StateDot solid marks and loading spinner
+
+Status: implemented
+
+English | [中文](2026-09-17-state-dot-visual-language.zh.md)
+
+## Problem
+
+`StateDot` mixed two drawing languages: settled states used a translucent halo around a solid core, while `ongoing` used an eight-cell pixel chase.
+
+## Decision
+
+`idle`, `done`, `warning`, and `error` render as one solid 6px circle inside the existing 10px layout slot, with no halo. `idle` uses the neutral `--dsw-alias-state-idle-primary` token, `done` remains success green, `warning` remains amber, and `error` remains red.
+
+`ongoing` is the sole non-dot member. Its default edge is 14px, while solid states retain their 10px layout slot. It renders a 25%-opacity complete ring behind a grey arc using the tertiary label token. The glyph rotates continuously over 1.5 seconds while the arc grows from 12 to 24 dash units around its center and returns to 12; the arc offset is zero at both ends, so the browser does not reset a second circular movement at the loop boundary. Reduced-motion environments retain an intermediate static arc. The explicit size override, `data-state`, and `aria-hidden` behavior do not change.
+
+Converted compact status-only presentations use this shared mapping instead of local dots or spinners: waiting or blocked is `warning`, active work is `ongoing`, successful completion is `done`, failure is `error`, and inactive or not-yet-started work is `idle`. Tool rows whose leading slot is a business icon retain the ordinary glyph in every lifecycle state; their collapsed summary turns red for failure and amber for `stopped`, preserving any tool-specific interruption text. The framework-free boot page remains separate because its arc reports aggregate loader progress before React and the shared primitive are available.
+
+## Alternatives considered
+
+**Keep the pixel chase.** Rejected because its block animation did not share the circular language of the settled markers and read as a decorative activity glyph rather than a conventional loading state.
+
+**Fill the complete 10px slot.** Rejected because the former visible core was 6px; retaining that diameter preserves row density while removing only the halo.
+
+## Testing
+
+The component specs pin the four solid-state elements, the two-circle loading artwork, both animation tracks, both size paths, the no-halo stylesheet, and every state token. Tool, Bash, and Skill row specs pin the retained business glyph plus visible red failure and amber interruption summaries. Workspace, Job, Workflow, Subagent, Deliverables, terminal, plugin, Schedule, Todo, Team, approval, document-preview, Trajectory, and connection suites pin their state mappings and accessible labels.
+
+## Consequences
+
+Consumers keep their accessibility labels while status-only presentations share one visual vocabulary. Every settled marker becomes visually quieter and more compact, completion remains green, and every active marker uses the same tertiary-grey rotating loader. Action glyphs such as reconnect and business glyphs such as file or tool types remain available when the icon itself communicates the operation rather than only its state.
diff --git a/.agents/notes/implemented/feature/2026-09-17-state-dot-visual-language.zh.md b/.agents/notes/implemented/feature/2026-09-17-state-dot-visual-language.zh.md
new file mode 100644
index 0000000000..9746ec9af7
--- /dev/null
+++ b/.agents/notes/implemented/feature/2026-09-17-state-dot-visual-language.zh.md
@@ -0,0 +1,31 @@
+# Agent Note: StateDot 纯色标记与旋转 loading
+
+Status: implemented
+
+[English](2026-09-17-state-dot-visual-language.md) | 中文
+
+## 问题
+
+`StateDot` 混用了两套绘制语言：已结算状态在实心核外带半透明光晕，`ongoing` 则使用八格像素追逐动画。
+
+## 决策
+
+`idle`、`done`、`warning` 与 `error` 在既有 10px 布局槽内渲染一个 6px 纯色圆点，不再带光晕。`idle` 使用中性的 `--dsw-alias-state-idle-primary` token，`done` 保持成功绿色，`warning` 保持琥珀色，`error` 保持红色。
+
+`ongoing` 是唯一不是圆点的成员。它的默认边长为 14px，纯色状态仍保留 10px 布局槽。它在透明度为 25% 的完整圆环上方，使用 tertiary label token 渲染灰色圆弧。图形以 1.5 秒周期持续旋转，圆弧围绕中心从 12 个 dash 单位增长到 24 个、再回到 12 个；圆弧偏移在首尾都为零，因此浏览器不会在循环边界重置第二段圆周运动。减少动态效果的环境保留中间长度的静态圆弧。显式 size 覆盖、`data-state` 与 `aria-hidden` 行为均不改变。
+
+已转换的紧凑纯状态展示使用这套共享映射，不再自绘圆点或 spinner：等待或阻塞为 `warning`，活动工作为 `ongoing`，成功完成为 `done`，失败为 `error`，未活动或尚未开始为 `idle`。前置槽为业务图标的工具行在所有生命周期状态中都保留普通图标；收起摘要在失败时变红，在 `stopped` 时变为琥珀色并保留工具自有的中断文本。无框架的启动页保持独立，因为它会在 React 与共享原语可用前用圆弧表达 Loader 总体进度。
+
+## 考虑过的替代方案
+
+**保留像素追逐动画。** 否决，因为方块动画没有沿用已结算标记的圆形语言，看起来更像装饰性活动图形，而不是常规 loading 状态。
+
+**填满完整 10px 槽位。** 否决，因为原来的可见实心核就是 6px；保留该直径只移除光晕，同时维持行密度。
+
+## 测试
+
+组件测试固定四种纯色状态元素、双圆环 loading 图稿、两条动画轨道、两条尺寸路径、无光晕样式和每个状态 token。Tool、Bash 与 Skill 行测试固定保留的业务图形，以及可见的红色失败摘要与琥珀色中断摘要。Workspace、Job、Workflow、Subagent、Deliverables、终端、插件、Schedule、Todo、Team、审批、文档预览、Trajectory 与连接测试固定各自的状态映射和无障碍 label。
+
+## 后果
+
+消费方保留无障碍 label，纯状态展示共享同一套视觉词汇。所有已结算标记在视觉上更安静、更紧凑，完成态保持绿色，所有活动态使用同一种 tertiary 灰色旋转 loading。重连等动作图标和文件或工具类型等业务图标在图形本身表达操作而不只表达状态时继续保留。
diff --git a/.agents/notes/implemented/feature/2026-09-17-web-sidebar-session-title-hover-scroll.i18n.yaml b/.agents/notes/implemented/feature/2026-09-17-web-sidebar-session-title-hover-scroll.i18n.yaml
deleted file mode 100644
index 896278e3d6..0000000000
--- a/.agents/notes/implemented/feature/2026-09-17-web-sidebar-session-title-hover-scroll.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
-# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-17-web-sidebar-session-title-hover-scroll.md
-2026-09-17-web-sidebar-session-title-hover-scroll.md: 07f802f2c64aa40bb13ba679cda2007112b58d69
-2026-09-17-web-sidebar-session-title-hover-scroll.zh.md: aa08bac5018304a0e25e93062f7cc45ca415799e
diff --git a/.agents/notes/implemented/feature/2026-09-17-web-sidebar-session-title-hover-scroll.md b/.agents/notes/implemented/feature/2026-09-17-web-sidebar-session-title-hover-scroll.md
deleted file mode 100644
index 07f802f2c6..0000000000
--- a/.agents/notes/implemented/feature/2026-09-17-web-sidebar-session-title-hover-scroll.md
+++ /dev/null
@@ -1,41 +0,0 @@
-# Agent Note: Web sidebar Session title hover scroll
-
-Status: implemented
-
-English | [中文](2026-09-17-web-sidebar-session-title-hover-scroll.zh.md)
-
-## Problem
-
-A Session title wider than its sidebar row is clipped with an ellipsis, so the part that distinguishes two related Sessions is the part that disappears. Fork makes it visible: the child's persisted title is the parent's plus an increment, so a long parent title leaves the `(1)` off the row's right edge. Opening the hover card shows the full title, but the card needs a dwell, covers neighboring rows, and is not the comparison the user is trying to make.
-
-## Decision
-
-A Session row reveals its clipped title in place while the pointer rests on the row. `SessionNodeItem` writes `title.scrollLeft = scrollWidth - clientWidth` on pointer enter and returns it with `scrollTo({ left: 0, behavior: 'instant' })` on pointer leave; the title element keeps `overflow: hidden`, so nothing reflows, no scrollbar appears, and the page never scrolls. Entering glides because the title carries `scroll-behavior: smooth` (the file's reduced-motion block restores `auto`), so the handler owns no timer or animation loop. Returning is deliberately one step: a smooth return would travel under the resting ellipsis and the row's narrowing cell for its whole duration.
-
-While the pointer is on the row, `text-overflow` switches from `ellipsis` to `clip`: a scrolled `overflow: hidden` box still paints the ellipsis at its right edge, which would cover exactly the characters the scroll just revealed (verified in Chromium before the rule was written). That rule sits behind `@media (hover: hover)`, because a touch tap latches `:hover` on the row after the title has already returned, and an unguarded rule would leave the tapped row hard-clipped at its start.
-
-The reveal belongs to the Session row, not to a single cell: entering anywhere on the row starts it, and it ends only when the pointer leaves the row. Workspace rows and search results keep their ellipsis behavior — their titles distinguish nothing by a trailing token — and only the Session title carries the scroll behavior.
-
-The hovered row is also the wider cell: its trailing relative-time label yields to the row menu, so the hovered `clientWidth` is larger than the resting one and the hovered scroll maximum is smaller. A handler that read the resting width would compute a larger delta that the browser clamps to the hovered maximum, reaching the same far edge; the browser scenario therefore polls the live extent instead of the value the handler read.
-
-## Alternatives considered
-
-**A moving inner span or a duplicated-copy marquee.** Rejected: `text-overflow: ellipsis` ellipsizes text directly inside the clipping block, so moving the text requires a nested element whose own clipping (or the duplicate copy) moves with it; the resting ellipsis, the existing DOM, and the accessible text would all change. Scrolling the existing element keeps every one of them.
-
-**A rAF or CSS-loop marquee.** Rejected: a continuous animation keeps moving while the user reads and needs per-row lifetime management. One scroll to the far edge and one back is the whole reveal.
-
-**`scrollTo({ behavior: 'smooth' })` for both moves.** Rejected: it needs a `matchMedia` probe for reduced motion plus a capability branch, and it would keep the return animating under the resting ellipsis. The stylesheet supplies the entering glide, and the leaving move asks for `instant` explicitly.
-
-**A handler-owned clip state cleared on `scrollend`.** Considered for the return transient; rejected because returning in one step removes the transient without a second state, an event listener, or a browser capability the jsdom lane lacks.
-
-**`direction: rtl` on hover.** Rejected: it jumps instead of scrolling and reorders punctuation inside mixed-direction titles.
-
-**Leaving the reveal to the hover card.** Rejected: the card opens only after its dwell and covers neighboring rows, so it cannot support comparing two adjacent rows.
-
-## Consequences
-
-A long title still occupies exactly one row line; the scroll range is measured from the element's own box, so a width change (the sidebar resizing, or the hovered row's own cell change) is picked up on the next pointer enter, and the instant return leaves the resting ellipsis and the text consistent whenever the pointer leaves. Revealing depends on a pointer resting on the row, so touch and keyboard users still rely on the hover card and the Rename dialog for the full title; removing the reveal leaves an ordinary ellipsized row.
-
-## Testing
-
-`packages/client/ui-workspace/tests/rows.client.spec.tsx` pins the scroll position written on pointer enter, the explicit instant return, and that a title that fits stays at its start. `packages/client/ui-workspace/tests/browser-styles.client.spec.ts` pins the stylesheet contract for the hovered row. `apps/web/tests/sidebar-title-hover-scroll.e2e.ts` hovers a seeded clipped row in the assembled application and asserts that the title really overflows, reaches its own live extent under the pointer, stops ellipsizing, returns to its start within one step, and that the computed scroll behavior is `smooth` in the default media state and `auto` under reduced motion.
diff --git a/.agents/notes/implemented/feature/2026-09-17-web-sidebar-session-title-hover-scroll.zh.md b/.agents/notes/implemented/feature/2026-09-17-web-sidebar-session-title-hover-scroll.zh.md
deleted file mode 100644
index aa08bac501..0000000000
--- a/.agents/notes/implemented/feature/2026-09-17-web-sidebar-session-title-hover-scroll.zh.md
+++ /dev/null
@@ -1,41 +0,0 @@
-# Agent Note: Web 侧栏 Session 标题悬停滚动
-
-Status: implemented
-
-[English](2026-09-17-web-sidebar-session-title-hover-scroll.md) | 中文
-
-## 问题
-
-标题宽于侧栏行时会被省略号裁切，于是区分两个相关 Session 的那一部分恰好消失。Fork 会让这件事暴露出来：子会话持久化标题是父标题加一个递增序号，父标题一长，`(1)` 就落到行的右边界之外。悬停卡片能显示完整标题，但它需要停留等待、会盖住相邻行，而且用户想做的比较并不是看卡片。
-
-## 决策
-
-指针停在 Session 行上时，该行就地显示被裁切的标题。`SessionNodeItem` 在指针进入时写入 `title.scrollLeft = scrollWidth - clientWidth`，在指针离开时用 `scrollTo({ left: 0, behavior: 'instant' })` 一次性回到起点；标题元素保持 `overflow: hidden`，因此不会重排、不会出现滚动条，页面本身也不滚动。进入时之所以平滑，是因为标题带有 `scroll-behavior: smooth`（本文件的减少动效块恢复为 `auto`），处理函数因此不持有定时器或动画循环。返回被有意做成一步到位：平滑返回会让静止态省略号和收窄后的格子在整个返回过程中一直覆盖着文字。
-
-指针停留在行上期间，`text-overflow` 由 `ellipsis` 切换为 `clip`：已滚动的 `overflow: hidden` 盒子仍会在右边界绘制省略号，而那正是刚刚被滚动显示出来的字符（写这条规则前已在 Chromium 中验证）。这条规则位于 `@media (hover: hover)` 之内，因为触屏点按会在标题已经返回之后仍让该行的 `:hover` 保持钉住，不设保护就会让被点按的行停在起点且硬裁切、失去省略号。
-
-该行为属于 Session 行，而不是某一格：指针进入行的任意位置都会开始，只有离开该行才结束。Workspace 行与搜索结果保留省略号行为——它们的标题没有靠尾部记号区分的含义——只有 Session 标题带有滚动行为。
-
-悬停中的行同时也是更宽的格子：行尾的相对时间标签会让位给行操作菜单，因此悬停时的 `clientWidth` 比静止时更大，可滚动上限更小。若处理函数读到的是静止宽度，它会算出一个更大的位移，浏览器会把它夹到悬停状态的上限，最终同样到达远端；因此浏览器场景断言的是实时到达范围，而不是处理函数读到的数值。
-
-## 备选方案
-
-**移动的内层元素或复制副本的跑马灯。** 否决：`text-overflow: ellipsis` 只对裁切块内直接包含的文本生效，因此移动文本需要嵌套元素，而它自身的裁切（或复制副本）会随之移动；静止态的省略号、现有 DOM 和可访问文本都会改变。滚动现有元素则三者都保留。
-
-**rAF 或 CSS 循环跑马灯。** 否决：持续动画会在用户阅读时继续移动，并且需要逐行管理生命周期。滚到远端再滚回一次，就是这个揭示所需的全部动作。
-
-**两个方向都用 `scrollTo({ behavior: 'smooth' })`。** 否决：它需要一个 `matchMedia` 探测来处理减少动效，还需要一个能力分支，并且会让返回过程在静止态省略号之下持续动画。进入的平滑由样式表提供，离开则显式要求 `instant`。
-
-**由处理函数持有裁切状态并在 `scrollend` 时清除。** 曾用于消除返回过程的瞬态；否决，因为一步返回直接消除该瞬态，无需第二个状态、事件监听或 jsdom 车道缺少的浏览器能力。
-
-**悬停时使用 `direction: rtl`。** 否决：它是跳变而非滚动，并且会重排混合方向标题中的标点。
-
-**把揭示交给悬停卡片。** 否决：卡片要等停留时间结束才出现，而且会盖住相邻行，无法支持并排比较两行。
-
-## 后果
-
-长标题仍然只占一行；滚动范围按元素自身盒宽测量，因此宽度变化（侧栏缩放，或悬停行自身的格子变化）会在下一次指针进入时被重新读取，而一步返回保证指针离开时静止态省略号与文字始终一致。揭示依赖指针停在行上，所以触屏与键盘用户仍需通过悬停卡片和重命名对话框获取完整标题；去掉该行为后，这一行只是普通的省略号行。
-
-## 测试
-
-`packages/client/ui-workspace/tests/rows.client.spec.tsx` 钉住指针进入时写入的滚动位置、显式的一步返回，以及能放下的标题停留在起点。`packages/client/ui-workspace/tests/browser-styles.client.spec.ts` 钉住悬停行的样式表契约。`apps/web/tests/sidebar-title-hover-scroll.e2e.ts` 在组装后的应用中悬停一条被裁切的种子会话行，断言标题确实溢出、到达指针下的实时范围、停止省略、一步回到起点，并断言默认媒体状态下计算出的滚动行为为 `smooth`、减少动效下为 `auto`。
diff --git a/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.i18n.yaml b/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.i18n.yaml
index 5b23d66658..c8bfb9d43c 100644
--- a/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.i18n.yaml
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.md
-2026-07-26-frozen-agent-note-archive.md: 0c139c4a5d892de5bdace76b4935edf32586c4c1
-2026-07-26-frozen-agent-note-archive.zh.md: 2c2751c56a9b20423b00eac7a90c02286ce3e8b0
+2026-07-26-frozen-agent-note-archive.md: e9ecfa78f53a5912608201654e2c56e399defccd
+2026-07-26-frozen-agent-note-archive.zh.md: 9a3ce2e6e21864f2754f627be6f7576bfc1f9076
diff --git a/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.md b/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.md
index 0c139c4a5d..e9ecfa78f5 100644
--- a/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.md
+++ b/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.md
@@ -10,9 +10,9 @@ Implemented Agent Notes are maintained as current decision records, so every pat
## Decision
-Only implemented Agent Notes can be archived. An implemented note moves when its shipped decision is complete and its rationale, alternatives, consequences, negative guarantees, and reintroduction conditions are unlikely to guide future work. Foundational boundaries, durable and wire semantics, security rules, recurring design temptations, and unresolved reintroduction conditions remain active regardless of age or word count. Proposed notes never enter the archive; an obsolete proposal becomes rejected. A rejected note remains only while it prevents a tempting, meaningful mistake and is otherwise deleted as a complete triplet.
+Implemented notes that only describe small UI adjustments or purely mechanical changes are deleted as complete triplets, with inbound links repaired or removed. A small implementation can still carry lasting naming, compatibility, ownership, or behavior decisions; those records remain eligible for retention. Only other implemented Agent Notes can be archived: the shipped decision is complete, its rationale is unlikely to guide future work, and it still has historical decision value. Foundational boundaries, durable and wire semantics, security rules, recurring design temptations, and unresolved reintroduction conditions remain active regardless of age or word count. Proposed notes never enter the archive; an obsolete proposal becomes rejected. A rejected note remains only while it prevents a tempting, meaningful mistake and is otherwise deleted as a complete triplet.
-The archive uses `.agents/notes/archived/{kind}/yyyy-mm-dd-topic.md`; the redundant `implemented` segment is absent. The archival change moves the complete English, Chinese, and consistency-sidecar triplet, leaves `Status: implemented` intact, and inserts `Archived: YYYY-MM-DD` immediately below it in both language files. Relocation, that metadata line, the corresponding sidecar re-record, and mechanical inbound-link repair are the only permitted archival edits.
+The archive uses `.agents/notes/archived/{kind}/yyyy-mm-dd-topic.md`; the redundant `implemented` segment is absent. The archival change moves the complete English, Chinese, and consistency-sidecar triplet, leaves `Status: implemented` intact, and inserts `Archived: YYYY-MM-DD` immediately below it in both language files. Relocation, that metadata line, the corresponding sidecar re-record, and mechanical inbound-link repair are the only permitted archival edits. Archival admission checks lifecycle metadata and completeness, not title punctuation, blank-line layout, or language-switcher wording; requiring those repairs would rewrite the historical record.
The root `.rgignore` excludes the archive from searches that traverse a parent directory. Historical queries name the archive directory explicitly, so intentional access remains available without mixing frozen facts into active decision discovery.
@@ -42,4 +42,4 @@ Supersession is checked while a new Agent Note is being written, not deferred to
## Consequences
-The active corpus becomes a set of decisions expected to influence future work, while low-value implemented history remains explicitly searchable and linkable without consuming maintenance attention or appearing in parent-directory searches. Writing a new note includes a scoped supersession check, so replacement decisions cannot silently leave redundant active records behind. Rejected clutter can disappear when it no longer protects a meaningful choice, and proposed work cannot quietly evade a verdict through archival. The archive adds a manifest, a dedicated verifier, and an explicit one-time metadata step. Archived facts and outbound links can become stale by design, so readers and agents must treat active code and documentation as authority and cite an archived note only as history.
+The active corpus becomes a set of decisions expected to influence future work, while substantive historical decisions with little future guidance remain explicitly searchable and linkable without consuming maintenance attention or appearing in parent-directory searches. Writing a new note includes a scoped supersession check, so replacement decisions cannot silently leave redundant active records behind. Rejected clutter can disappear when it no longer protects a meaningful choice, and proposed work cannot quietly evade a verdict through archival. The archive adds a manifest, a dedicated verifier, and an explicit one-time metadata step. Archived facts and outbound links can become stale by design, so readers and agents must treat active code and documentation as authority and cite an archived note only as history.
diff --git a/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.zh.md b/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.zh.md
index 2c2751c56a..9a3ce2e6e2 100644
--- a/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.zh.md
+++ b/.agents/notes/implemented/process/2026-07-26-frozen-agent-note-archive.zh.md
@@ -10,9 +10,9 @@ implemented Agent Note 作为当前决策记录持续维护，因此活跃记录
## 决策
-只有 implemented Agent Note 可以归档。当一份已实施记录的交付决策已经完整落地，且其决策依据、备选方案、后果、否定性保证和重新引入条件不太可能再指导未来工作时，将其移入归档。基础性边界、持久语义与协议语义、安全规则、反复出现且看似诱人的设计选择和尚未解决的重新引入条件，无论记录的存续时间或字数如何，都继续作为活跃记录保留。proposed Agent Note 绝不进入归档；过时的提案应转为 rejected。仅当 rejected Agent Note 仍能避免一种诱人且影响重大的错误时保留，否则将其三个配对文件完整删除。
+仅描述小型 UI 调整或纯机械变更的 implemented Agent Note 会作为完整的三文件配对删除，并修复或移除入站链接。小规模实现仍可能承载长期有效的命名、兼容性、归属或行为决策；此类记录仍可保留。只有其他 implemented Agent Note 可以归档：交付决策已经完整落地，其依据不太可能再指导未来工作，但仍具有历史决策价值。基础性边界、持久语义与协议语义、安全规则、反复出现且看似诱人的设计选择和尚未解决的重新引入条件，无论记录的存续时间或字数如何，都继续作为活跃记录保留。proposed Agent Note 绝不进入归档；过时的提案应转为 rejected。仅当 rejected Agent Note 仍能避免一种诱人且影响重大的错误时保留，否则将其三个配对文件完整删除。
-归档路径为 `.agents/notes/archived/{kind}/yyyy-mm-dd-topic.md`，其中省略了冗余的 `implemented` 层级。归档变更会移动完整的英文、中文和一致性伴随记录三个文件，保留 `Status: implemented`，并在两种语言的文件中紧接该状态行插入 `Archived: YYYY-MM-DD`。归档时只允许做文件迁移、添加该元数据行、相应地重新记录伴随记录，以及机械修复入站链接。
+归档路径为 `.agents/notes/archived/{kind}/yyyy-mm-dd-topic.md`，其中省略了冗余的 `implemented` 层级。归档变更会移动完整的英文、中文和一致性伴随记录三个文件，保留 `Status: implemented`，并在两种语言的文件中紧接该状态行插入 `Archived: YYYY-MM-DD`。归档时只允许做文件迁移、添加该元数据行、相应地重新记录伴随记录，以及机械修复入站链接。 归档准入检查生命周期元数据与完整性，不检查标题标点、空行布局或语言切换栏措辞；要求修复这些格式会改写历史记录。
根目录的 `.rgignore` 会将归档目录排除在从上层目录开始的搜索之外。查找历史内容时会显式指定归档目录，因此仍可按需访问，同时不会把冻结事实混入对活跃决策的检索。
@@ -42,4 +42,4 @@ implemented Agent Note 作为当前决策记录持续维护，因此活跃记录
## 后果
-活跃记录集合由预计仍会影响未来工作的决策组成；未来指导价值较低的实施历史仍可显式搜索和链接，却不再消耗维护精力，也不会出现在从上层目录开始的搜索中。编写新记录时会包含一项范围明确的取代关系检查，因此取代既有决策的新决策无法悄然留下冗余的活跃记录。当被否决的记录不再保护有意义的选择时，可以清除这类杂项；提案也无法通过归档悄悄逃避明确结论。归档机制增加一份 manifest、一个专用校验器和一个显式的一次性元数据步骤。归档中的事实和出站链接可以按设计逐渐陈旧，因此读者和 agent（智能体）必须以活跃代码与文档为权威依据，并且仅将归档 Agent Note 作为历史引用。
+活跃记录集合由预计仍会影响未来工作的决策组成；未来指导价值较低但具有实质内容的历史决策仍可显式搜索和链接，却不再消耗维护精力，也不会出现在从上层目录开始的搜索中。编写新记录时会包含一项范围明确的取代关系检查，因此取代既有决策的新决策无法悄然留下冗余的活跃记录。当被否决的记录不再保护有意义的选择时，可以清除这类杂项；提案也无法通过归档悄悄逃避明确结论。归档机制增加一份 manifest、一个专用校验器和一个显式的一次性元数据步骤。归档中的事实和出站链接可以按设计逐渐陈旧，因此读者和 agent（智能体）必须以活跃代码与文档为权威依据，并且仅将归档 Agent Note 作为历史引用。
diff --git a/.agents/notes/implemented/process/2026-09-07-issue-policy-module-ownership.i18n.yaml b/.agents/notes/implemented/process/2026-09-07-issue-policy-module-ownership.i18n.yaml
deleted file mode 100644
index 37bf7d8e0c..0000000000
--- a/.agents/notes/implemented/process/2026-09-07-issue-policy-module-ownership.i18n.yaml
+++ /dev/null
@@ -1,6 +0,0 @@
-# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
-# side as of the last confirmed-consistent state. Both languages carry equal authority;
-# after editing either side, bring the other along and re-record with:
-# pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-09-07-issue-policy-module-ownership.md
-2026-09-07-issue-policy-module-ownership.md: 696343ddffa3f6a6e411330d038bb4a470ce78d8
-2026-09-07-issue-policy-module-ownership.zh.md: abe539a5baed35cf2f356194eab8e53d61b67314
diff --git a/.agents/notes/implemented/process/2026-09-07-issue-policy-module-ownership.md b/.agents/notes/implemented/process/2026-09-07-issue-policy-module-ownership.md
deleted file mode 100644
index 696343ddff..0000000000
--- a/.agents/notes/implemented/process/2026-09-07-issue-policy-module-ownership.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# Agent Note: Issue policy module ownership
-
-Status: implemented
-
-English | [中文](2026-09-07-issue-policy-module-ownership.zh.md)
-
-## Problem
-
-Issue validation and Project lifecycle processing use the same reference parser, metadata rules, and GitHub reads, but they make different decisions and perform different writes. Keeping those responsibilities in the command entry makes it harder to reuse policy rules without also depending on event dispatch and output handling.
-
-## Decision
-
-Issue management separates pure decisions, GitHub access, pull-request evaluation, lifecycle mutations, and command dispatch into owner modules. [The owner reference](../../../../.github/issue-management/README.md#module-ownership) maps those responsibilities to source files. Callers and tests import the module that owns the operation rather than using the command entry as an export collection.
-
-The separation preserves policy results, diagnostics, credentials, API requests, lifecycle mutations, and workflow entry commands. [Selective evaluation](2026-09-07-selective-issue-policy-evaluation.md) remains the independent owner of eligibility, Project-read selection, and event scheduling; this decision does not redefine those behaviors.
-
-## Alternatives considered
-
-**Keep one command module.** A single file avoids imports between local owners, but ties reusable decisions and GitHub access to command handling. Separate owners let PR validation and lifecycle processing share their existing rules and reads without sharing command dispatch.
-
-## Consequences
-
-Maintainers can locate a rule, network operation, or event handler by responsibility. Reuse occurs through ordinary local ESM imports, not a new package or plugin API. The added modules introduce imports that must stay coordinated when a shared function changes.
-
-Module separation does not grant stronger credentials, change check authority, serialize Project mutations, or prevent a future behavior regression. Existing lifecycle races and field-management limitations remain documented by their behavior owners.
-
-## Verification
-
-[Policy tests](../../../../.github/issue-management/policy.test.mjs) exercise the owner modules and check observable policy and lifecycle behavior. [Workflow tests](../../../../scripts/ci-workflow.spec.ts) cover the command wiring and workflow declarations. Their evidence concerns the checked implementation, not a guarantee that later edits preserve behavior.
diff --git a/.agents/notes/implemented/process/2026-09-07-issue-policy-module-ownership.zh.md b/.agents/notes/implemented/process/2026-09-07-issue-policy-module-ownership.zh.md
deleted file mode 100644
index abe539a5ba..0000000000
--- a/.agents/notes/implemented/process/2026-09-07-issue-policy-module-ownership.zh.md
+++ /dev/null
@@ -1,29 +0,0 @@
-# Agent Note: Issue 策略模块归属
-
-Status: implemented
-
-[English](2026-09-07-issue-policy-module-ownership.md) | 中文
-
-## 问题
-
-Issue 校验与 Project 生命周期处理使用相同的引用解析器、元数据规则和 GitHub 读取，但各自作出不同决策、执行不同写入。将这些职责放在命令入口中，会使复用策略规则时更难摆脱对事件分派与输出处理的依赖。
-
-## 决策
-
-Issue 管理将纯决策、GitHub 访问、PR（Pull Request）求值、生命周期 mutation 和命令分派分配给各自的所属模块。[所属参考文档](../../../../.github/issue-management/README.zh.md#module-ownership)将这些职责对应到源文件。调用方和测试直接导入拥有该操作的模块，不把命令入口用作导出集合。
-
-此职责分离保留策略结果、诊断、凭据、API 请求、生命周期 mutation 和工作流入口命令。[选择性求值](2026-09-07-selective-issue-policy-evaluation.zh.md)仍独立拥有强制范围、Project 读取选择和事件调度规则；本决策不重新定义这些行为。
-
-## 考虑过的替代方案
-
-**保留单一命令模块。** 单文件可以避免本地所属模块之间的导入，但会把可复用的决策与 GitHub 访问绑定到命令处理。独立的所属模块让 PR 校验和生命周期处理可以共享既有规则与读取，而无需共享命令分派。
-
-## 影响
-
-维护者可以按职责定位规则、网络操作或事件处理器。复用通过普通的本地 ESM 导入完成，而不是新增包或插件 API。新增模块引入的导入关系需要在共享函数变更时同步维护。
-
-模块分离不会授予更强的凭据、更改检查权威来源、串行化 Project mutation，也不能防止未来的行为回归。既有生命周期竞态与字段管理限制仍由各自的行为文档记录。
-
-## 验证
-
-[策略测试](../../../../.github/issue-management/policy.test.mjs)运行所属模块，并检查可观察的策略与生命周期行为。[工作流测试](../../../../scripts/ci-workflow.spec.ts)覆盖命令接线与工作流声明。这些证据针对被检查的实现，不保证后续编辑仍保留行为。
diff --git a/.agents/notes/implemented/architecture/2026-09-16-desktop-policy-login-loading.i18n.yaml b/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.i18n.yaml
similarity index 55%
rename from .agents/notes/implemented/architecture/2026-09-16-desktop-policy-login-loading.i18n.yaml
rename to .agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.i18n.yaml
index b25a4b72b4..04d246c108 100644
--- a/.agents/notes/implemented/architecture/2026-09-16-desktop-policy-login-loading.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.i18n.yaml
@@ -1,6 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
-# pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-16-desktop-policy-login-loading.md
-2026-09-16-desktop-policy-login-loading.md: 26fd635c6cc5b92cad8011919382a11497d2e835
-2026-09-16-desktop-policy-login-loading.zh.md: 16de25323afc971b3142d5359c769df50c08800d
+# pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.md
+2026-09-17-windows-runtime-signature-cache.md: 909e39b5c06ed9d529df7553de324295aadf43fe
+2026-09-17-windows-runtime-signature-cache.zh.md: c7ee5e1ca5105c21e3a7f4b43342dee20331e88b
diff --git a/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.md b/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.md
new file mode 100644
index 0000000000..909e39b5c0
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.md
@@ -0,0 +1,35 @@
+# Agent Note: Windows runtime signature cache
+
+Status: implemented
+
+English | [中文](2026-09-17-windows-runtime-signature-cache.zh.md)
+
+## Problem
+
+Windows packaging reconstructs unsigned native dependencies on each build. Signing unchanged Python and LibreOffice files repeats hardware-token and timestamp operations. Starting PowerShell for each public-key inspection also repeats process initialization.
+
+## Decision
+
+Cache complete signed runtime files by original content, public certificate, SignTool bytes, signing-script bytes and cache format. Keep valid vendor signatures. Restore a cache hit through a private staged copy only after checking the input record, signed-file digest, Windows trust, timestamp and configured certificate; reject invalid entries without automatic repair or hardware fallback. Publish complete entries atomically, and retain an existing valid entry when concurrent publishers collide.
+
+Group public-key inspection into bounded batches of 32 files with at most four processes. Require one ordered result for every requested path and await every process in a failed batch. Preserve verification immediately after each hardware signature, before the next signing request.
+
+The [primary-runtime decision](../feature/2026-09-14-desktop-primary-runtime.md) continues to own runtime contents, vendor-signature preservation and execution checks. The [release decision](../architecture/2026-08-25-electron-desktop-packaging-and-updates.md) continues to own release identity and signing. Neither is superseded. The cache must preserve their supervised preflight, per-user signing interlock, single-file hardware calls, signed inventory and final packaged-runtime validation.
+
+## Alternatives considered
+
+**Multi-file hardware signing.** The primary-runtime decision records that SignTool can continue after the first file fails. Reducing repeated hardware work through caching preserves the existing stop behavior.
+
+**Detached signature extraction and attachment.** Complete-file caching avoids adding PE-signature manipulation to packaging. Its additional disk use is measurable and confined to build storage.
+
+**Whole signed-runtime artifacts only.** They can also avoid extraction and copying, but require assembly and dependency-graph identities. Per-file caching can reuse unchanged native dependencies when application code or one dependency changes.
+
+## Consequences
+
+Repeated builds with unchanged native inputs avoid hardware calls for cached files while retaining preflight and final artifact signing. Changed content or signing policy misses the cache. Corrupt, incomplete, untrusted or incorrectly timestamped entries fail without replacing the target or retrying hardware. Concurrent publication and interrupted processes cannot expose incomplete entries or damage another build's files.
+
+Six complete signed Windows x64 builds cover an empty signature cache, repeated inputs, application changes and one controlled native-file content change. Warm builds reduce hardware calls from 379 to 17 and elapsed time from 37:38 to 12:36–12:42 on the measured host, while final runtime checks pass. Download caches remain populated; the controlled file change tests invalidation, not a dependency-version upgrade. Installer execution and update qualification remain separate.
+
+## Risks
+
+The cache consumes local disk and depends on the build account controlling its files and records. It is not a distribution format for untrusted remote caches. Signature validation still depends on Windows trust services; cache hits do not authorize clearing a signing interlock or retrying a failed token operation. A timestamp-service failure can interrupt a cold build even after a successful preflight.
diff --git a/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.zh.md b/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.zh.md
new file mode 100644
index 0000000000..c7ee5e1ca5
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.zh.md
@@ -0,0 +1,35 @@
+# Agent Note: Windows 运行时签名缓存
+
+Status: implemented
+
+[English](2026-09-17-windows-runtime-signature-cache.md) | 中文
+
+## Problem
+
+Windows 打包每次都会重新生成未签名的原生依赖。为未变化的 Python 和 LibreOffice 文件签名会重复执行硬件令牌操作和时间戳请求。每个公钥验签任务单独启动 PowerShell，也会重复进程初始化。
+
+## Decision
+
+按原始内容、公开证书、SignTool 字节、签名脚本字节和缓存格式缓存完整已签名运行时文件。保留有效厂商签名。缓存命中后，通过私有暂存副本核对输入记录、已签名文件摘要、Windows 信任、时间戳和配置的证书，再恢复目标文件；无效缓存项直接失败，不自动修复或回退到硬件签名。完整缓存项原子发布，并发发布冲突时保留已有有效项。
+
+公钥验签按每批 32 个文件分组，最多同时运行四个进程。要求每个请求路径都有一条顺序对应的结果，并等待失败批次中的所有进程退出。每次硬件签名后仍立即验签，通过后才开始下一个签名请求。
+
+[主要运行时决策](../feature/2026-09-14-desktop-primary-runtime.zh.md) 继续定义运行时内容、厂商签名保留和执行检查。[发布决策](../architecture/2026-08-25-electron-desktop-packaging-and-updates.zh.md) 继续定义发布身份和签名。两者均未被取代。缓存必须保留受监督预检、每用户签名互锁、单文件硬件调用、已签名内容清单和最终打包运行时验证。
+
+## Alternatives considered
+
+**多文件硬件签名。** 主要运行时决策记录了 SignTool 在首个文件失败后仍继续处理的行为。通过缓存减少重复硬件操作，可以保留现有停止语义。
+
+**分离签名的提取与附加。** 缓存完整文件可以避免给打包流程新增 PE 签名处理代码。其额外磁盘占用可测量，且限于构建存储。
+
+**仅复用整个已签名运行时制品。** 该方案还可以省去解压和复制，但需要标识组装流程及依赖图。逐文件缓存可以在应用代码或单个依赖变化时复用其余未变化的原生依赖。
+
+## Consequences
+
+原生输入未变化的重复构建不再为缓存覆盖的文件调用硬件签名，但仍执行预检和最终制品签名。内容或签名策略变化时缓存未命中。损坏、不完整、不可信或时间戳不合格的缓存项必须失败，不替换目标文件，也不重试硬件。并发发布和进程中断不能暴露不完整缓存项或损坏其他构建的文件。
+
+六轮完整 Windows x64 签名构建覆盖空签名缓存、重复输入、应用变化和单个原生文件的受控内容变化。在测量主机上，热构建将硬件调用从 379 次降至 17 次，耗时从 37:38 降至 12:36–12:42，且最终运行时检查通过。下载缓存保持已填充；受控文件变化验证缓存失效，不代表依赖版本升级。安装器执行和更新验收仍需单独进行。
+
+## Risks
+
+缓存占用本地磁盘，并依赖构建账户控制缓存文件及记录。它不是用于不可信远程缓存的分发格式。签名验证仍依赖 Windows 信任服务；缓存命中不构成清除签名互锁或重试失败令牌操作的授权。即使预检成功，时间戳服务故障仍可能中断冷构建。
diff --git a/.agents/notes/implemented/feature/2026-09-09-turn-duration-hour-unit.i18n.yaml b/.agents/notes/implemented/process/2026-09-17-windows-signature-completion.i18n.yaml
similarity index 56%
rename from .agents/notes/implemented/feature/2026-09-09-turn-duration-hour-unit.i18n.yaml
rename to .agents/notes/implemented/process/2026-09-17-windows-signature-completion.i18n.yaml
index 209fc7e492..c8a392f733 100644
--- a/.agents/notes/implemented/feature/2026-09-09-turn-duration-hour-unit.i18n.yaml
+++ b/.agents/notes/implemented/process/2026-09-17-windows-signature-completion.i18n.yaml
@@ -1,6 +1,6 @@
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
-# pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-09-turn-duration-hour-unit.md
-2026-09-09-turn-duration-hour-unit.md: f0f5cb478dafa7938614bdeeec3a6de9f58aed8d
-2026-09-09-turn-duration-hour-unit.zh.md: c9c94eef2a88a0f58d5f5a05332b4b5034ef977a
+# pnpm run verify-translation-pairing --write .agents/notes/implemented/process/2026-09-17-windows-signature-completion.md
+2026-09-17-windows-signature-completion.md: e9c81531633a41c87ea10c9e4af2999923aa4470
+2026-09-17-windows-signature-completion.zh.md: 3142749db309b638676c171d4b1da8bd34729fe4
diff --git a/.agents/notes/implemented/process/2026-09-17-windows-signature-completion.md b/.agents/notes/implemented/process/2026-09-17-windows-signature-completion.md
new file mode 100644
index 0000000000..e9c8153163
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-09-17-windows-signature-completion.md
@@ -0,0 +1,35 @@
+# Agent Note: Separate Windows hardware signing from timestamp completion
+
+Status: implemented
+
+English | [中文](2026-09-17-windows-signature-completion.zh.md)
+
+## Problem
+
+A combined SignTool command reports timestamp failure as signing failure. Retrying it repeats hardware access, while treating every timestamp error as an uncertain private-key outcome requires administrator recovery. Public timestamp-only requests can fail independently of the token.
+
+## Decision
+
+Sign a private PE copy once without a timestamp. Release the hardware interlock only after successful execution and Windows verification of the configured primary signature. Hardware or primary-verification failures retain the interlock; no path automatically recovers it. Appended signatures are unsupported.
+
+Timestamp fresh copies of the frozen signed file without signing credentials. Only normal failure or warning exits permit another attempt: at most three calls, with one- and two-second delays. Launch failures, uncertain termination, storage changes and verification failures stop immediately. The preflight's overall 60-second deadline includes these operations and does not guarantee three full subprocess deadlines.
+
+Require Windows trust, timestamp and certificate identity. Remove unsigned signature attributes from private copies with the configured SignTool and compare their complete normalized bytes. A removal warning is accepted only when all bytes remain unchanged. Certificate equality alone cannot exclude different content signed by the same certificate; full-file equality avoids a custom PE or ASN.1 canonicalizer.
+
+SignTool uses short filenames with the original extension in a private temporary directory. Its longest generated path is checked before hardware access, and the journal records the original-to-staged mapping. The target may occupy another volume: copy verified bytes into a private directory beside it, compare hashes, recheck the original and rename within that volume. Verify committed bytes afterward. The build account must own trusted storage and exclusive target access.
+
+Exhausted timestamp attempts stop packaging and queued work without another hardware call. Failure evidence is copied to the supervised run before staging cleanup; evidence or audit failure preserves staging. Final artifact verification and release completion remain mandatory. The [primary-runtime decision](../feature/2026-09-14-desktop-primary-runtime.md) owns runtime contents and vendor signatures.
+
+## Alternatives considered
+
+**Retry combined signing or classify diagnostic text.** Exit codes and localized text cannot establish the private-key outcome. Separate operations avoid repeated hardware access.
+
+**Reuse failed timestamp output.** A failed process may partially modify its file. Every attempt starts with identical verified primary-signature bytes.
+
+**Stage beside each target for all operations.** Nested dependencies can exceed SignTool's path limit even when the original fits. Short tool paths and same-volume publication address separate requirements.
+
+## Consequences
+
+Fault tests cover lock retention, isolated timestamp retries, queue rejection, credential exclusion, substituted content, changed targets, long paths and evidence failures. Public-only qualification covers EXE, DLL, PYD and NODE files, including failure followed by success and cross-volume publication. A real supervised signing preflight has passed; complete installer comparisons remain separate qualification. This decision does not identify or repair the timestamp service's network failures.
+
+DigiCert [supports separate signing and timestamping](https://knowledge.digicert.com/solution/troubleshooting-timestamping-problems). Microsoft documents [SignTool commands and exit codes](https://learn.microsoft.com/en-us/windows/win32/seccrypto/signtool). The configured tool and normalization implementation participate in signature-cache identity.
diff --git a/.agents/notes/implemented/process/2026-09-17-windows-signature-completion.zh.md b/.agents/notes/implemented/process/2026-09-17-windows-signature-completion.zh.md
new file mode 100644
index 0000000000..3142749db3
--- /dev/null
+++ b/.agents/notes/implemented/process/2026-09-17-windows-signature-completion.zh.md
@@ -0,0 +1,35 @@
+# Agent Note：分离 Windows 硬件签名与时间戳处理
+
+Status: implemented
+
+[English](2026-09-17-windows-signature-completion.md) | 中文
+
+## 问题
+
+合并的 SignTool 命令把时间戳失败报告为签名失败。重试会重复访问硬件，而把所有时间戳错误都视为私钥操作结果不确定，又需要管理员恢复。公开时间戳请求可以在不使用令牌的情况下独立失败。
+
+## 决策
+
+对私有 PE 副本仅签名一次，不请求时间戳。只有命令成功且 Windows 验证配置证书的主签名后，才释放硬件互锁。硬件或主签名验证失败保留互锁；任何路径都不自动恢复互锁。不支持追加签名。
+
+从固定的已签名文件生成新副本并请求时间戳，不传递签名凭据。只有正常退出但返回失败或警告时才允许再次尝试：最多调用三次，间隔为一秒和两秒。启动失败、终止状态不确定、存储变化和验签失败会立即停止。预检整体 60 秒期限包含这些操作，不保证每次子进程都能获得完整期限。
+
+要求 Windows 信任、时间戳和证书身份均通过验证。使用配置的 SignTool 删除私有副本的未签名属性，再比较完整的规范化字节。删除警告仅在所有字节未变时接受。仅比较证书无法排除由同一证书签署的不同内容；全文件相等检查避免自行实现 PE 或 ASN.1 规范化器。
+
+SignTool 在私有临时目录中使用保留原扩展名的短文件名。访问硬件前检查生成的最长路径，日志记录原文件与暂存文件的对应关系。目标可以位于另一个卷：将已验证字节复制到目标旁的私有目录，比较摘要，重新检查原文件，再在同一卷内重命名。随后验证提交后的字节。构建账户必须拥有受信任的存储和目标独占访问权。
+
+时间戳尝试耗尽后，停止打包和排队任务，不再次调用硬件。清理暂存目录前，将失败证据复制到受监督运行目录；证据保存或审计失败时保留暂存目录。最终产物验签和发布完成检查仍是必需步骤。[第一方运行时决策](../feature/2026-09-14-desktop-primary-runtime.zh.md)负责运行时内容与上游签名。
+
+## 考虑过的替代方案
+
+**重试合并签名命令或按诊断文本分类。** 退出码和本地化文本无法确定私钥操作结果。分离操作避免重复访问硬件。
+
+**复用失败的时间戳输出。** 失败进程可能已部分修改文件。每次尝试均从相同的已验证主签名字节开始。
+
+**所有操作都在目标旁暂存。** 即使原路径未超限，嵌套依赖的暂存路径也可能超出 SignTool 限制。短工具路径和同卷发布分别满足不同要求。
+
+## 影响
+
+故障测试覆盖互锁保留、独立时间戳重试、队列拒绝、凭据隔离、内容替换、目标变化、长路径和证据保存失败。仅使用公开操作的验收覆盖 EXE、DLL、PYD 和 NODE 文件，包括先失败后成功及跨卷发布。真实受监督签名预检已通过；完整安装包对比仍需单独验收。此决策不确定或修复时间戳服务的网络故障。
+
+DigiCert [支持分开签名与添加时间戳](https://knowledge.digicert.com/solution/troubleshooting-timestamping-problems)。Microsoft 记录了 [SignTool 命令及退出码](https://learn.microsoft.com/en-us/windows/win32/seccrypto/signtool)。配置的工具和规范化实现均参与签名缓存身份计算。
diff --git a/.agents/notes/implemented/simplification/2026-09-17-plugin-inventory-phase-dot.md b/.agents/notes/implemented/simplification/2026-09-17-plugin-inventory-phase-dot.md
deleted file mode 100644
index e90d49b6a3..0000000000
--- a/.agents/notes/implemented/simplification/2026-09-17-plugin-inventory-phase-dot.md
+++ /dev/null
@@ -1,35 +0,0 @@
-# Agent Note: The plugin inventory reserves its status dot for phases the tag cannot state
-
-Status: implemented
-
-English | [中文](2026-09-17-plugin-inventory-phase-dot.zh.md)
-
-## Problem
-
-The Settings plugin list marks every Loader entry with an enablement tag (`已启用`, `已停用`, `条件启用`, `预设中启用`, `启动失败`). It also drew a colored root-fiber status dot on enabled rows whose fiber was live. For the common `active` phase the dot and the tag stated the same thing twice on one collapsed card, while `pending`, `loading` and `unloading` — the phases the tag has no words for — were where the dot carried its own information.
-
-## Decision
-
-`PluginInventorySettingsTab` renders the status dot only for `pending`, `loading` and `unloading`. `active` and `failed` render no dot: a settled enabled row shows its enablement tag alone, and a failed row has the failure tag and card treatment. `PHASE_DOT_STATES` lists exactly the dotted phases, and `showsPhaseDot` narrows a phase to that union.
-
-Row enablement, tag tones, grouping, search and list behavior are unchanged, as are the Loader lifecycle and persistence. The expanded card still lists the phase under 运行状态 / Status, so the runtime phase stays readable without the collapsed dot.
-
-## Alternatives considered
-
-**Remove the dot for every phase.** Simpler to state, but it drops the only collapsed-state signal that a plugin is still loading or unloading — the one state the tag cannot express.
-
-**Keep the `active` dot on preset rows only.** The preset group is where the duplication was first noticed, but the global group renders the same tag-and-dot pair. A per-group exception would make one rendering rule depend on which group a row sits in, and would leave the duplicate in the global group.
-
-**Fold the phase into the enablement tag.** The tag reports the config fact the Host publishes as `enabled`; adding a runtime phase would make one control carry two lifecycles with different owners.
-
-## Consequences
-
-- A collapsed card no longer shows that an enabled entry's fiber is currently `active`. A reader who needs the phase expands the row, whose Status fact keeps it. That is the information the change deliberately gives up.
-- Rows mid-transition keep their dot, its animation and its `role="img"` name, so the accessible name still says `等待依赖`, `加载中` or `卸载中`.
-- Known gap, pre-existing and unchanged: the dot is gated on `row.enabled`, so a row a user just disabled while its fiber is still `unloading` shows `已停用` without a dot.
-
-## Testing
-
-The package spec pins the rule in both scopes: `loading` and `pending` (global) and `unloading` (preset) keep a dot, while `active`, `failed` and a row without a live fiber render none. `apps/web/tests/settings-chrome.e2e.ts` asserts the assembled global group contains enabled rows and no `role="img"` element named `运行中`.
-
-The remaining dots' palette, halo and animation, and the tag capsule itself, stay owned by [the shared client control decision](../architecture/2026-09-05-shared-client-control-primitives.md).
diff --git a/.agents/notes/implemented/simplification/2026-09-17-plugin-inventory-phase-dot.zh.md b/.agents/notes/implemented/simplification/2026-09-17-plugin-inventory-phase-dot.zh.md
deleted file mode 100644
index d344ede75c..0000000000
--- a/.agents/notes/implemented/simplification/2026-09-17-plugin-inventory-phase-dot.zh.md
+++ /dev/null
@@ -1,35 +0,0 @@
-# Agent Note: 插件列表只为主题标签无法表达的阶段保留状态圆点
-
-Status: implemented
-
-[English](2026-09-17-plugin-inventory-phase-dot.md) | 中文
-
-## 问题
-
-设置里的插件列表给每个 Loader 条目配一个启停标签（`已启用`、`已停用`、`条件启用`、`预设中启用`、`启动失败`），同时给 fiber 存活的已启用条目画一个彩色根 fiber 状态圆点。对最常见的 `active` 阶段，圆点与标签在同一张收起卡片上把同一件事说了两遍；而标签没有词可用的 `pending`、`loading`、`unloading`，才是圆点真正携带独立信息的阶段。
-
-## 决策
-
-`PluginInventorySettingsTab` 只为 `pending`、`loading`、`unloading` 渲染状态圆点。`active` 与 `failed` 不渲染：已稳定启用的条目只显示启停标签，失败条目由失败标签和卡片样式说明。`PHASE_DOT_STATES` 只列出有圆点的阶段，`showsPhaseDot` 把阶段收窄到该联合。
-
-条目启停、标签色调、分组、搜索与列表行为不变，Loader 生命周期与持久化也不变。展开卡片仍在「运行状态」下给出阶段名，因此不画收起态圆点也能读到运行时阶段。
-
-## 否决的备选方案
-
-**所有阶段都不画圆点。** 规则更简单，但会丢掉收起态下唯一能说明插件正在加载或卸载的信号——恰恰是标签无法表达的那个状态。
-
-**只在预设分组保留 `active` 圆点。** 重复最先是在预设分组被注意到的，但全局分组渲染的是同一套标签加圆点。按分组开例外会让同一条渲染规则取决于条目落在哪个分组，而且全局分组的重复仍然存在。
-
-**把阶段并进启停标签。** 标签报告的是 Host 以 `enabled` 发布的配置事实；再塞一个运行时阶段会让一个控件承载两条归属不同的生命周期。
-
-## 后果
-
-- 收起卡片不再显示已启用条目的 fiber 当前处于 `active`。需要该阶段的读者展开条目，其「运行状态」事实仍然给出。这是本次变更刻意放弃的信息。
-- 过渡中的条目保留圆点、动画与 `role="img"` 名称，无障碍名称仍会读出 `等待依赖`、`加载中` 或 `卸载中`。
-- 既有且未改变的缺口：圆点以 `row.enabled` 为前提，用户刚停用而 fiber 仍在 `unloading` 的条目只显示 `已停用`，没有圆点。
-
-## 测试
-
-包级用例在两个作用域钉住规则：`loading` 与 `pending`（全局）、`unloading`（预设）保留圆点，`active`、`failed` 与没有存活 fiber 的条目都不渲染。`apps/web/tests/settings-chrome.e2e.ts` 断言装配后的全局分组含有已启用条目，且没有名为 `运行中` 的 `role="img"` 元素。
-
-其余圆点的配色、光晕与动画，以及标签胶囊本身，仍由[共享客户端控件决策](../architecture/2026-09-05-shared-client-control-primitives.zh.md)拥有。
diff --git a/.agents/notes/proposed/simplification/2026-09-17-defer-office-background-scheduling.i18n.yaml b/.agents/notes/proposed/simplification/2026-09-17-defer-office-background-scheduling.i18n.yaml
new file mode 100644
index 0000000000..35fe5b54d9
--- /dev/null
+++ b/.agents/notes/proposed/simplification/2026-09-17-defer-office-background-scheduling.i18n.yaml
@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+# pnpm run verify-translation-pairing --write .agents/notes/proposed/simplification/2026-09-17-defer-office-background-scheduling.md
+2026-09-17-defer-office-background-scheduling.md: 82311022a015671b9fb4cf3a0f3eba2714f325cd
+2026-09-17-defer-office-background-scheduling.zh.md: ada0146f204fa40e71d48251c231c1b68c5fa5a1
diff --git a/.agents/notes/proposed/simplification/2026-09-17-defer-office-background-scheduling.md b/.agents/notes/proposed/simplification/2026-09-17-defer-office-background-scheduling.md
new file mode 100644
index 0000000000..82311022a0
--- /dev/null
+++ b/.agents/notes/proposed/simplification/2026-09-17-defer-office-background-scheduling.md
@@ -0,0 +1,40 @@
+# Agent Note: Defer Office background scheduling until a consumer needs it
+
+Status: proposed
+
+English | [中文](2026-09-17-defer-office-background-scheduling.zh.md)
+
+## Problem
+
+The [conversion queue](../../../../packages/document/office-to-pdf/src/queue.ts) implements foreground promotion, demotion after reader cancellation, eviction of queued background work, a reserved foreground reader allowance, and separate background concurrency accounting. These mechanisms protect foreground conversion from speculative prewarming; ordinary conversion still needs the queue's general resource limits.
+
+The [Office preview](../../../../packages/client/ui-sidebar-documentpreview/src/client/office/index.ts) calls its cache without a priority argument, so the [Client cache](../../../../packages/client/ui-sidebar-documentpreview/src/client/office/cache.ts) forwards the default foreground priority to the Host. Repository searches for `officeToPdf`, `OfficeToPdfRequest`, `OfficeToPdfPriority`, and `maxBackgroundConversions` find no production background request. The [conversion smoke](../../../../packages/bundle/web-app/tests/document-conversion.e2e.ts) also submits foreground requests. Background requests appear in queue, Remote, and Client-cache tests. The exposed API and Client priority plumbing alone do not establish which scheduling policy prewarming requires. The open delivery prewarming PR #4064 already provides a concrete prewarming consumer, but its implementation calls the older `documentRender` API without priority. Removing scheduling must first be reconciled with that consumer; absence from master is insufficient evidence to proceed.
+
+The [bounded conversion decision](../../implemented/architecture/2026-09-15-bounded-office-conversion.md) deliberately reserves capacity for foreground consumers. That remains the correct rule if speculation exists, but the current caller inventory does not justify maintaining the speculative request class and its lifecycle interactions.
+
+## Proposal
+
+Remove `OfficeToPdfPriority`, request `priority`, and configuration `maxBackgroundConversions`. Remove reader/job priority fields, promotion and demotion, speculative eviction, foreground reader reservation, and the queue's background counter. Remove Client-cache priority plumbing and update the Remote signature together. Admit the oldest queued job whose source reservation fits whenever conversion capacity is available; reject a new distinct job when the metadata queue is full. Continue joining an existing source job subject to the shared reader limit.
+
+Keep the provider, reusable converters, deferred authorized reads, all remaining resource limits, source-version checks, content sharing, bounded result cache, independent reader cancellation, and teardown that waits for actual work to settle. This proposal changes admission policy, not conversion ownership or engine selection.
+
+Update the request/config definitions, package README pair, subsystem and generated catalogs, and conversion fixtures together. Delete priority-only assertions; retain resource and cancellation regressions embedded in mixed priority tests by expressing them with ordinary requests. The existing bounded conversion note remains active because its cache, authorization, and lifetime rationale still applies; acceptance would replace only its scheduling policy.
+
+## Alternatives considered
+
+**Keep priority for a future prewarm consumer.** This avoids a later API change, but retains scheduling states and configuration before a product consumer can define their required behavior. Reintroduce priority with a concrete prewarming caller and measured foreground contention.
+
+**Disable background conversions by default.** This avoids speculative execution but retains the public request class, configuration, and all scheduling branches.
+
+**Remove the whole shared provider or cache.** That exceeds the evidence: independent conversion and bounded sharing remain coherent capabilities, and the Loader smoke exercises them without presentation plugins.
+
+## Acceptance criteria
+
+- Resolve the scheduling needs of delivery prewarming PR #4064 before implementation, then repeat the caller search. Retain priority if that consumer needs foreground protection; do not remove it merely because the consumer has not merged.
+- Priority types, fields, configuration, and scheduling branches disappear from maintained source, tests, documentation, and generated catalogs. Decision records may describe the removed policy.
+- Focused queue/provider tests preserve bounded admission, source/digest sharing, cancellation isolation, output ownership, and delayed capacity release. The real conversion Loader smoke still passes.
+- Verify the foreground Office preview path; update its recorded-session snapshot if affected. Run the relevant type checks, generated-reference checks, documentation checks, and lint.
+
+## Risks
+
+Out-of-tree callers can use the exposed pre-stable API even though repository searches find no background consumer. Removing priority and its config field requires callers to update; this proposal offers no compatibility alias. Speculative callers would lose foreground protection and must stop prewarming until an explicit scheduling requirement is implemented. No runtime behavior changes until this proposal is accepted and implemented.
diff --git a/.agents/notes/proposed/simplification/2026-09-17-defer-office-background-scheduling.zh.md b/.agents/notes/proposed/simplification/2026-09-17-defer-office-background-scheduling.zh.md
new file mode 100644
index 0000000000..ada0146f20
--- /dev/null
+++ b/.agents/notes/proposed/simplification/2026-09-17-defer-office-background-scheduling.zh.md
@@ -0,0 +1,40 @@
+# Agent Note: 待调用方需要时再引入 Office 后台调度
+
+Status: proposed
+
+[English](2026-09-17-defer-office-background-scheduling.md) | 中文
+
+## 问题
+
+[转换队列](../../../../packages/document/office-to-pdf/src/queue.ts) 实现了前台优先级提升、读取方取消后的降级、排队后台任务的驱逐、预留前台读取名额，以及独立的后台并发计数。这些机制保护前台转换不受推测性预热影响；普通转换仍需要队列的通用资源限制。
+
+[Office 预览](../../../../packages/client/ui-sidebar-documentpreview/src/client/office/index.ts) 调用缓存时未传优先级，因此[Client 缓存](../../../../packages/client/ui-sidebar-documentpreview/src/client/office/cache.ts) 向 Host 转发默认前台优先级。在仓库中搜索 `officeToPdf`、`OfficeToPdfRequest`、`OfficeToPdfPriority` 和 `maxBackgroundConversions`，未发现生产后台请求。[转换冒烟测试](../../../../packages/bundle/web-app/tests/document-conversion.e2e.ts) 也提交前台请求。后台请求出现在队列、Remote 和 Client 缓存测试中。仅凭暴露 API 和 Client 优先级传递逻辑，无法确定预热需要哪种调度策略。开放的交付文件预热 PR #4064已经提供具体预热消费者，但其实现仍调用不含优先级的旧 `documentRender` API。删除调度前必须先与该消费者协调；尚未进入 master 不足以支持直接实施。
+
+[有界转换决策](../../implemented/architecture/2026-09-15-bounded-office-conversion.zh.md) 有意为前台消费者预留容量。存在推测性任务时，这条规则仍然正确，但当前调用方清单不足以支持维护推测性请求类别及其生命周期交互。
+
+## 提案
+
+移除 `OfficeToPdfPriority`、请求中的 `priority` 和配置 `maxBackgroundConversions`。删除读取方及任务的优先级字段、升降级、推测性任务驱逐、前台读取名额预留，以及队列的后台计数器。同时删除 Client 缓存的优先级传递逻辑并更新 Remote 签名。在转换容量可用时，接纳源预留容量足够的最早排队任务；元数据队列满时拒绝新的独立任务。仍允许在共享读取方数量限制内加入已有源任务。
+
+保留提供者、可复用转换器、延迟授权读取、其余所有资源限制、源版本校验、内容共享、有界结果缓存、读取方独立取消，以及等待实际工作结束的清理。这项提案改变接纳策略，不改变转换所有权或引擎选择。
+
+同步更新请求及配置定义、包 README 双语文档、子系统与生成目录，以及转换 fixture（测试前置数据）。删除仅针对优先级的断言；将混合优先级测试中的资源与取消回归改写为普通请求，并保留覆盖。现有有界转换记录继续有效，因为其缓存、授权和生命周期理由仍然成立；采纳本提案只会替换其中的调度策略。
+
+## 考虑过的替代方案
+
+**为未来的预热调用方保留优先级。** 这可以避免后续 API 变更，但在产品调用方能够定义所需行为之前，就保留了调度状态与配置。应在有具体预热调用方和实测前台资源争用时重新引入优先级。
+
+**默认禁用后台转换。** 这可以避免推测性执行，但仍保留公开请求类别、配置及全部调度分支。
+
+**删除整个共享提供者或缓存。** 这超出了证据支持的范围：独立转换和有界共享仍是完整的能力，Loader 冒烟测试也在不依赖展示插件的情况下验证它们。
+
+## 验收标准
+
+- 实施前先明确交付文件预热 PR #4064 的调度需求，再重复调用方搜索。若该消费者需要前台保护，则保留优先级；不能仅因消费者尚未合入而删除。
+- 从维护中的源码、测试、文档和生成目录移除优先级类型、字段、配置及调度分支。决策记录可以描述被移除的策略。
+- 聚焦队列及提供者的测试保留有界接纳、源及摘要共享、取消隔离、输出所有权和延迟容量释放覆盖。真实转换的 Loader 冒烟测试仍然通过。
+- 验证前台 Office 预览路径；若受影响，同步更新其记录会话快照。运行相关类型检查、生成引用检查、文档检查及 lint。
+
+## 风险
+
+仓库外调用方可能使用已暴露的稳定前 API，即使仓库搜索未发现后台消费者。移除优先级及其配置字段要求调用方更新；本提案不提供兼容别名。推测性调用方会失去前台保护，必须停止预热，直到明确的调度需求得到实现。本提案被接受并实现之前，运行行为不变。
diff --git a/.agents/skills/dsh-archive-agent-notes/SKILL.md b/.agents/skills/dsh-archive-agent-notes/SKILL.md
index a08e4b5179..6052cbf1fc 100644
--- a/.agents/skills/dsh-archive-agent-notes/SKILL.md
+++ b/.agents/skills/dsh-archive-agent-notes/SKILL.md
@@ -1,6 +1,6 @@
---
name: dsh-archive-agent-notes
-description: Use when adding, auditing, pruning, archiving, restoring, or reviewing Agent Notes in deepseek-harness; checks every new note for superseded active records, classifies implemented notes by future decision value, deletes rejected notes that no longer prevent a tempting fallacy, and applies the frozen archived/{kind} triplet and manifest rules.
+description: Use when adding, auditing, pruning, archiving, restoring, or reviewing Agent Notes in deepseek-harness; checks every new note for superseded active records, deletes small UI and purely mechanical records, classifies other implemented notes by future decision value, deletes rejected notes that no longer prevent a tempting fallacy, and applies the frozen archived/{kind} triplet and manifest rules.
---
# Archive DeepSeek Harness Agent Notes
@@ -19,8 +19,9 @@ Before drafting, apply the [creation criteria](../../notes/README.md#when-to-wri
Apply these lifecycle-specific outcomes:
-- **Implemented — keep active:** retain a note when its rationale, alternatives, negative guarantees, durable/wire semantics, ownership boundary, security rule, or reintroduction condition is likely to guide a future change. Length does not matter.
-- **Implemented — archive:** archive a note when the shipped decision is complete and its body is unlikely to guide future work, such as one-off UI chrome, a narrow adapter, a minor closed bug, superseded implementation detail, or process history whose current behavior is obvious elsewhere.
+- **Implemented — delete:** delete complete triplets that only describe small UI adjustments or purely mechanical changes, and repair or remove inbound links. Local bug fixes, performance changes, new capabilities, and substantive behavior or ownership decisions do not qualify merely because they are implemented. Apply this criterion before keep/archive classification.
+- **Implemented — keep active:** retain a note when its rationale, alternatives, negative guarantees, durable/wire semantics, ownership boundary, security rule, or reintroduction condition is likely to guide a future change. Classify the decision, not the mechanics of its implementation: a mechanical rename or type extraction can still record lasting naming, compatibility, or ownership rules. Length does not matter.
+- **Implemented — archive:** archive a substantive historical decision when it is complete and unlikely to guide future work, but its historical rationale still warrants preservation. Do not archive records that meet the direct-deletion criterion.
- **Proposed — never archive:** keep a live proposal active; if it is no longer worth pursuing, reject it with an honest reason and satisfy the rejected lifecycle format.
- **Rejected — keep only as a guardrail:** retain a rejection only when the losing proposal remains a tempting, meaningful mistake and the note explains why it loses.
- **Rejected — delete:** delete the whole triplet when the rejected idea is obsolete, superseded, no longer plausible, or unlikely to prevent re-litigation. Repair or delete inbound links.
@@ -31,11 +32,10 @@ Do not archive toward a quota. Inspect every note in scope, classify analogous g
These examples set the bar; the word counts demonstrate that size is not the test.
-Archive implemented notes such as:
+Delete implemented notes such as:
- collapsed sidebar control rail — 533 words: closed, minor UI behavior;
-- Commander argument adapter — 1,498 words: substantial implementation detail with little future design leverage;
-- documentation graph atlas — 920 words: completed documentation machinery whose current generators are authoritative.
+- issue-policy module ownership — completed function relocation and import rewiring with unchanged behavior.
Keep implemented notes such as:
@@ -55,7 +55,7 @@ For rejected notes:
1. Move the complete `foo.md`, `foo.zh.md`, and `foo.i18n.yaml` triplet from `implemented//` to `archived//`; `implemented` is deliberately absent from the archive path.
2. Make no body edits. Insert only `Archived: YYYY-MM-DD` immediately below `Status: implemented` in both language files, using the archival date and the same value on both sides.
-3. Re-record the sidecar hashes mechanically for the two metadata-only edits. Do not translate, reformat, update facts, or repair links inside the note.
+3. Re-record the sidecar hashes mechanically for the two metadata-only edits. Do not translate, reformat, update facts, or repair links inside the note. Existing title punctuation, blank-line layout, and language-switcher wording are preserved, not prerequisites for archival.
4. Search for inbound links from active prose. Redirect them to current authority, retarget them to the archived path only when the historical snapshot is intentionally cited, or delete them. Never verify or repair links out of the archived note.
5. Run `pnpm run verify-archived-agent-notes --write`. Its append-only mode first proves every existing seal still matches, then adds only the new triplet hashes. Run the normal verifier afterward.
@@ -65,4 +65,4 @@ After the triplet is sealed, never edit, move, translate, reformat, or delete it
Run the archive verifier's focused test, `pnpm run verify-archived-agent-notes`, `pnpm run doc-sync`, `pnpm run lint`, and `git diff --check`; select any additional evidence through [dsh-pre-push-checks](../dsh-pre-push-checks/SKILL.md).
-Report active implemented notes kept, implemented notes archived, rejected notes kept/deleted, proposed notes rejected if any, and every genuinely borderline case with its word count and chosen outcome. Do not claim archived outbound links are valid: the archive verifier intentionally never checks them.
+Report active implemented notes kept, implemented notes deleted or archived, rejected notes kept/deleted, proposed notes rejected if any, and every genuinely borderline case with its word count and chosen outcome. Do not claim archived outbound links are valid: the archive verifier intentionally never checks them.
diff --git a/.agents/skills/dsh-find-simplifications/SKILL.md b/.agents/skills/dsh-find-simplifications/SKILL.md
index 6ee736796c..bce148ad18 100644
--- a/.agents/skills/dsh-find-simplifications/SKILL.md
+++ b/.agents/skills/dsh-find-simplifications/SKILL.md
@@ -93,7 +93,7 @@ Reject or downgrade a candidate when:
Audit the Agent Note tree when the user asks to reduce or coalesce it, or when the simplification being implemented makes an owning note obsolete. Do not expand every code-simplification survey into a repository-wide note audit.
-Use [`dsh-archive-agent-notes`](../dsh-archive-agent-notes/SKILL.md) for retention judgment and archive mechanics. Low-future-value implemented notes move as frozen triplets to `archived/{kind}`; proposed notes are never archived; rejected notes that no longer prevent a tempting mistake are deleted. Do not edit an archived note while simplifying current prose or code.
+Use [`dsh-archive-agent-notes`](../dsh-archive-agent-notes/SKILL.md) for retention judgment and archive mechanics. Implemented notes that only describe small UI adjustments or purely mechanical changes are deleted directly; other completed notes with historical decision value but little future guidance move as frozen triplets to `archived/{kind}`; proposed notes are never archived; rejected notes that no longer prevent a tempting mistake are deleted. Do not edit an archived note while simplifying current prose or code.
Follow the deletion rule in the [Agent Note rules](../../notes/README.md#when-to-write-one); do not duplicate or weaken it here. For each candidate chain:
diff --git a/.github/issue-management/README.i18n.yaml b/.github/issue-management/README.i18n.yaml
index 7d31f8418d..beaf888252 100644
--- a/.github/issue-management/README.i18n.yaml
+++ b/.github/issue-management/README.i18n.yaml
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write .github/issue-management/README.md
-README.md: a936b9358810fd3a8b8104609a5523e305e1aaa5
-README.zh.md: df743cac581c2125df9ac9e76f04d2528204eb74
+README.md: 49e91859f4b22fda13d0e93c6e6ea492272f6951
+README.zh.md: 8424f90cd2e3a59ba1212f64f3f1081a984b55f8
diff --git a/.github/issue-management/README.md b/.github/issue-management/README.md
index a936b93588..49e91859f4 100644
--- a/.github/issue-management/README.md
+++ b/.github/issue-management/README.md
@@ -61,7 +61,7 @@ Lifecycle processing is event-driven, not a reconciler. Omitted events do not re
## Module ownership
-Maintainers reuse the owning module directly; [policy.mjs](policy.mjs) only reads the event file, dispatches commands, and reports command failures. The [module-ownership decision](../../.agents/notes/implemented/process/2026-09-07-issue-policy-module-ownership.md) explains this separation.
+Maintainers reuse the owning module directly; [policy.mjs](policy.mjs) only reads the event file, dispatches commands, and reports command failures.
Implementation owners
diff --git a/.github/issue-management/README.zh.md b/.github/issue-management/README.zh.md
index df743cac58..8424f90cd2 100644
--- a/.github/issue-management/README.zh.md
+++ b/.github/issue-management/README.zh.md
@@ -61,7 +61,7 @@ PR 打开时，工作流按配置时区中的 PR 创建日期，为每个被引
## 模块归属
-维护者直接复用所属模块；[policy.mjs](policy.mjs)仅负责读取事件文件、分派命令并报告命令失败。[模块归属决策](../../.agents/notes/implemented/process/2026-09-07-issue-policy-module-ownership.zh.md)解释此职责分离。
+维护者直接复用所属模块；[policy.mjs](policy.mjs)仅负责读取事件文件、分派命令并报告命令失败。
实现职责
diff --git a/.github/workflows/build-exe-for-python-sdk.yml b/.github/workflows/build-exe-for-python-sdk.yml
index 5042778b72..e53d524ead 100644
--- a/.github/workflows/build-exe-for-python-sdk.yml
+++ b/.github/workflows/build-exe-for-python-sdk.yml
@@ -152,14 +152,15 @@ jobs:
if-no-files-found: error
retention-days: 7
+ # Blacksmith x64 CI builds use 2 vCPU for compilation, bundling, and wheel smokes.
build:
needs: [plan, sdk-wheel]
name: ${{ matrix.target }}
runs-on: >-
${{ inputs.ci && !inputs.release && matrix.target == 'node24-linux-x64'
- && vars.DSH_CI_FAILOVER_LINUX == 'blacksmith' && 'blacksmith-16vcpu-ubuntu-2404'
+ && vars.DSH_CI_FAILOVER_LINUX == 'blacksmith' && 'blacksmith-2vcpu-ubuntu-2404'
|| inputs.ci && !inputs.release && matrix.target == 'node24-win-x64'
- && vars.DSH_CI_FAILOVER_WINDOWS == 'blacksmith' && 'blacksmith-16vcpu-windows-2025'
+ && vars.DSH_CI_FAILOVER_WINDOWS == 'blacksmith' && 'blacksmith-2vcpu-windows-2025'
|| matrix.runner }}
timeout-minutes: 45
strategy:
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 2139231c06..e0da3c3125 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -33,7 +33,7 @@ jobs:
# vm-backup pool and re-running the failed jobs is the entire switch —
# see .agents/notes/implemented/process/2026-07-26-ci-failover-runbook.md.
# Setting the variable to 'blacksmith' instead routes the same jobs onto
- # Blacksmith's hosted runners at the matching vCPU size (see
+ # 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
@@ -497,6 +497,8 @@ jobs:
# per-job process count stays lower. Observational checks are 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; builds, coverage,
+ # and observational gates retain 16 for their concurrent work.
windows-build:
if: github.event_name == 'pull_request'
runs-on: >-
@@ -622,7 +624,7 @@ jobs:
windows-native-tests:
if: github.event_name == 'pull_request'
runs-on: >-
- ${{ vars.DSH_CI_FAILOVER_WINDOWS == 'blacksmith' && 'blacksmith-16vcpu-windows-2025'
+ ${{ 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"]')
diff --git a/THIRD_PARTY_NOTICES.md b/THIRD_PARTY_NOTICES.md
index 7eb0c36e18..ec698dca33 100644
--- a/THIRD_PARTY_NOTICES.md
+++ b/THIRD_PARTY_NOTICES.md
@@ -76,6 +76,7 @@ External packages installed for runtime use or distributed inside the prebuilt b
| [`commander`](https://github.com/tj/commander.js) | MIT |
| [`compression`](https://github.com/expressjs/compression) | MIT |
| [`diff`](https://github.com/kpdecker/jsdiff) | BSD-3-Clause |
+| [`dompurify`](https://github.com/cure53/DOMPurify) | (MPL-2.0 OR Apache-2.0) |
| [`electron-updater`](https://github.com/electron-userland/electron-builder) | MIT |
| [`eventsource-parser`](https://github.com/rexxars/eventsource-parser) | MIT |
| [`execa`](https://github.com/sindresorhus/execa) | MIT |
diff --git a/apps/desktop/README.i18n.yaml b/apps/desktop/README.i18n.yaml
index 3284b14418..68345cdb09 100644
--- a/apps/desktop/README.i18n.yaml
+++ b/apps/desktop/README.i18n.yaml
@@ -2,5 +2,5 @@
# side as of the last confirmed-consistent state. Both languages carry equal authority;
# after editing either side, bring the other along and re-record with:
# pnpm run verify-translation-pairing --write apps/desktop/README.md
-README.md: 62d51b39c802f1c3d047c27890a3c3fb91e832bd
-README.zh.md: a1e4ae4f1e3c6489ca49f7048ca8296327bdf434
+README.md: f7144fb776d114c519de327cbb4c2624a67ab76f
+README.zh.md: 1b62ebedfc5cc7e7344f3eea4d690d187bc8db82
diff --git a/apps/desktop/README.md b/apps/desktop/README.md
index 62d51b39c8..f7144fb776 100644
--- a/apps/desktop/README.md
+++ b/apps/desktop/README.md
@@ -18,7 +18,7 @@ The macOS PNG uses an inset rounded background for legacy ICNS packaging, with r
### Bundled workspace dependencies
-Signed Windows packaging preserves valid vendor signatures and signs unsigned PE executables, DLLs, Python extensions and Node addons in the primary runtime before executing its smoke checks. Each new signature must match the configured certificate and carry a timestamp; invalid existing signatures, signing errors and verification errors stop the run without retries. Electron-builder preserves copied runtime executables only after checking their signature and exact equality with the prepared file, preventing repeat signing during resource copying. Checks include decimal, XML, LZMA, UUID, numpy and pandas. Development, preparation-only and unsigned builds do not use the hardware token and can be blocked by Windows code-integrity policy; no build mode disables that policy. A passing smoke does not establish compatibility for every extension or enterprise policy.
+Signed Windows packaging scans the primary runtime and application production dependencies for PE content, including files without a conventional extension. The final scan covers the entire unpacked application. Directory links, malformed `MZ` files and non-PE `.exe`, `.dll` or `.pyd` files stop packaging; data files beginning with `MZ` are also rejected unless they contain a valid PE header. It preserves valid vendor signatures and signs unsigned code before sealing runtime hashes or executing smoke checks. Public-key inspection uses batches of 32 files with at most four processes; hardware-token signing remains serial, and each new signature must match the configured certificate and carry a timestamp. Hardware signing and verification failures stop the run; isolated timestamp requests follow the bounded policy below. Electron-builder preserves copied runtime executables only after signature and exact-byte verification. A final PE-signature audit and a fresh-cache ASAR payload and Host smoke must pass before the release completion record is written. Development, preparation-only and unsigned builds do not use the hardware token and can be blocked by Windows code-integrity policy; no build mode disables that policy. Passing smoke checks does not establish compatibility with every enterprise policy.
Desktop carries independent Python, Node.js and pnpm distributions. Python includes numpy, pandas, python-docx, python-pptx, openpyxl, Pillow, lxml and XlsxWriter with their complete dependencies. The `load_workspace_dependencies` tool installs this payload offline on first use under `$DSH_HOME/dsh-runtimes/dsh-primary-runtime` (normally `~/.dsh/dsh-runtimes/dsh-primary-runtime`) and returns absolute interpreter, pnpm script and library paths plus `pythonDistributions`, the bundled distribution names and versions. The version report excludes user-installed additions. Office tasks prefer these libraries unless user or workspace instructions select another environment. Execute the pnpm script with the returned Node executable. The returned Node library directory is reserved for bundled libraries, not pnpm's global installation directory.
@@ -46,7 +46,7 @@ The [thin-wrapper decision](../../.agents/notes/implemented/architecture/2026-09
Electron owns `$DSH_HOME/profiles/desktop`. Its `dependencies` contains packages installed by pnpm; `dsh.profile.bundles` contains the built-in bundles followed by enabled plugins. The signed application supplies dsh, the private Desktop Host, and their production packages from `resources/app.asar/dsh`. Packaged applications select runtime profile resolution without creating package links; development profiles use filesystem links. Both host and plugins execute in the same Electron Node-mode process; Desktop does not enable `--preserve-symlinks`. The CLI cannot boot or mutate this profile.
-The application preload exposes boot readiness, fatal startup reporting, and native directory selection. 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 exposes no plugin-management IPC or separate management document. No renderer receives filesystem access, raw Electron IPC, a shell, or arbitrary pnpm arguments.
+The application preload exposes boot readiness, fatal startup reporting, and native directory selection. 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 `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.
@@ -144,11 +144,11 @@ Each target owns its packed package inputs, prepared runtime, package set, dsh t
### Runtime file selection
-Desktop packs workspace packages locally and installs external dependencies through the target's bundled Node and pnpm. [Desktop's file policy](scripts/runtime-file-policy.ts) then filters the immutable `resources/app.asar/dsh/node_modules` copy before signing and integrity sealing. It omits TypeScript declarations, recognized JavaScript/CSS/TypeScript source maps, TypeScript build caches, Domino's test directory, selected native compiler outputs, and node-pty prebuilds for other platforms. It preserves runtime JavaScript, native modules and their DLL/EXE helpers, WASM, unknown assets, licenses, and notices. The policy does not alter npm tarballs, the bundled package manager, or user-installed plugin files.
+Desktop packs workspace packages locally and installs external dependencies through the target's bundled Node and pnpm. [Desktop's file policy](scripts/runtime-file-policy.ts) then filters the immutable `resources/app.asar/dsh/node_modules` copy before signing and integrity sealing. It omits TypeScript declarations, recognized JavaScript/CSS/TypeScript source maps, TypeScript build caches, Domino's test directory, selected native compiler outputs, and node-pty prebuilds for other platforms. It preserves runtime JavaScript, native modules and their DLL/EXE helpers, WASM, unknown assets, licenses, and notices. Dependency manifests pass through electron-builder's metadata cleanup before integrity sealing, so archiving preserves their recorded bytes. The policy does not alter npm tarballs, the bundled package manager, or user-installed plugin files.
The [Office conversion provider](../../packages/document/office-to-pdf/README.md) carries the target’s declared native engine, or WASM when the kit declares no matching native target. Preparation rejects a missing target engine before packaging. Engine assets, licenses, and notices remain in the runtime dependency tree.
-The packaged application runs compiled JavaScript and pre-generated Typert metadata; it does not compile TypeScript plugins. Source-level debugger navigation and editor declarations remain available in development packages. [Copy-policy tests](tests/runtime-file-policy.spec.ts) cover exclusions and retained assets; `prepare:dsh` runs the [payload smoke](tests/fixtures/runtime-payload-smoke.mjs) under Electron RunAsNode before the Host smoke and final inventory verification.
+The packaged application runs compiled JavaScript and pre-generated Typert metadata; it does not compile TypeScript plugins. Source-level debugger navigation and editor declarations remain available in development packages. [Copy-policy tests](tests/runtime-file-policy.spec.ts) cover exclusions and retained assets; The [payload smoke](tests/fixtures/runtime-payload-smoke.mjs) runs under Electron RunAsNode before the Host smoke and final inventory verification. Signed Windows builds run these checks after dependency signing; other builds run them during `prepare:dsh`.
Windows release qualification also runs [directory and replacement checks](scripts/smoke-windows.ps1) manually after the Desktop build. Set `$Makensis`, `$SevenZip`, and `$PluginDir` to the pinned builder’s NSIS compiler, 7-Zip executable, and x86-unicode NSIS plugin directory. From the repository root, run the command below. It verifies directory replacement and rollback, and both locked-file replacement modes; it is not part of the unit-test lane.
@@ -212,7 +212,9 @@ Run `pnpm --dir apps/desktop run test:installer` from the repository root on an
### Windows EV signing
-Signed Windows builds run a supervised signing preflight before compilation or dependency preparation. Static configuration, certificate validity, audit storage, compiler availability and any retained signing interlock are checked without token access. The local .NET Framework C# compiler creates a small private probe; the production signer signs it once, and verification requires the configured certificate and a timestamp before building continues. The probe is never executed. A 60-second preflight deadline, signing error or verification failure stops the run without retry. Success proves the current signing path works, not that the PIN was independently authenticated: SafeNet may reuse login state. Do not log out or repeat authentication to test the PIN. `--check`, preparation-only and `--unsigned` modes do not run this hardware preflight; unsigned artifacts remain ineligible for release upload. Automated regression tests use a fake signer; release operators qualify real hardware separately.
+Runtime signing caches complete signed files under `.desktop-build/targets/win-x64/signature-cache`. Entries identify the original bytes, public certificate and signing toolchain. Restoring an entry checks its digest, Windows trust, timestamp and certificate before replacing the unsigned file; invalid entries stop packaging without hardware fallback. The cache requires trusted local build storage and retains entries until removed. Preflight, hardware interlocks and final artifact signing still apply. Cache qualification and design limits are tracked in the [runtime signature cache decision](../../.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.md).
+
+Signed Windows builds run a supervised signing preflight before compilation or dependency preparation. Static configuration, certificate validity, audit storage, compiler availability and any retained signing interlock are checked without token access. The local .NET Framework C# compiler creates a small private probe; the production signer signs it once, and verification requires the configured certificate and a timestamp before building continues. The probe is never executed. The overall 60-second preflight deadline includes timestamp attempts; deadline expiry, hardware signing errors and verification failures stop the run without another hardware attempt. Success proves the current signing path works, not that the PIN was independently authenticated: SafeNet may reuse login state. Do not log out or repeat authentication to test the PIN. `--check`, preparation-only and `--unsigned` modes do not run this hardware preflight; unsigned artifacts remain ineligible for release upload. Automated regression tests use a fake signer; release operators qualify real hardware separately.
Windows NSIS uploads require the generated, nonempty `.exe.blockmap` beside the installer. The blockmap is uploaded before channel YAML; NSIS installer metadata does not require the embedded `blockMapSize` used by the separate web-installer format. File-plan tests use the pinned builder's blockmap generator, not a hand-authored embedded-map field.
@@ -222,7 +224,7 @@ For this project's SafeNet token, `SignTool Error: No private key is available.`
Windows package commands print `DESKTOP_PACKAGING_RECORD` with a unique directory under `.desktop-build/packaging-runs/`. Each run retains `run.json`, timestamped `events.jsonl`, redacted `stdout.log` and `stderr.log`, and `result.json`. A signing failure also writes `fatal.json` and notifies the parent through stderr; the supervisor immediately requests termination of its stage process tree and waits for exit. Failed stages cannot start subsequent stages or create a release completion record. Journal failures also stop the run. Termination errors remain failures and require operator inspection; a missing final record means completion was not established.
-Hardware signing requires a supervised run. Before invoking the command interpreter, the signer atomically acquires `%USERPROFILE%/.dsh-desktop-signing/attempt.json` and records the attempt. Only successful signing releases that file. Failure, interruption, an existing interlock, or unavailable audit storage prevents further hardware access, including from another signer instance, process, or checkout under the same Windows account. There is no timed recovery or automatic retry. An administrator must inspect the retained evidence and token state before explicitly authorizing interlock recovery; logging into the token or replacing a PIN file does not clear it. The records distinguish signing intent, command-interpreter PID, and completion; they do not measure internal CSP/token authentication attempts. Command arguments, PINs, and credential environments are not recorded. Independent Windows accounts and unrelated signing programs are outside this interlock.
+Hardware signing requires a supervised run. Before invoking the command interpreter, the signer atomically acquires `%USERPROFILE%/.dsh-desktop-signing/attempt.json` and records the attempt. Only successful signing followed by verification of the configured primary signature releases that file; timestamps are completed afterward without hardware access. Failure, interruption, an existing interlock, or unavailable audit storage prevents further hardware access, including from another signer instance, process, or checkout under the same Windows account. There is no timed recovery or automatic retry. An administrator must inspect the retained evidence and token state before explicitly authorizing interlock recovery; logging into the token or replacing a PIN file does not clear it. The records distinguish signing intent, command-interpreter PID, and completion; they do not measure internal CSP/token authentication attempts. Command arguments, PINs, and credential environments are not recorded. Independent Windows accounts and unrelated signing programs are outside this interlock.
Windows packaging fixes the 7-Zip filter to `BCJ` for compatibility with the bundled NSIS decoder. This preserves ARM64 binaries carried by dependencies in x64 installers; automatic ARM64 filtering produces entries that this decoder cannot extract.
@@ -234,9 +236,11 @@ Fill in `.env.windows` with `DSH_DESKTOP_WINDOWS_CER_FILE` (public EV leaf certi
pnpm run package:desktop:win:x64
```
-Insert and unlock the token before packaging. The electron-builder hook passes each artifact to the CRLF `scripts/windows-sign.cmd`, which invokes the configured SignTool once with `/f`, SafeNet `/kc "[{{PIN}}]=container"`, `/csp "eToken Base Cryptographic Provider"`, a SHA-256 file digest, and a DigiCert SHA-256 RFC 3161 timestamp. The hook never substitutes electron-builder's bundled SignTool and never retries a failed signing request. Windows release packaging fails instead of emitting unsigned artifacts when the SignTool, certificate, container, PIN, token, or signature is unavailable.
+Insert and unlock the token before packaging. The electron-builder hook passes each artifact to the CRLF `scripts/windows-sign.cmd`, which invokes the configured SignTool once with `/f`, SafeNet `/kc "[{{PIN}}]=container"`, `/csp "eToken Base Cryptographic Provider"`, a SHA-256 file digest, without a timestamp. The hook then completes a DigiCert SHA-256 RFC 3161 timestamp on isolated copies without signing credentials. The hook never substitutes electron-builder's bundled SignTool and never retries a failed signing request. Windows release packaging fails instead of emitting unsigned artifacts when the SignTool, certificate, container, PIN, token, or signature is unavailable.
-The PIN cannot contain `]`, a quote, or a line break because those characters delimit the SafeNet `/kc` value or its CMD argument. The CMD disables delayed expansion so a PIN containing `!` reaches SafeNet unchanged. Packaging withholds every `DSH_DESKTOP_WINDOWS_*` field from build and runtime-preparation subprocesses, gives signing preflight, the dedicated primary-runtime signing stage and electron-builder only the four configured inputs, gives the signing CMD only the validated signing fields in an otherwise scrubbed environment, clears those fields before SignTool starts, and redacts SignTool diagnostics. SafeNet still requires the PIN in the SignTool process command line. The local `.env.windows` stores the PIN in plaintext and needs restricted file access; CI uses a temporary file and deletes it after the job. Do not commit or share its contents or print credentials in logs. Configuration checks consume no token PIN attempts; signing still stops the batch on its first failure.
+Timestamp completion retries only a normally exited timestamp command returning failure or warning, at most three times with one- and two-second delays. Each attempt starts from the same verified primary signature. Launch errors, uncertain termination and verification failures stop immediately. SignTool operates on short private paths; publication copies verified bytes to the target volume before atomic replacement. Final Windows trust, certificate, timestamp and normalized full-file equality are required. Exhaustion stops packaging and preserves evidence without another hardware call. See the [signature completion decision](../../.agents/notes/implemented/process/2026-09-17-windows-signature-completion.md).
+
+The PIN cannot contain `]`, a quote, or a line break because those characters delimit the SafeNet `/kc` value or its CMD argument. The CMD disables delayed expansion so a PIN containing `!` reaches SafeNet unchanged. Packaging withholds every `DSH_DESKTOP_WINDOWS_*` field from build and runtime-preparation subprocesses, gives signing preflight, the dedicated runtime signing stages and electron-builder only the four configured inputs, gives the signing CMD only the validated signing fields in an otherwise scrubbed environment, clears those fields before SignTool starts, and redacts SignTool diagnostics. SafeNet still requires the PIN in the SignTool process command line. The local `.env.windows` stores the PIN in plaintext and needs restricted file access; CI uses a temporary file and deletes it after the job. Do not commit or share its contents or print credentials in logs. Configuration checks consume no token PIN attempts; signing still stops the batch on its first failure.
Create a runnable application directory instead of an installer by using the matching `:dir` command, such as:
@@ -253,7 +257,7 @@ pnpm run prepare:desktop
This diagnostic command is an alternative stopping point, not the first half of a two-command build. A later `package:desktop*` command repeats the official build and preparation so it cannot consume stale dsh packages, runtime files, or dsh content.
-Every package command builds the repository, packs the first-party production closures rooted at dsh and the private Desktop Host, and prepares the target Electron distribution and pnpm CLI. `prepare:dsh` installs the production graph once at build time, prepares materialized packages for electron-builder to archive under `app.asar/dsh`, removes package-manager metadata, and writes `desktop-runtime.json` with shared package versions and final file hashes. On macOS it signs and verifies native files before inventory generation; electron-builder excludes this already-signed tree from nested re-signing. Resource mappings explicitly include `dsh/node_modules`, which the default root-directory filter omits; the prepared runtime inventory is checked after native signing. Native executables and libraries are unpacked beside ASAR; Python, standalone Node and pnpm remain in external runtime resources. Signed installer, notarization, installed upgrade, and target-specific native-module qualification require the release environment.
+Every package command builds the repository, packs the first-party production closures rooted at dsh and the private Desktop Host, and prepares the target Electron distribution and pnpm CLI. `prepare:dsh` installs the production graph once at build time, prepares materialized packages for electron-builder to archive under `app.asar/dsh`, removes package-manager metadata, and writes `desktop-runtime.json` with shared package versions and final file hashes. On macOS it signs and verifies native files before inventory generation; electron-builder excludes this already-signed tree from nested re-signing. Resource mappings explicitly include `dsh/node_modules`, which the default root-directory filter omits; the prepared runtime inventory is checked after native signing. Native executables and libraries are unpacked beside ASAR; Python, standalone Node and pnpm remain in external runtime resources. Windows packaging checks every prepared PE against its ASAR unpacked entry and byte-identical disk copy, including unsigned builds. Builder glob rules match braces in PE filenames as single-character wildcards, so a matching neighboring file may also be unpacked. Prepared runtime smoke uses the verified target descriptor rather than the build host architecture. Signed installer, notarization, installed upgrade, and target-specific native-module qualification require the release environment.
macOS packaging writes `Contents/Resources/app-update.yml` while assembling the App and before code signing, including the directory build that feeds the parallel ZIP and DMG lanes. The signing hook verifies the exact feed and updater cache directory. Both lane copies and the promoted App are checked again before the release completion record is written; a missing or mismatched configuration prevents artifact promotion and therefore prevents upload.
diff --git a/apps/desktop/README.zh.md b/apps/desktop/README.zh.md
index a1e4ae4f1e..1b62ebedfc 100644
--- a/apps/desktop/README.zh.md
+++ b/apps/desktop/README.zh.md
@@ -18,7 +18,7 @@ macOS PNG 使用带留白的圆角底板，供传统 ICNS 打包使用，包含
### 内置工作区依赖
-Windows 签名打包保留有效的上游签名，并在执行冒烟检查前，为第一方运行时中未签名的 PE 可执行文件、DLL、Python 扩展和 Node 插件补签。每个新签名必须匹配配置的证书且带时间戳；已有签名无效、签名错误或验签错误都会停止本轮执行，不自动重试。electron-builder 只有在校验复制后运行时可执行文件的签名、且文件与已准备的源文件逐字节一致后，才保留其签名，避免复制资源时重复签名。检查覆盖 decimal、XML、LZMA、UUID、numpy 和 pandas。开发、仅准备和未签名构建不使用硬件令牌，可能被 Windows 代码完整性策略阻止；任何构建模式都不会关闭该策略。冒烟检查通过不代表所有扩展或企业策略都兼容。
+Windows 签名打包按 PE 文件内容扫描第一方运行时和应用生产依赖，包括没有常规扩展名的文件。最终扫描覆盖整个解包应用。目录链接、格式错误的 `MZ` 文件以及非 PE 的 `.exe`、`.dll` 或 `.pyd` 文件会使打包停止；以 `MZ` 开头的数据文件也会被拒绝，除非包含有效 PE 头。它保留有效的上游签名，并在记录运行时哈希或执行冒烟检查前为未签名代码补签。公钥验签每个进程处理最多 32 个文件，同时最多运行四个进程；硬件令牌签名仍串行执行，每个新签名必须匹配配置的证书且带时间戳。硬件签名或验签失败会停止本轮执行；独立的时间戳请求遵循下文的有界重试规则。electron-builder 只有在验签和逐字节比对通过后，才保留复制后运行时可执行文件的签名。写入发布完成记录前，必须通过最终 PE 签名检查，以及使用全新缓存的 ASAR 载荷和 Host 冒烟检查。开发、仅准备和未签名构建不使用硬件令牌，可能被 Windows 代码完整性策略阻止；任何构建模式都不会关闭该策略。冒烟检查通过不代表兼容所有企业策略。
Desktop 携带独立的 Python、Node.js 和 pnpm 分发包。Python 包含 numpy、pandas、python-docx、python-pptx、openpyxl、Pillow、lxml、XlsxWriter 及其完整依赖。`load_workspace_dependencies` 工具首次使用时，将该产物离线安装到 `$DSH_HOME/dsh-runtimes/dsh-primary-runtime`（通常为 `~/.dsh/dsh-runtimes/dsh-primary-runtime`），并返回解释器、pnpm 脚本和库目录的绝对路径，以及记录内置分发包名称与版本的 `pythonDistributions`。版本报告不包含用户自行安装的包。Office 任务默认使用这些库，用户或工作区指令指定其他环境时遵循其要求。pnpm 脚本通过返回的 Node 可执行文件运行。返回的 Node 库目录为随包交付的库预留，不是 pnpm 的全局安装目录。
@@ -46,7 +46,7 @@ Node 准备内置解释器和 Python 库，无需系统 Python 或 pip。[下载
Electron 拥有 `$DSH_HOME/profiles/desktop`。其 `dependencies` 包含 pnpm 安装的包；`dsh.profile.bundles` 包含内置 bundle，后接已启用插件。签名应用从 `resources/app.asar/dsh` 提供 dsh、私有 Desktop Host 及其生产依赖。打包应用选择 runtime profile 解析，不创建包链接；开发 profile 使用文件系统链接。宿主与插件在同一个 Electron Node 模式进程中执行；Desktop 不启用 `--preserve-symlinks`。CLI 不能启动或修改此 profile。
-应用 preload 暴露启动就绪、致命启动失败上报和原生目录选择。产品页面还获得 Desktop 标记、更新展示数据和打开原生确认的操作，不能选择安装产物或授权安装。插件管理使用 Web 应用经过认证的 HTTP API；Electron 不提供插件管理 IPC 或独立管理页面。
+应用 preload 暴露启动就绪、致命启动失败上报和原生目录选择。产品页面还获得 Desktop 标记、更新展示数据和打开原生确认的操作，不能选择安装产物或授权安装。插件管理使用 Web 应用经过认证的 HTTP API；Electron 在 `dsh-app://shell/` 本地提供更新弹窗文档和资源，不依赖 Host 就绪。Electron 不提供插件管理 IPC 或独立管理页面。
`dsh-app://shell/` 无需联系 Host 即可提供打包的更新文档、脚本和样式。静态请求保留 GET/HEAD、路径范围和 MIME 处理；每个更新文档继续使用隔离 preload 和所属窗口的 IPC 校验。
@@ -145,11 +145,11 @@ macOS arm64 命令要求 Apple Silicon。macOS x64 命令可以在 Intel macOS
### 运行时文件筛选
-Desktop 在本地打包工作区包，并通过目标捆绑的 Node 和 pnpm 安装外部依赖。[Desktop 文件策略](scripts/runtime-file-policy.ts)随后在签名和完整性封装前过滤不可变的 `resources/app.asar/dsh/node_modules` 副本。它排除 TypeScript 声明、已识别的 JavaScript/CSS/TypeScript source map、TypeScript 构建缓存、Domino 测试目录、选定的原生编译器输出和其他平台的 node-pty 预构建文件。它保留运行时 JavaScript、原生模块及其 DLL/EXE 辅助文件、WASM、未知资源、许可证和 notices。该策略不修改 npm tarball、捆绑的包管理器或用户安装的插件文件。
+Desktop 在本地打包工作区包，并通过目标捆绑的 Node 和 pnpm 安装外部依赖。[Desktop 文件策略](scripts/runtime-file-policy.ts)随后在签名和完整性封装前过滤不可变的 `resources/app.asar/dsh/node_modules` 副本。它排除 TypeScript 声明、已识别的 JavaScript/CSS/TypeScript source map、TypeScript 构建缓存、Domino 测试目录、选定的原生编译器输出和其他平台的 node-pty 预构建文件。它保留运行时 JavaScript、原生模块及其 DLL/EXE 辅助文件、WASM、未知资源、许可证和 notices。依赖清单在完整性封装前经过 electron-builder 的元数据清理，确保归档保持已记录的字节。该策略不修改 npm tarball、捆绑的包管理器或用户安装的插件文件。
[Office 转换提供方](../../packages/document/office-to-pdf/README.zh.md)携带目标已声明的原生引擎；kit 未声明匹配原生目标时携带 WASM 引擎。准备阶段在打包前拒绝缺少目标引擎的情况。引擎资源、许可证和 notices 保留在运行时依赖树中。
-打包应用运行编译后的 JavaScript 和预生成的 Typert 元数据，不编译 TypeScript 插件。源码级调试导航和编辑器声明仍可从开发包中获取。[复制规则测试](tests/runtime-file-policy.spec.ts)覆盖排除项和保留资源；`prepare:dsh` 在 Host smoke 和最终清单验证之前，使用 Electron RunAsNode 执行[产物 smoke](tests/fixtures/runtime-payload-smoke.mjs)。
+打包应用运行编译后的 JavaScript 和预生成的 Typert 元数据，不编译 TypeScript 插件。源码级调试导航和编辑器声明仍可从开发包中获取。[复制规则测试](tests/runtime-file-policy.spec.ts)覆盖排除项和保留资源；[产物 smoke](tests/fixtures/runtime-payload-smoke.mjs) 在 Host smoke 和最终清单验证之前，使用 Electron RunAsNode 执行。Windows 签名构建在依赖签名后运行这些检查；其他构建在 `prepare:dsh` 中运行。
Windows 发布验收还需在 Desktop 构建后手动运行[目录和替换检查](scripts/smoke-windows.ps1)。将 `$Makensis`、`$SevenZip` 和 `$PluginDir` 分别设为锁定版本构建器的 NSIS 编译器、7-Zip 可执行文件和 x86-unicode NSIS 插件目录。从仓库根目录运行以下命令。它验证 目录替换与回滚和两种文件占用替换方式；不属于单元测试通道。
@@ -213,7 +213,9 @@ Windows 打包使用 Visual C++ Build Tools 和 Windows SDK 编译 x86 Win32/GDI
### Windows EV 签名
-Windows 签名构建在编译或准备依赖前执行受监督的签名预检。静态配置、证书有效期、审计存储、编译器可用性及遗留签名锁的检查不访问 Token。本地 .NET Framework C# 编译器生成一个专用小探针，由正式签名器仅签名一次，随后必须验出配置的证书和时间戳才能继续构建。探针绝不执行。预检超过 60 秒、签名报错或验签失败都会停止本轮流程，不重试。成功只证明当前签名路径可用，不证明 PIN 已独立认证：SafeNet 可能复用登录状态。不要为了验证 PIN 而注销或重复认证。`--check`、仅准备和 `--unsigned` 模式不执行此硬件预检；未签名产物仍不能发布上传。自动回归测试使用假签名器，真实硬件由发布操作人员单独验收。
+运行时签名将完整的已签名文件缓存在 `.desktop-build/targets/win-x64/signature-cache`。缓存项标识原始字节、公钥证书和签名工具链。恢复缓存项时，先检查摘要、Windows 信任状态、时间戳和证书，再替换未签名文件；缓存项无效会停止打包，不回退到硬件签名。缓存要求受信任的本地构建存储，并保留缓存项直到被移除。预检、硬件互锁和最终产物签名仍然执行。[运行时签名缓存决策](../../.agents/notes/implemented/process/2026-09-17-windows-runtime-signature-cache.zh.md)记录缓存验收要求和设计限制。
+
+Windows 签名构建在编译或准备依赖前执行受监督的签名预检。静态配置、证书有效期、审计存储、编译器可用性及遗留签名锁的检查不访问 Token。本地 .NET Framework C# 编译器生成一个专用小探针，由正式签名器仅签名一次，随后必须验出配置的证书和时间戳才能继续构建。探针绝不执行。预检的整体 60 秒期限包含时间戳尝试；超时、硬件签名报错或验签失败都会停止本轮流程，不再次调用硬件。成功只证明当前签名路径可用，不证明 PIN 已独立认证：SafeNet 可能复用登录状态。不要为了验证 PIN 而注销或重复认证。`--check`、仅准备和 `--unsigned` 模式不执行此硬件预检；未签名产物仍不能发布上传。自动回归测试使用假签名器，真实硬件由发布操作人员单独验收。
Windows NSIS 上传要求安装包旁存在生成的非空 `.exe.blockmap`。blockmap 先于通道 YAML 上传；NSIS 安装包元数据不要求另一种 web-installer 格式使用的内嵌 `blockMapSize`。文件清单测试使用固定版本构建器的 blockmap 生成器，而不是手工编造内嵌映射字段。
@@ -223,7 +225,7 @@ Windows NSIS 上传要求安装包旁存在生成的非空 `.exe.blockmap`。blo
Windows 打包命令通过 `DESKTOP_PACKAGING_RECORD` 输出 `.desktop-build/packaging-runs/` 下的唯一目录。每次运行保留 `run.json`、带时间戳的 `events.jsonl`、脱敏后的 `stdout.log` 和 `stderr.log`，以及 `result.json`。签名失败还会写入 `fatal.json` 并通过 stderr 通知父进程；监督程序立即请求终止当前阶段的进程树并等待退出。失败阶段不能启动后续阶段或生成发布完成记录。日志写入失败也会停止运行。终止错误仍按失败处理，需要操作者检查；缺少最终记录表示尚未确认完成。
-硬件签名必须属于受监督的打包运行。调用命令解释器前，签名器原子获取 `%USERPROFILE%/.dsh-desktop-signing/attempt.json` 并记录本次尝试。只有签名成功才释放该文件。失败、中断、已有锁定文件或审计存储不可用都会阻止再次访问硬件，包括同一 Windows 账户下的另一个签名器实例、进程或代码检出目录。没有定时恢复或自动重试。管理员必须检查保留的证据及令牌状态，再明确授权恢复锁定状态；登录令牌或替换 PIN 文件不会清除它。记录区分签名意图、命令解释器 PID 和完成结果，不计量 CSP／令牌内部的认证次数。不记录命令参数、PIN 或凭据环境。其他 Windows 账户及无关签名程序不在此锁定机制的保护范围内。
+硬件签名必须属于受监督的打包运行。调用命令解释器前，签名器原子获取 `%USERPROFILE%/.dsh-desktop-signing/attempt.json` 并记录本次尝试。只有签名成功且配置证书的主签名通过验证后才释放该文件；随后完成时间戳，不再访问硬件。失败、中断、已有锁定文件或审计存储不可用都会阻止再次访问硬件，包括同一 Windows 账户下的另一个签名器实例、进程或代码检出目录。没有定时恢复或自动重试。管理员必须检查保留的证据及令牌状态，再明确授权恢复锁定状态；登录令牌或替换 PIN 文件不会清除它。记录区分签名意图、命令解释器 PID 和完成结果，不计量 CSP／令牌内部的认证次数。不记录命令参数、PIN 或凭据环境。其他 Windows 账户及无关签名程序不在此锁定机制的保护范围内。
Windows 打包将 7-Zip 过滤器固定为 `BCJ`，以兼容内置的 NSIS 解码器。这样可以保留 x64 安装包中由依赖携带的 ARM64 二进制文件；自动 ARM64 过滤会生成该解码器无法解压的条目。
@@ -235,7 +237,9 @@ NSIS 在安装阶段清理临时解压目录，完成后才显示完成页或自
pnpm run package:desktop:win:x64
```
-打包前插入并解锁 Token。electron-builder 钩子把每个产物交给采用 CRLF 的 `scripts/windows-sign.cmd`；该 CMD 只调用一次已配置的 SignTool，并指定 `/f`、SafeNet `/kc "[{{PIN}}]=容器"`、`/csp "eToken Base Cryptographic Provider"`、SHA-256 文件摘要和 DigiCert SHA-256 RFC 3161 时间戳。钩子不会改用 electron-builder 内置的 SignTool，也不会重试失败的签名请求。SignTool、证书、容器、PIN、Token 或签名不可用时，Windows 发布打包会失败，不会生成未签名产物。
+打包前插入并解锁 Token。electron-builder 钩子把每个产物交给采用 CRLF 的 `scripts/windows-sign.cmd`；该 CMD 只调用一次已配置的 SignTool，并指定 `/f`、SafeNet `/kc "[{{PIN}}]=容器"`、`/csp "eToken Base Cryptographic Provider"`和 SHA-256 文件摘要，不请求时间戳。随后钩子在隔离副本上完成 DigiCert SHA-256 RFC 3161 时间戳，不传递签名凭据。钩子不会改用 electron-builder 内置的 SignTool，也不会重试失败的签名请求。SignTool、证书、容器、PIN、Token 或签名不可用时，Windows 发布打包会失败，不会生成未签名产物。
+
+时间戳处理仅对正常退出但返回失败或警告的时间戳命令重试，最多尝试三次，间隔为一秒和两秒。每次均从同一份已验证的主签名开始。启动错误、终止状态不确定或验签失败会立即停止。SignTool 使用短的私有路径；发布时先把已验证字节复制到目标卷，再原子替换。最终必须通过 Windows 信任、证书、时间戳和规范化全文件相等检查。尝试耗尽后停止打包并保留证据，不再次调用硬件。参见[签名完成决策](../../.agents/notes/implemented/process/2026-09-17-windows-signature-completion.zh.md)。
PIN 不能包含 `]`、引号或换行，因为这些字符用于分隔 SafeNet `/kc` 值或对应的 CMD 参数。CMD 会禁用延迟展开，因此包含 `!` 的 PIN 可以原样到达 SafeNet。打包流程不会把任何 `DSH_DESKTOP_WINDOWS_*` 字段传给构建与 运行时准备子进程；它只向签名预检、独立的第一方运行时签名阶段与 electron-builder 提供四个配置输入，在其他字段已经清理的环境中只向签名 CMD 提供经过校验的签名字段，在 SignTool 启动前清除这些字段，并遮盖 SignTool 诊断。SafeNet 仍要求 PIN 出现在 SignTool 进程命令行中。本地 `.env.windows` 明文保存 PIN，应限制文件访问权限；CI 使用临时文件并在任务结束后删除。不要提交或分享文件内容，也不要把凭据写入日志。配置检查不会消耗 Token 的 PIN 尝试次数；签名仍在首次失败后停止整批任务。
@@ -254,7 +258,7 @@ pnpm run prepare:desktop
这条诊断命令是另一种停止位置，并非两条命令构建流程的前半段。之后执行 `package:desktop*` 时仍会重新完成正式构建与准备，避免使用陈旧的 dsh 包、运行时文件或 dsh 内容。
-每条打包命令都会构建仓库，打包以 dsh 和私有 Desktop Host 为根的第一方生产依赖闭包，并准备目标专用的 Electron 分发包与 pnpm CLI。`prepare:dsh` 在构建时安装一次生产依赖图，准备物化包供 electron-builder 归档到 `app.asar/dsh`，移除包管理器元数据，并生成包含共享包版本和最终文件哈希的 `desktop-runtime.json`。在 macOS 上，它先签名并验证原生文件，再生成清单；electron-builder 不对已签名的此目录重复进行嵌套签名。资源映射明确包含默认根目录过滤器会忽略的 `dsh/node_modules`；准备完成的运行时清单在原生签名后检查。原生可执行文件及库解包到 ASAR 旁；Python、独立 Node 和 pnpm 保留在外部 runtime 资源中。签名安装包、公证、已安装应用升级和各目标原生模块的验收需要发布环境。
+每条打包命令都会构建仓库，打包以 dsh 和私有 Desktop Host 为根的第一方生产依赖闭包，并准备目标专用的 Electron 分发包与 pnpm CLI。`prepare:dsh` 在构建时安装一次生产依赖图，准备物化包供 electron-builder 归档到 `app.asar/dsh`，移除包管理器元数据，并生成包含共享包版本和最终文件哈希的 `desktop-runtime.json`。在 macOS 上，它先签名并验证原生文件，再生成清单；electron-builder 不对已签名的此目录重复进行嵌套签名。资源映射明确包含默认根目录过滤器会忽略的 `dsh/node_modules`；准备完成的运行时清单在原生签名后检查。原生可执行文件及库解包到 ASAR 旁；Python、独立 Node 和 pnpm 保留在外部 runtime 资源中。Windows 打包逐项检查准备好的 PE，确认其 ASAR 条目已标记为解包，且磁盘副本字节一致；未签名构建也执行此检查。Builder glob 规则用单字符通配符匹配 PE 文件名中的花括号，因此同目录中名称匹配的文件也可能被解包。准备好的运行时 smoke 沿用已验证的目标描述符，不使用构建宿主的架构。签名安装包、公证、已安装应用升级和各目标原生模块的验收需要发布环境。
macOS 打包在组装 App 时、代码签名前写入 `Contents/Resources/app-update.yml`，供并行 ZIP 与 DMG 路线使用的目录构建也执行此操作。签名钩子验证准确的更新源和 updater 缓存目录。写入发布完成记录前，流程会再次检查两条路线的副本和最终移入的 App；配置缺失或不匹配会阻止移入产物，因而也会阻止上传。
diff --git a/apps/desktop/electron-builder.config.d.mts b/apps/desktop/electron-builder.config.d.mts
index b305647650..f7cfd63f42 100644
--- a/apps/desktop/electron-builder.config.d.mts
+++ b/apps/desktop/electron-builder.config.d.mts
@@ -1,3 +1,5 @@
+import type { AfterPackContext, BeforePackContext } from 'app-builder-lib'
+
/** Electron-builder fields asserted by the Desktop release tests. */
export interface DesktopElectronBuilderConfig {
readonly appId: string
@@ -45,7 +47,9 @@ export interface DesktopElectronBuilderConfig {
readonly installerLanguages: readonly ['en_US', 'zh_CN']
}
readonly beforeBuild: () => Promise
- readonly beforePack: (context: { readonly appOutDir: string }) => Promise
+ readonly beforePack: (context: BeforePackContext) => Promise
+ readonly afterPack: (context: AfterPackContext) => Promise
+ readonly afterSign: (context: AfterPackContext) => Promise
readonly artifactBuildCompleted: (artifact: { readonly file: string }) => Promise | undefined
readonly publish: readonly [{ readonly provider: 'generic', readonly url: string }] | null
}
diff --git a/apps/desktop/scripts/electron-builder-config.mjs b/apps/desktop/scripts/electron-builder-config.mjs
index ea33c60b2a..cf2f76768f 100644
--- a/apps/desktop/scripts/electron-builder-config.mjs
+++ b/apps/desktop/scripts/electron-builder-config.mjs
@@ -1,3 +1,5 @@
+import { X509Certificate } from 'node:crypto'
+import { readFile } from 'node:fs/promises'
import { join } from 'node:path'
import { fileURLToPath } from 'node:url'
import { execFile } from 'node:child_process'
@@ -19,7 +21,9 @@ import { resolveDesktopAutoUpdateConfig } from './desktop-auto-update-environmen
import { resolveDesktopPolicyEnvironment } from './desktop-policy-environment.mjs'
import { desktopTargetBuildPaths, resolveDesktopBuildTarget } from './desktop-build-paths.mjs'
import { installWindowsDirectoryInstaller } from './windows-directory-installer.mjs'
-import { preserveWindowsRuntimeSignature } from './windows-runtime-signature.mjs'
+import { preserveWindowsRuntimeSignature, signWindowsCode } from './windows-runtime-signature.mjs'
+import { prepareWindowsAsarUnpack, verifyWindowsAsarUnpack } from './windows-asar-unpack.mjs'
+import { recordPackagingEvent } from './packaging-run.mjs'
import {
resolveMacOSAppUpdateFeed,
verifyMacOSAppUpdateConfig,
@@ -57,17 +61,23 @@ export function createElectronBuilderConfig(
if (packagesMacOS) resolveMacOSNotarizationEnvironment(env)
const buildPaths = desktopTargetBuildPaths(resolveDesktopBuildTarget(env, hostPlatform, hostArch))
let primaryRuntimeDestination
+ let dshDestination
+ let windowsCode = []
+ const unpack = ['**/*.{node,dylib,dll,so,exe}', '**/*.so.*', '**/spawn-helper', '**/@vscode/ripgrep/bin/rg']
const windowsSigner = packagesWindows && !unsigned
? createWindowsTokenSigner({
certificateFile: env.DSH_DESKTOP_WINDOWS_CER_FILE,
signTool: env.DSH_DESKTOP_WINDOWS_SIGNTOOL,
tokenPin: env.DSH_DESKTOP_WINDOWS_TOKEN_PIN,
keyContainer: env.DSH_DESKTOP_WINDOWS_KEY_CONTAINER,
- preserveSignature: async path => primaryRuntimeDestination === undefined ? false : preserveWindowsRuntimeSignature(path, {
- sourceRoot: join(buildPaths.runtime, 'primary-runtime'),
- destinationRoot: primaryRuntimeDestination,
- runDirectory: env.DSH_DESKTOP_PACKAGING_RUN_DIR,
- }),
+ preserveSignature: async path => {
+ for (const [sourceRoot, destinationRoot] of [[join(buildPaths.runtime, 'primary-runtime'), primaryRuntimeDestination], [buildPaths.dsh, dshDestination]]) {
+ if (destinationRoot !== undefined && await preserveWindowsRuntimeSignature(path, {
+ sourceRoot, destinationRoot, runDirectory: env.DSH_DESKTOP_PACKAGING_RUN_DIR,
+ })) return true
+ }
+ return false
+ },
})
: undefined
if (windowsSigner !== undefined) {
@@ -108,12 +118,7 @@ export function createElectronBuilderConfig(
// electron-builder excludes a source directory's root node_modules.
{ from: join(buildPaths.dsh, 'node_modules'), to: 'dsh/node_modules', filter: ['**/*'] },
],
- asarUnpack: [
- '**/*.{node,dylib,dll,so,exe}',
- '**/*.so.*',
- '**/spawn-helper',
- '**/@vscode/ripgrep/bin/rg',
- ],
+ asarUnpack: unpack,
extraResources: [
{ from: buildPaths.runtime, to: 'runtime' },
{ from: fileURLToPath(new URL('../resources/icon-windows.png', import.meta.url)), to: 'icon.png' },
@@ -134,29 +139,36 @@ export function createElectronBuilderConfig(
writeUpdateInfo: false,
},
beforePack: async context => {
- if (windowsSigner !== undefined) primaryRuntimeDestination = join(context.appOutDir, 'resources', 'runtime', 'primary-runtime')
+ if (packagesWindows) windowsCode = await prepareWindowsAsarUnpack(context, buildPaths.dsh)
+ if (windowsSigner !== undefined) {
+ primaryRuntimeDestination = join(context.appOutDir, 'resources', 'runtime', 'primary-runtime')
+ dshDestination = join(context.appOutDir, 'resources', 'app.asar.unpacked', 'dsh')
+ }
if (policy === undefined) return
const { resolveDesktopPolicyConfig } = await import('../lib/types/mandatory-update-policy.js')
resolveDesktopPolicyConfig(policy)
},
afterPack: async context => {
- const { verifyDesktopRuntime, writeDesktopRuntime } = await import('../lib/types/runtime-tree.js')
+ const { verifyDesktopRuntime } = await import('../lib/types/runtime-tree.js')
const resourcesDir = context.packager.getResourcesDir(context.appOutDir)
if (resolvedPlatform === 'darwin' && update !== undefined) {
await writeMacOSAppUpdateConfig(resourcesDir, resolveMacOSAppUpdateFeed(context.packager.config.publish),
context.packager.appInfo.updaterCacheDirName)
}
- if (resolvedPlatform === 'win32' && !unsigned) {
- // Windows signs copied executable resources before afterPack runs.
- const prepared = await verifyDesktopRuntime(buildPaths.dsh,
- context.packager.appInfo.version, { platform: resolvedPlatform, arch: resolvedArch })
- writeDesktopRuntime(buildPaths.dsh, prepared.release, prepared.sharedPackages.map(entry => entry.name),
- { platform: resolvedPlatform, arch: resolvedArch })
- }
await verifyDesktopRuntime(buildPaths.dsh,
context.packager.appInfo.version, { platform: resolvedPlatform, arch: resolvedArch })
+ // Unsigned Windows builds skip electron-builder's afterSign hook.
+ if (packagesWindows && unsigned) await verifyWindowsAsarUnpack(buildPaths.dsh, resourcesDir, windowsCode)
},
afterSign: async context => {
+ if (windowsSigner !== undefined) {
+ await signWindowsCode(context.appOutDir, {
+ thumbprint: new X509Certificate(await readFile(env.DSH_DESKTOP_WINDOWS_CER_FILE)).fingerprint.replaceAll(':', ''),
+ sign: windowsSigner,
+ record: event => recordPackagingEvent(env.DSH_DESKTOP_PACKAGING_RUN_DIR, event),
+ })
+ await verifyWindowsAsarUnpack(buildPaths.dsh, context.packager.getResourcesDir(context.appOutDir), windowsCode)
+ }
if (context.electronPlatformName !== 'darwin') return
const appPath = join(context.appOutDir, `${context.packager.appInfo.productFilename}.app`)
if (update !== undefined) {
diff --git a/apps/desktop/scripts/installed-update-packaging.ts b/apps/desktop/scripts/installed-update-packaging.ts
index a1c61a5d76..f0660e6f96 100644
--- a/apps/desktop/scripts/installed-update-packaging.ts
+++ b/apps/desktop/scripts/installed-update-packaging.ts
@@ -55,7 +55,7 @@ async function inputHashes(manifest: string, version: string, environment: NodeJ
const paths = [manifest, join(run.root, 'application/result.json'), join(run.root, version, 'dsh/desktop-runtime.json'),
join(REPOSITORY, 'pnpm-lock.yaml'), join(APP_ROOT, 'package.json'),
...['electron-builder-config.mjs', 'installed-update-builder.ts', 'build-installed-update-worker.mjs',
- 'windows-sign.mjs', 'windows-sign.cmd', 'windows-signing-state.mjs', 'windows-directory-installer.mjs',
+ 'windows-sign.mjs', 'windows-sign.cmd', 'windows-signing-state.mjs', 'windows-timestamp.mjs', 'windows-directory-installer.mjs',
'installer.nsh', 'prepare-windows-installer.ps1'].map(path => join(import.meta.dirname, path)),
environment.DSH_DESKTOP_WINDOWS_CER_FILE!, environment.DSH_DESKTOP_WINDOWS_SIGNTOOL!]
const files = []
diff --git a/apps/desktop/scripts/package-target.ts b/apps/desktop/scripts/package-target.ts
index 0cbf4c6898..aede75a697 100644
--- a/apps/desktop/scripts/package-target.ts
+++ b/apps/desktop/scripts/package-target.ts
@@ -361,7 +361,8 @@ export async function packageTarget(
await execute(['run', 'prepare:runtime', ...(signPrimaryRuntime ? ['--defer-primary-runtime-smoke'] : [])], targetEnv)
if (signPrimaryRuntime) await execute(['run', 'sign:primary-runtime'], electronBuilderEnv)
await execute(['run', 'prepare:packages'], targetEnv)
- await execute(['run', 'prepare:dsh'], targetEnv)
+ await execute(['run', 'prepare:dsh', ...(signPrimaryRuntime ? ['--defer-runtime-smoke'] : [])], targetEnv)
+ if (signPrimaryRuntime) await execute(['run', 'sign:primary-runtime', '--dsh'], electronBuilderEnv)
if (invocation.prepareOnly) return
if (target.platform === 'darwin' && !invocation.directory) {
await execute([
@@ -377,6 +378,7 @@ export async function packageTarget(
} else {
await execute(desktopElectronBuilderArguments(target, invocation.directory), electronBuilderEnv)
}
+ if (signPrimaryRuntime) await execute(['exec', 'tsx', 'scripts/smoke-packaged-runtime.ts'], targetEnv)
if (!invocation.directory && !invocation.unsigned) writeReleaseRecord(target, electronBuilderEnv, buildPaths.artifacts)
}
diff --git a/apps/desktop/scripts/prepare-dsh.ts b/apps/desktop/scripts/prepare-dsh.ts
index e5c789c165..d1124618d6 100644
--- a/apps/desktop/scripts/prepare-dsh.ts
+++ b/apps/desktop/scripts/prepare-dsh.ts
@@ -1,6 +1,6 @@
/** Materialize the complete production runtime before publishing Desktop resources. */
-import { spawn, execFile } from 'node:child_process'
+import { spawn } from 'node:child_process'
import { copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
import { tmpdir } from 'node:os'
import { delimiter, join, relative, resolve } from 'node:path'
@@ -17,7 +17,8 @@ import {
verifyDesktopCoreLockfile,
} from '../src/core-package-set.ts'
import { smokePrimaryRuntime } from './prepare-primary-runtime.ts'
-import { smokeDesktopRuntime } from './smoke-runtime.ts'
+import { smokePreparedRuntime } from './smoke-prepared-runtime.ts'
+import { prepareRuntimeManifests } from './prepare-runtime-manifests.ts'
import { writeDesktopRuntime, verifyDesktopRuntime } from '../src/runtime-tree.ts'
import {
resolveDesktopAppId,
@@ -147,18 +148,14 @@ async function main(): Promise {
await signMacOSRuntime(DSH_OUTPUT_ROOT, resolveDesktopAppId(process.env), resolveMacOSSigningEnvironment(process.env))
await signMacOSRuntime(join(RUNTIME_ROOT, 'primary-runtime'), resolveDesktopAppId(process.env), resolveMacOSSigningEnvironment(process.env))
}
+ await prepareRuntimeManifests(DSH_OUTPUT_ROOT)
smokePrimaryRuntime(join(RUNTIME_ROOT, 'primary-runtime'))
writeDesktopRuntime(DSH_OUTPUT_ROOT, release, packageSet.packages.map(entry => entry.name), target)
const descriptor = await verifyDesktopRuntime(DSH_OUTPUT_ROOT, release.version, target)
- await new Promise((accept, reject) => {
- execFile(NODE, ['--expose-internals', join(APP_ROOT, 'tests/fixtures/runtime-payload-smoke.mjs'), DSH_OUTPUT_ROOT],
- { timeout: 120_000, env: desktopNodeEnvironment(NODE, join(RUNTIME_ROOT, 'bin'), { ...process.env, NODE_OPTIONS: '' }) }, (error, stdout, stderr) => {
- if (error !== null) reject(new Error(`desktop native payload smoke failed: ${stderr}`, { cause: error }))
- else { process.stdout.write(stdout); accept() }
- })
- })
- await smokeDesktopRuntime(DSH_OUTPUT_ROOT, NODE, descriptor)
- await verifyDesktopRuntime(DSH_OUTPUT_ROOT, release.version, target)
+ if (!process.argv.includes('--defer-runtime-smoke')) {
+ await smokePreparedRuntime(DSH_OUTPUT_ROOT, NODE, RUNTIME_ROOT, descriptor)
+ await verifyDesktopRuntime(DSH_OUTPUT_ROOT, release.version, target)
+ }
} catch (error) {
rmSync(DSH_OUTPUT_ROOT, { recursive: true, force: true })
throw error
diff --git a/apps/desktop/scripts/prepare-runtime-manifests.ts b/apps/desktop/scripts/prepare-runtime-manifests.ts
new file mode 100644
index 0000000000..7f919b24fd
--- /dev/null
+++ b/apps/desktop/scripts/prepare-runtime-manifests.ts
@@ -0,0 +1,26 @@
+/** Apply electron-builder's dependency metadata cleanup before sealing runtime bytes. */
+import { readdir, writeFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { createRequire } from 'node:module'
+
+// electron-builder omits declarations for its internal manifest transformer.
+const { createTransformer } = createRequire(import.meta.url)('app-builder-lib/out/fileTransformer.js') as {
+ createTransformer: (root: string, config: object, extraMetadata: undefined) =>
+ (path: string) => Promise | null
+}
+
+/**
+ * Materialize the same manifest bytes electron-builder will put in the archive.
+ * @param root Prepared application dependency tree.
+ * @returns Resolves after dependency manifests are ready for integrity inventory.
+ */
+export async function prepareRuntimeManifests(root: string): Promise {
+ const transform = createTransformer(root, {}, undefined)
+ const modules = join(root, 'node_modules')
+ for (const entry of await readdir(modules, { recursive: true, withFileTypes: true })) {
+ if (!entry.isFile() || entry.name !== 'package.json') continue
+ const path = join(entry.parentPath, entry.name)
+ const transformed = await transform(path)
+ if (transformed != null) await writeFile(path, transformed)
+ }
+}
diff --git a/apps/desktop/scripts/sign-primary-runtime.ts b/apps/desktop/scripts/sign-primary-runtime.ts
index f196f56126..2f93208c60 100644
--- a/apps/desktop/scripts/sign-primary-runtime.ts
+++ b/apps/desktop/scripts/sign-primary-runtime.ts
@@ -1,85 +1,47 @@
/** Sign Windows runtime code before executing it, retaining vendor signatures and fail-stop hardware protection. */
import { X509Certificate } from 'node:crypto'
-import { lstat, open, readdir, readFile } from 'node:fs/promises'
-import { extname, join, resolve } from 'node:path'
+import { readFile, realpath } from 'node:fs/promises'
+import { join, resolve } from 'node:path'
import { createWindowsTokenSigner } from './windows-sign.mjs'
-import { inspectWindowsRuntimeSignature, type WindowsRuntimeSignature } from './windows-runtime-signature.mjs'
+import { inspectWindowsRuntimeSignature, signWindowsCode, type WindowsCodeSigningOptions } from './windows-runtime-signature.mjs'
+import { createCachedSigner, signatureCacheIdentity } from './windows-signature-cache.mjs'
import { failPackagingRun, recordPackagingEvent } from './packaging-run.mjs'
import { resolveDesktopBuildTarget, resolveDesktopTargetBuildPaths } from './desktop-build-paths.mjs'
import { smokePrimaryRuntime } from './prepare-primary-runtime.ts'
+import { verifyDesktopRuntime, writeDesktopRuntime, type DesktopRuntimeDescriptor } from '../src/runtime-tree.ts'
+import { smokePreparedRuntime } from './smoke-prepared-runtime.ts'
/**
- * Enumerate Windows code without following links or treating foreign .node files as PE binaries.
- * @param root - Owned, materialized runtime directory.
- * @returns Sorted real PE files; rejects links and malformed Windows executable files.
+ * Sign the bundled interpreters before their smoke checks.
+ * @param root Materialized primary runtime.
+ * @param options Supervised signer, certificate identity, audit sink and runtime check.
+ * @returns Resolves after verified signatures and a successful smoke.
*/
-export async function windowsRuntimeCode(root: string): Promise {
- const rootStat = await lstat(root)
- if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) throw new Error('primary runtime: expected a real directory')
- const files: string[] = []
- for (const entry of await readdir(root, { withFileTypes: true })) {
- const path = join(root, entry.name)
- if (entry.isSymbolicLink()) throw new Error(`primary runtime: directory links are not signable: ${path}`)
- if (entry.isDirectory()) { files.push(...await windowsRuntimeCode(path)); continue }
- if (!entry.isFile() || !['.exe', '.dll', '.pyd', '.node'].includes(extname(path).toLowerCase())) continue
- const file = await open(path, 'r')
- let portableExecutable = false
- let windowsCandidate = false
- try {
- const header = Buffer.alloc(64)
- const { bytesRead } = await file.read(header, 0, header.length, 0)
- windowsCandidate = bytesRead >= 2 && header.readUInt16LE(0) === 0x5a4d
- if (bytesRead === 64 && windowsCandidate) {
- const signature = Buffer.alloc(4)
- const offset = header.readUInt32LE(0x3c)
- const read = await file.read(signature, 0, 4, offset)
- portableExecutable = offset >= 64 && read.bytesRead === 4 && signature.readUInt32LE(0) === 0x4550
- }
- } finally { await file.close() }
- if (portableExecutable) files.push(path)
- else if (windowsCandidate || extname(path).toLowerCase() !== '.node') throw new Error(`primary runtime: invalid PE file: ${path}`)
- }
- return files.sort()
-}
-
-interface RuntimeSigningOptions {
- thumbprint: string
- sign: ReturnType
- inspect?: (path: string) => Promise
- record: (event: object) => void
- smoke: (root: string) => void
-}
-
-/**
- * Preserve valid signatures and sign only unsigned PE files before runtime execution.
- * @param root - Owned final runtime directory.
- * @param options - Supervised signer, certificate identity, audit sink and runtime check.
- * @returns Resolves only after sequential signatures, verification and execution; no retries.
- */
-export async function signWindowsPrimaryRuntime(root: string, options: RuntimeSigningOptions): Promise {
- const inspect = options.inspect ?? inspectWindowsRuntimeSignature
- const files = await windowsRuntimeCode(root)
- if (files.length === 0) throw new Error('primary runtime: no Windows code found')
- const unsigned: string[] = []
- for (const path of files) {
- const signature = await inspect(path)
- options.record({ type: 'primary-runtime-signature', path, ...signature })
- if (signature.status === 'NotSigned') unsigned.push(path)
- else if (signature.status !== 'Valid') throw new Error(`primary runtime: refusing ${signature.status} signature: ${path}`)
- }
- options.record({ type: 'primary-runtime-signing-plan', files: files.length, unsigned: unsigned.length })
- for (const path of unsigned) {
- await options.sign({ path, hash: 'sha256', isNest: false })
- const signature = await inspect(path)
- if (signature.status !== 'Valid' || !signature.timestamped || signature.thumbprint?.toUpperCase() !== options.thumbprint.toUpperCase()) {
- throw new Error(`primary runtime: signing verification failed: ${path}`)
- }
- options.record({ type: 'primary-runtime-signature-verified', path, ...signature })
- }
+export async function signWindowsPrimaryRuntime(
+ root: string, options: WindowsCodeSigningOptions & { smoke: (root: string) => void },
+): Promise {
+ await signWindowsCode(root, options)
options.smoke(root)
options.record({ type: 'primary-runtime-smoke-success' })
}
+/**
+ * Seal application dependency hashes only after all Windows code is signed.
+ * @param root Materialized production dependency directory.
+ * @param version Expected release version.
+ * @param options Supervised signing dependencies and a smoke receiving the signed descriptor.
+ * @returns Resolves after final inventory verification and smoke; any failure stops the stage.
+ */
+export async function signWindowsDesktopRuntime(root: string, version: string,
+ options: WindowsCodeSigningOptions & { smoke: (descriptor: DesktopRuntimeDescriptor) => Promise }): Promise {
+ const descriptor = await verifyDesktopRuntime(root, version)
+ await signWindowsCode(root, options)
+ writeDesktopRuntime(root, descriptor.release, descriptor.sharedPackages.map(entry => entry.name))
+ const signed = await verifyDesktopRuntime(root, version)
+ await options.smoke(signed)
+ await verifyDesktopRuntime(root, version)
+}
+
async function main(): Promise {
if (process.platform !== 'win32' || resolveDesktopBuildTarget() !== 'win-x64') throw new Error('primary runtime signing requires Windows x64')
const runDirectory = process.env.DSH_DESKTOP_PACKAGING_RUN_DIR
@@ -89,13 +51,29 @@ async function main(): Promise {
if (!certificateFile) throw new Error('primary runtime signing requires the configured certificate')
const thumbprint = new X509Certificate(await readFile(certificateFile)).fingerprint.replaceAll(':', '')
try {
- await signWindowsPrimaryRuntime(join(resolveDesktopTargetBuildPaths().runtime, 'primary-runtime'), {
+ const paths = resolveDesktopTargetBuildPaths()
+ const record = (event: object): void => { recordPackagingEvent(runDirectory, event) }
+ const sign = createWindowsTokenSigner({ certificateFile, signTool: process.env.DSH_DESKTOP_WINDOWS_SIGNTOOL,
+ keyContainer: process.env.DSH_DESKTOP_WINDOWS_KEY_CONTAINER, tokenPin: process.env.DSH_DESKTOP_WINDOWS_TOKEN_PIN })
+ const identity = await signatureCacheIdentity([
+ await realpath(certificateFile), await realpath(process.env.DSH_DESKTOP_WINDOWS_SIGNTOOL!),
+ join(import.meta.dirname, 'windows-sign.cmd'), join(import.meta.dirname, 'windows-sign.mjs'),
+ join(import.meta.dirname, 'windows-timestamp.mjs'),
+ ])
+ const options = {
thumbprint,
- sign: createWindowsTokenSigner({ certificateFile, signTool: process.env.DSH_DESKTOP_WINDOWS_SIGNTOOL,
- keyContainer: process.env.DSH_DESKTOP_WINDOWS_KEY_CONTAINER, tokenPin: process.env.DSH_DESKTOP_WINDOWS_TOKEN_PIN }),
- record: (event) => { recordPackagingEvent(runDirectory, event) },
- smoke: smokePrimaryRuntime,
- })
+ sign: createCachedSigner({ root: join(paths.root, 'signature-cache'), identity, thumbprint,
+ sign, inspect: inspectWindowsRuntimeSignature, record }),
+ record,
+ }
+ if (process.argv.includes('--dsh')) {
+ const version = JSON.parse(await readFile(join(paths.dsh, 'package.json'), 'utf8')).version as string
+ await signWindowsDesktopRuntime(paths.dsh, version, { ...options,
+ smoke: descriptor => smokePreparedRuntime(paths.dsh, join(paths.electron, 'electron.exe'), paths.runtime, descriptor),
+ })
+ } else {
+ await signWindowsPrimaryRuntime(join(paths.runtime, 'primary-runtime'), { ...options, smoke: smokePrimaryRuntime })
+ }
} catch (error) {
failPackagingRun(runDirectory, 'primary-runtime-signing-or-smoke-failed')
throw error
diff --git a/apps/desktop/scripts/smoke-packaged-runtime.ts b/apps/desktop/scripts/smoke-packaged-runtime.ts
new file mode 100644
index 0000000000..5fc993f25d
--- /dev/null
+++ b/apps/desktop/scripts/smoke-packaged-runtime.ts
@@ -0,0 +1,13 @@
+/** Validate the assembled Windows application before recording release completion. */
+import { join } from 'node:path'
+import { resolveDesktopTargetBuildPaths } from './desktop-build-paths.mjs'
+import { readDesktopRuntime, verifyDesktopRuntime } from '../src/runtime-tree.ts'
+import { verifyWindowsCode } from './windows-runtime-signature.mjs'
+import { smokePreparedRuntime } from './smoke-prepared-runtime.ts'
+
+const paths = resolveDesktopTargetBuildPaths()
+const application = join(paths.artifacts, 'win-unpacked')
+const descriptor = await verifyDesktopRuntime(paths.dsh, readDesktopRuntime(paths.dsh).release.version)
+await verifyWindowsCode(application)
+await smokePreparedRuntime(join(application, 'resources', 'app.asar', 'dsh'),
+ join(application, 'DeepSeek Harness.exe'), join(application, 'resources', 'runtime'), descriptor)
diff --git a/apps/desktop/scripts/smoke-prepared-runtime.ts b/apps/desktop/scripts/smoke-prepared-runtime.ts
new file mode 100644
index 0000000000..94f0c1e55e
--- /dev/null
+++ b/apps/desktop/scripts/smoke-prepared-runtime.ts
@@ -0,0 +1,36 @@
+/** Check payloads and Host boot with private native-cache and Harness directories. */
+import { execFile } from 'node:child_process'
+import { mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join, resolve } from 'node:path'
+import { promisify } from 'node:util'
+import { desktopNodeEnvironment } from '../src/node-environment.ts'
+import type { DesktopRuntimeDescriptor } from '../src/runtime-tree.ts'
+import { scrubWindowsSigningEnvironment } from './windows-sign.mjs'
+import { smokeDesktopRuntime } from './smoke-runtime.ts'
+
+/**
+ * Exercise real runtime files and Host composition, including an ASAR root when packaged.
+ * @param root Prepared or archived dsh directory.
+ * @param node Target Electron executable.
+ * @param resourcesRuntime External runtime directory beside the archive.
+ * @param descriptor Runtime descriptor already verified against the selected target, which may differ from the build host.
+ * @returns Resolves after payload checks, Host readiness and teardown.
+ */
+export async function smokePreparedRuntime(
+ root: string, node: string, resourcesRuntime: string, descriptor: DesktopRuntimeDescriptor,
+): Promise {
+ const cache = await mkdtemp(join(tmpdir(), 'desktop-native-smoke-'))
+ const environment = { ...scrubWindowsSigningEnvironment(process.env), NODE_OPTIONS: '',
+ NARB_NATIVE_CACHE_DIR: cache, NARB_DISABLE_NATIVE_CACHE: '0' }
+ try {
+ const { stdout } = await promisify(execFile)(node, [
+ '--expose-internals', resolve(import.meta.dirname, '../tests/fixtures/runtime-payload-smoke.mjs'), root, resourcesRuntime,
+ ], { timeout: 120_000, windowsHide: true,
+ env: desktopNodeEnvironment(node, join(resourcesRuntime, 'bin'), environment) })
+ process.stdout.write(stdout)
+ await smokeDesktopRuntime(root, node, descriptor, environment, resourcesRuntime)
+ } finally {
+ await rm(cache, { recursive: true, force: true })
+ }
+}
diff --git a/apps/desktop/scripts/smoke-runtime.ts b/apps/desktop/scripts/smoke-runtime.ts
index cf3d848d7f..f3697cf521 100644
--- a/apps/desktop/scripts/smoke-runtime.ts
+++ b/apps/desktop/scripts/smoke-runtime.ts
@@ -12,11 +12,18 @@ import type { DesktopRuntimeDescriptor } from '../src/runtime-tree.ts'
* @param root - Materialized dsh resources.
* @param node - Prepared target Electron executable.
* @param runtime - Verified resource descriptor.
+ * @param environment - Credential-scrubbed build environment and private native cache.
+ * @param resourcesRuntime - Bundled interpreters outside the application archive.
*/
-export async function smokeDesktopRuntime(root: string, node: string, runtime: DesktopRuntimeDescriptor): Promise {
+export async function smokeDesktopRuntime(
+ root: string, node: string, runtime: DesktopRuntimeDescriptor, environment: NodeJS.ProcessEnv, resourcesRuntime: string,
+): Promise {
const home = mkdtempSync(join(tmpdir(), 'dsh-desktop-smoke-'))
const profile = join(home, 'profiles', 'desktop')
- const host = new DesktopHostProcess(node, root, profile, undefined, { ...process.env, DSH_HOME: home })
+ const host = new DesktopHostProcess(node, root, profile, undefined, { ...environment, DSH_HOME: home },
+ undefined, join(resourcesRuntime, 'primary-runtime'), 'runtime',
+ { pnpm: join(resourcesRuntime, 'pnpm', 'bin', 'pnpm.cjs'), nodeBin: join(resourcesRuntime, 'bin') })
+ let timer: ReturnType | undefined
try {
createPluginProfile(profile)
const pluginName = 'desktop-runtime-smoke-plugin'
@@ -45,7 +52,10 @@ export function apply(ctx) {
manifest.dsh.profile.bundles.push(pluginName)
writeFileSync(join(profile, 'package.json'), JSON.stringify(manifest))
writeFileSync(join(profile, 'cordis.patch.yml'), '- id: webserver\n config:\n host: 127.0.0.1\n port: 0\n')
- const ready = await host.start()
+ const ready = await Promise.race([host.start(), new Promise((_, reject) => {
+ timer = setTimeout(() => { reject(new Error('desktop runtime: Host readiness exceeded 120 seconds')) }, 120_000)
+ })])
+ clearTimeout(timer)
const login = await fetch(ready.url, { redirect: 'manual' })
const cookie = login.headers.getSetCookie().map(value => value.split(';')[0]).join('; ')
const response = await fetch(new URL('/', ready.url), { headers: { cookie } })
@@ -55,6 +65,7 @@ export function apply(ctx) {
const pluginResponse = await fetch(new URL('/desktop-smoke', ready.url), { headers: { cookie } })
if (await pluginResponse.text() !== 'plugin route ready') throw new Error('desktop runtime: plugin HTTP route failed')
} finally {
+ clearTimeout(timer)
await host.stop()
rmSync(home, { recursive: true, force: true })
}
diff --git a/apps/desktop/scripts/windows-asar-unpack.d.mts b/apps/desktop/scripts/windows-asar-unpack.d.mts
new file mode 100644
index 0000000000..984c055737
--- /dev/null
+++ b/apps/desktop/scripts/windows-asar-unpack.d.mts
@@ -0,0 +1,18 @@
+import type { BeforePackContext } from 'app-builder-lib'
+
+/**
+ * Install source-relative PE patterns in the active builder configuration.
+ * @param context Active builder configuration and cleanup owner.
+ * @param sourceRoot Verified prepared dsh directory; external sources receive a build-owned staging copy.
+ * @returns PE paths relative to the original prepared directory.
+ */
+export function prepareWindowsAsarUnpack(context: BeforePackContext, sourceRoot: string): Promise
+
+/**
+ * Reject inline, absent, linked, or changed PE files in the assembled application.
+ * @param sourceRoot Original signed and sealed dsh directory.
+ * @param resourcesDir Assembled application resources directory.
+ * @param files PE paths returned by prepareWindowsAsarUnpack.
+ * @returns Resolves after every PE has an unpacked ASAR entry and identical bytes.
+ */
+export function verifyWindowsAsarUnpack(sourceRoot: string, resourcesDir: string, files: string[]): Promise
diff --git a/apps/desktop/scripts/windows-asar-unpack.mjs b/apps/desktop/scripts/windows-asar-unpack.mjs
new file mode 100644
index 0000000000..d406c27235
--- /dev/null
+++ b/apps/desktop/scripts/windows-asar-unpack.mjs
@@ -0,0 +1,70 @@
+/** Keep prepared Windows PE files outside ASAR without changing their sealed bytes. */
+import { cp, lstat, mkdir, mkdtemp, readFile, rm } from 'node:fs/promises'
+import { isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { readAsar } from 'app-builder-lib/out/asar/asar.js'
+import { windowsRuntimeCode } from './windows-runtime-signature.mjs'
+
+function inside(root, file) {
+ const suffix = relative(root, file)
+ return suffix !== '..' && !suffix.startsWith(`..${sep}`) && !isAbsolute(suffix)
+}
+
+function unpackPattern(path) {
+ // Builder removes backslash escapes; brace expansion also ignores character classes.
+ // A brace matches one character, so similarly named neighbors may also be unpacked.
+ return path.split(sep).join('/').replace(/[\[\]{}()*?+@#]/gu,
+ character => character === '{' || character === '}' ? '?' : `[${character}]`).replace(/^!/u, '@(!)')
+}
+
+/**
+ * Install source-relative PE patterns in the configuration consumed by electron-builder.
+ * @param {import('app-builder-lib').BeforePackContext} context Active builder configuration and cleanup owner.
+ * @param {string} sourceRoot Verified prepared dsh directory; its files remain unchanged.
+ * @returns {Promise} PE paths relative to the original prepared directory.
+ */
+export async function prepareWindowsAsarUnpack(context, sourceRoot) {
+ const files = (await windowsRuntimeCode(sourceRoot)).map(file => relative(sourceRoot, file))
+ const { config, info } = context.packager
+ const { appDir } = info
+ let copyRoot = sourceRoot
+ if (!inside(appDir, sourceRoot)) {
+ // Builder's source matcher slices the appDir prefix even for external FileSets.
+ const parent = join(appDir, '.desktop-build')
+ await mkdir(parent, { recursive: true })
+ const stage = await mkdtemp(join(parent, 'asar-source-'))
+ copyRoot = join(stage, 'dsh')
+ info.disposeOnBuildFinish(() => rm(stage, { recursive: true, force: true }))
+ await cp(sourceRoot, copyRoot, { recursive: true, force: false, errorOnExist: true })
+ config.files = config.files.map(file => {
+ if (typeof file === 'string' || file.from === undefined) return file
+ const from = resolve(appDir, file.from)
+ return inside(sourceRoot, from) ? { ...file, from: join(copyRoot, relative(sourceRoot, from)) } : file
+ })
+ }
+ const existing = config.asarUnpack ?? []
+ config.asarUnpack = [...(typeof existing === 'string' ? [existing] : existing),
+ ...files.map(file => unpackPattern(relative(appDir, join(copyRoot, file))))]
+ return files
+}
+
+/**
+ * Reject inline, absent, linked, or changed PE files in the assembled application.
+ * @param {string} sourceRoot Original signed and sealed dsh directory.
+ * @param {string} resourcesDir Assembled application resources directory.
+ * @param {string[]} files PE paths returned by prepareWindowsAsarUnpack.
+ * @returns {Promise} Resolves after every PE has an unpacked ASAR entry and identical bytes.
+ */
+export async function verifyWindowsAsarUnpack(sourceRoot, resourcesDir, files) {
+ const archive = await readAsar(join(resourcesDir, 'app.asar'))
+ for (const file of files) {
+ const entry = archive.getFile(join('dsh', file), false)
+ if (entry.unpacked !== true || entry.link !== undefined) {
+ throw new Error(`Windows ASAR: PE must be unpacked: ${file}`)
+ }
+ const copied = join(resourcesDir, 'app.asar.unpacked', 'dsh', file)
+ const stat = await lstat(copied)
+ if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`Windows ASAR: expected a real PE file: ${file}`)
+ const [prepared, packaged] = await Promise.all([readFile(join(sourceRoot, file)), readFile(copied)])
+ if (!prepared.equals(packaged)) throw new Error(`Windows ASAR: PE bytes changed: ${file}`)
+ }
+}
diff --git a/apps/desktop/scripts/windows-runtime-signature.d.mts b/apps/desktop/scripts/windows-runtime-signature.d.mts
index 7f9d9cf797..9c6e207a17 100644
--- a/apps/desktop/scripts/windows-runtime-signature.d.mts
+++ b/apps/desktop/scripts/windows-runtime-signature.d.mts
@@ -24,3 +24,34 @@ export function preserveWindowsRuntimeSignature(path: string, options: {
runDirectory: string
inspect?: typeof inspectWindowsRuntimeSignature
}): Promise
+
+/** Supervised signing dependencies shared by all Windows release trees. */
+export interface WindowsCodeSigningOptions {
+ thumbprint: string
+ sign: ReturnType
+ inspect?: typeof inspectWindowsRuntimeSignature
+ record: (event: object) => void
+}
+
+/**
+ * Enumerate PE files by content without following links.
+ * @param root Materialized directory to scan.
+ * @returns Sorted PE paths; rejects malformed Windows executables and links.
+ */
+export function windowsRuntimeCode(root: string): Promise
+
+/**
+ * Preserve valid signatures and sign unsigned PE files with a supervised signer.
+ * @param root Materialized directory to sign.
+ * @param options Signer, certificate identity and audit sink.
+ * @returns Resolves after verified sequential signing; rejects without retries.
+ */
+export function signWindowsCode(root: string, options: WindowsCodeSigningOptions): Promise
+
+/**
+ * Reject unsigned or invalid PE files in a completed directory.
+ * @param root Materialized artifact directory.
+ * @param inspect Public-key verifier.
+ * @returns Resolves after all PE signatures are valid.
+ */
+export function verifyWindowsCode(root: string, inspect?: typeof inspectWindowsRuntimeSignature): Promise
diff --git a/apps/desktop/scripts/windows-runtime-signature.mjs b/apps/desktop/scripts/windows-runtime-signature.mjs
index 04b1d7dbb8..ee70330fd7 100644
--- a/apps/desktop/scripts/windows-runtime-signature.mjs
+++ b/apps/desktop/scripts/windows-runtime-signature.mjs
@@ -1,10 +1,11 @@
/** Inspect runtime signatures and preserve byte-identical copies made by electron-builder. */
import { execFile } from 'node:child_process'
-import { readFile, realpath } from 'node:fs/promises'
-import { isAbsolute, join, relative, resolve, sep } from 'node:path'
+import { lstat, open, readdir, readFile, realpath } from 'node:fs/promises'
+import { extname, isAbsolute, join, relative, resolve, sep } from 'node:path'
import { promisify } from 'node:util'
import { scrubWindowsSigningEnvironment } from './windows-sign.mjs'
import { recordPackagingEvent } from './packaging-run.mjs'
+import { inspectSignaturesBatched } from './windows-signature-batch.mjs'
/**
* Read Windows trust, timestamp and signer identity using the engine's bundled modules, without accessing the private key.
@@ -22,13 +23,13 @@ export async function inspectWindowsRuntimeSignature(path) {
if (stderr || typeof value !== 'object' || value === null || typeof value.status !== 'string'
|| typeof value.timestamped !== 'boolean'
|| !(value.thumbprint === null || typeof value.thumbprint === 'string' && /^[A-F\d]{40}$/iu.test(value.thumbprint))) {
- throw new Error(`primary runtime: invalid signature inspection: ${path}`)
+ throw new Error(`Windows code: invalid signature inspection: ${path}`)
}
return { status: value.status, timestamped: value.timestamped, thumbprint: value.thumbprint }
}
/**
- * Preserve a copied primary-runtime executable only after signature and exact-byte verification.
+ * Preserve a copied runtime executable only after signature and exact-byte verification.
* @param {string} path Signing-hook target.
* @param {{sourceRoot: string, destinationRoot: string, runDirectory: string, inspect?: typeof inspectWindowsRuntimeSignature}} options Prepared and copied runtime roots with retained audit directory.
* @returns {Promise} True for a verified runtime copy; false for targets outside that directory.
@@ -38,12 +39,105 @@ export async function preserveWindowsRuntimeSignature(path, options) {
if (!suffix || suffix === '..' || suffix.startsWith(`..${sep}`) || isAbsolute(suffix)) return false
const source = join(options.sourceRoot, suffix)
for (const file of [source, path]) {
- if (await realpath(file) !== resolve(file)) throw new Error(`primary runtime: linked copy is not signable: ${file}`)
+ if (await realpath(file) !== resolve(file)) throw new Error(`Windows code: linked copy is not signable: ${file}`)
}
const [prepared, copied] = await Promise.all([readFile(source), readFile(path)])
- if (!prepared.equals(copied)) throw new Error(`primary runtime: copied executable changed: ${path}`)
+ if (!prepared.equals(copied)) throw new Error(`Windows code: copied executable changed: ${path}`)
const signature = await (options.inspect ?? inspectWindowsRuntimeSignature)(path)
- if (signature.status !== 'Valid') throw new Error(`primary runtime: copied signature is ${signature.status}: ${path}`)
+ if (signature.status !== 'Valid') throw new Error(`Windows code: copied signature is ${signature.status}: ${path}`)
recordPackagingEvent(options.runDirectory, { type: 'primary-runtime-copy-verified', path, ...signature })
return true
}
+
+/**
+ * Enumerate Windows code without following links or treating foreign .node files as PE binaries.
+ * @param {string} root - Owned, materialized runtime directory.
+ * @returns {Promise} Sorted real PE files; rejects links and malformed Windows executable files.
+ */
+export async function windowsRuntimeCode(root) {
+ const rootStat = await lstat(root)
+ if (!rootStat.isDirectory() || rootStat.isSymbolicLink()) throw new Error('Windows code: expected a real directory')
+ const files = []
+ for (const entry of await readdir(root, { withFileTypes: true })) {
+ const path = join(root, entry.name)
+ if (entry.isSymbolicLink()) throw new Error(`Windows code: directory links are not signable: ${path}`)
+ if (entry.isDirectory()) { files.push(...await windowsRuntimeCode(path)); continue }
+ if (!entry.isFile()) continue
+ const file = await open(path, 'r')
+ let portableExecutable = false
+ let windowsCandidate = false
+ try {
+ const header = Buffer.alloc(64)
+ const { bytesRead } = await file.read(header, 0, header.length, 0)
+ windowsCandidate = bytesRead >= 2 && header.readUInt16LE(0) === 0x5a4d
+ if (bytesRead === 64 && windowsCandidate) {
+ const signature = Buffer.alloc(4)
+ const offset = header.readUInt32LE(0x3c)
+ const read = await file.read(signature, 0, 4, offset)
+ portableExecutable = offset >= 64 && read.bytesRead === 4 && signature.readUInt32LE(0) === 0x4550
+ }
+ } finally { await file.close() }
+ if (portableExecutable) files.push(path)
+ else if (windowsCandidate || ['.exe', '.dll', '.pyd'].includes(extname(path).toLowerCase())) throw new Error(`Windows code: invalid PE file: ${path}`)
+ }
+ return files.sort()
+}
+
+/** Drain each public-key verification batch before signing or reporting a failure. */
+async function inspectWindowsCode(files, inspect) {
+ if (inspect === inspectWindowsRuntimeSignature) return inspectSignaturesBatched(files)
+ const signatures = []
+ for (let offset = 0; offset < files.length; offset += 4) {
+ const results = await Promise.allSettled(files.slice(offset, offset + 4).map(path => inspect(path)))
+ for (const result of results) {
+ if (result.status === 'rejected') throw result.reason
+ signatures.push(result.value)
+ }
+ }
+ return signatures
+}
+
+/**
+ * Preserve valid signatures and sign unsigned PE files with a supervised signer.
+ * @param {string} root - Owned final runtime directory.
+ * @param {import('./windows-runtime-signature.mjs').WindowsCodeSigningOptions} options - Supervised signer, certificate identity, audit sink.
+ * @returns {Promise} Resolves only after sequential signatures and verification; no retries.
+ */
+export async function signWindowsCode(root, options) {
+ const inspect = options.inspect ?? inspectWindowsRuntimeSignature
+ const files = await windowsRuntimeCode(root)
+ if (files.length === 0) throw new Error('Windows code: no Windows code found')
+ const unsigned = []
+ const signatures = await inspectWindowsCode(files, inspect)
+ for (const [index, path] of files.entries()) {
+ const signature = signatures[index]
+ options.record({ type: 'windows-code-signature', path, ...signature })
+ if (signature.status === 'NotSigned') unsigned.push(path)
+ else if (signature.status !== 'Valid') throw new Error(`Windows code: refusing ${signature.status} signature: ${path}`)
+ }
+ options.record({ type: 'windows-code-signing-plan', files: files.length, unsigned: unsigned.length })
+ for (const path of unsigned) {
+ await options.sign({ path, hash: 'sha256', isNest: false })
+ const signature = await inspect(path)
+ if (signature.status !== 'Valid' || !signature.timestamped || signature.thumbprint?.toUpperCase() !== options.thumbprint.toUpperCase()) {
+ throw new Error(`Windows code: signing verification failed: ${path}`)
+ }
+ options.record({ type: 'windows-code-signature-verified', path, ...signature })
+ }
+}
+
+/**
+ * Reject any unsigned or invalid PE remaining in a completed directory.
+ * @param {string} root Materialized artifact directory.
+ * @param {typeof inspectWindowsRuntimeSignature} inspect Public-key verifier.
+ * @returns {Promise} Resolves after every discovered PE has a valid signature.
+ */
+export async function verifyWindowsCode(root, inspect = inspectWindowsRuntimeSignature) {
+ const files = await windowsRuntimeCode(root)
+ if (files.length === 0) throw new Error('Windows code: no Windows code found')
+ const signatures = await inspectWindowsCode(files, inspect)
+ for (const [index, path] of files.entries()) {
+ const signature = signatures[index]
+ if (signature.status !== 'Valid') throw new Error(`Windows code: refusing ${signature.status} signature: ${path}`)
+ }
+}
diff --git a/apps/desktop/scripts/windows-sign.cmd b/apps/desktop/scripts/windows-sign.cmd
index 366f787f57..8afed8833e 100644
--- a/apps/desktop/scripts/windows-sign.cmd
+++ b/apps/desktop/scripts/windows-sign.cmd
@@ -13,5 +13,5 @@ set "DSH_DESKTOP_WINDOWS_TOKEN_PIN="
set "DSH_DESKTOP_WINDOWS_KEY_CONTAINER="
set "DSH_DESKTOP_WINDOWS_SIGN_TARGET="
set "DSH_DESKTOP_WINDOWS_SIGN_APPEND="
-set "signTool=" & set "certificateFile=" & set "tokenPin=" & set "keyContainer=" & set "targetFile=" & set "appendSignature=" & "%signTool%" sign /v /fd sha256 /f "%certificateFile%" /kc "[{{%tokenPin%}}]=%keyContainer%" /csp "eToken Base Cryptographic Provider" %appendSignature% /tr http://timestamp.digicert.com /td sha256 "%targetFile%"
+set "signTool=" & set "certificateFile=" & set "tokenPin=" & set "keyContainer=" & set "targetFile=" & set "appendSignature=" & "%signTool%" sign /v /fd sha256 /f "%certificateFile%" /kc "[{{%tokenPin%}}]=%keyContainer%" /csp "eToken Base Cryptographic Provider" %appendSignature% "%targetFile%"
exit /b %errorlevel%
diff --git a/apps/desktop/scripts/windows-sign.mjs b/apps/desktop/scripts/windows-sign.mjs
index d491196a74..3ebd199615 100644
--- a/apps/desktop/scripts/windows-sign.mjs
+++ b/apps/desktop/scripts/windows-sign.mjs
@@ -7,6 +7,8 @@ import { fileURLToPath } from 'node:url'
import { promisify } from 'node:util'
import wineVmModule from 'app-builder-lib/out/vm/WineVm.js'
import { beginWindowsSigningAttempt } from './windows-signing-state.mjs'
+import { completeWindowsSignature, normalizeWindowsSignature } from './windows-timestamp.mjs'
+import { failPackagingRun, recordPackagingEvent } from './packaging-run.mjs'
const execFileAsync = promisify(execFile)
const { WineVmManager } = wineVmModule
@@ -162,7 +164,7 @@ export function buildWindowsSigningEnvironment(environment, input) {
* @returns {(configuration: { path: string, hash: string, isNest: boolean }) => Promise} The signing hook.
*/
export function createWindowsTokenSigner(options) {
- const { path: certificateFile } = resolveCertificateFile(options.certificateFile)
+ const { path: certificateFile, certificate } = resolveCertificateFile(options.certificateFile)
const signTool = resolveSignTool(options.signTool)
const { keyContainer, tokenPin } = resolveTokenIdentity(options)
const commandInterpreter = options.commandInterpreter
@@ -174,43 +176,67 @@ export function createWindowsTokenSigner(options) {
if (configuration.hash !== 'sha256') {
throw new Error(`Windows release signing requires SHA-256, received ${configuration.hash}`)
}
+ if (configuration.isNest) throw new Error('Windows release signing does not support appended signatures')
if (await options.preserveSignature?.(configuration.path)) return
- await repairDanglingAuthenticodeDirectory(configuration.path)
const secrets = [tokenPin]
- const attempt = beginWindowsSigningAttempt({ runDirectory: options.runDirectory,
- stateDirectory: options.stateDirectory, target: configuration.path })
- let result
+ const runDirectory = options.runDirectory ?? process.env.DSH_DESKTOP_PACKAGING_RUN_DIR
+ if (!runDirectory) throw new Error('Windows hardware signing requires a supervised packaging run')
+ const { inspectWindowsRuntimeSignature: inspect } = await import('./windows-runtime-signature.mjs')
+ const thumbprint = certificate.fingerprint.replaceAll(':', '')
try {
- const operation = execFileAsync(commandInterpreter, [
- '/d',
- '/v:off',
- '/c',
- WINDOWS_SIGN_SCRIPT,
- ], {
- cwd: WINDOWS_SIGN_SCRIPT_DIRECTORY,
- env: buildWindowsSigningEnvironment(process.env, {
- certificateFile,
- signTool,
- path: configuration.path,
- isNest: configuration.isNest,
- tokenPin,
- keyContainer,
- }),
- windowsHide: true,
+ await completeWindowsSignature(configuration.path, {
+ thumbprint, inspect, evidenceDirectory: runDirectory,
+ record: event => recordPackagingEvent(runDirectory, event),
+ normalize: path => normalizeWindowsSignature(path, signTool, scrubWindowsSigningEnvironment(process.env)),
+ timestamp: async path => { await execFileAsync(signTool, ['timestamp', '/v', '/tr', 'http://timestamp.digicert.com', '/td', 'sha256', path], {
+ env: scrubWindowsSigningEnvironment(process.env), windowsHide: true, timeout: 60_000,
+ }) },
+ sign: async (path) => {
+ await repairDanglingAuthenticodeDirectory(path)
+ const attempt = beginWindowsSigningAttempt({ runDirectory,
+ stateDirectory: options.stateDirectory, target: path })
+ let result
+ try {
+ const operation = execFileAsync(commandInterpreter, [
+ '/d',
+ '/v:off',
+ '/c',
+ WINDOWS_SIGN_SCRIPT,
+ ], {
+ cwd: WINDOWS_SIGN_SCRIPT_DIRECTORY,
+ env: buildWindowsSigningEnvironment(process.env, {
+ certificateFile,
+ signTool,
+ path,
+ isNest: false,
+ tokenPin,
+ keyContainer,
+ }),
+ windowsHide: true,
+ })
+ attempt.started(operation.child?.pid ?? null)
+ result = await operation
+ const signature = await inspect(path)
+ if (signature.status !== 'Valid' || signature.timestamped || signature.thumbprint?.toUpperCase() !== thumbprint.toUpperCase()) {
+ throw new Error('Windows hardware signing: primary signature verification failed')
+ }
+ }
+ catch (error) {
+ const failure = createRedactedWindowsSigningError(error, path, secrets)
+ attempt.failure(typeof error.code === 'number' || typeof error.code === 'string' ? error.code : null, failure.message)
+ throw failure
+ }
+ attempt.success()
+ const stdout = redactedSigningOutput(result.stdout, secrets)
+ const stderr = redactedSigningOutput(result.stderr, secrets)
+ if (stdout !== '') process.stdout.write(stdout)
+ if (stderr !== '') process.stderr.write(stderr)
+ },
})
- attempt.started(operation.child?.pid ?? null)
- result = await operation
+ } catch (error) {
+ failPackagingRun(runDirectory, 'signature-completion-failed')
+ throw error
}
- catch (error) {
- const failure = createRedactedWindowsSigningError(error, configuration.path, secrets)
- attempt.failure(typeof error.code === 'number' || typeof error.code === 'string' ? error.code : null, failure.message)
- throw failure
- }
- attempt.success()
- const stdout = redactedSigningOutput(result.stdout, secrets)
- const stderr = redactedSigningOutput(result.stderr, secrets)
- if (stdout !== '') process.stdout.write(stdout)
- if (stderr !== '') process.stderr.write(stderr)
})
return pending
}
diff --git a/apps/desktop/scripts/windows-signature-batch.d.mts b/apps/desktop/scripts/windows-signature-batch.d.mts
new file mode 100644
index 0000000000..a58c652d42
--- /dev/null
+++ b/apps/desktop/scripts/windows-signature-batch.d.mts
@@ -0,0 +1,17 @@
+import type { WindowsRuntimeSignature } from './windows-runtime-signature.mjs'
+
+/**
+ * Validate complete, ordered, per-file inspection results.
+ * @param stdout Newline-delimited signature records.
+ * @param stderr Process diagnostics, which must be empty.
+ * @param files Exact requested file order.
+ * @returns Validated signatures; rejects missing, duplicate, reordered or malformed rows.
+ */
+export function parseSignatureRows(stdout: string, stderr: string, files: readonly string[]): WindowsRuntimeSignature[]
+
+/**
+ * Inspect every file with at most four processes and 32 files per process.
+ * @param files Materialized PE paths in stable order.
+ * @returns One signature per file, after all processes in each batch have exited, including on failure.
+ */
+export function inspectSignaturesBatched(files: readonly string[]): Promise
diff --git a/apps/desktop/scripts/windows-signature-batch.mjs b/apps/desktop/scripts/windows-signature-batch.mjs
new file mode 100644
index 0000000000..cbc37b9d30
--- /dev/null
+++ b/apps/desktop/scripts/windows-signature-batch.mjs
@@ -0,0 +1,57 @@
+/** Bounded public-key verification batches; every output row must match its requested file. */
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { scrubWindowsSigningEnvironment } from './windows-sign.mjs'
+
+const command = '$ErrorActionPreference="Stop"; [Console]::InputEncoding=[System.Text.UTF8Encoding]::new(); [Console]::OutputEncoding=[System.Text.UTF8Encoding]::new(); Import-Module "$PSHOME/Modules/Microsoft.PowerShell.Security/Microsoft.PowerShell.Security.psd1" -ErrorAction Stop; Import-Module "$PSHOME/Modules/Microsoft.PowerShell.Utility/Microsoft.PowerShell.Utility.psd1" -ErrorAction Stop; $files=[Console]::In.ReadToEnd()|ConvertFrom-Json; foreach($file in $files){ $s=Get-AuthenticodeSignature -LiteralPath $file; [pscustomobject]@{path=$file;status=[string]$s.Status;timestamped=($null -ne $s.TimeStamperCertificate);thumbprint=$s.SignerCertificate.Thumbprint}|ConvertTo-Json -Compress }'
+
+/**
+ * Reject missing, duplicated, reordered or malformed file results.
+ * @param {string} stdout Newline-delimited signature records.
+ * @param {string} stderr Process diagnostics; any content rejects the batch.
+ * @param {readonly string[]} files Exact requested order.
+ * @returns {Array<{status: string, timestamped: boolean, thumbprint: string|null}>} Complete signature results.
+ */
+export function parseSignatureRows(stdout, stderr, files) {
+ const rows = stdout.trim().split(/\r?\n/u)
+ if (stderr || rows.length !== files.length) throw new Error('Windows signature batch: incomplete inspection output')
+ return rows.map((row, index) => {
+ const value = JSON.parse(row)
+ if (value === null || typeof value !== 'object' || value.path !== files[index]
+ || typeof value.status !== 'string' || typeof value.timestamped !== 'boolean'
+ || !(value.thumbprint === null || typeof value.thumbprint === 'string' && /^[A-F\d]{40}$/iu.test(value.thumbprint))) {
+ throw new Error(`Windows signature batch: invalid inspection output: ${files[index]}`)
+ }
+ return { status: value.status, timestamped: value.timestamped, thumbprint: value.thumbprint }
+ })
+}
+
+async function inspectBatch(files) {
+ const pending = promisify(execFile)('powershell.exe', ['-NoProfile', '-NonInteractive', '-Command', command], {
+ env: scrubWindowsSigningEnvironment(process.env), encoding: 'utf8', windowsHide: true,
+ timeout: 60_000, maxBuffer: 64 * 1024 * files.length,
+ })
+ pending.child.stdin.on('error', () => { /* Process failure is reported by the awaited execFile result. */ })
+ pending.child.stdin.end(JSON.stringify(files))
+ const { stdout, stderr } = await pending
+ return parseSignatureRows(stdout, stderr, files)
+}
+
+/**
+ * Inspect every file through at most four processes, draining failures before returning.
+ * @param {readonly string[]} files Materialized PE paths in stable order.
+ * @returns {Promise>} One result per input.
+ */
+export async function inspectSignaturesBatched(files) {
+ const signatures = []
+ for (let offset = 0; offset < files.length; offset += 128) {
+ const groups = []
+ for (let i = offset; i < Math.min(files.length, offset + 128); i += 32) groups.push(files.slice(i, i + 32))
+ const settled = await Promise.allSettled(groups.map(inspectBatch))
+ for (const result of settled) {
+ if (result.status === 'rejected') throw result.reason
+ signatures.push(...result.value)
+ }
+ }
+ return signatures
+}
diff --git a/apps/desktop/scripts/windows-signature-cache.d.mts b/apps/desktop/scripts/windows-signature-cache.d.mts
new file mode 100644
index 0000000000..bc45bf1b52
--- /dev/null
+++ b/apps/desktop/scripts/windows-signature-cache.d.mts
@@ -0,0 +1,26 @@
+import type { WindowsRuntimeSignature } from './windows-runtime-signature.mjs'
+import type { createWindowsTokenSigner } from './windows-sign.mjs'
+
+/** File-owned cache policy and existing supervised signing operations. */
+export interface WindowsSignatureCacheOptions {
+ root: string
+ identity: string
+ thumbprint: string
+ sign: ReturnType
+ inspect: (path: string) => Promise
+ record: (event: object) => void
+}
+
+/**
+ * Hash the public certificate and files controlling signing output in fixed order.
+ * @param files Certificate and signing-toolchain paths, excluding credentials.
+ * @returns Content identity independent of installation paths and PIN values.
+ */
+export function signatureCacheIdentity(files: readonly string[]): Promise
+
+/**
+ * Reuse complete signed files only after input, integrity, identity and timestamp checks.
+ * @param options Cache policy, supervised signer, public-key verifier and audit sink.
+ * @returns Serial signer that stops its queue on any failure and never repairs invalid cache entries.
+ */
+export function createCachedSigner(options: WindowsSignatureCacheOptions): ReturnType
diff --git a/apps/desktop/scripts/windows-signature-cache.mjs b/apps/desktop/scripts/windows-signature-cache.mjs
new file mode 100644
index 0000000000..a4302badbe
--- /dev/null
+++ b/apps/desktop/scripts/windows-signature-cache.mjs
@@ -0,0 +1,97 @@
+/** Cache complete signed files; corrupt entries stop the caller before hardware access. */
+import { createHash } from 'node:crypto'
+import { copyFile, lstat, mkdir, mkdtemp, readFile, realpath, rename, rm, writeFile } from 'node:fs/promises'
+import { basename, dirname, join, resolve, toNamespacedPath } from 'node:path'
+
+const digest = bytes => createHash('sha256').update(bytes).digest('hex')
+
+/**
+ * Include public certificate and every file that controls signing output in the policy identity.
+ * @param {readonly string[]} files Certificate, SignTool, signing script and signer implementation paths, in fixed order.
+ * @returns {Promise} Content identity independent of installation paths and PIN values.
+ */
+export async function signatureCacheIdentity(files) {
+ return digest(JSON.stringify(await Promise.all(files.map(async path => digest(await regularFile(path))))))
+}
+
+async function regularFile(path) {
+ const stat = await lstat(path)
+ if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`signature cache: expected regular file: ${path}`)
+ return readFile(path)
+}
+
+async function directory(path) {
+ const stat = await lstat(path)
+ if (!stat.isDirectory() || stat.isSymbolicLink() || await realpath(path) !== resolve(path)) {
+ throw new Error(`signature cache: expected unlinked directory: ${path}`)
+ }
+}
+
+function validSignature(signature, thumbprint) {
+ return signature.status === 'Valid' && signature.timestamped
+ && signature.thumbprint?.toUpperCase() === thumbprint.toUpperCase()
+}
+
+/**
+ * Wrap a supervised signer with immutable entries keyed by unsigned bytes and signing policy.
+ * @param {import('./windows-signature-cache.mjs').WindowsSignatureCacheOptions} options Cache policy and existing supervised operations.
+ * @returns {ReturnType} Serial, fail-stop signing callback; cache hits still verify trust and timestamp.
+ */
+export function createCachedSigner(options) {
+ let pending = Promise.resolve()
+ async function readEntry(entry, key, inputDigest) {
+ await directory(entry)
+ const record = JSON.parse((await regularFile(join(entry, 'record.json'))).toString('utf8'))
+ if (record === null || typeof record !== 'object' || record.version !== 1 || record.key !== key || record.inputDigest !== inputDigest
+ || record.identity !== options.identity || typeof record.signedDigest !== 'string'
+ || !/^[a-f\d]{64}$/u.test(record.signedDigest)) throw new Error('signature cache: invalid input record')
+ const payload = await regularFile(join(entry, 'payload'))
+ if (digest(payload) !== record.signedDigest) throw new Error('signature cache: corrupt signed payload')
+ return record
+ }
+ async function sign(configuration) {
+ if (configuration.hash !== 'sha256' || configuration.isNest) throw new Error('signature cache: only unsigned SHA-256 runtime files are supported')
+ const inputDigest = digest(await regularFile(configuration.path))
+ const key = digest(JSON.stringify({ version: 1, inputDigest, identity: options.identity }))
+ await mkdir(options.root, { recursive: true })
+ await directory(options.root)
+ const entry = join(options.root, key)
+ let hit = false
+ try { await lstat(entry); hit = true }
+ catch (error) { if (error.code !== 'ENOENT') throw error }
+ if (hit) {
+ const record = await readEntry(entry, key, inputDigest)
+ const staging = await mkdtemp(toNamespacedPath(join(dirname(configuration.path), '.signature-restore-')))
+ try {
+ const candidate = join(staging, basename(configuration.path))
+ await copyFile(join(entry, 'payload'), candidate)
+ if (digest(await regularFile(candidate)) !== record.signedDigest) throw new Error('signature cache: restore changed signed bytes')
+ if (!validSignature(await options.inspect(candidate), options.thumbprint)) throw new Error('signature cache: invalid cached signature')
+ if (digest(await regularFile(configuration.path)) !== inputDigest) throw new Error('signature cache: target changed before restore')
+ await rename(candidate, configuration.path)
+ } finally { await rm(staging, { recursive: true, force: true }) }
+ options.record({ type: 'signature-cache-hit', key, path: configuration.path })
+ return
+ }
+ options.record({ type: 'signature-cache-miss', key, path: configuration.path })
+ await options.sign(configuration)
+ if (!validSignature(await options.inspect(configuration.path), options.thumbprint)) throw new Error('signature cache: new signature verification failed')
+ const staging = await mkdtemp(toNamespacedPath(join(options.root, '.publish-')))
+ try {
+ await copyFile(configuration.path, join(staging, 'payload'))
+ const signedDigest = digest(await regularFile(join(staging, 'payload')))
+ if (signedDigest !== digest(await regularFile(configuration.path))) throw new Error('signature cache: signed file changed during publication')
+ await writeFile(join(staging, 'record.json'), JSON.stringify({ version: 1, key, inputDigest, identity: options.identity, signedDigest }), { flag: 'wx', flush: true })
+ try { await rename(staging, entry) }
+ catch (error) {
+ if (!['EEXIST', 'ENOTEMPTY', 'EPERM'].includes(error.code)) throw error
+ await readEntry(entry, key, inputDigest)
+ }
+ options.record({ type: 'signature-cache-published', key, path: configuration.path })
+ } finally { await rm(staging, { recursive: true, force: true }) }
+ }
+ return configuration => {
+ pending = pending.then(() => sign(configuration))
+ return pending
+ }
+}
diff --git a/apps/desktop/scripts/windows-signing-preflight.ts b/apps/desktop/scripts/windows-signing-preflight.ts
index fd4546c869..6076e4cd4e 100644
--- a/apps/desktop/scripts/windows-signing-preflight.ts
+++ b/apps/desktop/scripts/windows-signing-preflight.ts
@@ -30,7 +30,7 @@ async function compileProbe(compiler: string, source: string, output: string, en
/**
* Sign one newly compiled, never-executed probe and verify its timestamp and configured certificate.
* @param options Supervised evidence directory, file-owned settings and isolated test adapters.
- * @returns Resolves after one signature and verification; failures retain evidence and never retry or unlock a token.
+ * @returns Resolves after one signature and verification; failures retain evidence; timestamp attempts never repeat hardware signing.
*/
export async function preflightWindowsSigning(options: SigningPreflightOptions): Promise {
const { environment, runDirectory } = options
diff --git a/apps/desktop/scripts/windows-timestamp.d.mts b/apps/desktop/scripts/windows-timestamp.d.mts
new file mode 100644
index 0000000000..bb1dd617c0
--- /dev/null
+++ b/apps/desktop/scripts/windows-timestamp.d.mts
@@ -0,0 +1,30 @@
+import type { WindowsRuntimeSignature } from './windows-runtime-signature.mjs'
+
+/**
+ * Remove unsigned signature attributes on a previously verified private copy.
+ * @param path Single-signature private copy.
+ * @param signTool Configured SignTool executable.
+ * @param environment Credential-free subprocess environment.
+ * @returns Resolves after removal or an unchanged-file warning; other failures reject.
+ */
+export function normalizeWindowsSignature(path: string, signTool: string, environment: NodeJS.ProcessEnv): Promise
+
+/** Public operations on isolated files; sign resolves only after verified hardware success. */
+export interface WindowsTimestampOptions {
+ sign: (path: string) => Promise
+ timestamp: (path: string) => Promise
+ normalize: (path: string) => Promise
+ inspect: (path: string) => Promise
+ thumbprint: string
+ evidenceDirectory: string
+ record: (event: object) => void
+ wait?: (milliseconds: number) => Promise
+}
+
+/**
+ * Complete a single verified hardware signature using bounded, isolated timestamp attempts.
+ * @param path Exclusively owned build file in trusted storage.
+ * @param options Verified signer, public operations, certificate and retained audit storage.
+ * @returns Resolves after a valid timestamp and exact normalized-content verification; failures preserve evidence.
+ */
+export function completeWindowsSignature(path: string, options: WindowsTimestampOptions): Promise
diff --git a/apps/desktop/scripts/windows-timestamp.mjs b/apps/desktop/scripts/windows-timestamp.mjs
new file mode 100644
index 0000000000..bb25e2d80f
--- /dev/null
+++ b/apps/desktop/scripts/windows-timestamp.mjs
@@ -0,0 +1,107 @@
+/** Finish timestamps on isolated copies without repeating a verified private-key operation. */
+import { createHash } from 'node:crypto'
+import { execFile } from 'node:child_process'
+import { promisify } from 'node:util'
+import { copyFile, cp, lstat, mkdtemp, readFile, rename, rm } from 'node:fs/promises'
+import { dirname, extname, join, toNamespacedPath } from 'node:path'
+import { tmpdir } from 'node:os'
+import { setTimeout } from 'node:timers/promises'
+
+async function digest(path) {
+ const stat = await lstat(path)
+ if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('Windows timestamp: expected a regular file')
+ return createHash('sha256').update(await readFile(path)).digest('hex')
+}
+
+/**
+ * Remove unsigned signature attributes on a private copy using the configured SignTool.
+ * @param {string} path Previously verified, single-signature private copy.
+ * @param {string} signTool Configured SignTool executable.
+ * @param {NodeJS.ProcessEnv} environment Credential-free subprocess environment.
+ * @returns {Promise} Resolves after removal, or a warning that left all bytes unchanged.
+ */
+export async function normalizeWindowsSignature(path, signTool, environment) {
+ const before = await digest(path)
+ try {
+ await promisify(execFile)(signTool, ['remove', '/u', path], { env: environment, windowsHide: true, timeout: 60_000 })
+ } catch (error) {
+ // SignTool returns warning status when a verified signature has no unsigned attributes.
+ if (error.code !== 2 || error.signal || error.killed || await digest(path) !== before) throw error
+ }
+}
+
+/**
+ * Sign once, timestamp fresh copies at most three times, then atomically replace the unchanged input.
+ * @param {string} path Exclusively owned build file; storage must be trusted.
+ * @param {import('./windows-timestamp.mjs').WindowsTimestampOptions} options Verified hardware signer and credential-free public operations.
+ * @returns {Promise} Resolves only after complete signature, exact normalized bytes and committed-byte verification.
+ */
+export async function completeWindowsSignature(path, options) {
+ const original = await digest(path)
+ const staging = await mkdtemp(join(tmpdir(), 'dsh-sign-'))
+ const extension = extname(path)
+ let publication
+ let completed = false
+ let retained = false
+ try {
+ const raw = join(staging, `raw${extension}`)
+ const normalized = join(staging, `normalized${extension}`)
+ // SignTool does not consistently support extended-length Windows paths.
+ if (normalized.length >= 260) throw new Error('Windows timestamp: temporary SignTool path exceeds MAX_PATH')
+ await copyFile(path, raw)
+ if (await digest(raw) !== original) throw new Error('Windows timestamp: input changed during staging')
+ options.record({ type: 'signature-staging', path, stagedPath: raw })
+ await options.sign(raw)
+ const frozen = await digest(raw)
+ await copyFile(raw, normalized)
+ await options.normalize(normalized)
+ const baseline = await digest(normalized)
+ for (let attempt = 1; attempt <= 3; attempt++) {
+ if (await digest(raw) !== frozen) throw new Error('Windows timestamp: signed input changed')
+ const candidate = join(staging, `attempt-${attempt}${extension}`)
+ await copyFile(raw, candidate)
+ if (await digest(candidate) !== frozen) throw new Error('Windows timestamp: copy changed')
+ options.record({ type: 'timestamp-start', path, attempt })
+ try { await options.timestamp(candidate) }
+ catch (error) {
+ options.record({ type: 'timestamp-failure', path, attempt, code: typeof error.code === 'number' ? error.code : null })
+ if (await digest(raw) !== frozen) throw new Error('Windows timestamp: signed input changed after failure')
+ if (attempt === 3 || ![1, 2].includes(error.code) || error.signal || error.killed) throw error
+ await (options.wait ?? setTimeout)(attempt * 1000)
+ continue
+ }
+ const signature = await options.inspect(candidate)
+ if (signature.status !== 'Valid' || !signature.timestamped || signature.thumbprint?.toUpperCase() !== options.thumbprint.toUpperCase()) {
+ throw new Error('Windows timestamp: completed signature verification failed')
+ }
+ await copyFile(candidate, normalized)
+ await options.normalize(normalized)
+ if (await digest(normalized) !== baseline) throw new Error('Windows timestamp: signing content changed')
+ if (await digest(raw) !== frozen || await digest(path) !== original) throw new Error('Windows timestamp: input changed before publication')
+ const expected = await digest(candidate)
+ publication = await mkdtemp(toNamespacedPath(join(dirname(path), '.complete-signature-')))
+ const ready = join(publication, `ready${extension}`)
+ await copyFile(candidate, ready)
+ if (await digest(ready) !== expected || await digest(path) !== original) throw new Error('Windows timestamp: input changed before publication')
+ await rename(ready, path)
+ if (await digest(path) !== expected) throw new Error('Windows timestamp: committed bytes changed')
+ options.record({ type: 'timestamp-success', path, attempt })
+ completed = true
+ return
+ }
+ } catch (error) {
+ try {
+ const evidence = await mkdtemp(join(options.evidenceDirectory, 'signature-failure-'))
+ await cp(staging, join(evidence, 'files'), { recursive: true, errorOnExist: true, force: false })
+ options.record({ type: 'signature-failure-evidence', path, directory: evidence })
+ retained = true
+ } catch (evidenceError) {
+ throw new AggregateError([error, evidenceError], 'Windows signature failed and its evidence could not be retained')
+ }
+ throw error
+ } finally {
+ if (publication) await rm(publication, { recursive: true, force: true })
+ // Failure staging remains available if evidence publication or its audit record fails.
+ if (completed || retained) await rm(staging, { recursive: true, force: true })
+ }
+}
diff --git a/apps/desktop/src/main.ts b/apps/desktop/src/main.ts
index c57865e434..5c21833b0e 100644
--- a/apps/desktop/src/main.ts
+++ b/apps/desktop/src/main.ts
@@ -397,6 +397,9 @@ async function main(): Promise {
protocol.handle(SCHEME, (request) => {
const url = new URL(request.url)
+ // Serves shell URLs declared in update-dialog.ts and mandatory-update-window.ts plus their renderer assets.
+ // Removing this route leaves those modal windows empty while their parent remains blocked.
+ if (url.hostname === 'shell') return serveWebDocument(request, join(app.getAppPath(), 'renderer'))
if (url.hostname === 'app') {
if (url.pathname === '/' || url.pathname === '/index.html' || url.pathname.startsWith('/assets/')
|| ['/favicon.svg', '/manifest.webmanifest'].includes(url.pathname)) {
@@ -407,7 +410,6 @@ async function main(): Promise {
}
return forwardWebRequest(request, hostUrl, hostCookie)
}
- if (url.hostname === 'shell') return serveWebDocument(request, join(app.getAppPath(), 'renderer'))
return Promise.resolve(new Response(null, { status: 404 }))
})
@@ -708,7 +710,7 @@ async function main(): Promise {
if (quitting) return
event.preventDefault()
quitting = true
- mainWindow?.hide()
+ if (mainWindow !== undefined && !mainWindow.isDestroyed()) mainWindow.hide()
updateSchedule.dispose()
updateDialog.dispose()
mandatoryUI?.dispose()
diff --git a/apps/desktop/src/mandatory-update-window.ts b/apps/desktop/src/mandatory-update-window.ts
index 2705eeb3fb..a3ca6bcf8f 100644
--- a/apps/desktop/src/mandatory-update-window.ts
+++ b/apps/desktop/src/mandatory-update-window.ts
@@ -43,6 +43,7 @@ export interface MandatoryUpdateWindowOptions {
readonly install: (version: string) => Promise
}
+// main.ts's protocol.handle shell route serves this document and its renderer assets; the modal requires that route.
const page = 'dsh-app://shell/mandatory-update.html'
/** A modal child blocks the product window without cancelling work in the Host. */
diff --git a/apps/desktop/src/update-dialog.ts b/apps/desktop/src/update-dialog.ts
index 6ba2fc269a..f48f70d075 100644
--- a/apps/desktop/src/update-dialog.ts
+++ b/apps/desktop/src/update-dialog.ts
@@ -30,6 +30,7 @@ export interface UpdateDialogApi {
respond(index: number): Promise
}
+// main.ts's protocol.handle shell route serves this document and its renderer assets; the modal requires that route.
const page = 'dsh-app://shell/update-dialog.html'
/** One replaceable confirmation window; aborted checks and mandatory policy cancel ordinary prompts. */
diff --git a/apps/desktop/tests/fixtures/runtime-payload-smoke.mjs b/apps/desktop/tests/fixtures/runtime-payload-smoke.mjs
index a069118006..41f6b4223b 100644
--- a/apps/desktop/tests/fixtures/runtime-payload-smoke.mjs
+++ b/apps/desktop/tests/fixtures/runtime-payload-smoke.mjs
@@ -15,14 +15,16 @@ const descriptor = JSON.parse(readFileSync(join(root, 'desktop-runtime.json'), '
assert.equal(process.versions.node, descriptor.release.nodeVersion, 'Run with the Electron Node runtime version')
assert.equal(process.platform, descriptor.platform)
assert.equal(process.arch, descriptor.arch)
+const resourcesRuntime = process.argv[3] ?? join(dirname(root), 'runtime')
+const { verifyDesktopRuntime } = await import('../../lib/types/runtime-tree.js')
+await verifyDesktopRuntime(root, descriptor.release.version, { platform: process.platform, arch: process.arch })
const requireRuntime = createRequire(join(root, 'package.json'))
const scratch = mkdtempSync(join(tmpdir(), 'dsh-runtime-payload-'))
/** Run a package script with only the shipped node launcher available on PATH. */
function checkPnpm() {
- const resources = dirname(root)
- const bin = join(resources, 'runtime', 'bin')
- const pnpm = join(resources, 'runtime', 'pnpm', 'bin', 'pnpm.mjs')
+ const bin = join(resourcesRuntime, 'bin')
+ const pnpm = join(resourcesRuntime, 'pnpm', 'bin', 'pnpm.mjs')
writeFileSync(join(scratch, 'package.json'), JSON.stringify({
name: 'desktop-node-script-smoke', private: true, scripts: { check: 'node check.cjs' },
}))
@@ -54,7 +56,7 @@ async function checkPty() {
)))
Object.assign(env, { HOME: scratch, USERPROFILE: scratch, TMP: scratch, TEMP: scratch, TMPDIR: scratch })
env.DSH_DESKTOP_NODE_EXECUTABLE = process.execPath
- env.PATH = `${join(dirname(root), 'runtime', 'bin')}${delimiter}${env.PATH ?? env.Path ?? ''}`
+ env.PATH = `${join(resourcesRuntime, 'bin')}${delimiter}${env.PATH ?? env.Path ?? ''}`
// A Windows GUI executable needs a console-owning shell when launched inside ConPTY.
const executable = process.platform === 'win32' ? process.env.ComSpec : process.execPath
const args = process.platform === 'win32' ? ['/d', '/c', 'node', script] : [script]
@@ -137,6 +139,8 @@ function checkHtml() {
}
try {
+ const builtin = requireRuntime('node-addon-require-builtin')
+ assert.equal(typeof builtin.requireBuiltin('internal/modules/esm/loader').getOrInitializeCascadedLoader, 'function')
checkPnpm()
checkKoffi()
await checkSharp()
diff --git a/apps/desktop/tests/main-startup.spec.ts b/apps/desktop/tests/main-startup.spec.ts
index 93f7abb0b8..3910bacd2a 100644
--- a/apps/desktop/tests/main-startup.spec.ts
+++ b/apps/desktop/tests/main-startup.spec.ts
@@ -145,6 +145,7 @@ const harness = await vi.hoisted(async () => {
set publishUpdate(value: (state: DesktopUpdateState) => DesktopUpdateState) { publishUpdate = value },
dialog: { showOpenDialog: vi.fn(), showErrorBox: vi.fn(), showMessageBox: vi.fn() },
openExternal: vi.fn(),
+ protocolHandle: vi.fn<(scheme: string, handler: (request: Request) => Response | Promise) => void>(),
applyRelease: vi.fn(() => { preparing.resolve(); return prepared.promise }),
disableAllPlugins: vi.fn(async () => {
pluginsEnabled = false
@@ -207,7 +208,7 @@ vi.mock('electron', () => ({
},
Menu: { setApplicationMenu: harness.menu.setApplicationMenu, buildFromTemplate: harness.menu },
session: { defaultSession: { webRequest: { onBeforeSendHeaders: harness.socketHeaders } } },
- protocol: { registerSchemesAsPrivileged: vi.fn(), handle: vi.fn() },
+ protocol: { registerSchemesAsPrivileged: vi.fn(), handle: harness.protocolHandle },
powerMonitor: harness.powerMonitor,
}))
vi.mock('node:fs/promises', async (importOriginal) => {
@@ -341,6 +342,19 @@ describe('desktop main startup', () => {
}
})
+ it('serves shell dialogs and their assets without forwarding them to the Host', async () => {
+ await readyForUpdate()
+ const { serveWebDocument, forwardWebRequest } = await import('../src/web-document.ts')
+ const handler = harness.protocolHandle.mock.calls[0]![1]
+ for (const file of ['update-dialog.html', 'update-dialog.js', 'update-dialog.css', 'update-close.svg', 'mandatory-update.html']) {
+ const request = new Request(`dsh-app://shell/${file}`)
+ await handler(request)
+ expect(serveWebDocument).toHaveBeenLastCalledWith(request, join('desktop-test-app', 'renderer'))
+ }
+ expect(forwardWebRequest).not.toHaveBeenCalled()
+ expect((await handler(new Request('dsh-app://unknown/update-dialog.html'))).status).toBe(404)
+ })
+
it.each([
['darwin', true, 'en-US'],
['darwin', false, 'zh-CN'],
@@ -751,6 +765,19 @@ describe('desktop main startup', () => {
await harness.quitCompleted.promise
})
+ it('finishes quitting when the native window is destroyed before its closed listener clears ownership', async () => {
+ const host = await readyForUpdate()
+ const window = harness.windows[0]!
+ window.destroyed = true
+ window.hide.mockImplementation(() => { throw new TypeError('Object has been destroyed') })
+ expect(() => { harness.app.quit() }).not.toThrow()
+ expect(window.hide).not.toHaveBeenCalled()
+ await host.stopping.promise
+ window.emit('closed')
+ host.exited.resolve()
+ await harness.quitCompleted.promise
+ })
+
it('shares the failed-check deadline across focus and resume, while explicit checks reset polling', async () => {
vi.stubEnv('DSH_DESKTOP_UPDATE_CHECK_INTERVAL_MS', '1000')
vi.stubEnv('DSH_DESKTOP_UPDATE_CHECK_MAX_BACKOFF_MS', '4000')
diff --git a/apps/desktop/tests/package-target-stages.spec.ts b/apps/desktop/tests/package-target-stages.spec.ts
index 309c446909..6a238f1026 100644
--- a/apps/desktop/tests/package-target-stages.spec.ts
+++ b/apps/desktop/tests/package-target-stages.spec.ts
@@ -31,10 +31,18 @@ it('requires one signing preflight before building, then records only the comple
expect(stages.filter(stage => stage === 'preflight:windows-signing')).toHaveLength(1)
expect(run.run.mock.calls[0]![3]).toMatchObject({ env: { DSH_DESKTOP_WINDOWS_TOKEN_PIN: 'fixture-pin' }, timeoutMs: 60_000 })
expect(run.run.mock.calls[1]![3].env).not.toHaveProperty('DSH_DESKTOP_WINDOWS_TOKEN_PIN')
+ expect(stages.indexOf('run sign:primary-runtime --dsh')).toBeGreaterThan(stages.indexOf('run prepare:dsh --defer-runtime-smoke'))
+ expect(stages.at(-1)).toBe('exec tsx scripts/smoke-packaged-runtime.ts')
+ for (const call of run.run.mock.calls) {
+ if (call[0].startsWith('run prepare:') || call[0].includes('smoke-packaged-runtime')) {
+ expect(call[3].env).not.toHaveProperty('DSH_DESKTOP_WINDOWS_TOKEN_PIN')
+ }
+ }
expect(writeFileSync).toHaveBeenCalledOnce()
})
-it.each(['preflight:windows-signing', 'run build:official', 'run sign:primary-runtime', 'run prepare:dsh',
+it.each(['preflight:windows-signing', 'run build:official', 'run sign:primary-runtime', 'run prepare:dsh --defer-runtime-smoke', 'run sign:primary-runtime --dsh',
+ 'exec tsx scripts/smoke-packaged-runtime.ts',
'exec electron-builder --config electron-builder.config.mjs --win --x64 --publish never'])
('never continues or records a release after %s fails', async (failure) => {
const { run, stages } = supervisor(failure)
@@ -50,6 +58,7 @@ it.each(['--unsigned', '--prepare-only'])('keeps %s hardware-free and creates no
expect(stages[0]).toBe('run build:official')
expect(stages).not.toContain('preflight:windows-signing')
expect(stages).not.toContain('run sign:primary-runtime')
+ expect(stages).not.toContain('run sign:primary-runtime --dsh')
for (const call of run.run.mock.calls) expect(call[3].env).not.toHaveProperty('DSH_DESKTOP_WINDOWS_TOKEN_PIN')
expect(writeFileSync).not.toHaveBeenCalled()
})
diff --git a/apps/desktop/tests/prepared-runtime-smoke.spec.ts b/apps/desktop/tests/prepared-runtime-smoke.spec.ts
new file mode 100644
index 0000000000..2a2644719e
--- /dev/null
+++ b/apps/desktop/tests/prepared-runtime-smoke.spec.ts
@@ -0,0 +1,44 @@
+import { existsSync, mkdtempSync, rmSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { afterEach, expect, it, vi } from 'vitest'
+import { smokePreparedRuntime } from '../scripts/smoke-prepared-runtime.ts'
+import { smokeDesktopRuntime } from '../scripts/smoke-runtime.ts'
+import { verifyDesktopRuntime, writeDesktopRuntime } from '../src/runtime-tree.ts'
+import { runtimeFixture } from './runtime-fixture.ts'
+
+const { payload } = vi.hoisted(() => ({ payload: vi.fn(async (..._args: unknown[]) => ({ stdout: '' })) }))
+vi.mock('node:child_process', async (importOriginal) => {
+ const { promisify } = await import('node:util')
+ return { ...await importOriginal(),
+ execFile: Object.assign(vi.fn(), { [promisify.custom]: payload }) }
+})
+vi.mock('../scripts/smoke-runtime.ts', () => ({ smokeDesktopRuntime: vi.fn(async () => {}) }))
+
+const roots: string[] = []
+const hostArch = Object.getOwnPropertyDescriptor(process, 'arch')!
+afterEach(() => {
+ Object.defineProperty(process, 'arch', hostArch)
+ for (const root of roots.splice(0)) rmSync(root, { recursive: true, force: true })
+ vi.clearAllMocks()
+})
+
+it('smokes an x64 target verified on an arm64 build host without revalidating against the host', async () => {
+ const root = mkdtempSync(join(tmpdir(), 'prepared-runtime-target-'))
+ roots.push(root)
+ const fixture = runtimeFixture(root)
+ const target = { platform: 'darwin' as const, arch: 'x64' }
+ writeDesktopRuntime(root, fixture.release, fixture.sharedPackages.map(entry => entry.name), target)
+ Object.defineProperty(process, 'arch', { ...hostArch, value: 'arm64' })
+ await expect(verifyDesktopRuntime(root, fixture.release.version, { ...target, arch: process.arch }))
+ .rejects.toThrow(/incompatible/u)
+ const descriptor = await verifyDesktopRuntime(root, fixture.release.version, target)
+ const electron = join(root, 'target-electron')
+ const resources = join(root, 'runtime')
+ await smokePreparedRuntime(root, electron, resources, descriptor)
+ expect(payload.mock.calls[0]![0]).toBe(electron)
+ expect(payload.mock.calls[0]![1]).toEqual(expect.arrayContaining([root, resources]))
+ expect(smokeDesktopRuntime).toHaveBeenCalledWith(root, electron, descriptor, expect.any(Object), resources)
+ const environment = vi.mocked(smokeDesktopRuntime).mock.calls[0]![3]
+ expect(existsSync(environment.NARB_NATIVE_CACHE_DIR!)).toBe(false)
+})
diff --git a/apps/desktop/tests/primary-runtime-signing.spec.ts b/apps/desktop/tests/primary-runtime-signing.spec.ts
index 56381f4aa6..242c93f339 100644
--- a/apps/desktop/tests/primary-runtime-signing.spec.ts
+++ b/apps/desktop/tests/primary-runtime-signing.spec.ts
@@ -2,8 +2,10 @@ import { mkdtemp, mkdir, readFile, realpath, rm, symlink, writeFile } from 'node
import { tmpdir } from 'node:os'
import { join } from 'node:path'
import { afterEach, expect, it, vi } from 'vitest'
-import { signWindowsPrimaryRuntime, windowsRuntimeCode } from '../scripts/sign-primary-runtime.ts'
-import { inspectWindowsRuntimeSignature, preserveWindowsRuntimeSignature } from '../scripts/windows-runtime-signature.mjs'
+import { signWindowsPrimaryRuntime, signWindowsDesktopRuntime } from '../scripts/sign-primary-runtime.ts'
+import { inspectWindowsRuntimeSignature, preserveWindowsRuntimeSignature, windowsRuntimeCode, verifyWindowsCode, signWindowsCode } from '../scripts/windows-runtime-signature.mjs'
+import { runtimeFixture } from './runtime-fixture.ts'
+import { verifyDesktopRuntime } from '../src/runtime-tree.ts'
import { createPackagingRun } from '../scripts/packaging-run.mjs'
const roots: string[] = []
@@ -25,11 +27,11 @@ async function fixture(names = ['a.exe', 'b.pyd', 'vendor.dll']): Promise { for (const root of roots.splice(0)) await rm(root, { recursive: true, force: true }) })
it('selects real PE code, including .node, without signing foreign native modules or data', async () => {
- const root = await fixture(['runtime.node', 'python.exe'])
+ const root = await fixture(['runtime.node', 'python.exe', 'extensionless', 'custom.binary'])
await mkdir(join(root, 'nested'))
await writeFile(join(root, 'nested', 'foreign.node'), Buffer.from([0x7f, 0x45, 0x4c, 0x46]))
await writeFile(join(root, 'readme.txt'), 'text')
- expect(await windowsRuntimeCode(root)).toEqual([join(root, 'python.exe'), join(root, 'runtime.node')].sort())
+ expect(await windowsRuntimeCode(root)).toEqual(['python.exe', 'runtime.node', 'extensionless', 'custom.binary'].map(name => join(root, name)).sort())
})
it('refuses malformed executables and root or nested directory links', async () => {
@@ -150,3 +152,60 @@ it('preserves only identical, valid runtime copies and records verification with
await writeFile(join(sourceRoot, 'linked', 'python.exe'), await readFile(join(sourceRoot, 'python.exe')))
await expect(preserveWindowsRuntimeSignature(join(destinationRoot, 'linked', 'python.exe'), options)).rejects.toThrow('linked copy')
})
+
+it('rejects a newly added unsigned dependency in the final artifact audit', async () => {
+ const root = await fixture(['new-dependency.node', 'vendor.dll'])
+ await expect(verifyWindowsCode(root, async path => path.endsWith('.node') ? unsigned : valid)).rejects.toThrow('NotSigned')
+ await expect(verifyWindowsCode(root, async () => valid)).resolves.toBeUndefined()
+})
+
+it('records signed dependency bytes before smoke and rejects changes after smoke', async () => {
+ const root = await fixture(['dependency.node'])
+ runtimeFixture(root)
+ let signed = false
+ const options = { thumbprint, record: () => {},
+ inspect: async () => signed ? valid : unsigned,
+ sign: async ({ path }: { path: string }) => {
+ await writeFile(path, Buffer.concat([await readFile(path), Buffer.from('signature')]))
+ signed = true
+ },
+ smoke: vi.fn(async () => { await verifyDesktopRuntime(root, '1.0.0') }),
+ }
+ await signWindowsDesktopRuntime(root, '1.0.0', options)
+ expect(options.smoke).toHaveBeenCalledOnce()
+ await expect(signWindowsDesktopRuntime(root, '1.0.0', { ...options,
+ smoke: async () => { await writeFile(join(root, 'dependency.node'), 'mutated') },
+ })).rejects.toThrow('integrity')
+})
+
+it('bounds public-key inspection to four files and drains a failed batch before returning', async () => {
+ const root = await fixture(['a.node', 'b.node', 'c.node', 'd.node', 'e.node'])
+ const started = Promise.withResolvers()
+ const finish = Promise.withResolvers()
+ let active = 0
+ let maximum = 0
+ const calls: string[] = []
+ const inspect = async (path: string) => {
+ calls.push(path)
+ active += 1
+ maximum = Math.max(maximum, active)
+ if (active === 4) started.resolve(undefined)
+ try {
+ await finish.promise
+ if (path.endsWith('a.node')) throw new Error('inspection failed')
+ return unsigned
+ } finally { active -= 1 }
+ }
+ const sign = vi.fn()
+ const pending = signWindowsCode(root, { thumbprint, inspect, sign, record: () => {} })
+ const rejected = expect(pending).rejects.toThrow('inspection failed')
+ try {
+ await started.promise
+ expect(calls).toHaveLength(4)
+ expect(sign).not.toHaveBeenCalled()
+ } finally { finish.resolve(undefined); await rejected }
+ expect(maximum).toBe(4)
+ expect(active).toBe(0)
+ expect(calls).toHaveLength(4)
+ expect(sign).not.toHaveBeenCalled()
+})
diff --git a/apps/desktop/tests/runtime-manifests.spec.ts b/apps/desktop/tests/runtime-manifests.spec.ts
new file mode 100644
index 0000000000..beb778c0df
--- /dev/null
+++ b/apps/desktop/tests/runtime-manifests.spec.ts
@@ -0,0 +1,27 @@
+import { mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { expect, it } from 'vitest'
+import { prepareRuntimeManifests } from '../scripts/prepare-runtime-manifests.ts'
+import { verifyDesktopRuntime, writeDesktopRuntime } from '../src/runtime-tree.ts'
+import { runtimeFixture } from './runtime-fixture.ts'
+
+it('seals dependency metadata that remains unchanged by archive preparation', async () => {
+ const root = mkdtempSync(join(tmpdir(), 'runtime-manifests-'))
+ const fixture = runtimeFixture(root)
+ try {
+ const directory = join(root, 'node_modules/example/node_modules/nested')
+ mkdirSync(directory, { recursive: true })
+ const manifest = join(directory, 'package.json')
+ writeFileSync(manifest, JSON.stringify({ name: 'nested', version: '1.0.0',
+ scripts: { test: 'vitest' }, keywords: ['example'], bugs: 'https://example.com',
+ main: 'index.js', dependencies: { runtime: '1.0.0' } }))
+ await expect(verifyDesktopRuntime(root, fixture.release.version)).rejects.toThrow('integrity')
+ await prepareRuntimeManifests(root)
+ expect(JSON.parse(readFileSync(manifest, 'utf8'))).toEqual({ name: 'nested', version: '1.0.0',
+ main: 'index.js', dependencies: { runtime: '1.0.0' } })
+ writeDesktopRuntime(root, fixture.release, fixture.sharedPackages.map(entry => entry.name))
+ await prepareRuntimeManifests(root)
+ await verifyDesktopRuntime(root, fixture.release.version)
+ } finally { rmSync(root, { recursive: true, force: true }) }
+})
diff --git a/apps/desktop/tests/windows-asar-unpack.spec.ts b/apps/desktop/tests/windows-asar-unpack.spec.ts
new file mode 100644
index 0000000000..fc45a38ef9
--- /dev/null
+++ b/apps/desktop/tests/windows-asar-unpack.spec.ts
@@ -0,0 +1,185 @@
+import { lstat, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import type { Stats } from 'node:fs'
+import { Arch, Packager, type BeforePackContext, type Configuration } from 'app-builder-lib'
+import { WinPackager } from 'app-builder-lib/out/winPackager.js'
+import { getFileMatchers } from 'app-builder-lib/out/fileMatcher.js'
+import { readAsar } from 'app-builder-lib/out/asar/asar.js'
+import { afterEach, expect, it, vi } from 'vitest'
+import { prepareWindowsAsarUnpack, verifyWindowsAsarUnpack } from '../scripts/windows-asar-unpack.mjs'
+import { createElectronBuilderConfig } from '../scripts/electron-builder-config.mjs'
+
+vi.mock('../scripts/windows-sign.mjs', async importOriginal => ({
+ ...await importOriginal(),
+ createWindowsTokenSigner: () => async () => {},
+ installWindowsNsisBootstrapSigner: () => {},
+ resolveWindowsUpdatePublisher: () => 'Fixture Publisher',
+}))
+vi.mock('../scripts/windows-runtime-signature.mjs', async importOriginal => ({
+ ...await importOriginal(),
+ signWindowsCode: async () => {},
+}))
+// Vite's root-relative IDs also resolve mocked build outputs on a clean checkout.
+vi.mock('/apps/desktop/lib/types/runtime-tree.js', () => ({ verifyDesktopRuntime: async () => {} }))
+vi.mock('/apps/desktop/lib/types/mandatory-update-policy.js', async () => import('../src/mandatory-update-policy.ts'))
+vi.mock('node:crypto', async importOriginal => ({
+ ...await importOriginal(),
+ X509Certificate: class { fingerprint = 'AA:BB' },
+}))
+
+const require = createRequire(import.meta.url)
+// The locked builder omits declarations for its AsarPackager implementation.
+const { AsarPackager } = require('app-builder-lib/out/asar/asarUtil.js') as {
+ AsarPackager: new (packager: object, configuration: object) => {
+ pack(files: { src: string; destination: string; files: string[]; metadata: Map }[]): Promise
+ }
+}
+const roots: string[] = []
+const cleanups: (() => Promise)[] = []
+afterEach(async () => {
+ for (const cleanup of cleanups.splice(0)) await cleanup()
+ for (const root of roots.splice(0)) await rm(root, { recursive: true, force: true })
+})
+
+async function fixture(external: boolean) {
+ const root = await mkdtemp(join(tmpdir(), 'windows-asar-'))
+ roots.push(root)
+ const appDir = join(root, 'app')
+ const source = external ? join(root, 'private', 'dsh') : join(appDir, '.desktop-build', 'dsh')
+ const resources = join(root, 'output', 'resources')
+ await mkdir(resources, { recursive: true })
+ await mkdir(appDir, { recursive: true })
+ const pe = Buffer.alloc(128)
+ pe.writeUInt16LE(0x5a4d, 0)
+ pe.writeUInt32LE(64, 0x3c)
+ pe.writeUInt32LE(0x4550, 64)
+ const names = ['extensionless', 'custom.binary', 'native.node', 'a[0]{x,y}+(z)@!#.binary', '${arch}.binary']
+ for (const name of names) {
+ const file = join(source, 'node_modules', 'foo', name)
+ await mkdir(dirname(file), { recursive: true })
+ await writeFile(file, pe)
+ }
+ await writeFile(join(source, 'node_modules', 'foo', 'companion.json'), '{}')
+ await writeFile(join(source, 'node_modules', 'foo', '$xarchy.binary'), 'neighbor')
+ const config = {
+ files: [{ from: source, to: 'dsh', filter: ['**/*'] },
+ { from: join(source, 'node_modules'), to: 'dsh/node_modules', filter: ['**/*'] }],
+ asarUnpack: ['**/*.node'],
+ } satisfies Configuration
+ const info = new Packager({ projectDir: appDir })
+ Object.defineProperties(info, {
+ appDir: { value: appDir }, config: { value: config },
+ metadata: { value: { name: 'fixture', version: '1.0.0', description: 'Fixture' } },
+ framework: { value: { name: 'electron' } },
+ })
+ vi.spyOn(info, 'disposeOnBuildFinish').mockImplementation((cleanup) => { cleanups.push(cleanup) })
+ const context: BeforePackContext = { packager: new WinPackager(info), arch: Arch.x64,
+ appOutDir: dirname(resources), outDir: dirname(resources), electronPlatformName: 'win32', targets: [] }
+ return { root, appDir, source, resources, config, context, names }
+}
+
+async function packageFixture(input: Awaited>) {
+ const destination = join(input.resources, 'app')
+ const matchers = getFileMatchers(input.config, 'asarUnpack', destination, {
+ defaultSrc: input.appDir, globalOutDir: dirname(input.resources), customBuildOptions: {},
+ macroExpander: value => value.replaceAll('${arch}', 'x64'),
+ })!
+ const mapping = input.config.files[0]!
+ if (typeof mapping === 'string' || mapping.from === undefined) throw new Error('missing source mapping')
+ const files: string[] = []
+ const metadata = new Map()
+ async function visit(directory: string): Promise {
+ for (const name of await readdir(directory)) {
+ const file = join(directory, name)
+ const stat = await lstat(file)
+ if (stat.isDirectory()) await visit(file)
+ else { files.push(file); metadata.set(file, stat) }
+ }
+ }
+ await visit(mapping.from)
+ await new AsarPackager({ info: { getWorkspaceRoot: async () => input.root } }, {
+ defaultDestination: destination, resourcePath: input.resources, options: {}, unpackPattern: matchers[0]!.createFilter(),
+ }).pack([{ src: mapping.from, destination: join(destination, 'dsh'), files, metadata }])
+}
+
+it.each([false, true])('unpacks PE files through builder source patterns (external=%s)', async (external) => {
+ const input = await fixture(external)
+ const files = await prepareWindowsAsarUnpack(input.context, input.source)
+ await packageFixture(input)
+ await verifyWindowsAsarUnpack(input.source, input.resources, files)
+ const archive = await readAsar(join(input.resources, 'app.asar'))
+ expect(archive.getFile(join('dsh', 'node_modules', 'foo', 'companion.json')).unpacked).not.toBe(true)
+ expect(archive.getFile(join('dsh', 'node_modules', 'foo', '$xarchy.binary')).unpacked).toBe(true)
+ expect(files).toEqual(input.names.map(name => join('node_modules', 'foo', name)).sort())
+ const first = input.config.files[0]!
+ const nested = input.config.files[1]!
+ if (typeof first === 'string' || typeof nested === 'string') throw new Error('missing source mappings')
+ expect(first.from === input.source).toBe(!external)
+ expect(nested.from).toBe(join(first.from, 'node_modules'))
+ expect(cleanups.length).toBe(external ? 1 : 0)
+ if (external) {
+ await cleanups.pop()!()
+ await expect(lstat(first.from)).rejects.toMatchObject({ code: 'ENOENT' })
+ expect(await readFile(join(input.source, files[0]!))).toHaveLength(128)
+ }
+})
+
+it('rejects an inline PE even when a neighboring unpacked copy exists', async () => {
+ const input = await fixture(false)
+ const files = await prepareWindowsAsarUnpack(input.context, input.source)
+ input.config.asarUnpack = ['**/*.node']
+ await packageFixture(input)
+ const path = join(input.resources, 'app.asar.unpacked', 'dsh', files[0]!)
+ await mkdir(dirname(path), { recursive: true })
+ await writeFile(path, await readFile(join(input.source, files[0]!)))
+ await expect(verifyWindowsAsarUnpack(input.source, input.resources, files)).rejects.toThrow('PE must be unpacked')
+})
+
+it.each(['changed', 'missing'] as const)('rejects %s unpacked PE bytes', async (state) => {
+ const input = await fixture(false)
+ const files = await prepareWindowsAsarUnpack(input.context, input.source)
+ await packageFixture(input)
+ const path = join(input.resources, 'app.asar.unpacked', 'dsh', files[0]!)
+ if (state === 'changed') await writeFile(path, 'changed')
+ else await rm(path)
+ await expect(verifyWindowsAsarUnpack(input.source, input.resources, files)).rejects.toThrow(state === 'changed' ? 'PE bytes changed' : 'ENOENT')
+})
+
+it('registers external staging cleanup before a configuration rewrite fails', async () => {
+ const input = await fixture(true)
+ const files = input.config.files
+ // The source still passes PE discovery; a destination mapping setter fails after staging is copied.
+ Object.defineProperty(input.config, 'files', { get: () => files, set: () => { throw new Error('configuration rejected') } })
+ await expect(prepareWindowsAsarUnpack(input.context, input.source)).rejects.toThrow('configuration rejected')
+ const staging = await readdir(join(input.appDir, '.desktop-build'))
+ expect(staging).toHaveLength(1)
+ expect(cleanups).toHaveLength(1)
+ await cleanups.pop()!()
+ expect(await readdir(join(input.appDir, '.desktop-build'))).toEqual([])
+})
+
+it.each([true, false])('validates the real builder hook for unsigned=%s', async (unsigned) => {
+ const input = await fixture(true)
+ const certificate = join(input.root, 'certificate.cer')
+ await writeFile(certificate, 'fixture public certificate')
+ const config = createElectronBuilderConfig({
+ DSH_DESKTOP_APP_ID: 'com.example.unpack', DSH_DESKTOP_MANDATORY_UPDATE_TEST_ORIGIN: 'https://policy.example.com',
+ DSH_DESKTOP_TARGET_PLATFORM: 'win32', DSH_DESKTOP_TARGET_ARCH: 'x64', DSH_DESKTOP_UNSIGNED: unsigned ? '1' : '0',
+ DSH_DESKTOP_WINDOWS_CER_FILE: certificate, DOWNLOAD_TEST_ORIGIN: 'https://updates.example.com',
+ }, 'win32', 'x64', input.source)
+ // Qualification replaces files after creating the base configuration; builder owns a separate config object.
+ input.config.asarUnpack = [...config.asarUnpack]
+ await config.beforePack(input.context)
+ await packageFixture(input)
+ await config.afterPack(input.context)
+ if (!unsigned) await config.afterSign(input.context)
+ const file = join(input.resources, 'app.asar.unpacked', 'dsh', 'node_modules', 'foo', 'custom.binary')
+ await writeFile(file, 'changed after packaging')
+ if (unsigned) await expect(config.afterPack(input.context)).rejects.toThrow('PE bytes changed')
+ else {
+ await config.afterPack(input.context)
+ await expect(config.afterSign(input.context)).rejects.toThrow('PE bytes changed')
+ }
+})
diff --git a/apps/desktop/tests/windows-sign.spec.ts b/apps/desktop/tests/windows-sign.spec.ts
index 367d418d42..8af2036a5f 100644
--- a/apps/desktop/tests/windows-sign.spec.ts
+++ b/apps/desktop/tests/windows-sign.spec.ts
@@ -1,4 +1,5 @@
import { execFile } from 'node:child_process'
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
import { mkdtemp, readFile, rm, writeFile } from 'node:fs/promises'
import { tmpdir } from 'node:os'
import { join, resolve } from 'node:path'
@@ -16,13 +17,23 @@ import {
vi.mock('node:child_process', async (importOriginal) => {
const actual = await importOriginal()
- return { ...actual, execFile: vi.fn() }
+ const { promisify } = await import('node:util')
+ const mock = vi.fn()
+ // Node's execFile promisifier returns both output streams; generic promisify drops stderr.
+ Object.defineProperty(mock, promisify.custom, { value: (...args: unknown[]) => new Promise((resolve, reject) => {
+ mock(...args, (error: Error | null, stdout: string, stderr: string) => {
+ if (error) reject(error)
+ else resolve({ stdout, stderr })
+ })
+ }) })
+ return { ...actual, execFile: mock }
})
vi.mock('node:crypto', async importOriginal => ({
...await importOriginal(),
X509Certificate: class {
readonly ca = false
+ readonly fingerprint = 'A'.repeat(40)
readonly keyUsage = ['1.3.6.1.5.5.7.3.3']
constructor(contents: Buffer) {
@@ -37,6 +48,84 @@ const CERTIFICATE_FILE = 'C:\\release\\server.cer'
const SIGN_SCRIPT = resolve(import.meta.dirname, '../scripts/windows-sign.cmd')
describe('Windows token signing', () => {
+ it.each(['invalid-primary', 'timestamp-exhausted', 'timestamp-recovered', 'normalization-corrupt'] as const)(
+ 'keeps hardware protection separate from %s', async (mode) => {
+ const root = await mkdtemp(join(tmpdir(), 'dsh-sign-completion-'))
+ const certificateFile = join(root, 'server.cer')
+ const signTool = join(root, 'signtool.exe')
+ const path = join(root, 'application.exe')
+ const stateDirectory = join(root, 'state')
+ await writeFile(certificateFile, 'code-signing-certificate-fixture')
+ await writeFile(signTool, 'fixture')
+ await writeFile(path, 'input')
+ const run = createPackagingRun(join(root, 'records'), {})
+ let hardware = 0
+ let timestamps = 0
+ vi.mocked(execFile).mockImplementation((...args: unknown[]) => {
+ const command = args[0] as string
+ const argv = args[1] as string[]
+ const options = args[2] as { env: NodeJS.ProcessEnv }
+ const callback = args.at(-1) as (error: Error | null, stdout?: string, stderr?: string) => void
+ if (argv[0] === '/d') {
+ hardware++
+ expect(existsSync(join(stateDirectory, 'attempt.json'))).toBe(true)
+ writeFileSync(options.env.DSH_DESKTOP_WINDOWS_SIGN_TARGET!, 'signed:input')
+ callback(null, '', '')
+ } else {
+ expect(options.env.DSH_DESKTOP_WINDOWS_TOKEN_PIN).toBeUndefined()
+ expect(options.env.DSH_DESKTOP_WINDOWS_KEY_CONTAINER).toBeUndefined()
+ if (command === 'powershell.exe') {
+ const timestamped = readFileSync(options.env.DSH_RUNTIME_VERIFY_FILE!, 'utf8').endsWith(':timestamp')
+ if (!timestamped) expect(existsSync(join(stateDirectory, 'attempt.json'))).toBe(true)
+ callback(null, JSON.stringify({ status: mode === 'invalid-primary' ? 'NotTrusted' : 'Valid', timestamped, thumbprint: 'A'.repeat(40) }), '')
+ } else if (argv[0] === 'remove') {
+ const target = argv.at(-1)!
+ const content = readFileSync(target, 'utf8')
+ if (mode === 'normalization-corrupt') writeFileSync(target, 'unexpected modification')
+ else writeFileSync(target, content.replace(':timestamp', ''))
+ if (mode === 'normalization-corrupt' || !content.endsWith(':timestamp')) {
+ callback(Object.assign(new Error('normalization warning'), { code: 2 }))
+ } else callback(null, '', '')
+ } else {
+ expect(argv[0]).toBe('timestamp')
+ expect(existsSync(join(stateDirectory, 'attempt.json'))).toBe(false)
+ const target = argv.at(-1)!
+ expect(readFileSync(target, 'utf8')).toBe('signed:input')
+ timestamps++
+ if (mode === 'timestamp-exhausted' || timestamps === 1) {
+ writeFileSync(target, 'failed partial output')
+ callback(Object.assign(new Error('timestamp unavailable'), { code: 1, stderr: 'timestamp unavailable' }))
+ } else {
+ writeFileSync(target, 'signed:input:timestamp')
+ callback(null, '', '')
+ }
+ }
+ }
+ return undefined as unknown as ReturnType
+ })
+ try {
+ const sign = createWindowsTokenSigner({ certificateFile, signTool, tokenPin: 'fixture-pin', keyContainer: 'fixture-container',
+ runDirectory: run.directory, stateDirectory })
+ const task = { path, hash: 'sha256', isNest: false }
+ if (mode === 'timestamp-recovered') {
+ await sign(task)
+ expect(await readFile(path, 'utf8')).toBe('signed:input:timestamp')
+ expect(timestamps).toBe(2)
+ } else {
+ const results = await Promise.allSettled([sign(task), sign(task)])
+ expect(results.map(result => result.status)).toEqual(['rejected', 'rejected'])
+ expect(await readFile(path, 'utf8')).toBe('input')
+ expect(timestamps).toBe(mode === 'timestamp-exhausted' ? 3 : 0)
+ expect(existsSync(join(run.directory, 'fatal.json'))).toBe(true)
+ }
+ expect(hardware).toBe(1)
+ expect(existsSync(join(stateDirectory, 'attempt.json'))).toBe(mode === 'invalid-primary')
+ } finally {
+ vi.mocked(execFile).mockReset()
+ await rm(root, { recursive: true, force: true })
+ }
+ }, 15_000,
+ )
it('preserves verified copies without hardware and rejects the entire queue after preservation failure', async () => {
const directory = await mkdtemp(join(tmpdir(), 'dsh-windows-copy-signature-'))
try {
@@ -147,7 +236,7 @@ describe('Windows token signing', () => {
expect(text).toContain('setlocal DisableDelayedExpansion\r\n')
expect(text).toContain('set "DSH_DESKTOP_WINDOWS_CER_FILE="\r\n')
expect(text).toContain('set "DSH_DESKTOP_WINDOWS_TOKEN_PIN="\r\n')
- expect(text).toContain('"%signTool%" sign /v /fd sha256 /f "%certificateFile%" /kc "[{{%tokenPin%}}]=%keyContainer%" /csp "eToken Base Cryptographic Provider" %appendSignature% /tr http://timestamp.digicert.com /td sha256 "%targetFile%"\r\n')
+ expect(text).toContain('"%signTool%" sign /v /fd sha256 /f "%certificateFile%" /kc "[{{%tokenPin%}}]=%keyContainer%" /csp "eToken Base Cryptographic Provider" %appendSignature% "%targetFile%"\r\n')
})
it('rejects incomplete signing identities and non-SHA-256 signing tasks', async () => {
@@ -197,6 +286,9 @@ describe('Windows token signing', () => {
hash: 'sha1',
isNest: false,
})).rejects.toThrow(/requires SHA-256/u)
+ await expect(createWindowsTokenSigner({ certificateFile, signTool, tokenPin: 'fixture-pin', keyContainer: 'fixture-container' })({
+ path: 'C:\\release\\setup.exe', hash: 'sha256', isNest: true,
+ })).rejects.toThrow('does not support appended signatures')
}
finally {
await rm(directory, { recursive: true })
diff --git a/apps/desktop/tests/windows-signature-batch.spec.ts b/apps/desktop/tests/windows-signature-batch.spec.ts
new file mode 100644
index 0000000000..6e6ebe602f
--- /dev/null
+++ b/apps/desktop/tests/windows-signature-batch.spec.ts
@@ -0,0 +1,50 @@
+/** Parser fault checks; real-file equivalence is measured separately. */
+import { it as test } from 'vitest'
+import assert from 'node:assert/strict'
+import { copyFile, mkdtemp, rm } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { join } from 'node:path'
+import { parseSignatureRows, inspectSignaturesBatched } from '../scripts/windows-signature-batch.mjs'
+import { inspectWindowsRuntimeSignature, signWindowsCode, verifyWindowsCode } from '../scripts/windows-runtime-signature.mjs'
+
+const files = ['one.node', 'two.dll']
+const rows = files.map(path => ({ path, status: 'Valid', timestamped: true, thumbprint: 'A'.repeat(40) }))
+const output = (input: readonly unknown[]): string => input.map(value => JSON.stringify(value)).join('\n')
+
+test('each row retains its own signature status', () => {
+ const input = [rows[0], { ...rows[1], status: 'NotSigned', timestamped: false, thumbprint: null }]
+ const result = parseSignatureRows(output(input), '', files)
+ assert.deepEqual(result.map(signature => signature.status), ['Valid', 'NotSigned'])
+})
+
+for (const [name, input] of [
+ ['missing', [rows[0]]], ['duplicate', [rows[0], rows[0]]], ['reordered', [...rows].reverse()],
+ ['extra', [...rows, rows[0]]], ['null', [rows[0], null]],
+ ['bad timestamp', [rows[0], { ...rows[1], timestamped: 'true' }]],
+ ['bad certificate', [rows[0], { ...rows[1], thumbprint: 'wrong' }]],
+] as const) test(`${name} output is rejected`, () => {
+ assert.throws(() => parseSignatureRows(output(input), '', files))
+})
+
+test('stderr rejects otherwise complete output', () => {
+ assert.throws(() => parseSignatureRows(output(rows), 'warning', files))
+})
+test('empty input launches no verifier and returns no rows', async () => {
+ assert.deepEqual(await inspectSignaturesBatched([]), [])
+})
+
+test.skipIf(process.platform !== 'win32')('Unicode paths retain the same Windows trust result as individual inspection', async (t) => {
+ const root = await mkdtemp(join(tmpdir(), 'signature-batch-'))
+ t.onTestFinished(() => rm(root, { recursive: true, force: true }))
+ const path = join(root, "验证 ' 文件.exe")
+ await copyFile(join(process.env.SystemRoot!, 'System32', 'cmd.exe'), path)
+ const expected = await inspectWindowsRuntimeSignature(path)
+ assert.equal(expected.status, 'Valid')
+ assert.deepEqual(await inspectSignaturesBatched([path]), [expected])
+ await signWindowsCode(root, {
+ thumbprint: 'A'.repeat(40),
+ sign: async () => { throw new Error('vendor-signed files must not access signing hardware') },
+ record: () => {},
+ })
+ await verifyWindowsCode(root)
+})
diff --git a/apps/desktop/tests/windows-signature-cache.spec.ts b/apps/desktop/tests/windows-signature-cache.spec.ts
new file mode 100644
index 0000000000..d1794a66e0
--- /dev/null
+++ b/apps/desktop/tests/windows-signature-cache.spec.ts
@@ -0,0 +1,168 @@
+/** Fault checks for the exploratory cache; these never call signing hardware. */
+import { it as test, type TestContext } from 'vitest'
+import assert from 'node:assert/strict'
+import { mkdtemp, readFile, readdir, rm, writeFile, mkdir, symlink } from 'node:fs/promises'
+import { join } from 'node:path'
+import { createCachedSigner, signatureCacheIdentity } from '../scripts/windows-signature-cache.mjs'
+
+async function fixture(t: TestContext) {
+ const root = await mkdtemp(join(import.meta.dirname, 'cache-test-'))
+ t.onTestFinished(() => rm(root, { recursive: true, force: true }))
+ const path = join(root, 'module.node')
+ await writeFile(path, 'original')
+ const cache = join(root, 'cache')
+ const state = { hardwareCalls: 0, events: [] as object[] }
+ const thumbprint = 'A'.repeat(40)
+ const options: import('../scripts/windows-signature-cache.mjs').WindowsSignatureCacheOptions = {
+ root: cache, identity: 'test-policy', thumbprint,
+ sign: async ({ path }) => { state.hardwareCalls++; await writeFile(path, `signed:${await readFile(path, 'utf8')}`) },
+ inspect: async path => ({ status: (await readFile(path, 'utf8')).startsWith('signed:') ? 'Valid' : 'NotSigned', timestamped: true, thumbprint }),
+ record: event => state.events.push(event),
+ }
+ const request = { path, hash: 'sha256', isNest: false }
+ return { root, path, cache, state, options, request }
+}
+
+test('unchanged bytes restored in another file avoid another hardware call', async (t) => {
+ const f = await fixture(t)
+ await createCachedSigner(f.options)(f.request)
+ const second = join(f.root, 'other.node')
+ await writeFile(second, 'original')
+ await createCachedSigner(f.options)({ ...f.request, path: second })
+ assert.equal(f.state.hardwareCalls, 1)
+ assert.equal(await readFile(second, 'utf8'), 'signed:original')
+ assert.equal(f.state.events.filter(e => 'type' in e && e.type === 'signature-cache-hit').length, 1)
+})
+
+test('restores cached signatures into deeply nested dependency paths', async (t) => {
+ const f = await fixture(t)
+ await createCachedSigner(f.options)(f.request)
+ const directory = join(f.root, 'dependency'.repeat(12))
+ await mkdir(directory)
+ const path = join(directory, 'module.node')
+ await writeFile(path, 'original')
+ await createCachedSigner(f.options)({ ...f.request, path })
+ assert.equal(await readFile(path, 'utf8'), 'signed:original')
+ assert.equal(f.state.hardwareCalls, 1)
+ assert.deepEqual(await readdir(directory), ['module.node'])
+})
+
+test('different content or signing policy misses the cache', async (t) => {
+ const f = await fixture(t)
+ await createCachedSigner(f.options)(f.request)
+ await writeFile(f.path, 'changed')
+ await createCachedSigner(f.options)(f.request)
+ await writeFile(f.path, 'original')
+ await createCachedSigner({ ...f.options, identity: 'changed-policy' })(f.request)
+ assert.equal(f.state.hardwareCalls, 3)
+})
+
+for (const corrupt of ['payload', 'record.json']) test(`corrupt ${corrupt} stops without signing or replacing the input`, async (t) => {
+ const f = await fixture(t)
+ await createCachedSigner(f.options)(f.request)
+ await writeFile(f.path, 'original')
+ const entry = (await readdir(f.cache)).find(name => !name.startsWith('.'))
+ assert(entry)
+ await writeFile(join(f.cache, entry, corrupt), 'corrupt')
+ await assert.rejects(createCachedSigner(f.options)(f.request))
+ assert.equal(f.state.hardwareCalls, 1)
+ assert.equal(await readFile(f.path, 'utf8'), 'original')
+})
+
+for (const signature of [
+ { status: 'NotTrusted', timestamped: true, thumbprint: 'A'.repeat(40) },
+ { status: 'Valid', timestamped: false, thumbprint: 'A'.repeat(40) },
+ { status: 'Valid', timestamped: true, thumbprint: 'B'.repeat(40) },
+]) test(`cache refuses signature ${JSON.stringify(signature)}`, async (t) => {
+ const f = await fixture(t)
+ await createCachedSigner(f.options)(f.request)
+ await writeFile(f.path, 'original')
+ await assert.rejects(createCachedSigner({ ...f.options, inspect: async () => signature })(f.request), /invalid cached signature/u)
+ assert.equal(f.state.hardwareCalls, 1)
+ assert.equal(await readFile(f.path, 'utf8'), 'original')
+})
+
+test('hardware failure rejects queued work without publishing an entry or retrying', async (t) => {
+ const f = await fixture(t)
+ const signer = createCachedSigner({ ...f.options, sign: async () => { f.state.hardwareCalls++; throw new Error('hardware failed') } })
+ const results = await Promise.allSettled([signer(f.request), signer(f.request)])
+ assert(results.every(result => result.status === 'rejected'))
+ assert.equal(f.state.hardwareCalls, 1)
+ assert.deepEqual(await readdir(f.cache), [])
+})
+
+test('a failed new signature verification never publishes a cache entry', async (t) => {
+ const f = await fixture(t)
+ await assert.rejects(createCachedSigner({ ...f.options, inspect: async () => ({ status: 'NotTrusted', timestamped: false, thumbprint: null }) })(f.request), /new signature verification failed/u)
+ assert.deepEqual(await readdir(f.cache), [])
+})
+
+test('an incomplete entry is rejected without hardware access', async (t) => {
+ const f = await fixture(t)
+ await createCachedSigner(f.options)(f.request)
+ const entry = (await readdir(f.cache))[0]
+ assert(entry)
+ await rm(join(f.cache, entry, 'record.json'))
+ await writeFile(f.path, 'original')
+ await assert.rejects(createCachedSigner(f.options)(f.request))
+ assert.equal(f.state.hardwareCalls, 1)
+})
+
+test('certificate and toolchain content invalidate policy identity independently of paths', async (t) => {
+ const f = await fixture(t)
+ const certificate = join(f.root, 'certificate.cer')
+ const command = join(f.root, 'sign.cmd')
+ await writeFile(certificate, 'certificate A')
+ await writeFile(command, 'signing policy A')
+ const first = await signatureCacheIdentity([certificate, command])
+ const relocated = join(f.root, 'relocated.cer')
+ await writeFile(relocated, 'certificate A')
+ assert.equal(await signatureCacheIdentity([relocated, command]), first)
+ await writeFile(certificate, 'certificate B')
+ assert.notEqual(await signatureCacheIdentity([certificate, command]), first)
+ await writeFile(command, 'signing policy B')
+ assert.notEqual(await signatureCacheIdentity([relocated, command]), first)
+})
+
+test('two writers publish one complete entry without overwriting another writer', async (t) => {
+ const f = await fixture(t)
+ const second = join(f.root, 'second.node')
+ await writeFile(second, 'original')
+ const entered = Promise.withResolvers()
+ let arrivals = 0
+ const options: import('../scripts/windows-signature-cache.mjs').WindowsSignatureCacheOptions = { ...f.options, sign: async (request) => {
+ if (++arrivals === 2) entered.resolve(undefined)
+ await entered.promise
+ await f.options.sign(request)
+ } }
+ const results = await Promise.allSettled([
+ createCachedSigner(options)(f.request),
+ createCachedSigner(options)({ ...f.request, path: second }),
+ ])
+ for (const result of results) if (result.status === 'rejected') throw result.reason
+ assert.equal((await readdir(f.cache)).length, 1)
+ await writeFile(f.path, 'original')
+ await createCachedSigner(f.options)(f.request)
+ assert.equal(f.state.hardwareCalls, 2)
+ assert.equal(await readFile(f.path, 'utf8'), 'signed:original')
+})
+
+test('linked cache directories cannot redirect cache restoration', async (t) => {
+ const f = await fixture(t)
+ const elsewhere = join(f.root, 'elsewhere')
+ await mkdir(elsewhere)
+ await symlink(elsewhere, f.cache, process.platform === 'win32' ? 'junction' : 'dir')
+ await assert.rejects(createCachedSigner(f.options)(f.request), /unlinked directory/u)
+ assert.equal(f.state.hardwareCalls, 0)
+})
+
+test('a target changed during verification is never replaced with stale cache bytes', async (t) => {
+ const f = await fixture(t)
+ await createCachedSigner(f.options)(f.request)
+ await writeFile(f.path, 'original')
+ const inspect = async (candidate: string) => { await writeFile(f.path, 'new input'); return f.options.inspect(candidate) }
+ await assert.rejects(createCachedSigner({ ...f.options, inspect })(f.request), /target changed/u)
+ assert.equal(await readFile(f.path, 'utf8'), 'new input')
+ assert.equal(f.state.hardwareCalls, 1)
+ assert(!(await readdir(f.root)).some(name => name.startsWith('.signature-restore-')))
+})
diff --git a/apps/desktop/tests/windows-timestamp.spec.ts b/apps/desktop/tests/windows-timestamp.spec.ts
new file mode 100644
index 0000000000..71e1cbc911
--- /dev/null
+++ b/apps/desktop/tests/windows-timestamp.spec.ts
@@ -0,0 +1,139 @@
+/** Timestamp retries use fresh signed inputs and cannot publish partial or substituted files. */
+import { it, expect, type TestContext } from 'vitest'
+import { mkdir, mkdtemp, readFile, readdir, rm, writeFile } from 'node:fs/promises'
+import { tmpdir } from 'node:os'
+import { dirname, join } from 'node:path'
+import { completeWindowsSignature, type WindowsTimestampOptions } from '../scripts/windows-timestamp.mjs'
+
+async function fixture(t: TestContext) {
+ const root = await mkdtemp(join(tmpdir(), 'dsh-timestamp-'))
+ t.onTestFinished(() => rm(root, { recursive: true, force: true }))
+ const path = join(root, 'input.exe')
+ const evidenceDirectory = join(root, 'evidence')
+ await mkdir(evidenceDirectory)
+ await writeFile(path, 'input')
+ const state = { hardware: 0, requests: [] as string[], events: [] as object[] }
+ const options: WindowsTimestampOptions = {
+ evidenceDirectory, thumbprint: 'A'.repeat(40),
+ sign: async (file) => { state.hardware++; await writeFile(file, 'signed:input') },
+ timestamp: async (file) => { state.requests.push(await readFile(file, 'utf8')); await writeFile(file, 'signed:input:timestamp') },
+ normalize: async (file) => { await writeFile(file, (await readFile(file, 'utf8')).replace(':timestamp', '')) },
+ inspect: async file => ({ status: 'Valid', timestamped: (await readFile(file, 'utf8')).endsWith(':timestamp'), thumbprint: 'A'.repeat(40) }),
+ record: (event) => { state.events.push(event) },
+ wait: async () => {},
+ }
+ return { root, path, options, state }
+}
+
+it('a failed timestamp cannot contaminate the next input or repeat hardware signing', async (t) => {
+ const f = await fixture(t)
+ const timestamp = f.options.timestamp
+ let requests = 0
+ f.options.timestamp = async (path) => {
+ if (++requests === 1) {
+ expect(await readFile(path, 'utf8')).toBe('signed:input')
+ await writeFile(path, 'damaged by failed timestamp')
+ throw Object.assign(new Error('timestamp failed'), { code: 1 })
+ }
+ await timestamp(path)
+ }
+ await completeWindowsSignature(f.path, f.options)
+ expect(f.state.hardware).toBe(1)
+ expect(requests).toBe(2)
+ expect(f.state.requests).toEqual(['signed:input'])
+ expect(await readFile(f.path, 'utf8')).toBe('signed:input:timestamp')
+ expect((await readdir(f.root)).filter(name => name.startsWith('.complete-signature-'))).toEqual([])
+})
+
+it('exhausted timestamp attempts retain evidence and leave the original untouched', async (t) => {
+ const f = await fixture(t)
+ let requests = 0
+ f.options.timestamp = async () => { requests++; throw Object.assign(new Error('offline'), { code: 1 }) }
+ await expect(completeWindowsSignature(f.path, f.options)).rejects.toThrow('offline')
+ expect(requests).toBe(3)
+ expect(f.state.hardware).toBe(1)
+ expect(await readFile(f.path, 'utf8')).toBe('input')
+ expect(await readdir(f.options.evidenceDirectory)).toHaveLength(1)
+ expect((await readdir(f.root)).filter(name => name.startsWith('.complete-signature-'))).toEqual([])
+})
+
+it('retains staging when failure evidence cannot be stored', async (t) => {
+ const f = await fixture(t)
+ f.options.evidenceDirectory = f.path
+ let staging = ''
+ f.options.sign = async (path) => { staging = dirname(path); throw new Error('hardware failed') }
+ t.onTestFinished(async () => { if (staging) await rm(staging, { recursive: true, force: true }) })
+ await expect(completeWindowsSignature(f.path, f.options)).rejects.toThrow('evidence could not be retained')
+ expect(await readdir(staging)).toEqual(['raw.exe'])
+ expect(await readFile(f.path, 'utf8')).toBe('input')
+})
+
+it('uses short tool paths for deeply nested targets and publishes the completed bytes', async (t) => {
+ const f = await fixture(t)
+ const directory = join(f.root, 'nested'.repeat(20), 'dependency'.repeat(12))
+ await mkdir(directory, { recursive: true })
+ const path = join(directory, 'native-module.node')
+ await writeFile(path, 'input')
+ function checked(operation: (file: string) => Promise) {
+ return async (file: string) => {
+ expect(file.length).toBeLessThan(260)
+ expect(file.endsWith('.node')).toBe(true)
+ expect(dirname(file)).not.toBe(directory)
+ return operation(file)
+ }
+ }
+ f.options.sign = checked(f.options.sign)
+ f.options.timestamp = checked(f.options.timestamp)
+ f.options.normalize = checked(f.options.normalize)
+ f.options.inspect = checked(f.options.inspect)
+ await completeWindowsSignature(path, f.options)
+ expect(await readFile(path, 'utf8')).toBe('signed:input:timestamp')
+ expect(await readdir(directory)).toEqual(['native-module.node'])
+})
+
+for (const failure of [{ code: 'ENOENT' }, { code: 1, killed: true }, { code: 1, signal: 'SIGTERM' }]) {
+ it(`does not retry uncertain timestamp process failure ${JSON.stringify(failure)}`, async (t) => {
+ const f = await fixture(t)
+ let requests = 0
+ f.options.timestamp = async () => { requests++; throw Object.assign(new Error('process failure'), failure) }
+ await expect(completeWindowsSignature(f.path, f.options)).rejects.toThrow('process failure')
+ expect(requests).toBe(1)
+ expect(await readFile(f.path, 'utf8')).toBe('input')
+ })
+}
+
+for (const signature of [
+ { status: 'Valid', timestamped: false, thumbprint: 'A'.repeat(40) },
+ { status: 'Valid', timestamped: true, thumbprint: 'B'.repeat(40) },
+ { status: 'HashMismatch', timestamped: true, thumbprint: 'A'.repeat(40) },
+]) it(`rejects successful commands with an invalid final signature ${JSON.stringify(signature)}`, async (t) => {
+ const f = await fixture(t)
+ f.options.inspect = async () => signature
+ await expect(completeWindowsSignature(f.path, f.options)).rejects.toThrow('verification failed')
+ expect(f.state.requests).toHaveLength(1)
+ expect(await readFile(f.path, 'utf8')).toBe('input')
+})
+
+it('rejects changed contents even when the substituted file has the expected valid certificate', async (t) => {
+ const f = await fixture(t)
+ f.options.timestamp = async (path) => { await writeFile(path, 'signed:different-input:timestamp') }
+ await expect(completeWindowsSignature(f.path, f.options)).rejects.toThrow('signing content changed')
+ expect(await readFile(f.path, 'utf8')).toBe('input')
+})
+
+it('does not overwrite an input changed while its signature is being completed', async (t) => {
+ const f = await fixture(t)
+ const timestamp = f.options.timestamp
+ f.options.timestamp = async (path) => { await timestamp(path); await writeFile(f.path, 'new input') }
+ await expect(completeWindowsSignature(f.path, f.options)).rejects.toThrow('input changed before publication')
+ expect(await readFile(f.path, 'utf8')).toBe('new input')
+})
+
+it('does not retry hardware failures or request timestamps after them', async (t) => {
+ const f = await fixture(t)
+ f.options.sign = async () => { f.state.hardware++; throw new Error('hardware failed') }
+ await expect(completeWindowsSignature(f.path, f.options)).rejects.toThrow('hardware failed')
+ expect(f.state.hardware).toBe(1)
+ expect(f.state.requests).toHaveLength(0)
+ expect(await readFile(f.path, 'utf8')).toBe('input')
+})
diff --git a/apps/web/tests/access-confirmation.e2e.ts b/apps/web/tests/access-confirmation.e2e.ts
index 2b2ba0e135..b1c57c60e7 100644
--- a/apps/web/tests/access-confirmation.e2e.ts
+++ b/apps/web/tests/access-confirmation.e2e.ts
@@ -73,7 +73,7 @@ describe('web e2e: experimental Auto and Full access confirmation', () => {
const currentMenuBox = await currentMenu.boundingBox()
expect(currentTriggerBox).not.toBeNull()
expect(currentMenuBox).not.toBeNull()
- expect(Math.abs(currentMenuBox!.width - 218)).toBeLessThan(1)
+ expect(Math.abs(currentMenuBox!.width - 144)).toBeLessThan(1)
expect(currentMenuBox!.width).toBeGreaterThan(currentTriggerBox!.width)
expect(Math.abs(currentTriggerBox!.y - currentMenuBox!.y - currentMenuBox!.height - 4)).toBeLessThan(1)
@@ -183,7 +183,7 @@ describe('web e2e: experimental Auto and Full access confirmation', () => {
await menu.waitFor()
await captureAutoReviewState(page, 'experimental-narrow-menu')
const menuBox = (await menu.boundingBox())!
- expect(menuBox.width).toBeGreaterThanOrEqual(218)
+ expect(menuBox.width).toBeGreaterThanOrEqual(144)
expect(menuBox.width).toBeLessThanOrEqual(360)
expect(menuBox.x).toBeGreaterThanOrEqual(0)
expect(menuBox.x + menuBox.width).toBeLessThanOrEqual(420)
diff --git a/apps/web/tests/assembled-remote.ts b/apps/web/tests/assembled-remote.ts
index 23c66da520..2ccb7dcd02 100644
--- a/apps/web/tests/assembled-remote.ts
+++ b/apps/web/tests/assembled-remote.ts
@@ -71,7 +71,14 @@ interface ControlBaseline {
interface CapturedFixture {
readonly sessionList: { readonly ok: true; readonly value: { readonly items: readonly SessionSummary[] } }
- readonly settingsDescribe: unknown
+ readonly settingsDescribe: {
+ readonly ok: true
+ readonly value: {
+ readonly writable: boolean
+ readonly hasDocument: boolean
+ readonly namespaces: readonly unknown[]
+ }
+ }
readonly credentialsDescribe: unknown
readonly modelCatalog: unknown
readonly agentPresets: unknown
@@ -90,6 +97,8 @@ interface CapturedFixture {
}
export interface AssembledRemoteOptions {
+ /** Supply an enabled Host preference for diagnostic View scenarios. */
+ readonly developerTools?: boolean
/** Return the fixture's image-dimension admission error from Session prompt. */
readonly rejectPrompt?: boolean
}
@@ -131,7 +140,16 @@ export function createAssembledRemote(options: AssembledRemoteOptions = {}): Ass
const mock = RemoteMock.create().load(remoteDefaultResponses)
mock.load({
unary: {
- 'settings/describe': structuredClone(fixture.settingsDescribe),
+ 'settings/describe': options.developerTools === true
+ ? ok({
+ ...fixture.settingsDescribe.value,
+ namespaces: [...fixture.settingsDescribe.value.namespaces, {
+ ns: 'ui-developer-tools',
+ schema: { type: 'object', dict: { enabled: { type: 'boolean' } } },
+ value: { enabled: true }, applies: 'live', secrets: [], revision: 0,
+ }],
+ })
+ : structuredClone(fixture.settingsDescribe),
'credentials/describe': structuredClone(fixture.credentialsDescribe),
'session/modelCatalog': structuredClone(fixture.modelCatalog),
'agentPresets/list': structuredClone(fixture.agentPresets),
diff --git a/apps/web/tests/built-boot.expected.e2e.ts b/apps/web/tests/built-boot.expected.e2e.ts
index 17a741dac4..46115eff44 100644
--- a/apps/web/tests/built-boot.expected.e2e.ts
+++ b/apps/web/tests/built-boot.expected.e2e.ts
@@ -91,6 +91,7 @@ it('boots the built plugin graph and renders a fixture session end to end', asyn
expect(waitingRow.querySelector('[data-state="warning"]')).not.toBeNull()
expect(waitingRow.querySelector('[data-state="ongoing"]')).toBeNull()
within(waitingRow).getByText('Waiting for answer')
+ within(waitingRow).getByText('Answer')
// Opening a session reaches chat content through the RemoteMock transport.
fireEvent.click(waitingTitle)
@@ -103,7 +104,12 @@ it('boots the built plugin graph and renders a fixture session end to end', asyn
for (let index = 0; index < 3; index += 1) {
fireEvent.click(await screen.findByRole('button', { name: 'Skip' }))
}
- fireEvent.click(await screen.findByRole('button', { name: 'Allow once' }))
+ const allowOnce = await screen.findByRole('button', { name: 'Allow once' })
+ await waitFor(() => {
+ within(waitingRow).getByText('Waiting for approval')
+ within(waitingRow).getByText('Approval')
+ })
+ fireEvent.click(allowOnce)
// The fixture mirrors all three token-meter projections, so the assembled
// ContextMeter reaches its composition panel instead of only the occupancy
diff --git a/apps/web/tests/changed-files-turn.e2e.ts b/apps/web/tests/changed-files-turn.e2e.ts
index 08045544fc..295c8d65fb 100644
--- a/apps/web/tests/changed-files-turn.e2e.ts
+++ b/apps/web/tests/changed-files-turn.e2e.ts
@@ -51,6 +51,7 @@ describe('web e2e: a git workspace turn ends with its changed files', () => {
await writeFile(replayOverride, JSON.stringify(script).replaceAll('{{cwd}}', JSON.stringify(cwdToken).slice(1, -1)))
}
scaffold = await launchWebScaffold({
+ developerTools: false,
compareReplaySession: true,
extraOverlayPath: fileURLToPath(new URL('./changed-files-turn.overlay.yml', import.meta.url)),
...(replayOverride === undefined ? {} : { replayFixture: FIXTURE, replayOverride }),
@@ -106,6 +107,18 @@ describe('web e2e: a git workspace turn ends with its changed files', () => {
expect(await readFile(join(cwd, 'notes.txt'), 'utf8')).toBe('start\ndone\n')
const card = page.locator('[data-changed-files]')
+ expect(await card.count()).toBe(0)
+ const header = page.locator('header').filter({ has: page.locator('[data-conversation-header-leading]') })
+ expect(await header.getByRole('tablist').count()).toBe(0)
+ const compactHeight = await header.evaluate(element => element.getBoundingClientRect().height)
+ expect(compactHeight).toBeLessThan(60)
+ await page.getByRole('button', { name: '设置', exact: true }).click()
+ const settings = page.getByRole('dialog', { name: '设置' })
+ await settings.getByRole('switch', { name: '开发者工具' }).click()
+ await expect.poll(() => settings.getByRole('switch', { name: '开发者工具' }).getAttribute('aria-checked')).toBe('true')
+ await settings.getByRole('button', { name: '关闭', exact: true }).click()
+ await header.getByRole('tablist').waitFor({ state: 'visible' })
+ expect(await header.evaluate(element => element.getBoundingClientRect().height)).toBeGreaterThan(compactHeight)
await card.waitFor({ state: 'visible' })
expect(await card.getByText('已编辑 4 个文件', { exact: true }).count()).toBe(1)
expect(await card.getByRole('listitem').count()).toBe(3)
diff --git a/apps/web/tests/clickable-links-gallery.e2e.ts b/apps/web/tests/clickable-links-gallery.e2e.ts
index 5f210b0bab..21e4f78bae 100644
--- a/apps/web/tests/clickable-links-gallery.e2e.ts
+++ b/apps/web/tests/clickable-links-gallery.e2e.ts
@@ -436,8 +436,8 @@ describe('web e2e: clickable links gallery', () => {
// globe in the same seat.
const repoLink = markdown.locator(`a[href="${REPO_URL}"]`)
expect(await repoLink.count()).toBe(1)
- const repoMark = await repoLink.locator('svg path').getAttribute('d')
- const globeMark = await guideLink.locator('svg path').getAttribute('d')
+ const repoMark = await repoLink.locator('svg path').first().getAttribute('d')
+ const globeMark = await guideLink.locator('svg path').first().getAttribute('d')
expect(repoMark).not.toBe(globeMark)
await guideLink.hover()
expect(await styleOf(guideLink, 'text-decoration-line')).toBe('underline')
diff --git a/apps/web/tests/developer-tools-settings.e2e.ts b/apps/web/tests/developer-tools-settings.e2e.ts
new file mode 100644
index 0000000000..16c0e6500a
--- /dev/null
+++ b/apps/web/tests/developer-tools-settings.e2e.ts
@@ -0,0 +1,29 @@
+/** Shared settings are off on a fresh Host and survive browser reload through the ordinary settings UI. */
+import { readFile } from 'node:fs/promises'
+import { join } from 'node:path'
+import { chromium } from 'playwright'
+import { expect, it, onTestFinished } from 'vitest'
+import { launchWebScaffold } from './scaffold.ts'
+import { newEnglishPage } from './support.ts'
+
+it('persists developer tools in the Host settings document and restores the accepted choice', async () => {
+ const scaffold = await launchWebScaffold({ developerTools: false })
+ onTestFinished(() => scaffold.close())
+ const browser = await chromium.launch()
+ onTestFinished(() => browser.close())
+ const page = await newEnglishPage(browser)
+ await page.goto(scaffold.authenticatedUrl)
+ await page.getByRole('button', { name: 'Settings', exact: true }).click()
+ const toggle = page.getByRole('switch', { name: 'Developer tools' })
+ expect(await toggle.getAttribute('aria-checked')).toBe('false')
+ expect(await readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8')).not.toContain('ui-developer-tools:')
+ await toggle.click()
+ await expect.poll(() => toggle.getAttribute('aria-checked')).toBe('true')
+ expect(await readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8')).toContain('ui-developer-tools:\n enabled: true')
+ await page.reload()
+ await page.getByRole('button', { name: 'Settings', exact: true }).click()
+ await expect.poll(() => toggle.getAttribute('aria-checked')).toBe('true')
+ await toggle.click()
+ await expect.poll(() => toggle.getAttribute('aria-checked')).toBe('false')
+ expect(await readFile(join(scaffold.harnessHome, 'settings.yaml'), 'utf8')).toContain('ui-developer-tools:\n enabled: false')
+})
diff --git a/apps/web/tests/document-preview.e2e.ts b/apps/web/tests/document-preview.e2e.ts
index 24137b06ad..7e2d43331c 100644
--- a/apps/web/tests/document-preview.e2e.ts
+++ b/apps/web/tests/document-preview.e2e.ts
@@ -86,7 +86,9 @@ describe.skipIf(MODE === 'record')('web e2e: document preview through Files', ()
beforeAll(async () => {
outsideRoot = await mkdtemp(join(tmpdir(), 'dsh-preview-outside-'))
- scaffold = await launchWebScaffold({ replayFixture: FIXTURE, paceMs: 5, compareReplaySession: false, extraOverlayPath: PAGING_PATCH })
+ scaffold = await launchWebScaffold({
+ developerTools: false, replayFixture: FIXTURE, paceMs: 5, compareReplaySession: false, extraOverlayPath: PAGING_PATCH,
+ })
browser = await chromium.launch()
page = await newEnglishPage(browser)
tripwire = watchConsole(page)
@@ -111,17 +113,30 @@ describe.skipIf(MODE === 'record')('web e2e: document preview through Files', ()
await mkdir(SHOT_DIR, { recursive: true })
await saveFailureShot(page, `screenshots/0908-document-preview/smoke-${process.pid}`)
})
+ expect(await page.locator('[data-slot="conversation.hero.agentPreset"] button').count()).toBe(0)
+ expect(scaffold.ctx.settings.get('ui-developer-tools')).toEqual({ enabled: false })
const settled = scaffold.whenTurnSettled()
const input = page.locator('[data-composer-input]').first()
await input.fill(PROMPT)
await input.press('Enter')
const sessionId = await settled
await page.getByText('LIGHTHOUSE', { exact: true }).waitFor({ timeout: 15_000 })
+ expect(await page.getByRole('tablist').count()).toBe(0)
const cwd = scaffold.ctx.agents.get(sessionId)?.session.header.cwd
if (cwd === undefined) throw new Error('settled Session has no workspace cwd')
if (outsideRoot === undefined) throw new Error('outside fixture directory is unavailable')
const outsideScript = join(outsideRoot, 'outside.js')
const outsideReference = relative(cwd, outsideScript).replace(/\\/g, '/')
+ let previewNetworkRequests = 0
+ await page.route('https://preview.invalid/developer-tools.png', async (route) => {
+ previewNetworkRequests += 1
+ await route.fulfill({ status: 200, contentType: 'image/png', body: TINY_PNG })
+ })
+ const blockedRequests: string[] = []
+ await page.route('https://blocked-preview.invalid/**', async (route) => {
+ blockedRequests.push(route.request().url())
+ await route.fulfill({ status: 200, contentType: 'text/html', body: 'ESCAPED' })
+ })
const markdownText = [
'# Markdown smoke', '', 'Rendered from the workspace.', '',
...Array.from({ length: (PAGE_LINES - 4) / 2 }, (_, index) => [`Paragraph ${index + 1}: ${'visible prefix '.repeat(20)}`, '']).flat(),
@@ -132,12 +147,24 @@ describe.skipIf(MODE === 'record')('web e2e: document preview through Files', ()
'const tail = "CODE_TAIL";',
]
await Promise.all([
+ writeFile(join(cwd, 'hostile.html'), `
+
+
+