Merge remote-tracking branch 'origin/master' into worktree/llm-deepseek-messages

.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md
-2026-07-19-gui-web-client-architecture.md: 409c4347bca42dd96fd134e0133a1721fdaebd5d
-2026-07-19-gui-web-client-architecture.zh.md: 58235981471eeb365f7416fcd2e5530468e1e3ff
+2026-07-19-gui-web-client-architecture.md: 55421d1ad6df192d08c431af3633675036a4a857
+2026-07-19-gui-web-client-architecture.zh.md: 6fb3f9a512389710f6708b7f36f42e90eef11b28

.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.md

@@ -44,7 +44,7 @@ Implementation homes: registry core and the props-share types live in `packages/
 
 A service is a plugin's only API toward other plugins (UI components and injection faces are not APIs; a plugin nobody calls mounts no service — ui-trajectory is the minimal-plugin exemplar: no ctx service, only view-slot registrations). The roster: `ctx.connection` (RPC transport + generation state), `ctx.slots` (registry wrapper emitting `slots/changed`, render entry, renderer installation contract), `ctx.sessions` (list store, current-session state, scope tree), `ctx.loader`, `ctx.theme`, `ctx.i18n`, `ctx.layout` (cross-plugin view navigation), `ctx.conversation` (send/cancel/startSession). Viewing state that used to live in service stores (panel widths, selection, drafts) now lives in entry-declared stores per the [slot system standard](2026-07-22-slot-type-chain-implementation.md).
 
-There is no component registration model besides slots — the former view and tool rings both dissolved into it. Conversation views are entries of the `'conversation.view'` list slot ui-conversation declares, tab metadata rides the registration options (`id`/`order`/`label`), and per-view chrome lives inside the view components themselves. Final Chat business Nodes dispatch through the keyed/session `'conversation.chat.node'` slot; ui-tool owns its `tool-call` entry, recursively renders the supplied `subCalls`, and declares the keyed/session `'tool.call.toolview'` child slot. The key space stays runtime-open (SlotMap declares slots, never keys), and roots and descendants dispatch by `entryKey: toolName` with `GenericToolCard` as the fallback. Business packages register atomic views through `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>' }, Row))`; the declaration is the load and reload dependency ([decision](../../archived/architecture/2026-08-05-slot-declaration-injection.md)). ui-conversation separately delegates the selected call's details body through `'conversation.details.tool'`, so ui-tool's card models remain the single presentation owner without making conversation import Tool components. The target-neutral event and view registries are data assembly seams rather than parallel component registries ([decision](2026-08-09-client-conversation-node-assembly.md)).
+There is no component registration model besides slots — the former view and tool rings both dissolved into it. Conversation views are entries of the `'conversation.view'` list slot ui-conversation declares, tab metadata rides the registration options (`id`/`order`/`label`), and per-view chrome lives inside the view components themselves. Final Chat business Nodes dispatch through the keyed/session `'conversation.chat.node'` slot; ui-tool owns its `tool-call` entry, recursively renders the supplied `subCalls`, and declares the keyed/session `'tool.call.toolview'` child slot. The key space stays runtime-open (SlotMap declares slots, never keys), and roots and descendants dispatch by `entryKey: toolName` with `GenericToolCard` as the fallback. Business packages register atomic views through `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>' }, Row))`; the declaration is the load and reload dependency ([decision](../../archived/architecture/2026-08-05-slot-declaration-injection.md)). The right column is the `rightbar` seat ui-sidebar-right fills with one docking surface per session; the former details column and its `'conversation.details.tool'` seat are gone ([decision](../feature/2026-09-04-right-sidebar-docking-infrastructure.md)). The target-neutral event and view registries are data assembly seams rather than parallel component registries ([decision](2026-08-09-client-conversation-node-assembly.md)).
 
 **Scope addressing** mirrors the host's agent-scope idiom: services are root singletons whose methods take no sessionId — they read the caller's scope mark (`scopeOf(ctx)`). Inside a session scope, `ctx.conversation.send('hi', 'queue')` targets that session; cross-session calls re-target by switching ctx (`ctx.sessions.scope(id)!.conversation.send(...)`); calling a scoped method from root ctx throws. Client session scopes are minted like host agent scopes (a no-op plugin fiber + a scope-key extend), built lazily on first viewing and torn down only when the session is removed and unwatched — host-session death alone does not tear a scope (it freezes into a read-only viewport).
 

.agents/notes/implemented/architecture/2026-07-19-gui-web-client-architecture.zh.md

@@ -44,7 +44,7 @@ slot 体系有自己的笔记——[slot 体系标准](2026-07-22-slot-type-chai
 
 服务是插件对其他插件的唯一 API（UI 组件与注入面都不是 API；无人调用的插件不挂服务——ui-trajectory 即最小插件样板：无 ctx 服务，只做视图 slot 注册）。名册：`ctx.connection`（RPC 传输 + generation 状态）、`ctx.slots`（注册表包装层，发 `slots/changed`，渲染入口，渲染器安装约定）、`ctx.sessions`（列表 store、当前会话状态、scope 树）、`ctx.loader`、`ctx.theme`、`ctx.i18n`、`ctx.layout`（跨插件视图导航）、`ctx.conversation`（send/cancel/startSession）。过去住在服务 store 里的观看态（面板宽、选中、草稿）现按 [slot 体系标准](2026-07-22-slot-type-chain-implementation.zh.md) 住 entry 声明的 store。
 
-slot 之外不存在第二种组件注册模型——原视图环与工具环都已溶解进来。会话视图即 ui-conversation 声明的 `'conversation.view'` list slot entry，tab 元数据随注册 options（`id`/`order`/`label`）走，per-view chrome 住视图组件自身。最终 Chat 业务 Node 通过 keyed/session `'conversation.chat.node'` slot 分发；ui-tool 拥有其中的 `tool-call` entry，递归渲染传入的 `subCalls`，并声明 keyed/session `'tool.call.toolview'` 子 slot。key 空间仍在运行时开放（SlotMap 声明 slot、从不声明 key），root 与任意深度的后代都按 `entryKey: toolName` 分发，以 `GenericToolCard` 兜底。业务包通过 `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>' }, Row))` 注册原子视图；声明本身就是加载与重载依赖（[决策](../../archived/architecture/2026-08-05-slot-declaration-injection.md)）。ui-conversation 还通过 `'conversation.details.tool'` 委托 selected call 的详情正文，使 ui-tool 的 card model 保持为唯一展示所有者，同时避免 conversation 导入 Tool 组件。与 target 无关的事件注册表和视图注册表是数据组装 seam，不是平行组件注册表（[决策](2026-08-09-client-conversation-node-assembly.zh.md)）。
+slot 之外不存在第二种组件注册模型——原视图环与工具环都已溶解进来。会话视图即 ui-conversation 声明的 `'conversation.view'` list slot entry，tab 元数据随注册 options（`id`/`order`/`label`）走，per-view chrome 住视图组件自身。最终 Chat 业务 Node 通过 keyed/session `'conversation.chat.node'` slot 分发；ui-tool 拥有其中的 `tool-call` entry，递归渲染传入的 `subCalls`，并声明 keyed/session `'tool.call.toolview'` 子 slot。key 空间仍在运行时开放（SlotMap 声明 slot、从不声明 key），root 与任意深度的后代都按 `entryKey: toolName` 分发，以 `GenericToolCard` 兜底。业务包通过 `ctx.slots.inject('tool.call.toolview', () => ctx.slots.register({ name: 'tool.call.toolview', key: '<tool>' }, Row))` 注册原子视图；声明本身就是加载与重载依赖（[决策](../../archived/architecture/2026-08-05-slot-declaration-injection.md)）。右列是 ui-sidebar-right 以每会话一个停靠面填充的 `rightbar` 坑位；原来的详情列及其 `'conversation.details.tool'` 坑位已删除（[决策](../feature/2026-09-04-right-sidebar-docking-infrastructure.zh.md)）。与 target 无关的事件注册表和视图注册表是数据组装 seam，不是平行组件注册表（[决策](2026-08-09-client-conversation-node-assembly.zh.md)）。
 
 **scope 寻址**与 host 侧 agent（智能体）scope 惯例同构：服务是 root 单例，方法不收 sessionId——它们读调用方 ctx 上的 scope 标（`scopeOf(ctx)`）。在会话 scope 内，`ctx.conversation.send('hi', 'queue')` 自动打到该会话；跨会话调用换 ctx 定向（`ctx.sessions.scope(id)!.conversation.send(...)`）；从 root ctx 直接调 scoped 方法即 throw。client 会话 scope 的铸造方式与 host agent scope 相同（no-op 插件 fiber + scope 键 extend），首次观看时惰性建，只有会话被移除且无人观看才拆——仅 host 会话死亡不拆 scope（冻结为只读视窗）。
 

.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.md
-2026-07-31-claimed-pre-step-inbox-lifecycle.md: 73768e1eee8957f8976d40812b0a31a2961f0825
-2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md: 343816abaf394b8f64924cf36b753c6b1b2e34ca
+2026-07-31-claimed-pre-step-inbox-lifecycle.md: 737e3835263a3215a0fd2e52dad4ee05402bd888
+2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md: ecb731df663e0d48b374a3118d7db7f6a34bfc18

.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.md

@@ -12,17 +12,19 @@ Occurrence-local inbox wrappers also duplicated the identity already carried by
 
 ## Decision
 
-Before every proposed step, `Inbox.claim(target)` atomically removes the complete batch: all `next-step` messages and, at a turn boundary, one `next-turn` message. At the initial boundary the loop first commits `turn/start`, so the claim and its single `agent/pre-step` decision have durable turn ownership. Claiming records normalized `agent/inbox/spliced` pure deletions with no outcome. The loop then emits `agent/inbox/claimed { message, turn }` once per claimed message and awaits the waterfall with that exclusive batch and `{ turn, step, signal }`.
+Before every proposed step, the loop's package-internal `ReactLoopInbox` atomically claims the complete batch: all `next-step` messages and, at a turn boundary, one `next-turn` message. At the initial boundary the loop first commits `turn/start`, so the claim and its single `agent/pre-step` decision have durable turn ownership. Claiming records normalized `agent/inbox/spliced` pure deletions with no outcome, emits `agent/inbox/claimed { message, turn }` once per claimed message, and returns the exclusive batch for the loop's waterfall with `{ turn, step, signal }`.
 
 `PreStepDecision` is `{ kind: 'reject' } | { kind: 'enter'; messages: UserMessage[] }`. Reject opens no step, leaves the claimed batch removed, and closes the turn as blocked without any step events. Empty entry, cancellation, and failure before `step/start` likewise close a balanced no-step turn. Enter supplies the complete batch appended as `user/message` events after `step/start`. A listener wrapping `next()` preserves downstream changes unless it intentionally replaces them, so all message rewrites settle once in the final return value. There is no `agent/prompt-prepare`, `agent/prompt-submit`, or `agent/step` extension point.
 
-The durable inbox remains two `UserMessage[]` lists addressed by `MessageId`. `append`, `prepend`, and `splice` take a target, while `replace(messageId, newMessage)` and `remove(messageId)` locate the pending message across both lists before committing a normalized splice. Replacement may change identity and emits the old message as discarded followed by the new message as inserted. Every insertion emits `agent/inbox/inserted { message }`; an ordinary removal records `outcome: 'canceled'` and emits `agent/inbox/discarded { message }`. Claiming is the loop's internal step-boundary operation on the inbox and records pure deletions without notifications or an outcome, so the loop can publish claimed events itself. These live events add no placement, outcome, or batch fields.
+The durable inbox remains two `UserMessage[]` lists addressed by `MessageId`. `append`, `prepend`, and `splice` take a target, while `replace(messageId, newMessage)` and `remove(messageId)` locate the pending message across both lists before committing a normalized splice. Replacement may change identity and emits the old message as discarded followed by the new message as inserted. Every insertion emits `agent/inbox/inserted { message }`; an ordinary removal records `outcome: 'canceled'` and emits `agent/inbox/discarded { message }`. Claiming records pure deletions without an outcome and emits claimed events from `ReactLoopInbox`. These live events add no placement, outcome, or batch fields.
 
-The two event surfaces have separate consumers. Observers following one message use `agent/inbox/inserted`, `claimed`, and `discarded`. Whole-queue consumers, including the Web queue projection and reconnect baseline, use the durable `agent/inbox/spliced` stream; UI edits and removals route through `Inbox.splice()` or another Inbox mutation method so the same projection records every change.
+`Agent.inbox` exposes only the structural `Inbox` interface for reading and mutating pending work; loop-only `hasPending` and claim operations are absent from that public face. dsh-agent-loop constructs one `ReactLoopInbox` and uses it for both structural commands and driver operations. The concrete constructor receives `SessionProjectionRegistry` directly instead of the wider Cordis `Context` and registers the standard definition on the agent scope before its first read. `AgentLoop` requires the registry service at activation, and the registry reference-counts the definition across live agent scopes.
+
+The two event surfaces have separate consumers. Observers following one message use `agent/inbox/inserted`, `claimed`, and `discarded`. Each `ReactLoopInbox` contributes the standard `inbox` projection over the durable `agent/inbox/spliced` stream from its agent scope; UI edits and removals route through an Inbox mutation method so the same projection records every change. When that projection reconstructs durable history, it rejects unsafe or out-of-range coordinates and duplicate `MessageId` values across both lists, and reports the offending event seq. Whole-queue control consumers use the projection change feed: the Session controller publishes the projection frame, then derives the queue replacement from the same post-fold inbox value.
 
 Plugins that need current-step atomic rewriting return messages from `agent/pre-step`. Plugins that only need later context may mutate `agent.inbox` directly. Workspace context uses both paths: asynchronous filesystem projections stage one replaceable `next-step` item, while the next entering pre-step folds that item or a newly composed baseline into its final batch and removes the pending copy. Rejection keeps the item queued.
 
-The archived [addressable queue occurrence decision](../../archived/feature/2026-07-29-addressable-queue-operations.md) describes the superseded occurrence-wrapper design. `MessageId` now owns addressability, while the retained Host queue mirror derives its snapshots from the durable splice projection.
+The archived [addressable queue occurrence decision](../../archived/feature/2026-07-29-addressable-queue-operations.md) describes the superseded occurrence-wrapper design. `MessageId` owns addressability, while `ReactLoopInbox` contributes `inbox` as the standard session projection over durable splices. The generic projection carrier serves that fold for live updates, history-tail reconnect baselines, and cold process-restart recovery without a live Agent mirror.
 
 ## Alternatives considered
 
@@ -34,7 +36,7 @@ The archived [addressable queue occurrence decision](../../archived/feature/2026
 
 ## Verification
 
-Agent-loop coverage pins turn-start-before-claim-before-pre-step ordering, exact live event payloads, balanced no-step rejection, final-batch rewriting, input inserted after a claim, listener failure, and cancellation. Inbox and consumer tests pin pure claim deletions, canceled ordinary removals, agent-instructions staging, replacement, and same-step entry, plan/goal/hook behavior, UI cleanup, compaction, checkpointing, and resumed durable projection. Generated event and type catalogs expose only the new waterfall and payloads.
+Agent-loop coverage pins turn-start-before-claim-before-pre-step ordering, exact live event payloads, balanced no-step rejection, final-batch rewriting, input inserted after a claim, listener failure, cancellation, and agent-scope projection removal after the last owner unloads. Inbox and consumer tests pin pure claim deletions, canceled ordinary removals, agent-instructions staging, replacement, and same-step entry, plan/goal/hook behavior, UI cleanup, compaction, checkpointing, resumed durable projection, rejection of invalid persisted coordinates or cross-list identities, and post-fold queue replacement when the controller registers before the projection registry. Consumer-domain tests use a process-local Inbox stub only when durability is outside the test subject; claiming, durable projection, recovery, validation, and live-notification tests create Agents through the production AgentLoop test harness, so test support never reimplements the projection. Generated event and type catalogs expose only the new waterfall and payloads.
 
 ## Consequences
 

.agents/notes/implemented/architecture/2026-07-31-claimed-pre-step-inbox-lifecycle.zh.md

@@ -12,17 +12,19 @@ Status: implemented
 
 ## 决策
 
-每个拟议步骤之前，`Inbox.claim(target)` 会原子移除完整批次：全部 `next-step` 消息，以及轮次边界上的一条 `next-turn` 消息。在首次边界，循环会先提交 `turn/start`，使领取及其唯一一次 `agent/pre-step` 决策拥有持久轮次归属。领取会记录规范化、不带 outcome 的纯删除 `agent/inbox/spliced`。随后，循环针对每条已领取消息发出一次 `agent/inbox/claimed { message, turn }`，并用该独占批次与 `{ turn, step, signal }` 等待 waterfall（瀑布式事件）。
+每个拟议步骤之前，循环包内部的 `ReactLoopInbox` 会原子领取完整批次：全部 `next-step` 消息，以及轮次边界上的一条 `next-turn` 消息。在首次边界，循环会先提交 `turn/start`，使领取及其唯一一次 `agent/pre-step` 决策拥有持久轮次归属。领取会记录规范化、不带 outcome 的纯删除 `agent/inbox/spliced`，针对每条已领取消息发出一次 `agent/inbox/claimed { message, turn }`，并把独占批次返回给循环，由后者用 `{ turn, step, signal }` 等待 waterfall（瀑布式事件）。
 
 `PreStepDecision` 为 `{ kind: 'reject' } | { kind: 'enter'; messages: UserMessage[] }`。reject 不会打开步骤，会让已领取批次保持已删除，并将轮次关闭为 blocked，且不产生任何步骤事件。空的 enter、取消以及 `step/start` 前的失败同样会关闭一个边界平衡的无步骤轮次。enter 提供在 `step/start` 后以 `user/message` 追加的完整批次。包装 `next()` 的监听器会保留下游变更，除非有意替换，因此全部消息改写只在最终返回值中一次性结算。系统不再存在 `agent/prompt-prepare`、`agent/prompt-submit` 或 `agent/step` 扩展点。
 
-持久 inbox 仍是两份通过 `MessageId` 寻址的 `UserMessage[]` 列表。`append`、`prepend` 与 `splice` 接受 target；`replace(messageId, newMessage)` 与 `remove(messageId)` 则在提交规范化 splice 前，通过 `MessageId` 跨两份列表定位待处理消息。替换可以改变标识，并先将旧消息作为 discarded 发布，再将新消息作为 inserted 发布。每次插入发出 `agent/inbox/inserted { message }`；普通删除记录 `outcome: 'canceled'` 并发出 `agent/inbox/discarded { message }`。领取是循环在 inbox 上的内部步骤边界操作，记录不带通知或 outcome 的纯删除，因此循环可以自行发布 claimed 事件。这些实时事件不增加 placement、outcome 或批次字段。
+持久 inbox 仍是两份通过 `MessageId` 寻址的 `UserMessage[]` 列表。`append`、`prepend` 与 `splice` 接受 target；`replace(messageId, newMessage)` 与 `remove(messageId)` 则在提交规范化 splice 前，通过 `MessageId` 跨两份列表定位待处理消息。替换可以改变标识，并先将旧消息作为 discarded 发布，再将新消息作为 inserted 发布。每次插入发出 `agent/inbox/inserted { message }`；普通删除记录 `outcome: 'canceled'` 并发出 `agent/inbox/discarded { message }`。领取记录不带 outcome 的纯删除，并由 `ReactLoopInbox` 发出 claimed 事件。这些实时事件不增加 placement、outcome 或批次字段。
 
-两类事件接口服务不同消费方。跟踪单条消息的观察方使用 `agent/inbox/inserted`、`claimed` 与 `discarded`。包括 Web 队列投影和重连基线在内的整体队列消费方使用持久 `agent/inbox/spliced` 流；UI 编辑与移除通过 `Inbox.splice()` 或其他 Inbox 变更方法处理，从而让同一投影记录所有变化。
+`Agent.inbox` 只暴露用于读取和变更待处理工作的结构化 `Inbox` 接口；仅供循环使用的 `hasPending` 与领取操作不在该公开接口上。dsh-agent-loop 只构造一个 `ReactLoopInbox`，同时用于结构化命令与驱动器操作。具体构造函数直接接收 `SessionProjectionRegistry`，而不是更宽泛的 Cordis `Context`，并在首次读取前从 agent 作用域注册标准定义。`AgentLoop` 激活时要求该注册表服务存在，注册表则对多个 live agent 作用域贡献的定义进行引用计数。
+
+两类事件接口服务不同消费方。跟踪单条消息的观察方使用 `agent/inbox/inserted`、`claimed` 与 `discarded`。每个 `ReactLoopInbox` 都从其 agent 作用域在持久 `agent/inbox/spliced` 流上贡献标准 `inbox` 投影；UI 编辑与移除通过 Inbox 变更方法处理，从而让同一投影记录所有变化。该投影重建持久历史时，会拒绝不安全或越界的坐标，以及跨两份列表重复的 `MessageId`，并报告出错事件的 seq。整体队列的 control 消费方使用投影变更流：Session controller 先发布 projection frame，再从同一份折叠后的 inbox 值派生 queue replacement。
 
 必须对当前步骤进行原子改写的插件从 `agent/pre-step` 返回消息。只需要稍后上下文的插件可以直接修改 `agent.inbox`。Workspace context 同时使用两条路径：异步文件系统投影会暂存一条可替换的 `next-step` 消息，而下一次进入步骤的 pre-step 会把该消息或新组合的基线折入最终批次，并移除仍待处理的副本。reject 会让该条目继续排队。
 
-已归档的[可寻址队列项决策](../../archived/feature/2026-07-29-addressable-queue-operations.md)描述了已被取代的单次出现包装层设计。现在由 `MessageId` 负责寻址，而保留的 Host 队列镜像根据持久 splice 投影派生快照。
+已归档的[可寻址队列项决策](../../archived/feature/2026-07-29-addressable-queue-operations.md)描述了已被取代的单次出现包装层设计。`MessageId` 负责寻址，而 `ReactLoopInbox` 把 `inbox` 作为持久 splice 上的标准会话投影贡献给投影注册表。通用投影传输层会将该折叠结果用于实时更新、历史尾页的重连基线和冷进程重启恢复，无需 live Agent 镜像。
 
 ## 曾考虑的替代方案
 
@@ -34,7 +36,7 @@ Status: implemented
 
 ## 验证
 
-agent loop（智能体循环）覆盖固定先 `turn/start`、再领取、后 pre-step 的顺序、实时事件的确切载荷、边界平衡的无步骤 reject、最终批次改写、领取后插入的输入、监听器失败与取消。Inbox 和消费方测试固定纯领取删除、普通删除的 canceled 结果、agent-instructions 的暂存、替换与同一步骤进入、plan/goal/钩子行为、UI 清理、压缩（compaction）、检查点以及恢复后的持久投影。生成的事件与类型目录只公开新的 waterfall 与载荷。
+agent loop（智能体循环）覆盖固定先 `turn/start`、再领取、后 pre-step 的顺序、实时事件的确切载荷、边界平衡的无步骤 reject、最终批次改写、领取后插入的输入、监听器失败、取消，以及最后一个所有者卸载后移除 agent 作用域投影。Inbox 和消费方测试固定纯领取删除、普通删除的 canceled 结果、agent-instructions 的暂存、替换与同一步骤进入、plan/goal/钩子行为、UI 清理、压缩（compaction）、检查点、恢复后的持久投影、对非法持久坐标或跨列表重复标识的拒绝，以及 controller 早于投影注册表注册时仍使用折叠后队列值。只有当持久性不属于测试对象时，消费方领域测试才使用进程内 Inbox 桩；领取、持久投影、恢复、校验与实时通知测试通过生产 AgentLoop 测试 harness 创建 Agent，因此测试支持代码不会重新实现该投影。生成的事件与类型目录只公开新的 waterfall 与载荷。
 
 ## 后果
 

.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: 58a8f23d717580355b852703f448c723d9c3a7ea
-2026-08-23-client-derived-tool-presentation.zh.md: 8e1a02eff57cce7967985a22c5bdcec7c18e6059
+2026-08-23-client-derived-tool-presentation.md: 6b19dc881d572bfece345cbbd5eca688b2e05aab
+2026-08-23-client-derived-tool-presentation.zh.md: 98ada31627398f317e4c41336af56e8c6cf0837e

.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.md

@@ -248,7 +248,7 @@ Host presenter APIs describe top-level calls and results. Code Dispatch subcalls
 
 Code Dispatch start and result events already carry `parentCallId`. Conversation preserves that existing fact on each child `ToolCallBlock`; root Session calls omit it. The diff, read, search, and web models accept only blocks without `parentCallId`; the terminal model and existing renderers that intentionally support nested calls accept child blocks.
 
-The Details panel delegates the selected block unchanged. Shared card models apply the same terminal eligibility and nonterminal child restrictions in rows and Details, so the Details slot needs no placement field.
+Shared card models apply the same terminal eligibility and nonterminal child restrictions wherever a block renders, so no second presentation surface needs a placement field; the details panel that once delegated a selected block was removed with the right-hand details column ([decision](../feature/2026-09-04-right-sidebar-docking-infrastructure.md)).
 
 The keyed slot continues dispatching every subcall by its real tool name. `parentCallId` restricts only the diff, read, search, and web structured models covered by this decision. Existing specialized renderers such as Skill and Cordis, which already read raw blocks, remain unchanged.
 

.agents/notes/implemented/architecture/2026-08-23-client-derived-tool-presentation.zh.md

@@ -248,7 +248,7 @@ Host presenter API 描述顶层 call/result。本决定覆盖的 diff、read、s
 
 Code Dispatch start 与 result event 已经携带 `parentCallId`。Conversation 在每个 child `ToolCallBlock` 上保留这项现有事实，root Session call 则不携带它。diff、read、search 和 web model 只接受没有 `parentCallId` 的 block；terminal model 与原本有意支持嵌套调用的 renderer 接受 child block。
 
-Details panel 原样委托选中的 block。共享 card model 在行与 Details 中应用相同的 terminal 适用规则和非 terminal 子调用限制，因此 Details slot 不需要 placement 字段。
+共享的 card model 在 block 渲染到哪里都施加同样的终端资格与非终端子调用限制，因此不需要第二个展示面带 placement 字段；曾经原样委托选中 block 的详情面板已随右侧详情列一并删除（[决策](../feature/2026-09-04-right-sidebar-docking-infrastructure.zh.md)）。
 
 keyed slot 仍按每个子调用的真实 tool name 分发；`parentCallId` 只限制本决定覆盖的 diff/read/search/web 结构化模型。Skill、Cordis 等已经直接读取 raw block 的专用 renderer 保持现状。
 

.agents/notes/implemented/architecture/2026-08-25-electron-desktop-packaging-and-updates.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-08-25-electron-desktop-packaging-and-updates.md
+2026-08-25-electron-desktop-packaging-and-updates.md: 6d22777c8913911dbb1d89c09de9e891636873c8
+2026-08-25-electron-desktop-packaging-and-updates.zh.md: 5108492ba6f029847735f570aa77c2cb505f981c

.agents/notes/implemented/architecture/2026-09-05-client-resource-model.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-05-client-resource-model.md
+2026-09-05-client-resource-model.md: 75502ffc91af049bf89b7c36ec6ae3dc1339a5f8
+2026-09-05-client-resource-model.zh.md: d1430e88fc16b46a6ad32bbeacb1d59e0a7f6131

.agents/notes/implemented/architecture/2026-09-05-client-resource-model.md

@@ -0,0 +1,88 @@
+# Agent Note: Client resource model
+
+Status: implemented
+
+English | [中文](2026-09-05-client-resource-model.zh.md)
+
+## Problem
+
+A right-Sidebar tab body, a chat card, or any other slot component often needs live data it knows only by address: the file an agent just wrote, later a chat node or a terminal. Before the resource model each consumer fetched for itself — the text preview owned its own Remote call and refresh loop — so every mount re-read, two components showing one file held two copies, switching tabs unmounted the body and lost its content, and each new kind of content meant a new bespoke hook.
+
+The tab record set the constraint. A tab must survive undo, redo, reload, and hot module replacement without the code that opened it, so the record can hold only serializable data: an address and navigation parameters. The opener therefore cannot hand a body its data, and injection is the wrong tool — injection is a registration-time relation between a domain and a seat, while opening is a runtime event. A component has to find its data from the address alone, through something registered once by whoever owns that kind of data.
+
+## Decision
+
+[`packages/client/resources`](../../../../packages/client/resources/README.md) (`@deepseek-ai/dsh-client-resources`) provides `ctx.resources` and the `useResource` global standard hook. Anything a consumer reads live is a **resource**, a resource is identified by its **address** and nothing else, and the address's protocol names the one **provider** that turns it into a frame stream.
+
+### Addresses
+
+A resource address is a `dsh-resource://<type>/…` URL. The host is the protocol key — the key of `ResourceProtocolMap` — and the path belongs to the protocol's owner. `RESOURCE_SCHEME = 'dsh-resource'` is the one scheme constant; `protocolOf(address)` parses the string with `new URL`, requires `protocol === 'dsh-resource:'`, and returns the lower-cased host, or `undefined` for a string the parser rejects, another scheme, or an empty host. `dsh-resource` is not one of the URL specification's special schemes, so the parser keeps the host's case and treats the path as opaque; the lower-casing is explicit, and each path segment is percent-encoded by the protocol that defines it. A protocol that needs a scope encodes it in the path: `dsh-resource://file/session/<sessionId>/<path relative to that session's workspace root>`, with `session/<sessionId>` naming the session whose root resolves the file, or `dsh-resource://file/absolute/<absolute path>`, which carries no session and is read through the current one ([grammar](../../../../packages/util/workspace-path/README.md)). Any other scheme — `sidebar://guide` — is a navigation address: it names a tab, not data, and the model answers `none` for it ([tab types and navigation](2026-09-05-sidebar-tab-types-and-navigation.md)).
+
+### The service
+
+```ts ignore-check
+interface Resources {
+  register<P extends ResourceProtocol>(provider: ResourceProvider<P>): () => void
+  pin(address: string, signal: AbortSignal): void
+  source(address: string): ObservableSnapshot<ResourceSnapshot<unknown>>
+}
+
+interface ResourceProvider<P extends ResourceProtocol> {
+  readonly protocol: P
+  open(address: string, ctx: { readonly signal: AbortSignal }): AsyncIterable<RemoteResult<ResourceProtocolMap[P]>>
+  reload?(address: string): void
+}
+
+interface ResourceSnapshot<Value> {
+  readonly status: 'none' | 'loading' | 'live' | 'failed'
+  readonly value: Value | undefined
+  readonly failure: RemoteFailure | undefined
+  readonly reload: () => void
+}
+
+type UseResource = <P extends ResourceProtocol>(address: string) => ResourceSnapshot<ResourceProtocolMap[P]>
+```
+
+`register` owns exactly one provider per protocol: a second registration for the same protocol throws, and the registration is an effect on the registering plugin's fiber, so a protocol leaves with its plugin and may be registered again afterwards. `pin` holds a resource open without subscribing until the signal aborts; an already-aborted signal pins nothing. `source` is the bare observable behind the hook, reference-stable per address, for callers outside React. The value type is looked up in `ResourceProtocolMap`, declared as an empty interface in `ui-slots` beside `SlotMap` — a module augmentation cannot introduce an export the target module lacks, and every consumer already depends on `ui-slots` — and each protocol's owner declaration-merges its member (`file: WorkspaceFileResource`); the resources package re-exports the type.
+
+### The hook
+
+`useResource` is declared on `GlobalStandardProps` in `ui-slots`, so every slot component has it whatever its scope, and the plugin provides it through `ctx.slots.provideRoot({ keyedHooks: { resource: address => resources.source(address) } })`, the same root keyed-hook path `useSessions` uses. It is not a session standard prop: a resource carries its own scope in its address, and components outside any session scope read resources too. `useResource<P>(address)` returns the snapshot: `none` when the address's protocol has no provider or the address is not a resource address, `loading` between the stream opening and its first frame, `live` with the latest `ok` value, `failed` with the latest frame's failure beside the last value. `reload()` asks the provider for a fresh frame and is a no-op when the protocol has no provider or no `reload`.
+
+### Frames
+
+A provider yields `RemoteResult` frames: the current state first, one frame per later change. An `ok` frame makes the resource `live`, replaces the value, and clears the failure; an `ok: false` frame makes it `failed`, records the failure, and keeps the last value. Failure is data, not an exception: the Remote face already folds failures into `ok: false` and never rejects, providers pass those frames on, and the model neither catches nor wraps — a throw inside a provider's stream is a programming error left to surface. A stream that ends on its own keeps its last state; frames a provider yields after the release that aborted it are dropped and the iterator is returned. Streams carry metadata, not payload: the `file` value is `{ absolutePath, version, bytes?, changed }`, and a consumer reads content itself, by page, through the [Workspace Files service](2026-09-05-workspace-files-service.md).
+
+### Lifecycle
+
+One record exists per address. Its holders are the hook's subscribers plus pins; the first holder opens the provider's stream under an `AbortController`, later holders share it and read the latest value at once, and the last release aborts the stream and resets the snapshot to idle — `loading` while a provider is registered, `none` otherwise. A provider that arrives while an address is already held opens that address's stream; one that leaves aborts it and the address reads `none`. Records are kept for the page lifetime so `source(address)` stays reference-stable across React's render-then-subscribe window and a StrictMode remount, where a recreated record would resubscribe and restart the stream on every render.
+
+The right Sidebar's Tab domain pins every open tab record's address for the record's life, so switching tabs unmounts a body without closing its stream and switching back reads the latest value; a record restored by undo is a new pin, and a resource the model already let go is read again ([tab types and navigation](2026-09-05-sidebar-tab-types-and-navigation.md)). `openResource(address)` accepts resource addresses only; pages such as the guide and the file tree are opened by kind and never enter the resource model.
+
+## Alternatives considered
+
+**Session-bound resources: `useResource` on the session kit and a `(session, address)` identity.** The first form. Rejected because a file is not a session concern — the session is only who authorizes the path — and because the model must serve protocols and components outside any session scope. Identity became the address alone, the scope moved into the address grammar, and the hook moved to the global kit.
+
+**Content in the resource stream.** Rejected: content can be arbitrarily large, and a stream is for pushing change, not payload. The stream carries metadata and the consumer reads content by page, which is also what lets one open tab hold a multi-megabyte file at the cost of one page.
+
+**Failure as a thrown error, wrapping a non-`RemoteFailure` throw as `gateway/internal`.** Rejected: the Remote face never rejects, so anything a provider throws is a bug, and wrapping it would be a fallback that hides the bug from the developer who caused it. A failure is an `ok: false` frame; a throw surfaces.
+
+**`file:/<scope>/<id>/<path>`, then `file://<scope>/<id>/<path>` with the scope in the authority.** Two earlier grammars. The single-slash form was not a URL the platform parser accepted, so every consumer hand-parsed it. Moving the scope into the authority made it a URL but gave each resource protocol its own scheme — `file://`, later `chat://`, `terminal://` — so the set of schemes grew with the set of protocols, a `file://` address no longer meant what it means everywhere else, and telling a resource address from a navigation address needed a list. The single `dsh-resource://<type>/…` scheme makes that test one comparison, leaves the host free to name the protocol, and keeps every other scheme available to navigation.
+
+**A hand-parsed scheme prefix instead of the URL parser.** The first `protocolOf` matched a regular expression for the scheme. Rejected once addresses were URLs: the parser already decides validity and case, and a string it rejects should read as "no protocol" rather than be half-parsed.
+
+**A per-tab stream hook, or a framework-managed `useTabResource(fetch)`.** Rejected in turn: a stream hook on the tab domain asks the wrong owner — `file` data must come from the workspace file service, chat data from the chat domain — and a framework-owned fetch has no good cache key. What remains is owner props on the tab plus one client-wide `useResource` keyed by address.
+
+## Consequences
+
+Any slot component reads live data by address and nothing else, so an opener passes data only and a body reconstructs itself from its record after undo, reload, or hot replacement. Two components showing one address share one stream, and a pinned address survives its body's unmount. A protocol's transport lives in exactly one provider, and adding a protocol is one declaration-merged type plus one registration.
+
+The costs are recorded here so they are not rediscovered. Records are never reclaimed: memory grows with the number of distinct addresses ever read, not with reads. Abort compliance rests with the provider; the model drops what a released stream still yields but cannot stop a provider that ignores the signal before its next frame. The failure type is the Remote face's `RemoteFailure`, so a provider whose source is not a Remote call has to mint one. A navigation address or a malformed string reads as `none` rather than an error, which keeps mixed address lists cheap to render but gives a misspelled protocol no diagnostic beyond the missing value.
+
+## Testing
+
+`packages/client/resources/tests/resources.client.spec.ts` drives the registry with scripted feeds: protocol ownership and disposal, `none` for a protocol without a provider and for a navigation address, a provider arriving after a held address and leaving while it is held, registrations dropped with their fiber, open-on-first-holder and close-on-last, one source per address, pins including an already-aborted signal, a remount reading the latest value without reopening, reopening as a fresh stream, frames after abort dropped with the iterator returned, a stream ending on its own, failure frames beside the last value, and `reload` forwarding. `tests/apply.client.spec.ts` mounts the plugin in `SlotTestRuntime` and checks, through a root-scope probe component, that `useResource` reaches props, that rendering it opens the provider's stream, and that disposing the plugin withdraws both the service and the hook.
+
+## Deferred
+
+Reclaiming idle records, a resource-owned failure type decoupled from the Remote face, and the `chat` and `terminal` protocols are open; each waits for a consumer. The developer-facing reference is [docs/subsystems/client-resources.md](../../../../docs/subsystems/client-resources.md); the Sidebar that consumes the model is described in [docs/subsystems/sidebar-right.md](../../../../docs/subsystems/sidebar-right.md).

.agents/notes/implemented/architecture/2026-09-05-client-resource-model.zh.md

@@ -0,0 +1,88 @@
+# Agent Note: 客户端资源模型
+
+Status: implemented
+
+[English](2026-09-05-client-resource-model.md) | 中文
+
+## Problem
+
+右侧 Sidebar 的 tab 正文、聊天卡片或任何别的 slot 组件，常常需要只以地址可知的活数据：agent 刚写的文件，将来的聊天节点或终端。资源模型出现前每个消费方各自取数——文本预览自己持有 Remote 调用与刷新循环——于是每次挂载都重读、两个组件显示同一文件就持有两份、切 tab 卸载正文就丢内容，每种新内容都意味着一个新的专用 hook。
+
+约束来自 tab 记录。tab 必须在打开它的代码不在场时挺过撤销、重做、刷新与热替换，所以记录只能存可序列化的数据：一个地址与导航参数。因此开启方不能把数据交给正文，注入也不是合适的工具——注入是领域与席位之间注册期的关系，而打开是运行期事件。组件必须只凭地址找到数据，途径是由数据拥有者注册一次的东西。
+
+## Decision
+
+[`packages/client/resources`](../../../../packages/client/resources/README.zh.md)（`@deepseek-ai/dsh-client-resources`）提供 `ctx.resources` 与 `useResource` 全局标准 hook。消费方活读的任何东西都是**资源**，资源只由其**地址**标识，地址的协议命名唯一一个把它变成帧流的**提供方**。
+
+### 地址
+
+资源地址是 `dsh-resource://<type>/…` 形式的 URL。host 是协议键——`ResourceProtocolMap` 的键——路径归协议拥有者。`RESOURCE_SCHEME = 'dsh-resource'` 是唯一的 scheme 常量；`protocolOf(address)` 用 `new URL` 解析字串，要求 `protocol === 'dsh-resource:'`，返回小写 host；解析器拒绝的字串、其它 scheme 或空 host 返回 `undefined`。`dsh-resource` 不是 URL 规范里的特殊 scheme，解析器会保留 host 的大小写并把路径当作不透明串，所以小写化是显式做的，每段路径由定义它的协议做百分号编码。需要作用域的协议把作用域编进路径：`dsh-resource://file/session/<sessionId>/<相对该会话工作区根的路径>`，`session/<sessionId>` 命名以其根解析该文件的会话；或 `dsh-resource://file/absolute/<绝对路径>`，不带会话、经当前会话读取（[语法](../../../../packages/util/workspace-path/README.zh.md)）。其它任何 scheme——`sidebar://guide`——是导航地址：它命名一个 tab 而非数据，模型对它回答 `none`（[tab 类型与导航](2026-09-05-sidebar-tab-types-and-navigation.zh.md)）。
+
+### 服务
+
+```ts ignore-check
+interface Resources {
+  register<P extends ResourceProtocol>(provider: ResourceProvider<P>): () => void
+  pin(address: string, signal: AbortSignal): void
+  source(address: string): ObservableSnapshot<ResourceSnapshot<unknown>>
+}
+
+interface ResourceProvider<P extends ResourceProtocol> {
+  readonly protocol: P
+  open(address: string, ctx: { readonly signal: AbortSignal }): AsyncIterable<RemoteResult<ResourceProtocolMap[P]>>
+  reload?(address: string): void
+}
+
+interface ResourceSnapshot<Value> {
+  readonly status: 'none' | 'loading' | 'live' | 'failed'
+  readonly value: Value | undefined
+  readonly failure: RemoteFailure | undefined
+  readonly reload: () => void
+}
+
+type UseResource = <P extends ResourceProtocol>(address: string) => ResourceSnapshot<ResourceProtocolMap[P]>
+```
+
+`register` 让每个协议恰有一个提供方：同一协议的第二次注册抛错，注册是挂在注册方插件 fiber 上的 effect，所以协议随插件离开、之后可再注册。`pin` 在不订阅的情况下让资源保持打开直到信号中止；已中止的信号什么也不钉。`source` 是 hook 背后的裸 observable，按地址引用稳定，供 React 之外的调用方使用。值类型在 `ResourceProtocolMap` 里查得，它作为空接口声明在 `ui-slots` 里、与 `SlotMap` 并列——模块增强无法给目标模块添加它没有的导出，而每个消费方本来就依赖 `ui-slots`——各协议拥有者声明合并自己的成员（`file: WorkspaceFileResource`）；resources 包再导出这个类型。
+
+### hook
+
+`useResource` 声明在 `ui-slots` 的 `GlobalStandardProps` 上，因此每个 slot 组件不论作用域都有它，插件经 `ctx.slots.provideRoot({ keyedHooks: { resource: address => resources.source(address) } })` 提供，与 `useSessions` 走同一条根 keyed hook 路径。它不是会话标准 prop：资源的作用域随地址携带，会话作用域之外的组件也要读资源。`useResource<P>(address)` 返回快照：地址协议没有提供方或地址不是资源地址时为 `none`，流已打开、首帧未到时为 `loading`，`live` 携带最新 `ok` 值，`failed` 在最后一个值旁携带最新帧的失败。`reload()` 请提供方给一个新帧，协议没有提供方或提供方没有 `reload` 时是空操作。
+
+### 帧
+
+提供方产出 `RemoteResult` 帧：首帧是当前状态，之后每次变化一帧。`ok` 帧使资源 `live`、替换值、清除失败；`ok: false` 帧使其 `failed`、记下失败、保留最后一个值。失败是数据不是异常：Remote 面本来就把失败折进 `ok: false` 且从不 reject，提供方原样转发这些帧，模型既不捕获也不包装——提供方流里抛出是编程错误，任其冒出。自行结束的流保持最后状态；提供方在中止它的那次释放之后产出的帧被丢弃，迭代器被归还。流只推元数据不推载荷：`file` 的值是 `{ absolutePath, version, bytes?, changed }`，消费方自己经 [Workspace Files 服务](2026-09-05-workspace-files-service.zh.md)按页读内容。
+
+### 生命周期
+
+每个地址一条记录。持有者是 hook 的订阅者加 pin；第一个持有者在 `AbortController` 下打开提供方的流，之后的持有者共享它并立刻读到最新值，最后一个释放时中止流并把快照重置为空闲——有提供方注册时为 `loading`，否则为 `none`。地址已被持有时到达的提供方会打开该地址的流；离开的提供方中止它，地址读作 `none`。记录在页面存续期内保留，使 `source(address)` 在 React 渲染到订阅的窗口与 StrictMode 重挂载之间保持引用稳定，否则重建记录会让每次渲染重订阅、重开流。
+
+右侧 Sidebar 的 Tab 域在每条打开的 tab 记录存续期内钉住其地址，所以切 tab 卸载正文不关流、切回读到最新值；撤销恢复的记录是一次新的钉住，模型已放掉的资源会重新读取（[tab 类型与导航](2026-09-05-sidebar-tab-types-and-navigation.zh.md)）。`openResource(address)` 只收资源地址；引导页与文件树这类页面按 kind 打开，从不进入资源模型。
+
+## Alternatives considered
+
+**会话绑定的资源：`useResource` 挂会话标准件、身份为 `(session, address)`。** 第一版形态。被否，因为文件不是会话的事——会话只是路径的授权者——而且模型必须服务会话作用域之外的协议与组件。身份改为只有地址，作用域进入地址语法，hook 移到全局标准件。
+
+**内容进资源流。** 被否：内容可能任意大，流是用来推变化的，不是推载荷。流只带元数据，消费方按页读内容，这也是一个打开的 tab 能以一页的代价承载数兆字节文件的原因。
+
+**以抛错表达失败，并把非 `RemoteFailure` 的抛出包装成 `gateway/internal`。** 被否：Remote 面从不 reject，所以提供方抛出的任何东西都是 bug，包装它就是把 bug 藏起来不让肇事者看见的 fallback。失败是 `ok: false` 帧；抛出就冒出来。
+
+**`file:/<scope>/<id>/<path>`，再到把作用域放在 authority 位的 `file://<scope>/<id>/<path>`。** 两版更早的语法。单斜杠形态不是平台解析器接受的 URL，每个消费方都得手工解析。把作用域移到 authority 位使它成为 URL，却让每个资源协议各占一个 scheme——`file://`、将来的 `chat://`、`terminal://`——scheme 的集合随协议集合增长，`file://` 地址不再是它在别处的含义，区分资源地址与导航地址需要一张清单。单一 scheme `dsh-resource://<type>/…` 让这个判断只需一次比较，host 留给协议命名，其它所有 scheme 留给导航。
+
+**手写 scheme 前缀解析代替 URL 解析器。** 第一版 `protocolOf` 用正则匹配 scheme。地址成为 URL 后被否：解析器已经决定合法性与大小写，它拒绝的字串应读作「无协议」而不是被解析一半。
+
+**每 tab 一个流 hook，或框架代管的 `useTabResource(fetch)`。** 依次被否：挂在 tab 域上的流 hook 问错了拥有者——`file` 数据必须来自工作区文件服务，聊天数据来自聊天域——而框架代管的 fetch 没有好的缓存键。留下的是 tab 上的 owner props 加一个按地址的客户端级 `useResource`。
+
+## Consequences
+
+任何 slot 组件只凭地址读活数据，于是开启方只传数据，正文在撤销、刷新或热替换后能从记录重建自己。显示同一地址的两个组件共享一条流，被钉住的地址在正文卸载后仍存活。一个协议的传输只住在一个提供方里，新增协议只是一个声明合并的类型加一次注册。
+
+代价记录在此以免被重新发现。记录不回收：内存随读过的不同地址数增长，而非随读取次数增长。中止合规归提供方；模型会丢弃已释放的流仍产出的帧，却阻止不了忽略信号的提供方跑到下一帧。失败类型是 Remote 面的 `RemoteFailure`，来源不是 Remote 调用的提供方得自己铸一个。导航地址或畸形字串读作 `none` 而非报错，这让混合地址列表渲染起来便宜，却让拼错的协议除了缺值之外没有任何诊断。
+
+## Testing
+
+`packages/client/resources/tests/resources.client.spec.ts` 用脚本化的 feed 驱动注册表：协议归属与注销、无提供方的协议与导航地址都为 `none`、提供方在地址已被持有后到达与在持有中离开、注册随 fiber 消失、首个持有者开流末个关流、一址一源、包括已中止信号在内的 pin、重挂读到最新值且不重开、重开为新流、中止后帧丢弃且迭代器归还、流自行结束、失败帧与最后值并存、`reload` 转发。`tests/apply.client.spec.ts` 在 `SlotTestRuntime` 里挂载插件，经一个根作用域探针组件验证 `useResource` 到达 props、渲染它即打开提供方的流、dispose 插件同时撤走服务与 hook。
+
+## Deferred
+
+回收空闲记录、与 Remote 面解耦的资源自有失败类型、`chat` 与 `terminal` 协议都还开放；各自等待一个消费方。面向开发者的参考是 [docs/subsystems/client-resources.md](../../../../docs/subsystems/client-resources.zh.md)；消费这个模型的 Sidebar 见 [docs/subsystems/sidebar-right.md](../../../../docs/subsystems/sidebar-right.zh.md)。

.agents/notes/implemented/architecture/2026-09-05-sidebar-tab-types-and-navigation.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-05-sidebar-tab-types-and-navigation.md
+2026-09-05-sidebar-tab-types-and-navigation.md: a79292eba25828287ce43ad16b7eb917dcdddcb4
+2026-09-05-sidebar-tab-types-and-navigation.zh.md: bf661948036257366714617b192525ac35b0905f

.agents/notes/implemented/architecture/2026-09-05-sidebar-tab-types-and-navigation.md

@@ -0,0 +1,121 @@
+# Agent Note: Right Sidebar tab types and navigation
+
+Status: implemented
+
+English | [中文](2026-09-05-sidebar-tab-types-and-navigation.zh.md)
+
+## Problem
+
+The [docking surface](../feature/2026-09-04-right-sidebar-docking-infrastructure.md) gives the right Sidebar panes, tabs, and floating panels, but a pane full of tabs is only useful if other plugins can put content into them. That needs three contracts the surface itself does not define: how a plugin declares a kind of tab and the addresses it can show, how any caller — a produced-file chip in the conversation, a row in a file tree, a plugin's own button — asks the Sidebar to show something, and what a tab's body may rely on at runtime. Each contract is a public face that plugins shipped from outside this repository will write against, so each has to be settled before those plugins exist: a renamed field, a changed enum value, or a different address grammar afterwards breaks every one of them.
+
+Two constraints shaped the answers. Dynamic client plugins may not import runtime values from one another — a function, a constant, a class — only types, so nothing in these contracts may require a helper function or an exported constant from the Sidebar package. And the Web client already has one component model, the Slot system; a second one for tabs would be a parallel framework to learn and maintain.
+
+## Decision
+
+A tab type is a static registration into `ctx.sidebarRightTabs`; a tab's body and title are ordinary keyed Slot registrations; `ctx.sidebarRight` opens content in exactly two ways — a resource by address, or a page by kind — and otherwise only operates the layout; and bodies read occurrence information through the framework-injected `useTabInfo()`. The four faces are described below in the order a plugin author meets them.
+
+### The type registry: `ctx.sidebarRightTabs`
+
+`register(definition): () => void` records one tab type and returns the disposer the caller holds in its own `ctx.effect`, so a type lives exactly as long as the plugin that contributed it. The definition is static:
+
+```ts ignore-check
+interface SidebarRightTabDefinition {
+  readonly id: string                                   // this implementation's identity in the tab system
+  readonly kind: string                                 // what the tabs of this type are; what openTab names
+  readonly patterns?: readonly string[]                 // resource-address globs; omitted by a page type
+  readonly priority?: 'extension' | 'builtin' | 'fallback'   // defaults to extension
+  readonly canOpen?: (address: string) => boolean       // veto after a glob matched
+  readonly title: (address: string) => string           // chip text, captured at open time
+  readonly guide?: readonly SidebarRightGuideEntry[]    // entry boxes on the guide page
+}
+```
+
+`id` and `kind` are different things. `kind` is the type discriminator — what a tab *is*, what `openTab` names, what tab identity is built from. `id` is the identity of one *implementation* of a kind, unique across every registration; a package name is the natural value. The two are separate because a kind is not unique: an `extension` may register the kind a `builtin` already holds, and the two implementations then coexist in the registry with the extension in force. The registry rejects a second registration of an `id`, a second registration in the same band of a kind, and any registration meeting a `fallback` of the same kind; it accepts exactly the extension-over-builtin pair, and the builtin resumes when the extension unregisters.
+
+`patterns` are globs over resource addresses, matched with `picomatch` under VS Code's editor-resolver rule with one local change: a pattern containing `:` is matched against the whole address (`dsh-resource://file/**`), one without is matched against the URI's path at any depth (`*.md`), matching ignores case and does not hide dotfiles, and an address that is not a URI matches no path pattern. A page type — the guide, the file tree — recognizes no address and omits `patterns`; it is opened by kind.
+
+`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)` and `guide[].title()` are thunks read on every use, so a language change needs no re-registration. 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`
+
+The type registry says what a type is; the Slot system says what it looks like. A type registers its body into the keyed, session-scoped seat `sidebar.right.pane.tab` under its own `id`, and may register a title component into `sidebar.right.pane.tab.title` under the same key. The seat that draws a tab resolves the tab's `kind` to the type in force through the registry and dispatches to that type's `id`, so an extension taking over a builtin's kind is rendered without either package knowing about the other, and without any priority number crossing a package boundary. A kind with no type in force renders the owner's "nothing can view this" notice; a type with no title registration gets the `title(address)` text the registry captured when the tab opened.
+
+Two further seats extend the guide and the menu: `sidebar.right.tab.guide` is a chain whose first non-declining entry replaces the shipped guide body without replacing the tab, and `sidebar.right.tab.menu.item` is a list appended after the kit's own layout actions, for actions that mean something about a tab's content. A type's controls — a reload, a wrap toggle — live inside its own body; the strip belongs to the panel and carries only the panel's controls. A type's own state is an ordinary Slot store and inject face on the body registration; the framework adds nothing to the component model.
+
+### Tab occurrence information
+
+[Responsive Sidebar and tab information](2026-09-07-sidebar-responsive-tab-info.md) supersedes this note's choice of flat owner props for occurrence information. Bodies, titles and guide replacements receive the framework-injected `useTabInfo()` to read `{ sidebar, panel, tab }`. The record, navigation, visibility, signal and bound actions live inside `tab`; exact fields belong to the [Sidebar reference](../../../../docs/subsystems/sidebar-right.md).
+
+The Tab domain still owns one occurrence per committed record, with an `AbortController`, navigation snapshot and actions bound to its Session. It pins the address in the [resource model](2026-09-05-client-resource-model.md) for the record's lifetime; hiding and switching Sessions do not end it, while closing the record aborts and releases it. Existing framework store and navigation hooks provide live reads, without subscriptions in tab implementations.
+
+### Navigation: `ctx.sidebarRight`
+
+The face opens content in two ways and does nothing else with content:
+
+```ts ignore-check
+openResource(address: string, options?: { kind?: string; params?: SidebarRightResourceParams; paneId?; replaceTab?: TabId; revealIfOpened?: boolean }): void
+openTab<K extends string>(kind: K, options?: { params?: SidebarRightTabParamsFor<K>; paneId?; replaceTab?: TabId; revealIfOpened?: boolean }): void
+```
+
+`openResource` takes a resource address — a `dsh-resource://<type>/…` URI, the only scheme the resource model has — and asks the registry who shows it: without `kind`, every type is consulted and the ranking decides; with `kind`, that type's implementation in force opens it. An address with any other scheme fails on the same path as an address nothing claims. `openTab` opens a page type by kind and never sees an address: the Sidebar records the tab under `sidebar://<kind>`, composed in one place inside the package, so that a page tab has a `contentId` for identity and history like any other tab. The scheme is bookkeeping: no caller composes it, no business package contains the literal, and the file tree and the guide are opened as `openTab('files')` and `openTab('guide')`.
+
+Both opens run the same four steps: resolve the type (by ranking or by kind), locate an existing tab by `(kind, contentId)` unless `revealIfOpened` is `false`, place the tab — in `replaceTab`'s pane and strip slot, in `paneId`, or in the active pane — and record the expansion, the open-or-focus, and the `replaceTab` close as one history entry before handing `{ address, params }` to the tab domain. Placement is the caller's business, never a type-level trait: the file tree opens into its own pane because it says so, as VS Code's Explorer passes `SIDE_GROUP` or `ACTIVE_GROUP` itself. `replaceTab` means one thing — open in that tab's place and close it in the same step — and exists for the guide's entry boxes, which hand their tab over to the page they name.
+
+Parameters are typed by what is being opened, through two merge-extensible maps declared in the Sidebar package and augmented by the owners of the keys:
+
+```ts
+interface SidebarRightResourceParamsMap {}   // key: resource type — the text preview declares { line?: number }
+interface SidebarRightTabParamsMap {}        // key: kind — a page type declares its own shape, or nothing
+```
+
+`openResource` accepts the union of every declared resource shape and `openTab<K>` the shape declared for `K`; a body narrows `navigation.params` by the protocol or kind it knows it serves. Parameters belong to the resource type rather than to the viewer because a line number is a fact about a file location, not about the text preview, and any type that claims `file` addresses receives the same shape. Values must be JSON-serializable, and a record must be rebuildable from address and parameters alone, because undo, redo, reload, and HMR rebuild tabs after the opener is gone.
+
+Beside the two opens, the face carries `close(tabId)`, `active()`, `isExpanded()`, `toggleExpanded()`, and four operational methods — `focus(tabId)`, `split(paneId?)` (returning the new pane, or `undefined` when the pane budget or the width rule forbids the split, recording nothing), `float(tabId, rect?)`, and `dock(paneId)` — each recording one history entry and a no-op on a missing target or one already in the requested state. There is no layout snapshot, no subscription, and no lookup by address: the face grants control over the layout, not a view of it. The seat publishes its binding — its session, its store's actions, and its surface — while mounted; a command on the public face acts on the mounted session and throws with no mounted session surface. A tab's own actions reach their session's own store instead: the slot runtime mints one store per session, the plugin adopts each as it is minted, and the controller routes by session id, so an action fired after the user switched sessions still lands, and does nothing for a session whose store was never minted.
+
+### Addresses
+
+Addresses come in two families that never mix. Resource addresses are the resource model's `dsh-resource://<type>/…` URIs (a workspace file is `dsh-resource://file/session/<sessionId>/<path relative to that session's workspace root>`, an arbitrary file `dsh-resource://file/absolute/<absolute path>`, both built and parsed by `dsh-util-workspace-path`); they are what `openResource` takes, what `patterns` match, and what `useResource` reads. Navigation addresses name pages rather than data; today the only one is the internal `sidebar://<kind>` a page tab is recorded under. Only the resource family is a contract: the navigation family is composed and consumed inside the Sidebar, and a fuller navigation protocol is a later decision that this one leaves room for by keeping every navigation literal in one place.
+
+### Entry points
+
+The conversation's `openFile(path, { line? })` — tool-row path links, produced-file chips, closing-message mentions — encodes the path as a file resource address for the Session, and calls `openResource` with `params.line` when the caller knows one; the `read` tool row passes the line its `offset` argument started from. The strip's `+` calls `openTab('guide', { paneId, revealIfOpened: false })` for the pane it sits in; a guide entry box calls `tab.actions.openTab(entry.kind, { replaceTab: true })`; a file-tree row calls `tab.actions.openResource(address)`, which lands in the tree's own pane.
+
+## Alternatives considered
+
+**A chain slot for tab dispatch, or a keyed slot alone.** A chain's `select` is not enumerable, and the guide page and the navigation face must enumerate types; a keyed slot carries a body and nothing else, so a type's title and address recognition had nowhere to live. Two stages — a definition registry plus keyed component seats — is the repository's existing pattern (`ConversationViewRegistry`).
+
+**Runtime hooks or an instance object per tab.** Several forms were tried on paper — a Cordis fiber per tab, an abstract base class, an `initial`/`create` pair returning an instance with `dispose`, a set of `useTab*` hooks, a framework-managed `useTabResource(fetch)`, a `useTabStream`. Rejected in turn: a fiber per tab is far too heavy; dynamic packages cannot share a base class or an exported constant; an instance layer duplicates what a Slot store and inject face already are; per-tab hooks restate owner props; a framework-owned fetch has no good cache key; and a stream hook on the tab domain asks the wrong owner — chat data must come from the chat domain, file data from the workspace file service. What remains is owner props plus one client-wide `useResource`. `visible` was later added as a prop rather than a hook for the same reason: it is one more fact about the occurrence, and the props already carry the occurrence. The rejection of occurrence-reading hooks is superseded by the [tab information decision](2026-09-07-sidebar-responsive-tab-info.md); the independent instance, fiber and data-stream ownership rationale still applies.
+
+**A per-pane tools seat for the active tab's controls (`sidebar.right.pane.tab.tools`).** Shipped for one review round, then removed: it put type-private buttons on the panel's strip beside the split and collapse controls, where they read as panel chrome. A type's controls belong in its own body.
+
+**Type-level placement (`opensInto`) and a hidden sibling heuristic.** Rejected: where a tab lands is the opener's business, exactly as VS Code's Explorer decides `sideBySide` itself.
+
+**Extension lists and numeric priorities.** `claims.extensions` cannot express `.d.ts`, `Dockerfile`, a directory constraint, or a whole scheme — it is a degenerate glob; numeric priorities need an exported constant that dynamic packages cannot import. Literal bands over globs. VS Code's own bands were reduced from five to three: an `option` band (listed, never chosen automatically) has no consumer until an "open with…" affordance exists, and a `default` band was renamed `extension` because the name read as the lowest tier while it is the highest.
+
+**One `open(address)` for everything, with a helper that builds page addresses.** The first design opened pages by address too, so a business package needed a `sidebar://<kind>` literal or a `sidebarAddress(kind)` helper from the Sidebar package. Both are forbidden by the value-import rule and both leak a navigation scheme that is not yet designed. Splitting the face into `openResource` and `openTab` puts the only literal inside the package and lets each mode type its parameters.
+
+**Naming a specific implementation when opening (`?impl=`), `find(address)`, `mode()`/`setMode()`, a layout snapshot, a `features` list.** All considered and left out. Naming an implementation belongs to a navigation protocol that does not exist yet; `find` and a snapshot would make the face a view of the layout when it is meant to be control over it; presentation mode is a UI toggle, not a plugin concern; a capability list is premature while the face is settling.
+
+**Slot priorities to express an extension taking over a builtin, then registry-minted slot keys.** The first attempt had the overriding type register its body at a lower slot priority through an exported constant — a value import across dynamic plugins, and a second rule system (slot priority) standing in for the registry's. The second attempt had the registry mint a key per registration and return it from `register()`, which made registration a two-step dance whose ordering mattered. Letting the implementation declare its own `id` — required, unique, the same string it registers its seats under — needs no constant, no minting, and no ordering, and gives the registry the identity it needs to reject duplicates.
+
+## Consequences
+
+- A type is one static object plus one or two keyed seat registrations; its occurrence information is read through injected `useTabInfo()`. The framework grows no per-type API surface, and a type shipped from outside this repository imports only types from the Sidebar package.
+- Two opens with two parameter maps mean a caller cannot open a page by address or a resource by kind alone, and the compiler tells it so; the cost is that every new resource type or page kind that wants typed parameters augments a map.
+- `id` and `kind` being distinct lets an extension replace a shipped type in place, per kind, with the builtin resuming when the extension unregisters; the cost is one more required field on every definition.
+- The navigation face is control-only. A plugin that needs to know the layout cannot ask for it, which keeps the layout's shape out of every plugin's contract until a navigation protocol decides what to expose.
+- The `sidebar://<kind>` literal lives in one file. Changing the navigation grammar later touches the Sidebar package and nothing else.
+- These faces are the part of the Sidebar that is fixed: addresses, registration fields and bands, the two opens and their parameter maps, seat names and injected tab information. Everything a user sees as behaviour — where a float snaps, when a split control greys out, the copy, the tree's ordering — is a product rule outside every contract here and changes without notice to any plugin.
+
+## Testing
+
+`ui-sidebar-right` specs cover the registry (bands, extension-over-builtin with resumption, `id` and same-band collisions, glob and path matching, `canOpen`, ranking and tiebreaks), both opens (normal, edge, and failure paths including the wrong scheme and an unregistered kind), `replaceTab` as one history entry, the seat resolving a kind to the implementation in force and back, `useTabInfo()` including `tab.visible` under collapse and floating, and the operational methods with their no-op and throw cases. The Web e2e suite drives the guide, the file tree, and a file open through the real plugin graph in Chromium. Both suites are keyless.
+
+## Deferred
+
+- A navigation protocol beyond `sidebar://<kind>`: sub-routes within a page, naming an implementation, and the ecosystem-facing rules for other navigation schemes.
+- Parameters for the shipped page types, which today declare none.
+- Opening into a session other than the one on screen from the public face, which acts on the mounted session only; a tab's own actions already act on their tab's session.
+- A localized message when an open fails from the conversation; the failure is currently the thrown error's text.

.agents/notes/implemented/architecture/2026-09-05-sidebar-tab-types-and-navigation.zh.md

@@ -0,0 +1,121 @@
+# Agent Note: 右侧 Sidebar 的 tab 类型与导航
+
+Status: implemented
+
+[English](2026-09-05-sidebar-tab-types-and-navigation.md) | 中文
+
+## Problem
+
+[停靠面](../feature/2026-09-04-right-sidebar-docking-infrastructure.zh.md)给了右侧 Sidebar 分栏、tab 与浮动面板，但一格 tab 只有在别的插件能往里放内容时才有用。这需要三份停靠面自身不定义的契约：插件如何声明一种 tab 及其能展示的地址；任何调用方——会话区里的产出文件 chip、文件树里的一行、插件自己的按钮——如何请 Sidebar 展示某样东西；以及 tab 的正文在运行时能依赖什么。每一份都是仓外插件将来要对着写的公开面，所以必须在那些插件出现之前定下来：之后改一个字段名、一个枚举值或地址语法，就会同时弄坏它们全部。
+
+两条约束决定了答案。动态客户端插件之间不允许引用运行时值——函数、常量、类——只能引类型，因此这些契约里不得要求从 Sidebar 包引入帮助函数或导出常量。而 Web 客户端已经有一套组件模型，即 Slot 系统；再为 tab 造一套，就是第二个要学要维护的并行框架。
+
+## Decision
+
+tab 类型是向 `ctx.sidebarRightTabs` 的一次静态注册；tab 的正文与标题是普通的 keyed Slot 注册；`ctx.sidebarRight` 只以两种方式打开内容——按地址开资源、按 kind 开页——其余只操作布局；正文通过框架注入的 `useTabInfo()` 读取实例信息。下面按插件作者遇到的顺序描述这四个面。
+
+### 类型注册表：`ctx.sidebarRightTabs`
+
+`register(definition): () => void` 记录一种 tab 类型并返回注销器，调用方把它放进自己的 `ctx.effect`，于是类型的寿命恰好等于贡献它的插件。定义是静态的：
+
+```ts ignore-check
+interface SidebarRightTabDefinition {
+  readonly id: string                                   // this implementation's identity in the tab system
+  readonly kind: string                                 // what the tabs of this type are; what openTab names
+  readonly patterns?: readonly string[]                 // resource-address globs; omitted by a page type
+  readonly priority?: 'extension' | 'builtin' | 'fallback'   // defaults to extension
+  readonly canOpen?: (address: string) => boolean       // veto after a glob matched
+  readonly title: (address: string) => string           // chip text, captured at open time
+  readonly guide?: readonly SidebarRightGuideEntry[]    // entry boxes on the guide page
+}
+```
+
+`id` 与 `kind` 是两回事。`kind` 是类型判别符——tab *是什么*、`openTab` 点名什么、tab 身份由什么构成。`id` 是某个 kind 的一个*实现*的身份，在全部注册里唯一，包名是自然的取值。两者分开是因为 kind 并不唯一：`extension` 可以注册一个 `builtin` 已持有的 kind，两个实现随即在注册表里共存，生效的是 extension。注册表拒绝重复的 `id`、同一 kind 在同一档的第二次注册、以及任何与同 kind 的 `fallback` 相遇的注册；它只接受 extension 压 builtin 这一对，extension 注销后 builtin 恢复。
+
+`patterns` 是资源地址上的 glob，用 `picomatch` 按 VS Code 编辑器解析器的规则匹配，只有一处本地改动：含 `:` 的 pattern 匹配整个地址（`dsh-resource://file/**`），不含的匹配 URI 的路径且任意深度（`*.md`），匹配不区分大小写、不隐藏 dotfile，不是 URI 的地址不匹配任何路径 pattern。页类型——引导页、文件树——不识别任何地址，省略 `patterns`，按 kind 打开。
+
+`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()` 是每次使用时重读的 thunk，语言切换无需重新注册。注册表本身是 `apply` 顶层提供的普通对象，**不带** `Service.tracker`：tracker 会把 `this.ctx` 重绑到调用方上下文，跨包 `register()` 就会在调用方 fiber 仍是活动作用域时往它上加 effect，浏览器启动会无声卡死。
+
+### 正文与标题：按定义 `id` keyed 的 Slot 坑位
+
+类型注册表说类型是什么；Slot 系统说它长什么样。类型把正文注册进 keyed、session 作用域的坑位 `sidebar.right.pane.tab`，键是自己的 `id`，并可把标题组件注册进 `sidebar.right.pane.tab.title`，键相同。画 tab 的座位经注册表把 tab 的 `kind` 解析成生效类型，再派发到该类型的 `id`，于是 extension 接管 builtin 的 kind 时两个包互不知晓也能正确渲染，且没有任何优先级数字跨过包边界。没有生效类型的 kind 渲染属主的「没有东西能查看它」提示；没注册标题的类型得到注册表在打开时捕获的 `title(address)` 文本。
+
+另有两个坑位扩展引导与菜单：`sidebar.right.tab.guide` 是 chain，第一个不拒绝的条目在不替换 tab 的前提下替换随包引导正文；`sidebar.right.tab.menu.item` 是 list，追加在库自身布局动作之后，放与 tab 内容有关的动作。类型自己的控件——重载、换行开关——住在自己正文里；tab 条属于面板，只放面板的控件。类型自己的状态是正文注册上普通的 Slot store 与 inject 面；框架不给组件模型添任何东西。
+
+### 标签实例信息
+
+[响应式 Sidebar 与标签信息](2026-09-07-sidebar-responsive-tab-info.zh.md)取代本记录中以平铺 owner props 传递实例信息的选择。正文、标题与引导页替换项接收框架注入的 `useTabInfo()`，以 `{ sidebar, panel, tab }` 读取所属 Sidebar、窗格与标签。实例的记录、导航、可见性、signal 与绑定动作均在 `tab` 内；精确字段见 [Sidebar 参考](../../../../docs/subsystems/sidebar-right.zh.md)。
+
+标签域仍为每个已提交记录拥有一个实例，包括 `AbortController`、导航快照和绑定到所属 Session 的动作。记录存活期间，其地址被钉在[资源模型](2026-09-05-client-resource-model.zh.md)中；隐藏与切换 Session 不结束实例，关闭记录则中止并释放它。框架已有的存储与导航钩子提供实时读取，类型不自行订阅。
+
+### 导航：`ctx.sidebarRight`
+
+该面以两种方式打开内容，对内容不做别的事：
+
+```ts ignore-check
+openResource(address: string, options?: { kind?: string; params?: SidebarRightResourceParams; paneId?; replaceTab?: TabId; revealIfOpened?: boolean }): void
+openTab<K extends string>(kind: K, options?: { params?: SidebarRightTabParamsFor<K>; paneId?; replaceTab?: TabId; revealIfOpened?: boolean }): void
+```
+
+`openResource` 接一个资源地址——`dsh-resource://<type>/…` URI，资源模型仅有的 scheme——并问注册表谁来展示：不带 `kind` 时问遍所有类型由排序决定；带 `kind` 时由该类型生效的实现打开。其它 scheme 的地址与无人认领的地址走同一条失败路径。`openTab` 按 kind 打开页类型，永远见不到地址：Sidebar 把该 tab 记账在 `sidebar://<kind>` 下，这个字面量只在包内一处拼装，为的是页 tab 与其它 tab 一样有 `contentId` 供身份与历史使用。这个 scheme 只是记账：没有调用方拼它，业务包里没有这个字面量，文件树与引导页分别以 `openTab('files')`、`openTab('guide')` 打开。
+
+两种打开走同样四步：解析类型（按排序或按 kind）；除非 `revealIfOpened` 为 `false`，否则按 `(kind, contentId)` 定位已有 tab；落位——落在 `replaceTab` 的格与条位、`paneId`、或活跃格；把展开、打开或聚焦、以及 `replaceTab` 的关闭记为一条历史，再把 `{ address, params }` 交给 tab 域。落位是调用方的事，从不是类型级特性：文件树把文件开进自己的格是因为它自己说了，正如 VS Code 的 Explorer 自己传 `SIDE_GROUP` 或 `ACTIVE_GROUP`。`replaceTab` 只有一个含义——在那个 tab 的位置打开并在同一步关掉它——为的是引导页入口框把自己的 tab 交给所点的页。
+
+参数按被打开的东西定型，经 Sidebar 包声明、由键的拥有者增补的两张可声明合并表：
+
+```ts
+interface SidebarRightResourceParamsMap {}   // key: resource type — the text preview declares { line?: number }
+interface SidebarRightTabParamsMap {}        // key: kind — a page type declares its own shape, or nothing
+```
+
+`openResource` 接受所有已声明资源形状的联合，`openTab<K>` 接受为 `K` 声明的形状；正文按自己所服务的协议或 kind 收窄 `navigation.params`。参数属于资源类型而非查看器，因为行号是关于文件位置的事实，不是关于文本预览的，任何认领 `file` 地址的类型收到同一形状。值必须可 JSON 序列化，一条记录必须只凭地址与参数就能重建，因为撤销、重做、刷新与 HMR 都在开启方已不在时重建 tab。
+
+除两种打开外，该面还有 `close(tabId)`、`active()`、`isExpanded()`、`toggleExpanded()`，以及四个操作型方法——`focus(tabId)`、`split(paneId?)`（返回新格，预算或宽度规则不允许分栏时返回 `undefined` 且不记账）、`float(tabId, rect?)` 与 `dock(paneId)`——每个记一条历史，目标不存在或已在目标态时为 no-op。没有布局快照、没有订阅、没有按地址查找：该面给的是对布局的控制权，不是布局的视图。座位挂载期间发布其绑定——自己的会话、其 store 的 action 与其面；公开面上的命令作用于已挂载会话，没有已挂载会话面时抛错。tab 自己的动作则到达其会话自己的 store：slot 运行时每个会话铸一个 store，插件在铸出时逐个收养，控制器按会话 id 路由，因此用户切换会话之后触发的动作照样落地，而 store 从未铸出的会话什么也不做。
+
+### 地址
+
+地址分两族，永不混用。资源地址是资源模型的 `dsh-resource://<type>/…` URI（工作区文件是 `dsh-resource://file/session/<sessionId>/<相对该会话工作区根的路径>`，任意文件是 `dsh-resource://file/absolute/<绝对路径>`，都由 `dsh-util-workspace-path` 构造与解析）；它们是 `openResource` 的入参、`patterns` 的匹配对象、`useResource` 的读取对象。导航地址命名的是页而非数据；今天唯一的一种是页 tab 记账用的内部 `sidebar://<kind>`。只有资源族是契约：导航族在 Sidebar 内部拼装与消费，更完整的导航协议是之后的决定，本决定通过把所有导航字面量留在一处为它预留空间。
+
+### 入口
+
+会话区的 `openFile(path, { line? })`——工具行路径链接、产出文件 chip、收尾消息提及——把路径编码为该 Session 的文件资源地址并调用 `openResource`，调用方知道行号时带 `params.line`；`read` 工具行传入其 `offset` 参数起始的行。tab 条的「+」为所在格调用 `openTab('guide', { paneId, revealIfOpened: false })`；引导入口框调用 `tab.actions.openTab(entry.kind, { replaceTab: true })`；文件树的一行调用 `tab.actions.openResource(address)`，落在树自己的格里。
+
+## Alternatives considered
+
+**用 chain 坑位派发 tab，或只用 keyed 坑位。** chain 的 `select` 不可枚举，而引导页与导航面必须枚举类型；keyed 坑位只带正文，类型的标题与地址识别无处可住。两段——定义注册表加 keyed 组件坑位——是仓库既有模式（`ConversationViewRegistry`）。
+
+**运行时 hook 或每 tab 一个实例对象。** 纸面上试过多种形态——每 tab 一个 Cordis fiber、抽象基类、返回带 `dispose` 实例的 `initial`/`create` 对、一组 `useTab*` hook、框架托管的 `useTabResource(fetch)`、`useTabStream`。依次否决：每 tab 一个 fiber 太重；动态包无法共享基类或导出常量；实例层重复了 Slot store 与 inject 面已经是的东西；每 tab hook 复述 owner props；框架托管的 fetch 没有好的缓存键；tab 域上的流 hook 问错了主人——聊天数据必须来自聊天域，文件数据来自工作区文件服务。剩下的是 owner props 加一个全客户端的 `useResource`。`visible` 后来以 prop 而非 hook 加入也是同一理由：它是关于该次出现的又一个事实，而 props 已经承载了该次出现。 对实例读取钩子的否决由[标签信息决策](2026-09-07-sidebar-responsive-tab-info.zh.md)取代；对独立实例对象、fiber 与数据流所有权的理由仍适用。
+
+**每格一个工具区坑位放活跃 tab 的控件（`sidebar.right.pane.tab.tools`）。** 上线一轮评审后删除：它把类型私有按钮放到面板 tab 条上、与分栏和收起控件并列，读起来像面板 chrome。类型的控件属于自己的正文。
+
+**类型级落位（`opensInto`）与隐藏的相邻格启发式。** 否决：tab 落在哪是开启方的事，正如 VS Code 的 Explorer 自己决定 `sideBySide`。
+
+**扩展名列表与数字优先级。** `claims.extensions` 表达不了 `.d.ts`、`Dockerfile`、目录约束或整个 scheme——它是退化的 glob；数字优先级需要动态包无法引入的导出常量。字面量档位加 glob。VS Code 自己的档位从五个收成三个：`option` 档（只列出、永不自动选中）在「用其他方式打开」存在之前没有消费者，`default` 档改名 `extension`，因为那个名字读起来像最低档而它是最高档。
+
+**一个 `open(address)` 包打天下，外加拼页地址的帮助函数。** 第一版页也按地址打开，于是业务包需要 `sidebar://<kind>` 字面量或来自 Sidebar 包的 `sidebarAddress(kind)` 帮助函数。两者都被值引用规则禁止，也都泄露了尚未设计的导航 scheme。把面拆成 `openResource` 与 `openTab`，唯一的字面量留在包内，且每种模式各自定型参数。
+
+**打开时点名某个实现（`?impl=`）、`find(address)`、`mode()`/`setMode()`、布局快照、`features` 清单。** 都考虑过并留在外面。点名实现属于尚不存在的导航协议；`find` 与快照会把该面变成布局的视图，而它本该是对布局的控制；呈现模式是 UI 开关不是插件关心的事；能力清单在该面尚在收敛时为时过早。
+
+**用 Slot 优先级表达 extension 接管 builtin，随后是注册表铸造的坑位键。** 第一次尝试让覆盖方经一个导出常量以更低的 Slot 优先级注册正文——这是动态插件间的值引用，也是拿第二套规则（Slot 优先级）替注册表的规则站台。第二次尝试让注册表为每次注册铸一个键并从 `register()` 返回，这把注册变成了两步且顺序敏感的舞步。让实现自己声明 `id`——必填、唯一、与它注册坑位所用的同一个串——既不需要常量，也不需要铸键与顺序，还给了注册表拒绝重复所需的身份。
+
+## Consequences
+
+- 一个类型 = 一个静态对象 + 一到两个 keyed 坑位注册；其实例信息通过注入的 `useTabInfo()` 读取。框架不长任何按类型的 API 面，仓外类型从 Sidebar 包只引类型。
+- 两种打开配两张参数表，意味着调用方无法只按地址开页或只按 kind 开资源，编译器会说明；代价是每个想要类型化参数的新资源类型或页 kind 都要增补一张表。
+- `id` 与 `kind` 分离让 extension 能按 kind 原位替换随包类型，extension 注销后 builtin 恢复；代价是每个定义多一个必填字段。
+- 导航面只有控制权。需要知道布局的插件无法索取，这让布局的形状在导航协议决定暴露什么之前不进任何插件的契约。
+- `sidebar://<kind>` 字面量住在一个文件里。之后改导航语法只碰 Sidebar 包。
+- 这些面是 Sidebar 里被定死的部分：地址、注册字段与档位、两种打开及其参数表、slot 名与注入的标签信息。用户看到的一切行为——浮窗贴到哪、分栏控件何时置灰、文案、树的排序——都是这里任何契约之外的产品规则，改动无需通知任何插件。
+
+## Testing
+
+`ui-sidebar-right` 的 spec 覆盖注册表（档位、extension 压 builtin 及恢复、`id` 与同档冲突、glob 与路径匹配、`canOpen`、排序与平局）、两种打开（正常、边界与失败路径，含错误 scheme 与未注册 kind）、`replaceTab` 记一条历史、座位把 kind 解析到生效实现并回退、`useTabInfo()` 含折叠与浮窗下的 `tab.visible`、以及操作型方法的 no-op 与抛错情形。Web e2e 套件在 Chromium 里经真实插件图驱动引导页、文件树与一次文件打开。两套均无需密钥。
+
+## Deferred
+
+- `sidebar://<kind>` 之外的导航协议：页内子路由、点名实现、以及面向生态的其它导航 scheme 规则。
+- 随包页类型的参数，今天未声明任何。
+- 从公开面往屏上会话之外的会话里打开；公开面只作用于已挂载的会话，而 tab 自己的动作已作用于其所在会话。
+- 从会话区打开失败时的本地化提示；目前是抛错文本本身。

.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-05-workspace-files-service.md
+2026-09-05-workspace-files-service.md: a95e083f8cea57b957a2c060fe1b7f2b76050153
+2026-09-05-workspace-files-service.zh.md: 59c638157f3e65efe3b89b220401434d1f2370b0

.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.md

@@ -0,0 +1,151 @@
+# Agent Note: Workspace file service
+
+Status: implemented
+
+English | [中文](2026-09-05-workspace-files-service.zh.md)
+
+## Problem
+
+The Web client needs to look at files inside a session's workspace from a browser that may not be on the Host machine: a file the agent produced, the path a `read` tool row names, later a file tree and previews of files that are neither small nor text. The one endpoint that read a workspace file over the wire lived on the Session Controller as `workspace-file.ts`, beside session lifecycle it had nothing to do with. It returned a whole file under one total byte cap, so a large log could not be looked at even in part and a binary could not be looked at at all; it had no `stat`, no listing, and no change signal, so a preview could not learn that the agent had rewritten the file without re-reading it; and its result named the file by a Host `url`, a spelling nothing on the Client used as an address.
+
+Two constraints frame any answer. Reads through `ctx.fs` are deliberately unconfined — the sandboxing backend fences writes and edits only and says so — so a web-facing read endpoint must own every fence itself, and the fences must survive a symlink that leaves the workspace, which a string-prefix test cannot see. And `dsh-fs` exposed one raw-byte read, `readBytes(target, signal, maxBytes)`, which refuses any file longer than its cap: correct for an image the model ingests whole, useless for one window of a large file.
+
+## Decision
+
+`packages/api/workspace-files` (`@deepseek-ai/dsh-api-workspace-files`) owns the Host `ctx.workspaceFiles` service, the `workspaceFiles` Remote namespace, and the Client `file` provider that turns `stat` and `changes` into live metadata for the [resource model](2026-09-05-client-resource-model.md); [dual-face packaging](2026-09-07-workspace-files-dual-face-package.md) governs their package organization. Every method confines itself to the workspace root the sandbox policy resolves for the addressed session, names files by their absolute path in the filesystem's execution world, and pages or windows content so that no method ever buffers a whole file. The byte window rides on a new `dsh-fs` seam, `FileSystem.readByteRange`, implemented by every provider. The Session Controller carries no workspace-file code.
+
+### Package topology
+
+[dual-face packaging](2026-09-07-workspace-files-dual-face-package.md) supersedes this note's choice of separate Host and Client packages; the file service, authorization, paging, and change-feed decisions here remain in force. Host and Client compile in separate leaf configurations, share wire types, and the Client does not import the Host runtime entry.
+
+| Face | Package | Files | Depends on |
+|---|---|---|---|
+| Host | `api/workspace-files/tsconfig.host.json` | `src/index.ts` (`WorkspaceFiles`, `Config`, gates, pager), `src/changes.ts` (`WorkspaceChangeFeed`), `src/types.ts` (wire types, error codes) | `dsh-fs`, `dsh-sandbox-policy`, `dsh-typert-protocol`, `dsh-agent`, `dsh-session` |
+| Client | `api/workspace-files/tsconfig.client.json` | `src/client/index.ts` (plugin body), `provider.ts`, `change-feed.ts`, `remote.ts`, `types.ts`, and shared `src/types.ts` | `dsh-api-gateway/client`, `dsh-api-session-controller/client`, `dsh-client-resources`, `dsh-util-workspace-path`, `dsh-typert-protocol`, and the package's generated `./remote` |
+
+`api/remotes` and both root aggregates reference the matching Host/Client leaf. The package exports `.`, `./client`, `./types`, `./typert`, and `./remote`, with one `workspace-files` web-app row supplying both faces. The Client plugin injects `['resources', 'remote', 'remote.workspaceFiles', 'sessions']`; the resource model takes result types directly from the protocol package, and the text preview owns the Sidebar parameter declaration, so the Client compilation graph has no reverse dependency on Remote assembly or Sidebar UI.
+
+### The `workspaceFiles` Remote namespace
+
+Every Host method takes the target `Agent` first, resolved by the Gateway from the Session identity on the wire, so a Client calls `remote.workspaceFiles.stat(sessionId, path, signal)` and never names a root. The five signatures, as `src/index.ts` declares them:
+
+```ts ignore-check
+@Remote async read(agent: Agent, path: string, range: WorkspaceFileRange, signal: AbortSignal): Promise<WorkspaceFileText>
+@Remote async readBytes(agent: Agent, path: string, range: WorkspaceByteRange, signal: AbortSignal): Promise<WorkspaceFileBytes>
+@Remote async stat(agent: Agent, path: string, signal: AbortSignal): Promise<WorkspaceFileStat>
+@Remote async list(agent: Agent, path: string, signal: AbortSignal): Promise<WorkspaceDirectoryListing>
+@Remote({ mode: 'stream' }) changes(agent: Agent, signal: AbortSignal): AsyncIterable<WorkspaceFileWatchFrame>
+```
+
+- **`stat`** returns `WorkspaceFileStat { absolutePath, version, bytes? }`: the file's identity, its opaque freshness token, and its size when the backend reports one. It accepts a regular file only.
+- **`read`** returns one window of lines, `WorkspaceFileText = WorkspaceFileStat & { offset, text, lines, eof }`; `lines` counts the page's lines, so a page holding one empty line (`text: ''`, `lines: 1`) and a page past the end (`lines: 0`) read differently. `range.offset` is the 1-based first line and defaults to 1; `range.limit` is the largest number of lines and defaults to `maxLines`, which it may not exceed. Lines end at `\n` and a final `\n` terminates the last line rather than opening an empty one; `text` joins the page's lines with `\n` and carries no terminator; `eof` is true when the page includes the last line, and an offset past the end returns an empty page with `eof` true. The pager walks `streamText`, counts the lines before the window without keeping them, admits each in-window segment against `maxBytes` before buffering it, and returns at the first character past the window, so a file of any size costs one page of memory. The `version` and `bytes` on a page are the stat's, taken before the stream.
+- **`readBytes`** returns one window of raw bytes, `WorkspaceFileBytes = WorkspaceFileStat & { offset, data, eof }`. `range.offset` is the 0-based first byte and defaults to 0; `range.length` is the largest byte count and defaults to `maxBytes`, which it may not exceed. `data` is base64, shorter than `length` where the file ends and empty at or past it; `eof` is true when the window includes the last byte. Nothing is decoded and nothing is refused as binary. `read` pages by lines and never by bytes; a byte window is `readBytes`.
+- **`list`** returns `WorkspaceDirectoryListing { path, entries, truncated }`: the listed directory as a workspace path relative to the root (empty for the root), its direct children in the backend's stable name order as `{ name, type, size? }`, and whether `maxEntries` cut the list. `type` is `file`, `directory`, or `other`; a symlink child reports the type of what it points to and a dangling one is `other`, while opening such a child still fails the link gate below. Dotfiles are listed; nothing is filtered.
+- **`changes`** yields `WorkspaceFileWatchFrame`: `{ kind: 'ready' }` after the observation queue is registered and the workspace root resolves, followed by `{ kind: 'change', change }`. The `WorkspaceFileChange` payload is `{ absolutePath, version }` for a present file or `{ absolutePath, absent: true }` for one observed gone. Its source is `fs/observed` inside the workspace root, never an OS watcher. Observations after the first pull are queued, including during root resolution; cancellation or plugin disposal ends the generation.
+
+### Paths on the wire
+
+Two path vocabularies leave the service, and each method uses exactly one. `read`, `readBytes`, `stat`, and `changes` name a file by `absolutePath`: its absolute path in the filesystem's execution world, symlinks resolved (`ctx.fs.processPath(target)`), so the Client provider matches a change frame to an open address by absolute path: the Client sends the address's path unchanged to the Host and binds the follower only to a successful `stat.absolutePath`, without reading a Session summary's cwd. `list` speaks workspace paths — the same syntax its `path` argument accepts, absolute or relative to the root — because its consumer is a tree rooted there. The field is called `absolutePath` and not `url` because it is not a resource address; the address grammar belongs to `dsh-util-workspace-path` and is described with the resource model. Input paths to `read`, `readBytes`, `stat`, and `list` are absolute or relative to the session's workspace root, never to the backend's own cwd.
+
+`version` is an opaque string a consumer compares for equality and never parses: the local backend derives it from device, inode, size, and nanosecond mtime and ctime, so a rewrite that leaves the content identical still changes it. `offset` means a line on `read` and a byte on `readBytes`; the two units never mix, and `eof` on either means the window reached the file's end.
+
+### The four gates
+
+Every `read`, `readBytes`, `stat`, and `list` passes four gates in order, and the constraints are the service's own because the filesystem does not confine reads. The path is inspected before containment is decided, so a caller learns whether an outside path exists and what kind it is before `outside-workspace` refuses it; that is accepted because the caller is the Session's own owner, who can already read the Host through the Agent.
+
+1. **The path itself.** `lstat` inspects the path before anything follows it: a missing path is `not-found`, and a symlink — wherever it points, including back inside the workspace — is `not-regular-file` (kind `symlink`) for the file methods and `not-directory` for `list`. An empty path is a `gateway/bad-request`.
+2. **Containment.** The path resolves to a target and `ctx.fs.contains(root, target)` decides, where `root` is `sandboxPolicy.resolve({ session }).workspaceRoot` resolved the same way (the session's cwd, falling back to the policy's configured root). A `..` traversal or an absolute path outside the root is `outside-workspace`. A string-prefix comparison is never used: `resolve` realpaths, so a prefix test cannot see a link that leaves the root.
+3. **The caps.** A page or window above `maxBytes`, or a `read` asking for more than `maxLines`, is refused, never shortened, because a silently cut page reads as the whole page; a listing above `maxEntries` is cut and says so.
+4. **Text.** For `read` only: content that is not UTF-8 up to the end of the page, a NUL byte in the backend's 8 KiB opening sample, or a NUL byte anywhere in the page is `not-text`; bytes past the page are not inspected.
+
+After the gates the file methods `stat` the target once more, because the file may have gone or changed kind between the inspection and the read: a vanished file is `not-found` and a replaced one `not-regular-file` with the new kind. The gate order has one visible consequence: an entry outside the root whose type already disqualifies it reports its kind, not its position.
+
+### Failures
+
+Each failure is one `RemoteError` code with typed details, declared beside the throwing code and discriminated by code, never by message.
+
+| Code | When | Details |
+|---|---|---|
+| `workspace-file/not-found` | no entry at the path, or the file vanished after the gates | `{ path }` |
+| `workspace-file/outside-workspace` | the resolved target is not inside the workspace root | `{ path }` |
+| `workspace-file/too-large` | a page's text or a requested byte window exceeds `maxBytes` | `{ path, limit }` |
+| `workspace-file/not-text` | invalid UTF-8 up to the page's end, or a NUL byte in the sample or the page (`read` only) | `{ path }` |
+| `workspace-file/not-regular-file` | `read`, `readBytes`, or `stat` on something that is not a regular file | `{ path, kind: 'directory' \| 'symlink' \| 'other' }` |
+| `workspace-file/not-directory` | `list` on something that is not a directory | `{ path, kind: 'file' \| 'symlink' \| 'other' }` |
+| `workspace-file/unsupported-address` | Client-minted: a resource address this provider cannot serve | `{ address }` |
+| `workspace-file/unknown-workspace` | Client-minted: an `absolute` address with no current Session | `{ address }` |
+| `gateway/bad-request` | an empty path, or an `offset`, `limit`, or `length` that is not an integer in range | `{}` |
+
+The set is append-only: a code may be added, and none is renamed or removed, because consumers branch on these strings across the wire.
+
+### Configuration
+
+Three fields, all validated positive integers changeable from `cordis.yml`, and no other tunables: `maxBytes` (default 2,097,152, 2 MiB) is the inclusive cap on one page's text and on one byte window; `maxLines` (default 5,000) is the default and largest page in lines; `maxEntries` (default 2,000) is the cap on returned directory entries. The file itself has no size cap: a caller pages or windows through it.
+
+### The `readByteRange` seam in `dsh-fs`
+
+A byte window of a large file needs a filesystem read bounded by the window, and `FileSystem` had only `readBytes(target, signal, maxBytes)`, which bounds by the whole file. `dsh-fs` therefore gains a second raw-byte primitive:
+
+```ts ignore-check
+abstract readByteRange(target: FsTarget, range: { offset: number; length: number }, signal?: AbortSignal): Promise<Uint8Array>
+```
+
+It returns the bytes at `[offset, offset + length)`, shorter when the file ends inside the window and empty when `offset` lies at or past the end. The window is the bound: a backend transfers at most `length` bytes beyond the prefix it skips to reach `offset` and never buffers the whole file, so the caller's cap on `length` is the guard against unbounded buffering, sitting beside `readBytes`'s bound rather than replacing it. The parameter order follows `readText`, `streamText`, and `listDir` — target, then the operation's own arguments, then an optional signal — rather than `readBytes`'s signal-in-the-middle form, which is the one exception in the class. Both `offset` and `length` are non-negative integers by precondition; the seam is a typed same-process boundary and validates nothing, and the Remote method validates at the wire.
+
+`fs-local` opens `createReadStream(targetKey, { start: offset, end: offset + length - 1 })` after the same regular-file stat as its other reads, returning an empty array for `length` 0 without opening a stream; `fs-sandbox` extends `LocalFileSystem` and inherits it. `fs-e2b` has an SDK that streams only from a file's start, so it skips `offset` bytes, copies `length` into the window, and cancels the stream the moment the window is full, transferring no more than the window beyond the skipped prefix; a stream that ends first is left to close. The four test doubles that extend `FileSystem` implement the method too.
+
+### The Client `file` provider
+
+The Client export registers one `ResourceProvider<'file'>` into `ctx.resources` for the plugin's lifetime and declares `ResourceProtocolMap.file`. The text-preview package registers this package's exported `WorkspaceFileParams` as `SidebarRightResourceParamsMap.file`.
+
+- **The value is metadata**, `WorkspaceFileResource { absolutePath, version, bytes?, changed }`; content never rides the stream because content can be arbitrarily large and a stream is for pushing change, not payload. A consumer reads pages with `read` (or windows with `readBytes`) and uses `version` and `changed` to know when they are stale.
+- **The address names the file; its scope selects the Session.** A `session` address's relative path reaches the Host unchanged for resolution and containment against that Session's workspace root; Client cwd is not a prerequisite. An `absolute` address reads through the current Session, failing with `workspace-file/unknown-workspace` when none is current. Unsupported grammar yields `workspace-file/unsupported-address`. These two Client errors end the stream and make reload a no-op.
+- **The frames.** The first frame is a `stat` (`changed: false`) or its failure as an `ok: false` frame; the provider throws and catches nothing, because the Remote face never rejects and a throw inside a provider stream is a programming error left to surface. A Host write carrying a version the value does not hold yields `changed: true` with the byte count kept and no stat; a frame carrying the held version is dropped. A reported disappearance stats again — still there is fresh metadata flagged `changed`, gone is a `not-found` frame with the previous value left for display. `reload(address)` stats again and yields `changed: false`. The follow is on the address, not the file: after a failed stat the stream continues, so the agent creating the file, or a reload, brings the resource live. Aborting the signal ends the stream silently.
+- **One `changes` subscription per Session.** The first follower opens `remote.$stream`, the last release disposes it, and successor streams and plugin teardown await pending closes. The Client starts its first `stat` only after accepting Host `ready`; sending a local WebSocket request is not Host acknowledgement. A follower registers by address, queues changes before its path is known, then filters queued and live frames by the successful stat's `absolutePath`, normalizing backslashes to slashes. Any Session write can trigger a re-stat before the first successful binding. Gateway supervision reconnects carrier loss; Host end or terminal failure ends followers and retains their last metadata until reopened.
+- **Navigation parameters.** `SidebarRightResourceParamsMap.file` is `WorkspaceFileParams { line?: number }`, a 1-based line to reveal. A line travels as a navigation parameter and not as part of the address, because the file is one piece of content whether it opens at the top or at line 400.
+
+### Related notes
+
+The [resource model](2026-09-05-client-resource-model.md) owns `ctx.resources`, `useResource`, the `dsh-resource://<type>/…` address grammar, and the reasoning for one resource per address; the [text preview and file tree](../feature/2026-09-05-sidebar-text-preview-and-file-tree.md) are the shipped consumers of `read`, `list`, and the `file` provider; the [right Sidebar docking infrastructure](../feature/2026-09-04-right-sidebar-docking-infrastructure.md) is the surface they open into; [workspace file links](../feature/2026-07-31-web-workspace-file-links.md) is where serving files over HTTP was rejected. Anyone extending this system reaches the same five methods through `remote.workspaceFiles` and the same `file` resource through `useResource<'file'>`; the wire types are published as `@deepseek-ai/dsh-api-workspace-files/types`.
+
+## Alternatives considered
+
+**Keeping the workspace file endpoint on the Session Controller.** The first form: one `read` under a total byte cap, registered as a sub-plugin of the Session Controller because that is where the wire entry already was. Rejected because a Workspace File service is its own capability — reading, statting, listing, and observing files inside a workspace root — and everything that queries workspace files belongs to it, while the Session Controller's concern is session lifecycle. The move also let the service grow to five methods without the Controller's file gaining a second purpose.
+
+**A dual-face package with reverse UI dependencies.** The split-package choice followed two project-reference cycles after `api/remotes` referenced the Client leaf: the resource model imported Remote assembly for result types, and the file provider imported Sidebar UI for its parameter map. TypeScript rejected these cycles with `TS6202`. [dual-face packaging](2026-09-07-workspace-files-dual-face-package.md) supersedes that split: result types come directly from the protocol package, and Sidebar parameter registration belongs to the text preview; both root aggregates retain explicit compiler entries.
+
+**Serving workspace files over HTTP.** Already rejected by [workspace file links](../feature/2026-07-31-web-workspace-file-links.md) on origin grounds and not revisited: `read` and `readBytes` carry plain text and base64 over the authenticated Remote carrier, so no document is served, no URL is minted, and no origin question arises.
+
+**Log-reachable authorization for the read.** The one precedent that sends file content over the wire, command attachments, authorizes only files that appear in the session log. Enough for produced files, but a typed path or a directory tree could never open. Path containment inside the workspace root was chosen, with the endpoint owning the constraints the filesystem's unconfined reads do not, and containment decided by `fs.contains` on resolved targets so a symlink cannot escape it.
+
+**Whole-file read and slice for the byte window.** The interim form of `readBytes` read the file from its start to the window's end through `readBytes(target, signal, offset + length)` and sliced. It cannot read a window of a file longer than that end — the seam refuses such a file as too large — so no window could ever report `eof: false`, which contradicts the reason the method exists. Rejected in favour of the `readByteRange` seam, whose bound is the window.
+
+**Naming the file field `url` (or `hostUrl`).** The Session Controller's `WorkspaceFileText.url` was the Host's `file:` URL of the file. Rejected once resource addresses existed: a URL on the wire reads as an address, and this one was not one — it was a differently encoded spelling of the same path the address carries, which the Client had to decode to match change frames. A wire field is named by what it is, so the field is `absolutePath` and the `changes` frames carry the same field.
+
+**A default `readByteRange` in the `FileSystem` base class.** A non-abstract default over `readBytes` would have spared the test doubles a method but could only be implemented by reading the whole file up to the window's end, the very behaviour rejected above, or by passing an unbounded cap. Abstract, with every provider and double implementing it.
+
+**String-prefix containment.** Comparing resolved path strings against the root is simpler than `fs.contains`, but `resolve` realpaths, so a symlink that leaves the root resolves to a path outside it while a prefix test on the unresolved spelling passes; and a prefix test on the resolved spelling still needs the backend's notion of "same file". The filesystem decides containment.
+
+## Consequences
+
+- Workspace file access belongs to the Host/Client faces of `api/workspace-files`; the Session Controller carries neither implementation, and compiler and runtime entries stay separate.
+- A file of any size opens: text by line page, anything by byte window, each costing one page or window of memory on the Host and never a whole file; the cost is that a consumer assembles pages itself and that a single line above `maxBytes` has no page at all, because pages are cut by lines.
+- Every filesystem provider now offers a windowed raw read. `fs-e2b` pays for it by transferring the skipped prefix, since its SDK cannot seek; `fs-local` seeks.
+- Paths on the wire are canonical: `absolutePath` and change frames spell a file with symlinks resolved. An address built from another spelling of the same file — a workspace root reached through a symlink — opens and stats it, but its change frames never match, so `changed` stays false until a reload.
+- Change frames report the agent's own operations only. A file edited by the user's editor, a shell, or a subprocess raises no frame; an agent merely reading a file that something else changed does raise one, because the read observes a new version.
+- The gate order reports kind before position, a page's `version` may be one write behind its content, and a stalled `changes` consumer grows Host memory, because a generation's queue is unbounded; each is a known trade-off recorded in the package README.
+- The `file` resource pushes change, not content, so a preview learns a file moved on without a payload and reads the pages it wants; a failed open keeps following the address, so the agent creating the file brings the tab live without user action.
+- `readBytes` has no shipped consumer yet: it is the wire form the image and binary previews build on.
+
+## Testing
+
+Host specs in `packages/api/workspace-files/tests` exercise the paged read (whole file, nested path, empty file, multi-byte UTF-8, the line window's edges, defaults and refused limits, carriage returns kept), the byte window (defaults, a middle window with more following, tail windows exact and short, past-end and empty files, NUL and invalid UTF-8 round-tripping through base64, version parity with `stat`, the cap as `too-large`, bad ranges, a window of a file far above the cap, and `eof` inferred without a size), `stat`, `list` with truncation, symlink children, and `not-directory`, the `changes` stream driven by `fs/observed` and filtered by root, and every gate and code against a real local backend, because a fake filesystem would let a prefix test pass the symlink case the gate exists to catch. Client specs in `packages/api/workspace-files/tests` cover the provider's frames (opening stat, failure frames, writes without content, disappearance, reload, recovery, abort), the change feed (one stream per session, fan-out by normalized path, queued frames, ending on signal or Host close), the unsupported-address cases, and registration and disposal with the fiber. `fs/fs`, `fs-local`, and `fs-e2b` specs pin `readByteRange`'s range semantics — a middle window, a tail shorter than asked, past-end and zero-length windows, errors, aborts, and the e2b cancel — and `dsh-util-workspace-path` specs pin the file-address grammar. The connection fixture serves `stat`, paged `read`, `list`, and an opt-in `changes` frame for the web e2e suite.
+
+## Deferred
+
+- A web e2e chain through the Sidebar: open a file, have the agent write it, see `changed`, reload.
+- Aliasing a follower under the Host's canonical spelling once the first `stat` reveals it, so a symlinked workspace root still receives change frames.
+- A bound on a `changes` generation's queue.
+- The shipped consumer of `readBytes` (image and binary previews) and any write, search, or media route; the service is read-only.
+- Scopes other than `session` in the file address; the grammar leaves room, the provider serves one.
+- Reload delivery per record: today `reload` re-stats every follower of the file's absolute path in the session, so two records naming one file — a `session` and an `absolute` address, or two readers with different addresses — clear each other's `changed` flag.

.agents/notes/implemented/architecture/2026-09-05-workspace-files-service.zh.md

@@ -0,0 +1,151 @@
+# Agent Note: 工作区文件服务
+
+Status: implemented
+
+[English](2026-09-05-workspace-files-service.md) | 中文
+
+## Problem
+
+Web 客户端需要从一个未必在 Host 机器上的浏览器查看会话工作区里的文件：agent 产出的文件、`read` 工具行点名的路径，之后还有文件树，以及既不小也不是文本的文件预览。唯一一个经线路读取工作区文件的端点以 `workspace-file.ts` 住在 Session Controller 上，与它毫无关系的会话生命周期为邻。它在一个总字节上限之下返回整个文件，因此大日志连一部分都看不了、二进制根本看不了；它没有 `stat`、没有列举、没有变更信号，预览不重读就无法得知 agent 已改写文件；其结果还以 Host 的 `url` 命名文件，而 Client 上没有任何东西把这种拼法当地址用。
+
+两个约束框定了任何答案。经 `ctx.fs` 的读取是有意不受限的——沙箱后端只围栏写与编辑，并明说了这一点——所以面向 web 的读端点必须自己拥有每一道围栏，而且围栏必须经得住一条离开工作区的符号链接，这是字符串前缀测试看不见的。另外 `dsh-fs` 只暴露一种原始字节读取 `readBytes(target, signal, maxBytes)`，它拒绝任何比上限更长的文件：对模型整体摄入的图片是正确的，对大文件的一个窗口则毫无用处。
+
+## Decision
+
+`packages/api/workspace-files`（`@deepseek-ai/dsh-api-workspace-files`）同时拥有 Host 服务 `ctx.workspaceFiles`、`workspaceFiles` Remote 命名空间，以及将 `stat` 与 `changes` 转成[资源模型](2026-09-05-client-resource-model.zh.md)实时元数据的 Client `file` 提供者；包组织方式由[双面包组织](2026-09-07-workspace-files-dual-face-package.zh.md)规定。每个方法都把自己限制在沙箱策略为被寻址会话解析出的工作区根内，以文件在文件系统执行环境中的绝对路径命名文件，并对内容分页或开窗，因此没有任何方法会缓冲整个文件。字节窗口依托 `dsh-fs` 新增的 seam `FileSystem.readByteRange`，由每个提供者实现。Session Controller 不再携带任何工作区文件代码。
+
+### 包拓扑
+
+[双面包组织](2026-09-07-workspace-files-dual-face-package.zh.md)取代本记录中把 Host 与 Client 分成两个包的组织选择；这里的文件服务、授权、分页和变更流约定保持不变。Host 与 Client 分别编译在两个叶配置中，共享线路类型，Client 不导入 Host 运行时入口。
+
+| 面 | 包 | 文件 | 依赖 |
+|---|---|---|---|
+| Host | `api/workspace-files/tsconfig.host.json` | `src/index.ts`（`WorkspaceFiles`、`Config`、围栏、切页器）、`src/changes.ts`（`WorkspaceChangeFeed`）、`src/types.ts`（线路类型、错误码） | `dsh-fs`、`dsh-sandbox-policy`、`dsh-typert-protocol`、`dsh-agent`、`dsh-session` |
+| Client | `api/workspace-files/tsconfig.client.json` | `src/client/index.ts`（插件体）、`provider.ts`、`change-feed.ts`、`remote.ts`、`types.ts`，以及共享的 `src/types.ts` | `dsh-api-gateway/client`、`dsh-api-session-controller/client`、`dsh-client-resources`、`dsh-util-workspace-path`、`dsh-typert-protocol`，以及本包生成的 `./remote` |
+
+`api/remotes` 和两个根聚合分别引用匹配的 Host/Client 叶子。包导出 `.`、`./client`、`./types`、`./typert` 和 `./remote`，web-app 中单个 `workspace-files` 条目供应两面。Client 插件注入 `['resources', 'remote', 'remote.workspaceFiles', 'sessions']`；资源模型直接从协议包取结果类型，Sidebar 参数声明归文本预览，因此 Client 编译图不再反向依赖 Remote 装配或右栏 UI。
+
+### `workspaceFiles` Remote 命名空间
+
+每个 Host 方法首参都是目标 `Agent`，由 Gateway 从线路上的 Session 身份解析而来，因此 Client 调用 `remote.workspaceFiles.stat(sessionId, path, signal)`，从不自行命名根。五个签名照 `src/index.ts` 的声明：
+
+```ts ignore-check
+@Remote async read(agent: Agent, path: string, range: WorkspaceFileRange, signal: AbortSignal): Promise<WorkspaceFileText>
+@Remote async readBytes(agent: Agent, path: string, range: WorkspaceByteRange, signal: AbortSignal): Promise<WorkspaceFileBytes>
+@Remote async stat(agent: Agent, path: string, signal: AbortSignal): Promise<WorkspaceFileStat>
+@Remote async list(agent: Agent, path: string, signal: AbortSignal): Promise<WorkspaceDirectoryListing>
+@Remote({ mode: 'stream' }) changes(agent: Agent, signal: AbortSignal): AsyncIterable<WorkspaceFileWatchFrame>
+```
+
+- **`stat`** 返回 `WorkspaceFileStat { absolutePath, version, bytes? }`：文件身份、不透明的新鲜度令牌，以及后端报得出时的大小。它只接受普通文件。
+- **`read`** 返回一个行窗口 `WorkspaceFileText = WorkspaceFileStat & { offset, text, lines, eof }`；`lines` 计页内行数，使只含一个空行的页（`text: ''`、`lines: 1`）与越过文件末尾的页（`lines: 0`）可区分。`range.offset` 是 1 起算的首行，缺省 1；`range.limit` 是最多行数，缺省 `maxLines` 且不得超过。行以 `\n` 结束，末尾的 `\n` 终止最后一行而不是开启一空行；`text` 以 `\n` 连接本页各行且不带终止符；页含最后一行时 `eof` 为 true，越过末尾的 offset 返回 `eof` 为 true 的空页。切页器沿 `streamText` 前进，数过窗口前的行而不保留，把每个窗内片段先按 `maxBytes` 核准再缓冲，并在越过窗口的第一个字符处返回，因此任意大小的文件只花一页内存。页上的 `version` 与 `bytes` 来自流之前的那次 stat。
+- **`readBytes`** 返回一个原始字节窗口 `WorkspaceFileBytes = WorkspaceFileStat & { offset, data, eof }`。`range.offset` 是 0 起算的首字节，缺省 0；`range.length` 是最多字节数，缺省 `maxBytes` 且不得超过。`data` 为 base64，文件在窗内结束则短于 `length`，位于或越过末尾则为空；窗口含最后一个字节时 `eof` 为 true。不做任何解码，也不按二进制拒绝。`read` 按行分页、绝不按字节；字节窗口走 `readBytes`。
+- **`list`** 返回 `WorkspaceDirectoryListing { path, entries, truncated }`：被列目录相对根的工作区路径（根为空串）、其直接子项按后端的稳定名序以 `{ name, type, size? }` 给出，以及 `maxEntries` 是否截断了列表。`type` 为 `file`、`directory` 或 `other`；符号链接子项报告其指向目标的类型，悬空者为 `other`，而打开这样的子项仍会在下文的链接关被拒。dotfile 照常列出，不做任何过滤。
+- **`changes`** 产出 `WorkspaceFileWatchFrame`：在观察队列注册且工作区根解析完成后先发 `{ kind: 'ready' }`，随后为 `{ kind: 'change', change }`。载荷 `WorkspaceFileChange` 对存在的文件为 `{ absolutePath, version }`，对消失的文件为 `{ absolutePath, absent: true }`。来源是工作区根内的 `fs/observed`，不监视操作系统。首次拉取后的观察都会排队，包括根解析期间的观察；取消或插件释放会结束该代流。
+
+### 线路上的路径
+
+离开服务的路径词汇有两套，每个方法只用其中一套。`read`、`readBytes`、`stat` 与 `changes` 以 `absolutePath` 命名文件：它在文件系统执行环境中、符号链接已解析的绝对路径（`ctx.fs.processPath(target)`），因此 Client 提供者按绝对路径把变更帧匹配到已打开的地址：Client 把地址路径原样交给 Host，并只按成功的 `stat.absolutePath` 绑定跟随者，不读取会话摘要的 cwd。`list` 说工作区路径——与其 `path` 参数相同的语法，绝对或相对根——因为其消费方是一棵以根为起点的树。该字段叫 `absolutePath` 而不叫 `url`，因为它不是资源地址；地址语法归 `dsh-util-workspace-path` 所有，与资源模型一并描述。`read`、`readBytes`、`stat` 与 `list` 的输入路径是绝对路径或相对会话工作区根的路径，从不相对后端自己的 cwd。
+
+`version` 是消费者只比较是否相等、从不解析的不透明字符串：本地后端由设备、inode、大小及纳秒级 mtime 与 ctime 导出，因此内容不变的重写也会改变它。`offset` 在 `read` 上指行、在 `readBytes` 上指字节；两套单位从不混用，二者的 `eof` 都表示窗口到达了文件末尾。
+
+### 四道关
+
+每次 `read`、`readBytes`、`stat` 与 `list` 依次过四道关，而这些约束是服务自己的，因为文件系统并不限制读取。路径先被检视再判定是否在工作区内，因此调用方在 `outside-workspace` 拒绝之前就能得知工作区外的路径是否存在、是何种类；这一点被接受，因为调用方就是 Session 的所有者，本来就能经 Agent 读 Host。
+
+1. **路径本身。** `lstat` 在跟随任何东西之前检查路径：缺失路径为 `not-found`；符号链接——不论指向哪里，包括指回工作区内——对文件方法为 `not-regular-file`（kind 为 `symlink`），对 `list` 为 `not-directory`。空路径是 `gateway/bad-request`。
+2. **包含关系。** 路径解析为目标，由 `ctx.fs.contains(root, target)` 判定，其中 `root` 是以同样方式解析的 `sandboxPolicy.resolve({ session }).workspaceRoot`（会话 cwd，退而取策略配置的根）。`..` 爬出或根外绝对路径为 `outside-workspace`。从不使用字符串前缀比较：`resolve` 会取 realpath，前缀测试看不见离开根的链接。
+3. **上限。** 超过 `maxBytes` 的页或窗口，或 `read` 索要超过 `maxLines` 的行数，一律拒绝、绝不截短，因为悄悄截短的页读起来就像整页；超过 `maxEntries` 的列表被截断并如实报告。
+4. **文本。** 仅限 `read`：到页末为止不是 UTF-8 的内容、后端 8 KiB 开头样本里的 NUL 字节，或页内任何位置的 NUL 字节，都是 `not-text`；页之后的字节不检查。
+
+过关之后文件方法再对目标 `stat` 一次，因为在检查与读取之间文件可能已消失或换了种类：消失者为 `not-found`，被替换者为带新种类的 `not-regular-file`。关的顺序有一个可见后果：根外条目若类型本身已不合格，报告的是其种类而不是其位置。
+
+### 失败
+
+每种失败都是一个带类型化 details 的 `RemoteError` 代码，声明在抛出它的代码旁，按代码而非消息区分。
+
+| 代码 | 何时 | Details |
+|---|---|---|
+| `workspace-file/not-found` | 路径处无条目，或文件在过关后消失 | `{ path }` |
+| `workspace-file/outside-workspace` | 解析出的目标不在工作区根内 | `{ path }` |
+| `workspace-file/too-large` | 一页文本或所请求的字节窗口超过 `maxBytes` | `{ path, limit }` |
+| `workspace-file/not-text` | 到页末为止的非法 UTF-8，或样本或页内的 NUL 字节（仅 `read`） | `{ path }` |
+| `workspace-file/not-regular-file` | 对非普通文件执行 `read`、`readBytes` 或 `stat` | `{ path, kind: 'directory' \| 'symlink' \| 'other' }` |
+| `workspace-file/not-directory` | 对非目录执行 `list` | `{ path, kind: 'file' \| 'symlink' \| 'other' }` |
+| `workspace-file/unsupported-address` | Client 铸出：本提供者无法服务的资源地址 | `{ address }` |
+| `workspace-file/unknown-workspace` | Client 铸出：没有当前会话时的 `absolute` 地址 | `{ address }` |
+| `gateway/bad-request` | 空路径，或不是范围内整数的 `offset`、`limit`、`length` | `{}` |
+
+这个集合只增不改不删：可以新增代码，但不重命名、不移除任何一个，因为消费方跨线路按这些字符串分支。
+
+### 配置
+
+三个字段，都是可在 `cordis.yml` 中修改、经校验的正整数，此外没有其他可调项：`maxBytes`（默认 2,097,152，即 2 MiB）是单页文本与单个字节窗口的含上限；`maxLines`（默认 5,000）是页的缺省与最大行数；`maxEntries`（默认 2,000）是返回目录条目数的上限。文件本身没有大小上限：调用方分页或开窗读完它。
+
+### `dsh-fs` 中的 `readByteRange` seam
+
+大文件的字节窗口需要一种以窗口为界的文件系统读取，而 `FileSystem` 只有以整文件为界的 `readBytes(target, signal, maxBytes)`。因此 `dsh-fs` 新增第二个原始字节原语：
+
+```ts ignore-check
+abstract readByteRange(target: FsTarget, range: { offset: number; length: number }, signal?: AbortSignal): Promise<Uint8Array>
+```
+
+它返回 `[offset, offset + length)` 处的字节，文件在窗内结束则变短，`offset` 位于或越过末尾则为空。窗口即界：后端最多传输为到达 `offset` 而跳过的前缀之外的 `length` 字节，从不缓冲整个文件，因此调用方对 `length` 的上限就是防无界缓冲的守卫，与 `readBytes` 的界并列而非取代它。参数顺序遵循 `readText`、`streamText` 与 `listDir`——先目标，再操作自己的参数，最后可选 signal——而不是 `readBytes` 把 signal 放中间的形式，那是该类中唯一的例外。`offset` 与 `length` 按前置条件都是非负整数；seam 是类型化的同进程边界，不做任何校验，由 Remote 方法在线路处校验。
+
+`fs-local` 在与其他读取相同的普通文件 stat 之后打开 `createReadStream(targetKey, { start: offset, end: offset + length - 1 })`，对 `length` 为 0 直接返回空数组而不开流；`fs-sandbox` 继承 `LocalFileSystem`，随之继承该方法。`fs-e2b` 的 SDK 只能从文件开头开始流式读取，于是它跳过 `offset` 字节、把 `length` 字节拷入窗口，并在窗口填满的那一刻取消流，除跳过的前缀外传输量不超过窗口；先行结束的流则任其关闭。继承 `FileSystem` 的四个测试替身也实现了该方法。
+
+### Client `file` 提供者
+
+Client 导出向 `ctx.resources` 注册一个 `ResourceProvider<'file'>`，存活期与插件相同，并声明 `ResourceProtocolMap.file`。文本预览包把本包导出的 `WorkspaceFileParams` 注册为 `SidebarRightResourceParamsMap.file`。
+
+- **值是元数据**，`WorkspaceFileResource { absolutePath, version, bytes?, changed }`；内容从不进入流，因为内容可以任意大，而流是用来推送变更而不是载荷的。消费者用 `read` 读页（或用 `readBytes` 开窗），并以 `version` 与 `changed` 得知它们何时过时。
+- **地址命名文件，作用域决定读取会话。** `session` 地址携带的相对路径原样交给 Host，由 Host 按该会话的工作区根解析并检查包含关系，不要求 Client 持有 cwd。`absolute` 地址经当前会话读取，缺少当前会话时产生 `workspace-file/unknown-workspace`。不支持的语法产生 `workspace-file/unsupported-address`。这两种 Client 错误会结束流，刷新无动作。
+- **帧。** 第一帧是 `stat`（`changed: false`）或其失败的 `ok: false` 帧；提供者不抛也不接，因为 Remote 面从不 reject，而提供者流里的抛错只可能是编程错误，任其浮出。携带值尚未持有的版本的 Host 写入产生 `changed: true`、保留字节数、不做 stat；携带已持有版本的帧被丢弃。报告的消失会再 stat 一次——仍在则是标为 `changed` 的新元数据，不在则是保留上一个值供展示的 `not-found` 帧。`reload(address)` 再 stat 一次并产生 `changed: false`。跟随的是地址而不是文件：stat 失败后流继续，因此 agent 创建该文件或一次刷新会让资源恢复正常。中止 signal 则流静默结束。
+- **每会话一条 `changes` 订阅。** 首位跟随者打开 `remote.$stream`，最后一位离开时释放，后继流和插件拆除等待关闭完成。Client 接受 Host 的 `ready` 后才开始首次 `stat`；本地发出 WebSocket 请求不是 Host 确认。跟随者先按地址注册，缓冲路径未知期间的变更，成功 stat 后按返回的 `absolutePath` 过滤排队与实时帧，反斜杠归一为斜杠。尚未成功绑定时，Session 内任何写入均可触发重新 stat。载体掉线由 Gateway 监督器重连；Host 结束或终态失败会结束跟随者，并保留最近元数据，直到重新打开。
+- **导航参数。** `SidebarRightResourceParamsMap.file` 是 `WorkspaceFileParams { line?: number }`，即要显露的 1 起算行号。行号作为导航参数而不是地址的一部分传递，因为不论从顶部还是第 400 行打开，文件都是同一份内容。
+
+### 相关记录
+
+[资源模型](2026-09-05-client-resource-model.zh.md)拥有 `ctx.resources`、`useResource`、`dsh-resource://<type>/…` 地址语法以及"每个地址一份资源"的推理；[文本预览与文件树](../feature/2026-09-05-sidebar-text-preview-and-file-tree.zh.md)是 `read`、`list` 与 `file` 提供者随包交付的消费方；[右侧 Sidebar 停靠基础设施](../feature/2026-09-04-right-sidebar-docking-infrastructure.zh.md)是它们打开进去的界面；[工作区文件链接](../feature/2026-07-31-web-workspace-file-links.zh.md)是经 HTTP 供文件被否决之处。任何在这套体系上扩展的人都经 `remote.workspaceFiles` 触达同样的五个方法、经 `useResource<'file'>` 触达同样的 `file` 资源；线路类型以 `@deepseek-ai/dsh-api-workspace-files/types` 发布。
+
+## Alternatives considered
+
+**把工作区文件端点留在 Session Controller 上。** 最初形态：总字节上限之下的一个 `read`，作为 Session Controller 的子插件注册，因为线路入口本来就在那里。被否，因为 Workspace File 服务是自己的能力——在工作区根内读取、stat、列举与观察文件——凡查询工作区文件的都归它，而 Session Controller 关心的是会话生命周期。搬出也让服务长到五个方法而不给 Controller 的文件添第二重目的。
+
+**带有反向 UI 依赖的双面包。** 拆包选择源于 `api/remotes` 引用 Client 叶子后形成的两条工程引用环：资源模型为了结果类型引用 Remote 装配，文件提供者为了 Sidebar 参数表引用右栏 UI。TypeScript 以 `TS6202` 拒绝这些环。[双面包组织](2026-09-07-workspace-files-dual-face-package.zh.md)取代拆包选择：结果类型直接取自协议包，Sidebar 参数注册移至文本预览；保留两个根聚合中的显式编译入口。
+
+**经 HTTP 供工作区文件。** 已被[工作区文件链接](../feature/2026-07-31-web-workspace-file-links.zh.md)以 origin 理由否决且未重议：`read` 与 `readBytes` 经认证的 Remote 载体传送纯文本与 base64，因此不供文档、不铸 URL，也不产生 origin 问题。
+
+**读取的"日志可达"授权。** 唯一把文件内容送过线路的先例——命令附件——只授权出现在会话日志里的文件。对产出文件够用，但手输的路径或目录树永远打不开。选择了工作区根内的路径包含，端点自行承担文件系统不受限读取所不具备的约束，并由 `fs.contains` 对已解析目标判定包含关系，使符号链接无法逃逸。
+
+**为字节窗口整文件读取再切片。** `readBytes` 的临时形态经 `readBytes(target, signal, offset + length)` 从文件开头读到窗口末端再切片。它读不了比该末端更长的文件的窗口——seam 会以过大拒绝这样的文件——因此没有任何窗口能报告 `eof: false`，与该方法存在的理由相悖。被否，改为以窗口为界的 `readByteRange` seam。
+
+**把文件字段命名为 `url`（或 `hostUrl`）。** Session Controller 的 `WorkspaceFileText.url` 是 Host 侧文件的 `file:` URL。资源地址出现后即被否：线路上的 URL 读起来像地址，而这个不是——它只是地址所携同一路径的另一种编码拼法，Client 必须解码才能匹配变更帧。线路字段按其所是命名，因此字段为 `absolutePath`，`changes` 帧携带同一字段。
+
+**在 `FileSystem` 基类里给 `readByteRange` 一个默认实现。** 基于 `readBytes` 的非抽象默认能免去测试替身一个方法，但只能靠把文件从头读到窗口末端来实现——正是上文否决的行为——或者传一个无界上限。改为抽象方法，由每个提供者与替身实现。
+
+**字符串前缀包含判定。** 把解析后的路径字符串与根比较比 `fs.contains` 简单，但 `resolve` 会取 realpath，离开根的符号链接解析到根外路径，而对未解析拼法的前缀测试会放行；对已解析拼法的前缀测试也仍需后端对"同一文件"的定义。由文件系统判定包含关系。
+
+## Consequences
+
+- 工作区文件访问由 `api/workspace-files` 的 Host/Client 两面共同承担；Session Controller 不携带其中任何实现，两面的编译与运行时入口保持独立。
+- 任意大小的文件都能打开：文本按行页、任何文件按字节窗口，在 Host 上各自只花一页或一窗内存、从不整文件；代价是消费者自己拼装页面，且单行超过 `maxBytes` 的行没有任何页，因为页按行切。
+- 每个文件系统提供者现在都提供开窗的原始读取。`fs-e2b` 为此付出传输被跳过前缀的代价，因为其 SDK 不能 seek；`fs-local` 能 seek。
+- 线路上的路径是规范的：`absolutePath` 与变更帧以符号链接已解析的拼法命名文件。由同一文件另一种拼法铸出的地址——经符号链接到达的工作区根——能打开并 stat 它，但其变更帧永不匹配，因此 `changed` 在刷新前保持 false。
+- 变更帧只报告 agent 自己的操作。用户编辑器、shell 或子进程改动的文件不产生帧；agent 仅仅读取一个被别处改动的文件却会产生帧，因为读取观察到了新版本。
+- 关的顺序先报种类后报位置，页的 `version` 可能落后内容一次写入，停滞的 `changes` 消费者会让 Host 内存增长，因为一代流的队列无界；每一条都是包 README 记录在册的已知取舍。
+- `file` 资源推送变更而非内容，因此预览不靠载荷就得知文件已更新并读取它想要的页；失败的打开继续跟随地址，因此 agent 创建该文件时 tab 无需用户动作即恢复正常。
+- `readBytes` 尚无随包交付的消费方：它是图片与二进制预览赖以构建的线路形态。
+
+## Testing
+
+`packages/api/workspace-files/tests` 中的 Host spec 覆盖分页读取（整文件、嵌套路径、空文件、多字节 UTF-8、行窗口边界、缺省与被拒的 limit、保留回车）、字节窗口（缺省值、后面还有内容的中段窗口、恰好与变短的尾窗、越界与空文件、NUL 与非法 UTF-8 经 base64 往返、与 `stat` 一致的版本、作为 `too-large` 的上限、坏范围、远超上限的文件的一个窗口、无大小时推断的 `eof`）、`stat`、带截断、符号链接子项与 `not-directory` 的 `list`、由 `fs/observed` 驱动并按根过滤的 `changes` 流，以及针对真实本地后端的每道关与每个代码——因为假文件系统会让前缀测试放过这道关本为捕获的符号链接场景。`packages/api/workspace-files/tests` 中的 Client spec 覆盖提供者的帧（开头 stat、失败帧、不带内容的写入、消失、刷新、恢复、中止）、变更流（每会话一条流、按归一路径扇出、排队的帧、因 signal 或 Host 关闭而结束）、不支持地址的各种情形，以及随 fiber 的注册与释放。`fs/fs`、`fs-local` 与 `fs-e2b` 的 spec 钉住 `readByteRange` 的范围语义——中段窗口、短于所求的尾窗、越界与零长窗口、错误、中止以及 e2b 的取消——`dsh-util-workspace-path` 的 spec 钉住文件地址语法。connection fixture 为 web e2e 套件提供 `stat`、分页 `read`、`list` 与一帧可选启用的 `changes`。
+
+## Deferred
+
+- 一条经 Sidebar 的 web e2e 链：打开文件、让 agent 写它、看到 `changed`、刷新。
+- 在首次 `stat` 揭示 Host 的规范拼法后为跟随者加别名，使经符号链接的工作区根也能收到变更帧。
+- 给 `changes` 一代流的队列加上限。
+- `readBytes` 随包交付的消费方（图片与二进制预览）以及任何写入、搜索或媒体路由；本服务只读。
+- 文件地址中 `session` 之外的作用域；语法留有余地，提供者只服务一个。
+- 按记录投递重载：今天 `reload` 重新 stat 该会话中此文件绝对路径的所有跟随者，因此命名同一文件的两条记录——`session` 与 `absolute` 地址，或地址不同的两个读者——会互相清掉 `changed` 标记。

.agents/notes/implemented/architecture/2026-09-07-sidebar-responsive-tab-info.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-07-sidebar-responsive-tab-info.md
+2026-09-07-sidebar-responsive-tab-info.md: ade20148cccd2233224417f762e65492828943bb
+2026-09-07-sidebar-responsive-tab-info.zh.md: 0903e4ff06ca187fcc1fd0e9d8de63f70d5cc427

.agents/notes/implemented/architecture/2026-09-07-sidebar-responsive-tab-info.md

@@ -0,0 +1,31 @@
+# Agent Note: Responsive Sidebar and injected tab information
+
+Status: implemented
+
+English | [中文](2026-09-07-sidebar-responsive-tab-info.zh.md)
+
+## Problem
+
+Tab extensions need consistent live information about their containing pane and Sidebar without a growing list of owner props. The workbench must also preserve content while adapting to limited viewport space, without reopening a Sidebar the user has closed.
+
+## Decision
+
+The slot framework injects one `useTabInfo()` returning nested `sidebar`, `panel`, and `tab` fields. It composes the framework-bound layout and navigation hooks; extensions neither subscribe themselves nor receive a service object. Body visibility requires an active tab in an expanded Sidebar; title visibility does not require an active tab. Hiding or switching Sessions leaves the tab lifetime intact. Closing the record aborts its signal. Tab actions stay bound to their owning Session. Store adoption is a private capability of the plugin assembly, not a public controller operation.
+
+The frame protects 400px for the conversation by shrinking the right column, then closing it before shrinking the conversation. Its first-open preference is 45% of the viewport, retained thereafter in pixels, with a 300px floor and 70% viewport ceiling. The left column keeps its preference at widths of at least 1024px. Closing is recorded state: widening never opens it, while a user action or explicit Session API may. Refresh restores defaults rather than persisting layout.
+
+Fullscreen uses the same mounted content tree and covers the viewport while retaining the underlying column reservation. Opening below 768px selects automatic fullscreen; exiting it there closes the Sidebar. Widening can end automatic fullscreen but leaves manually selected fullscreen intact. The product permits two horizontal panes, a 50/50 initial split, and a 20–80% divider; narrow panes refuse new splits. The generic docking engine retains its independent capabilities. A fullscreen entry completes its slide before reporting the underlying track; that covered width change is instantaneous, so neither entry nor returning to normal reveals a background reflow. At the two-pane budget the split control is hidden; a one-pane width refusal remains disabled. On exit, the frame prepares the destination before the overlay retreats: no right track for close, a normal track for restore. Transition suppression survives clearing the fullscreen report and ends on the next geometry action.
+
+This decision supersedes the flat owner-props choice in [tab types and navigation](2026-09-05-sidebar-tab-types-and-navigation.md) and the no-concession, overlay presentation and product pane limit in [docking infrastructure](../feature/2026-09-04-right-sidebar-docking-infrastructure.md). Their registration, record-lifetime, state ownership and engine-selection rationale remain active.
+
+## Alternatives considered
+
+**Flat information props or three separate hooks.** A single nested read groups the three ownership levels and allows additional fields without proliferating props or readers.
+
+**Automatic reopening after a viewport change.** It makes opening depend on layout history rather than an explicit action. A closed Sidebar stays closed, with its content preserved.
+
+**A separate fullscreen content tree.** Remounting would interrupt tab-local state. The same element changes presentation instead.
+
+## Consequences
+
+Tab extensions use a framework-injected reader and keep their own store actions separate from `tab.actions`. Layout, seat and docking tests cover width concessions, explicit reopening, body/title visibility, tab lifetimes, horizontal drop zones and divider limits; browser tests exercise the assembled application. Compact mobile controls and layout persistence remain outside this decision.

.agents/notes/implemented/architecture/2026-09-07-sidebar-responsive-tab-info.zh.md

@@ -0,0 +1,31 @@
+# Agent Note: 响应式 Sidebar 与注入的标签信息
+
+Status: implemented
+
+[English](2026-09-07-sidebar-responsive-tab-info.md) | 中文
+
+## 问题
+
+标签扩展需要一致的所属窗格与 Sidebar 实时信息，而不依赖不断增长的 owner props。工作区也需要适应有限的视口空间，同时保留内容，并且不重新打开用户已经关闭的 Sidebar。
+
+## 决策
+
+Slot 框架注入一个 `useTabInfo()`，返回嵌套的 `sidebar`、`panel` 与 `tab` 字段。它组合框架绑定的布局与导航 hook；扩展既不自行订阅，也不接收服务对象。正文可见要求 Sidebar 展开且标签活跃；标题可见不要求标签活跃。隐藏或切换 Session 保留标签生命周期。关闭记录会中止其 signal。标签动作始终绑定到所属 Session。Store 收编是插件组装的私有能力，不是公共控制器操作。
+
+框架先缩小右列，再关闭右列，最后才缩小会话区，以保护会话区的 400px 宽度。右列首次打开偏好为视口的 45%，此后按像素保留，下限为 300px，上限为视口的 70%。在宽度至少为 1024px 时，左列保持自身偏好。关闭是被记录的状态：变宽不会打开右栏，用户动作或显式 Session API 可以打开。刷新恢复默认值，不持久化布局。
+
+全屏使用同一棵已挂载内容树，覆盖视口并保留底层列的占位。在 768px 以下打开会选择自动全屏；在此宽度下退出全屏会关闭 Sidebar。变宽可以结束自动全屏，但保留手动选择的全屏。产品允许两个水平窗格，初始按 50/50 分割，分割线范围为 20–80%；窄窗格拒绝新分栏。通用停靠引擎保留其独立能力。 全屏入场先完成滑入，再报告底层轨道；被覆盖的宽度变化瞬间完成，因此入场及返回普通模式都不暴露底层重排。达到两格预算时隐藏分栏控件；单格宽度不足时仍显示禁用控件。 退场时，框架先准备目标布局，再让覆盖层退出：关闭不留右轨道，恢复保留普通轨道。清除全屏报告时仍保留过渡抑制，直到下一次几何操作才结束。
+
+本决策取代[标签类型与导航](2026-09-05-sidebar-tab-types-and-navigation.zh.md)的平铺 owner props 选择，以及[停靠基础设施](../feature/2026-09-04-right-sidebar-docking-infrastructure.zh.md)中的无让步、覆盖模式和产品窗格上限。它们的注册、记录生命周期、状态所有权与引擎选型理由继续有效。
+
+## 考虑过的替代方案
+
+**平铺信息 props 或三个独立 hook。** 一个嵌套读取接口按三个所有权层级分组，允许增加字段而不增加 props 或读取接口。
+
+**视口变化后自动重开。** 这会让打开依赖布局历史，而不是显式动作。关闭的 Sidebar 保持关闭，同时保留内容。
+
+**独立的全屏内容树。** 重新挂载会打断标签局部状态。因此由同一元素改变呈现方式。
+
+## 后果
+
+标签扩展使用框架注入的读取接口，自身 store actions 与 `tab.actions` 保持分离。布局、seat 与停靠测试覆盖列宽让步、显式重开、正文与标题可见性、标签生命周期、水平放置区与分割比例；浏览器测试覆盖组装后的应用。紧凑移动端控件与布局持久化不属于本决策。

.agents/notes/implemented/architecture/2026-09-07-workspace-files-dual-face-package.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/architecture/2026-09-07-workspace-files-dual-face-package.md
+2026-09-07-workspace-files-dual-face-package.md: adc900865cb8d5f19518828a9cb230a835d025f5
+2026-09-07-workspace-files-dual-face-package.zh.md: ccfa60417284129a280efd7ddad2ea275c242f1e

.agents/notes/implemented/architecture/2026-09-07-workspace-files-dual-face-package.md

@@ -0,0 +1,36 @@
+# Agent Note: Workspace files as one dual-face API package
+
+Status: implemented
+
+English | [中文](2026-09-07-workspace-files-dual-face-package.zh.md)
+
+## Problem
+
+The workspace file service and its browser resource provider evolve together, but their compiler graph contained reverse dependencies on Remote assembly and Sidebar UI. Splitting the packages avoided the cycles while separating ownership of the wire protocol from its Client model. A Host-only package with a types-only Client compiler entry also lacks the `dsh.client` and `./client` declarations that distinguish runtime exports in Client catalog analysis.
+
+## Decision
+
+`packages/api/workspace-files` owns both implementations. Its Host and Client leaf configurations remain direct references of their respective root aggregates; the solution root references both leaves. The Host exports the file service, `./client` exports the actual resource-provider plugin, and `dsh.client` declares the browser plugin. One web-app row loads both faces. This supersedes only the package-splitting decision in the [workspace file service note](2026-09-05-workspace-files-service.md), whose authorization, paging, and stream semantics remain unchanged.
+
+Two dependency directions keep the compiler graph acyclic:
+
+- `client/resources` imports `RemoteResult` and `RemoteFailure` from their defining `typert/protocol` package, not from `api/remotes`, which assembles providers that consume the resource model.
+- The text preview declares `SidebarRightResourceParamsMap.file` using the file package's exported parameter type. The file provider declares its resource value but imports no Sidebar UI. The caller imports the viewer's type entry when it needs that navigation declaration.
+
+These remove `remotes → workspace-files → resources → remotes` and `remotes → workspace-files → sidebar-right → ui-conversation → remotes`. Runtime Cordis service injection remains independent from TypeScript project references.
+
+## Alternatives considered
+
+**Keep separate packages.** This isolates the compiler cycle but splits one file capability's Host and Client ownership. Removing the reverse type dependencies permits the same dual-face organization as other API controllers.
+
+**Remove the root Client reference.** Transitive references still compile the leaf, but both root aggregates must explicitly name this package's matching face.
+
+**Change catalog analysis or add an empty Client plugin.** Neither supplies the requested browser implementation. A real `./client` export with `dsh.client` uses the analyzer's existing supported dual-face path.
+
+## Consequences
+
+Host wire methods and browser resource behavior are unchanged. The browser implementation, tests, and documentation have one package owner; Client type dependencies stop at the protocol and resource-model layers instead of reaching UI or Remote assembly.
+
+## Verification
+
+The Cordis inspect catalog check analyzes the declared Client export, both compiler aggregates retain their leaf references, and the Host and Client file-service tests exercise the same implementations. The existing dependency and project-reference checks enforce their compilation relationships.

.agents/notes/implemented/architecture/2026-09-07-workspace-files-dual-face-package.zh.md

@@ -0,0 +1,36 @@
+# Agent Note: 工作区文件统一为 API 双面包
+
+Status: implemented
+
+[English](2026-09-07-workspace-files-dual-face-package.md) | 中文
+
+## Problem
+
+工作区文件服务与浏览器资源提供者共同演进，但其编译图包含指向 Remote 装配和 Sidebar UI 的反向依赖。拆包避开了这些环，却分离了线路协议与其 Client 模型的归属。只有 Host 实现、Client 编译入口仅含类型的包，也缺少 Client 目录分析用于区分运行时导出的 `dsh.client` 与 `./client` 声明。
+
+## Decision
+
+`packages/api/workspace-files` 拥有两面的实现。Host 与 Client 叶配置仍由各自的根聚合直接引用，solution 根配置引用两片叶子。Host 导出文件服务，`./client` 导出实际的资源提供者插件，`dsh.client` 声明浏览器插件。web-app 的一个条目加载两面。这只取代[工作区文件服务记录](2026-09-05-workspace-files-service.zh.md)中的拆包决定，其授权、分页与流语义保持不变。
+
+两条依赖方向使编译图保持无环：
+
+- `client/resources` 从定义 `RemoteResult` 与 `RemoteFailure` 的 `typert/protocol` 包导入它们，不依赖 `api/remotes`；后者负责装配消费资源模型的提供者。
+- 文本预览使用文件包导出的参数类型声明 `SidebarRightResourceParamsMap.file`。文件提供者声明其资源值，但不导入 Sidebar UI。调用方需要该导航声明时，导入查看器的类型入口。
+
+这消除了 `remotes → workspace-files → resources → remotes` 和 `remotes → workspace-files → sidebar-right → ui-conversation → remotes`。Cordis 运行时服务注入仍独立于 TypeScript 工程引用。
+
+## Alternatives considered
+
+**保留两个包。** 这隔离了编译环，却拆开同一文件能力的 Host 与 Client 归属。删除反向类型依赖后，可以采用与其它 API Controller 相同的双面组织。
+
+**删除根 Client 引用。** 传递引用仍会编译该叶子，但两个根聚合必须显式命名本包对应的编译面。
+
+**修改目录分析或增加空 Client 插件。** 两者都不能提供要求的浏览器实现。实际的 `./client` 导出和 `dsh.client` 使用分析器已有的双面支持路径。
+
+## Consequences
+
+Host 线路方法和浏览器资源行为不变。浏览器实现、测试与文档归同一个包所有；Client 类型依赖止于协议和资源模型层，不反向触及 UI 或 Remote 装配。
+
+## Verification
+
+Cordis inspect 目录检查分析声明的 Client 导出，两个编译聚合保留其叶引用，Host 与 Client 文件服务测试覆盖相同的实现。现有依赖与工程引用检查约束这些编译关系。

.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.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-workspace-registration-deletion.md
-2026-07-27-workspace-registration-deletion.md: aa3b3aaa107a87fe55395ae8cba65ab0430b6fbf
-2026-07-27-workspace-registration-deletion.zh.md: 4552e54770eb85098093f0d8f366cd5f58fc3f31
+2026-07-27-workspace-registration-deletion.md: 1d9804cfc4e2d44ea6c44f69b69dd6b10578f08a
+2026-07-27-workspace-registration-deletion.zh.md: 54e10b67a7607e32b08609fe00191da87d75f7e8

.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md

@@ -52,7 +52,7 @@ The menu, Modal, and buttons retain their existing structure and design tokens.
 
 Workspace package tests pin successful metadata-only deletion, same-path re-registration, unknown-id idempotence, table-failure rollback, explicit-marker restart recovery, unexplained-corruption rejection, and cache/table invariant behavior. Apiproxy and carrier tests pin the schema, handler, `workspace-not-found`, retained Session/folder, fresh-id re-registration, and committed `host/workspace-removed` frame. Client tests pin unary direct echo, duplicate removal, late changed frames, and deletion racing an in-flight baseline. Component tests pin confirmation, projection-settled closing, success-frame-before-unary ordering, failure, Cancel, Escape, and Close. The browser scenario observes every transient alert, slot error, console error, and page error while reusing a deleted title for a different directory.
 
-The assembled keyless Web scenario registers an existing temporary project directory, accounts a persisted Session, makes that Session current, confirms deletion in Chromium, and verifies the Workspace group disappears while Ungrouped retains the current Session. It checks the user file and JSONL log before and after deletion and repeats the UI, directory, and log assertions after reload.
+The assembled keyless Web scenario registers an existing temporary project directory, accounts a persisted Session, makes that Session current, confirms deletion in Chromium, and verifies the Workspace group disappears while Ungrouped retains the current Session. It checks the user file and JSONL log before and after deletion and repeats the UI, directory, and log assertions after reload. The scenario holds the seeded attachment frame until the browser selects the adoption-created New Session, proves that the seed is absent from the group, then delivers the frame and selects the only non-blank Session. Host attachment completion and a two-row count cannot prove browser membership: the group header plus New Session already satisfy that count, and the arriving seed can replace the positional locator between click and assertion.
 
 ## Consequences
 

.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.zh.md

@@ -52,7 +52,7 @@ Host 流在前一笔全局顺序写入期间继续保留其已提交 id 集合
 
 Workspace 包测试固定了仅删除元数据的成功路径、同路径重新注册、未知 id 的幂等行为、表操作失败回滚、明确标记的重启恢复、来源不明损坏的拒绝，以及缓存／表不变量行为。Apiproxy 与载体测试固定了 schema、处理器、`workspace-not-found`、保留会话／文件夹、使用新 id 重新注册，以及已提交的 `host/workspace-removed` 帧。客户端测试固定了一元直接回显、重复移除、延迟到达的 changed 帧，以及删除与进行中基线并发的行为。组件测试固定了确认交互、投影稳定后关闭、成功帧先于一元响应、失败、Cancel、Escape 与 Close。浏览器场景会在为不同目录复用已删除名称时，观测每一次瞬时 alert、slot error、console error 与 page error。
 
-组装后的无密钥 Web 场景会注册一个已有临时项目目录，将持久化会话计入账本，把该会话设为当前会话，在 Chromium 中确认删除，并验证 Workspace 分组消失，而 Ungrouped 保留当前会话。该场景在删除前后检查用户文件和 JSONL 日志，并在刷新后重复验证 UI、目录与日志。
+组装后的无密钥 Web 场景会注册一个已有临时项目目录，将持久化会话计入账本，把该会话设为当前会话，在 Chromium 中确认删除，并验证 Workspace 分组消失，而 Ungrouped 保留当前会话。该场景在删除前后检查用户文件和 JSONL 日志，并在刷新后重复验证 UI、目录与日志。场景会扣住种子会话的归属帧，直到浏览器选中接纳目录时创建的 New Session，确认分组中尚无种子会话，再交付该帧并选中唯一的非空白会话。Host 完成归属写入和行数达到二都不能证明浏览器已收到成员关系：分组标题加 New Session 已满足该行数，而到达的种子会话会使位置定位器在点击与断言之间指向另一行。
 
 ## 后果
 

.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.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-31-web-workspace-file-links.md
-2026-07-31-web-workspace-file-links.md: 87e8829b52f36ab9eb12149ff28775931a5ded1b
-2026-07-31-web-workspace-file-links.zh.md: 36b31c1224d3e51d5ed18b071495b2389f1bface
+2026-07-31-web-workspace-file-links.md: 1fd58deafa99f6c84371d2a2c3975eae86522ac2
+2026-07-31-web-workspace-file-links.zh.md: 8cb1d06562398a832fed0743a7c06894d0a4212b

.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.md

@@ -18,6 +18,8 @@ Two distinct defects sat behind that. The transcript never said what a turn had
 
 **The path link reads as a link.** Underlined at rest, not only on hover. This is the smaller half of the diff and the larger half of the fix.
 
+**Superseded for the web client by the [right Sidebar](2026-09-04-right-sidebar-docking-infrastructure.md):** `openFile` now opens a text-preview tab in the right Sidebar, which reads the file's text over the authenticated Remote carrier — no document is served, so the origin questions below do not arise — and the **Show in folder** action is gone; `session/openWorkspacePath` remains on the Host with no web caller. The decision as it shipped in July follows.
+
 **Opening stays the Host's job, and prefers the default browser.** `session/openWorkspacePath` hands the path to the operating system, which yields a `file://` document in a real browser: full page capabilities, and no reachability into `/api`, because a `file://` document is not same-origin with it. Measured on the reported artifact: `localStorage` works, the theme toggle flips, the tabs switch, and `fetch` to the API fails. For documents a browser renders — `.html`, `.htm`, `.xhtml`, `.svg` — the opener resolves the default *browser* rather than the type's default application when the platform can name one, because a developer who binds `.html` to an editor would otherwise click a produced page and get source code. macOS reads the LaunchServices `https` handler and desktop Linux reads `$BROWSER`; either falls back to the default application when no browser can be named. Windows uses its registered association, and WSL first translates the path before using that same Windows handoff. When files are hidden, **Show in folder** passes `.` through the same owner `openFile`; it appears only for a loopback page whose current `host.describe.canOpenPath` permits native opening. Other deployments omit it, with `nativeOpen: false` available when desktop detection would be a false positive.
 
 **Serving workspace files over HTTP is out of scope, and so are non-local clients.** Serving files from the harness itself — same-origin with `/api`, behind `CSP: sandbox`, or from a second listener whose own port gives served documents their own origin — was rejected with the product scope: previews for a browser that is not on the Host machine are not supported, so the Host opener answers the supported case completely and the HTTP machinery would answer only the unsupported one.
@@ -33,4 +35,4 @@ Two distinct defects sat behind that. The transcript never said what a turn had
 
 ## Consequences
 
-Every existing file affordance changed at once: write, edit, read, and the generic single-file card all reach `openFile`, so the link fix and browser preference apply without per-row changes. The assembled Web test covers single-line CSS overflow and a one-click Host handoff without launching a native application. A produced `file://` document cannot `fetch` its own siblings (while `<script src>`, `<img>`, and CSS `@import` work), the one capability HTTP serving had that this does not. Remote clients keep the chips but omit the folder action; the full path remains in each chip's `title`. Markdown still opens in the platform's `.md` application; in-product rendering is separate work.
+Every existing file affordance changed at once: write, edit, read, and the generic single-file card all reach `openFile`, so the link fix and browser preference apply without per-row changes. The assembled Web test covers single-line CSS overflow and a one-click Host handoff without launching a native application. A produced `file://` document cannot `fetch` its own siblings (while `<script src>`, `<img>`, and CSS `@import` work), the one capability HTTP serving had that this does not. Every client keeps the chips and none offers a folder action; the full path remains in each chip's `title`. Markdown still opens in the platform's `.md` application; in-product rendering is separate work.

.agents/notes/implemented/feature/2026-07-31-web-workspace-file-links.zh.md

@@ -18,6 +18,8 @@ Status: implemented
 
 **路径链接读得出是链接。** 静止状态下就带下划线，而不只在悬停时。这是本次改动中更小的那一半，却是修复中更大的那一半。
 
+**对 web 客户端已被[右侧 Sidebar](2026-09-04-right-sidebar-docking-infrastructure.zh.md)取代：** `openFile` 现在在右侧 Sidebar 里打开一个文本预览 tab，经已认证的 Remote 载体读取文件文本——不再提供任何文档，下文的同源问题因此不再出现——**Show in folder** 动作已删除；`session/openWorkspacePath` 留在 Host 上，已无 web 调用方。以下是七月交付时的决定原文。
+
 **打开仍然是 Host 的职责，并且优先选用默认浏览器。** `session/openWorkspacePath` 把路径交给操作系统，得到的是真实浏览器里的一份 `file://` 文档：页面能力完整，且够不到 `/api`——因为 `file://` 文档与它并不同源。在所报告的那份产物上实测：`localStorage` 可用、主题切换生效、tabs 可切换，而对 API 的 `fetch` 失败。对浏览器能渲染的文档——`.html`、`.htm`、`.xhtml`、`.svg`——平台能够确定默认浏览器时，打开器解析的是默认**浏览器**而非该类型的默认应用，因为把 `.html` 绑给编辑器的开发者，否则点开一个产出的页面得到的会是源码。macOS 读取 LaunchServices 的 `https` 处理程序，桌面 Linux 读取 `$BROWSER`；无法确定浏览器时，两者都会回退到默认应用。Windows 使用其注册的文件关联，WSL 则先转换路径，再使用同一 Windows 交接。存在隐藏文件时，**在文件夹中显示**会把 `.` 经由同一 owner `openFile` 传递；它只在 loopback 页面的当前 `host.describe.canOpenPath` 允许原生打开时出现。其他部署会省略它；桌面探测误报时可配置 `nativeOpen: false`。
 
 **以 HTTP 提供工作区文件不在范围内，非本机客户端亦然。** 由 harness 自己提供文件——与 `/api` 同源、置于 `CSP: sandbox` 之后、或交给一个以自身端口给所服务文档独立源的第二监听器——随产品范围一并否决：不为「浏览器不在 Host 机器上」的场景提供预览，因此 Host 打开器完整回答受支持的场景，而那套 HTTP 机制只会回答不受支持的那个。
@@ -33,4 +35,4 @@ Status: implemented
 
 ## 后果
 
-现有的每一处文件交互都同时改变了：write、edit、read 与通用单文件卡片都汇到 `openFile`，因此链接修复与浏览器优先策略无需逐行改动。组装层 Web 测试覆盖单行 CSS 溢出和单次点击的 Host 交接，且不会启动原生应用。产出的 `file://` 文档无法 `fetch` 同级文件（但 `<script src>`、`<img>` 和 CSS `@import` 可用），这是 HTTP 提供曾有、而此处没有的能力。远程客户端保留 chip，但省略文件夹操作；每个 chip 的 `title` 仍保留完整路径。Markdown 仍由平台的 `.md` 应用打开；产品内渲染属于另一项工作。
+现有的每一处文件交互都同时改变了：write、edit、read 与通用单文件卡片都汇到 `openFile`，因此链接修复与浏览器优先策略无需逐行改动。组装层 Web 测试覆盖单行 CSS 溢出和单次点击的 Host 交接，且不会启动原生应用。产出的 `file://` 文档无法 `fetch` 同级文件（但 `<script src>`、`<img>` 和 CSS `@import` 可用），这是 HTTP 提供曾有、而此处没有的能力。每个客户端都保留 chip，且都不提供文件夹操作；每个 chip 的 `title` 仍保留完整路径。Markdown 仍由平台的 `.md` 应用打开；产品内渲染属于另一项工作。

.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.md
+2026-09-04-right-sidebar-docking-infrastructure.md: 8e1d1b5518c3b80a05be877ee9796883b6eb9a60
+2026-09-04-right-sidebar-docking-infrastructure.zh.md: 6830bf74734bbc8072b201ded6194e1d20ddbc88

.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.md

@@ -0,0 +1,100 @@
+# Agent Note: Right Sidebar docking infrastructure
+
+Status: implemented
+
+English | [中文](2026-09-04-right-sidebar-docking-infrastructure.zh.md)
+
+## Problem
+
+The Web client's right column was a single-purpose Detail panel: `ui-chat` occupied the `details` slot with `DetailsPanel`, which showed one selected Tool call's raw payload through a `conversation.details.tool` child seat. Nothing else could live there. A plugin that wanted a persistent side surface — a file preview, a task list, a diff — had no seat to register into, no way to open its content from the conversation, and no shared layout to share the column with.
+
+Files the agent produced were the sharpest case. A produced-file chip or a `read` row's path link handed the path to the operating system through `session/openWorkspacePath`, so a browser that was not on the Host machine could not look at the file at all, and even a local one left the product to do so. The details panel meanwhile duplicated the chat rows' cards at full height, a second presentation surface every card had to keep in step.
+
+## Decision
+
+The right column is a per-session docking surface — split panes, tabs, floating panels, and an undoable operation sequence — owned by `ui-sidebar-right` over the `ui-dockkit` engine, replacing the Detail panel. This note owns the surface: the engine, the frame's right column, the panel's presentations and controls, and the per-session state. What lives in the surface is decided elsewhere: how plugins declare tab types, open content, and receive their props is [tab types and navigation](../architecture/2026-09-05-sidebar-tab-types-and-navigation.md); live data behind an address is the [client resource model](../architecture/2026-09-05-client-resource-model.md); reading workspace files is the [workspace file service](../architecture/2026-09-05-workspace-files-service.md); and the guide, the text preview, and the file tree are the [shipped types](2026-09-05-sidebar-text-preview-and-file-tree.md).
+
+### Package topology
+
+| Package | Kind | Owns |
+|---|---|---|
+| `packages/client/ui-dockkit` | static-linked library, zero DSH dependencies | the layout engine and the React components that render and drive it; consumers compile its sources, and it keeps exactly one stylesheet because a consumer de-duplicates injected sheets by file name |
+| `packages/client/ui-sidebar-right` | dynamic plugin | the `rightbar` panel seat and the `conversation.session.header.corner` expand button over one store, one surface per session, both presentations, the float host, `ctx.sidebarRight`, `ctx.sidebarRightTabs`, the tab domain (one occurrence per tab record), the three extension seats, the guide tab type, and the `sidebarRight` copy namespace |
+
+The kit is the product's first embedder and knows nothing about it: every string arrives through `DockLabels`, every tab body through a `TabRenderer` dispatching on an opaque `kind`, and every gesture leaves through `DockIntents`. The integration package supplies what the kit refuses to know.
+
+### Layout engine
+
+The engine is a normalized recursive split tree: `nodes` keyed by id, `rootId` for the docked root, `floats` bottom-to-top. The ids are branded (`PaneId`, `SplitId`, `TabId`; `NodeId` is the pane/split union), minted only by a `Mint`, so no id kind stands in for another or for a bare string. A floating panel is a pane whose `host` is `'float'` with capacity one, drawn without a tab strip. `applyOp(state, op)` returns the next state and the operations that undo it, captured when the operation runs because the pre-operation state is gone by undo time. Every operation carries the ids it creates, so `replay(initial, ops)` reproduces the same tree from the same start; the engine reads no clock and no random source. The `Sequencer` keeps a linear history with one entry per intent — the operations one gesture or command produced undo and redo together — a run of consecutive focus-only entries steps as one, and a new entry after stepping back drops the forward branch. Planners are the pure intent layer — `(state, mint, args) → LayoutOp[]` — and `DockController` is a thin observable shell over them. `planSettle` is the opt-in follow-up planner that merges away every docked pane an intent emptied and reseeds an emptied root pane through the embedder's factory.
+
+Components render a snapshot and report settled intents, one per gesture: a drag previews in local state while the gesture's facts stay in its closure, and the release folds the net result into one operation. Gestures are pointer events with pointer capture rather than HTML5 drag-and-drop. A chip is a capsule carrying one control, its close; a secondary press opens the context menu (close plus the embedder's `renderTabMenuItems`). After the chips sits the add control, which asks the embedder through `DockIntents.addTab` to seat its seeded tab (`planAddTab`). Floating is the drag released clear of the surface, and copying has no kit control at all — `DockIntents.duplicateTab` stays for embedder APIs. The split control's glyph is a frame bisected vertically, as the split is. Four interaction rules fix defects found in a real browser and are kept on purpose: capture the pointer on gesture start, never make the tab strip a scroll container, land focus on click rather than press, and let a control nested in a draggable chip stop its own press. The tab's actions menu renders in a portal positioned against its control, because the strip's deliberate overflow clip would otherwise cut it off. The kit ships no undo/redo control, and no header: an embedder's surface-wide controls go through `DockSurface`'s `chrome` prop, which the kit places at the far end of the top-right pane's strip (`topRightPaneId`: the last child of every row split, the first of every column split). The generic kit defaults to four panes; the Sidebar supplies its two-pane product limit.
+
+### The frame's right column
+
+[Responsive Sidebar and tab information](../architecture/2026-09-07-sidebar-responsive-tab-info.md) supersedes this note's no-concession layout, overlay presentation and product pane limit. `ui-layout` still owns three-column geometry and pixel width preferences; the Sidebar occupant reports presentation through `ctx.layout.openRightbar(track, fullscreen)` and `closeRightbar()`, without the frame injecting the Sidebar package. Exact width rules belong to [ui-layout](../../../../packages/client/ui-layout/README.md).
+
+The right Sidebar uses one mounted content tree in normal and fullscreen modes; hiding preserves tab state, and fullscreen covers the viewport while retaining underlying column reservation. Floats still use viewport coordinates through a portal and remain open when the Sidebar closes. The product limits docking to two horizontal panes and a 20–80% divider; the generic engine keeps its own defaults.
+
+### State
+
+`ui-sidebar-right` keeps one `SurfaceState` per session id — the layout, its history, and the mint counter — in a store declared at the seat registration. Every action mints the ids its intent needs, asks a kit planner for the operations, runs the settle planner over the result, and records the whole intent as one history entry before assigning the session's surface back; no action edits a layout in place. The settle step is the product's rule: a docked pane whose last tab is closed, moved out, or floated is merged away, and when only the root pane remains and it is empty, the guide tab is reseeded — there is always at least one tab and never an empty pane, so no pane-closing gesture exists. State is memory-only: a reload returns every session to the collapsed default, and switching sessions keeps each surface where it was. Layout is presentation state and never enters the session log.
+
+### Beyond the surface
+
+The surface renders tabs whose bodies it does not know: each tab carries a `kind`, and the panel asks the type registry for the implementation in force and dispatches to its keyed body seat. Everything a body may rely on — its record, its pane, whether it is visible, how it was navigated to, an abort signal, and the actions it may take — is read through the framework-injected `useTabInfo()`. The registry, the navigation face `ctx.sidebarRight`, the seats, and the tab information are specified in [tab types and navigation](../architecture/2026-09-05-sidebar-tab-types-and-navigation.md); a body that shows data reads it through the [client resource model](../architecture/2026-09-05-client-resource-model.md).
+
+### Entry points and removals
+
+`ui-chat`'s `openFile(path, { line? })` — reached by tool-row path links, produced-file chips, and closing-message mentions — now opens the file into the Sidebar through the navigation face (see [tab types and navigation](../architecture/2026-09-05-sidebar-tab-types-and-navigation.md)). The `Show in folder` action and its `canOpenWorkspacePath` probe are removed from `ui-deliverables`: the Sidebar has no directory form, and the product keeps no secondary entry. `DetailsPanel`, `ToolDetails`, the tool-node reader, the chat store's selection, `ToolDetailsProps`, and `CENTER_MIN` are removed. `session/openWorkspacePath` remains on the Host with no web caller.
+
+## Alternatives considered
+
+**Adopt a docking library.** Six engines were evaluated against the product's state-ownership requirement (the layout is a recorded, replayable sequence the product owns). dockview is uncontrolled and its only external entry is a destructive `fromJSON`, with undo in a paid tier; react-mosaic has no floating layer and rests on a drag base unmaintained for years; rc-dock, golden-layout, and Lumino failed on state ownership. FlexLayout 0.10.x was the one viable candidate — external Model, vetoable `onAction`, content-preserving `fromJson` — and was kept as a verified fallback whose switch points were the prototype's five-zone dock and multi-float tests. Both passed self-built with no switch signal, and its 0.x minors carry breaking changes, so it was not adopted.
+
+**Layered reuse: `react-resizable-panels` for sizes, Pragmatic drag-and-drop for gestures.** The planned main line before the prototype. Rejected once the prototype's own size and gesture layers passed in a real browser: the layers the plan meant to save had already been written and verified, so the remaining value was only long-tail edge handling. It stays a replaceable layer if snap or priority sizing is ever required.
+
+**A drawer over `shell.overlay`, or a double-layer shell (root rail, session content).** The prototype shipped as a drawer to avoid touching the frame. Rejected for the product: a drawer is not a column and never squeezes the conversation, and the double-layer shell hit the slot core's one-handle-one-scope rule, which would have made collapsing un-undoable. The frame owns a real column; content and state stay session-bound.
+
+**A frame-owned 32px rail as the collapsed state, the panel living inside the animated grid track, and the overlay as a separate portal.** The first shipped form. Rejected after review: a solid rail track pushes the conversation's scrollbar inboard for a strip that exists only while collapsed; a panel inside the animating track is stretched and re-laid-out by every track transition, so the Sidebar itself visibly moved when it should not; and two code paths for one panel meant switching presentation remounted it. The panel is now one edge-anchored box that slides and the track only reserves room.
+
+**A 40px rail inside the conversation column, with its own `sidebar.right.rail.item` seat.** Tried next, so the rail could leave with the panel. Rejected on review as visually too heavy for what it carried: a full-height strip for one button and a placeholder. The expand control is now a single header button and the collapsed-state seat is deferred until something needs it.
+
+**A header row on the panel.** The first form carried a title and its controls in a 40px row above the strip. Removed: the strip already is the panel's top edge, so the controls sit at the strip's end in the top-right pane through the kit's chrome seat, and the title said nothing the tabs did not.
+
+**The expand button as a `conversation.session.header.utilities` entry.** Tried after the rail. Rejected on review: as a list entry it sat inside the utilities row, so it was not at the header's true corner, and its appearance and disappearance shifted the Session log control beside it. A dedicated corner seat with a reserved footprint fixes both.
+
+**A per-chip "more" control with copy and float items.** The first form gave every chip a `⋯` menu holding close, copy, and float. Rejected on review: the chip now carries only its close, the menu moved to the secondary press with only close (plus embedder items), and copy and float left the panel entirely — copy stays an API (`open` with `duplicate: true`), float stays the drag. The kit's `duplicateTab` / `floatTab` intents and planners are unchanged.
+
+**Undo and redo buttons on the panel header.** Shipped first, then removed: the sequence is an architectural fact, and stepping it is not a product action yet. The API stays reachable as `@internal` methods for tests and the future navigation controller.
+
+**Empty panes as a persistent state.** The first design allowed a pane to stay after its last tab left, with a placeholder. Rejected because nothing offered a way to close such a pane; every intent now settles the surface so an emptied pane is merged away and an emptied root pane reseeds the guide.
+
+**Inline the kit through `packages/util` and the `INLINE_SAFE` list.** A build probe showed it works, but the util build chain has no CSS pipeline and the kit ships a stylesheet; the static-linked client package (the `ui-primitives` precedent) was chosen knowing that changing the kit means rebuilding the shell and reloading.
+
+## Consequences
+
+- The docking surface itself no longer overflows its panel: `.surface` and `.pane` clamp to the column (`min-width: 0`, `overflow: hidden`), so a long unwrapped line scrolls inside the body and the strip's controls stay in view in every split.
+- Layout is undoable and per session, and it is memory-only; a reload starts every session collapsed. Undo is reachable only through `@internal` service methods; the product shows no history controls.
+- A pane cannot be left empty and the surface cannot be left tabless: closing, moving out, or floating a pane's last tab drops the pane, and emptying the last pane brings the guide back.
+- A pane holds at most one guide tab: a second one cannot be added, opened, duplicated, or moved in; the guide's uniqueness is per pane, so a split still seeds its new pane with a guide.
+- A pane may split only when each equal half can still hold what cannot shrink: the strip's fixed controls (its width minus the chip box and the fill, so the top-right pane's chrome counts on the half that hosts it) plus one chip at its minimum, measured in the component layer after every commit and on resize. Otherwise the split control stays, disabled with its own copy, the matching edge drop zones are withheld, and panes the user narrows keep their size; the product permits at most two horizontal panes, regardless of widening or divider movement.
+- The Sidebar panel never moves when the presentation switches, and its slide is the same in both presentations; the conversation is the only thing that animates on a switch. A hidden panel keeps its tabs mounted, so a preview survives a collapse.
+- Collapsed, the Sidebar is one header-corner button: the conversation keeps its full width and its scrollbar at its edge, the button leaves when the panel opens, and its footprint stays so nothing else in the header moves.
+- A tab is closed from its chip; copying and floating have no panel control (copying is API-only, floating is the drag). The context menu is reachable by right-click and carries close plus embedder items.
+- The Detail panel and its duplicate card presentation are gone (a net removal of roughly 1,400 lines); cards are read in place, and `inspect` opens the trajectory view.
+- The frame has no centre floor: a viewport narrower than the two edge columns squeezes the conversation toward zero instead of closing a column.
+- The kit is compiled by its consumers, so a kit change requires a shell rebuild and a page reload; there is no HMR for it.
+- The panel, the float host, and the portalled tab menu use hard-coded z-index values; the client still has no z-index token layer.
+
+## Testing
+
+`ui-dockkit` specs pin the engine's invariants — every operation's inverse round-trips, `replay` over any prefix of the history equals the recorded state, one compound intent steps as one entry, focus runs coalesce symmetrically, the pane cap and the width rule refuse with no record — and drive the components with props alone, with no scaffold. `ui-sidebar-right` specs cover the per-session store, the seat's presentations and controls, per-pane guide uniqueness, and the width-aware split. The Web e2e suite drives the shipped Sidebar in Chromium through the real plugin graph: expand and collapse, split to the limit and the greyed control, floats, docking back, and the guide. Both suites are keyless.
+
+## Deferred
+
+- A z-index token layer, then the panel's, the float host's, and the menu's hard-coded values.
+- The assembled session-switch case, blocked on the fixture composition opening its settings surface by default.
+- Chinese counterparts for the new packages' READMEs and for the English documentation this change edited.
+- Snap or priority pane sizing, touch tuning, and keyboard routes for split, move, and float.
+- Persistence of the layout, popout windows, and a content navigation stack (entries keyed by pane and content, adjacent duplicates replaced, a `navigating` guard, closed tabs left in the stack).
+- A non-closable tab (a `closable` flag on `TabRecord`, drawn as a fixed leading marker rather than a capsule) once a tab type needs one.

.agents/notes/implemented/feature/2026-09-04-right-sidebar-docking-infrastructure.zh.md

@@ -0,0 +1,100 @@
+# Agent Note: 右侧 Sidebar 停靠基础设施
+
+Status: implemented
+
+[English](2026-09-04-right-sidebar-docking-infrastructure.md) | 中文
+
+## Problem
+
+Web 客户端的右列曾是单一用途的 Detail 面板：`ui-chat` 以 `DetailsPanel` 占据 `details` 坑位，通过 `conversation.details.tool` 子坑位展示一个被选中 Tool 调用的原始载荷。其他任何内容都无法住在那里。想要一个常驻侧面的插件——文件预览、任务清单、diff——没有可注册的坑位，没有从会话流打开自己内容的通道，也没有可共享的布局来与他人分享这一列。
+
+Agent 产出的文件是最尖锐的案例。产出文件 chip 或 `read` 行的路径链接会经 `session/openWorkspacePath` 把路径交给操作系统，因此不在 Host 机器上的浏览器完全看不到该文件，即便本机浏览器也要离开产品才能查看。与此同时 Detail 面板以全高重复渲染会话行的卡片，成为每张卡片都必须保持同步的第二个展示面。
+
+## Decision
+
+右列是每会话一份的停靠面（分栏 pane、tab、浮动面板与可撤销的操作序列），由 `ui-sidebar-right` 基于 `ui-dockkit` 引擎持有，取代原来的 Detail 面板。本篇只管这个面：引擎、框架的右列、面板的两种呈现与控件、每会话的状态。面里放什么由别处决定：插件如何声明 tab 类型、打开内容、拿到 props 见[tab 类型与导航](../architecture/2026-09-05-sidebar-tab-types-and-navigation.zh.md)；地址背后的活数据见[客户端资源模型](../architecture/2026-09-05-client-resource-model.zh.md)；读工作区文件见[工作区文件服务](../architecture/2026-09-05-workspace-files-service.zh.md)；引导页、文本预览与文件树见[随包类型](2026-09-05-sidebar-text-preview-and-file-tree.zh.md)。
+
+### 包拓扑
+
+| 包 | 形态 | 所有物 |
+|---|---|---|
+| `packages/client/ui-dockkit` | 静态链接库，零 DSH 依赖 | 布局引擎与渲染/驱动它的 React 组件；消费方编译其源码，且它只保留一张样式表，因为消费方按文件名去重注入的样式表 |
+| `packages/client/ui-sidebar-right` | 动态插件 | 共用一个 store 的 `rightbar` 面板坑位与 `conversation.session.header.corner` 展开按钮、每会话一份 surface、两种呈现模式、浮层宿主、`ctx.sidebarRight`、`ctx.sidebarRightTabs`、tab 域（每条 tab 记录一个 occurrence）、三个扩展坑位、引导 tab 类型与 `sidebarRight` 文案命名空间 |
+
+该库的第一个嵌入方就是本产品，而库对此一无所知：所有字符串经 `DockLabels` 传入，所有 tab 正文经按不透明 `kind` 分派的 `TabRenderer` 传入，所有手势经 `DockIntents` 传出。集成包提供库拒绝知晓的一切。
+
+### 布局引擎
+
+引擎是归一化的递归分裂树：`nodes` 按 id 索引，`rootId` 指向停靠根，`floats` 自底向上排列。id 带 brand（`PaneId`、`SplitId`、`TabId`；`NodeId` 是 pane 与 split 的并集），只由 `Mint` 铸出，任何一种 id 都不能充当另一种或裸字符串。悬浮面板是 `host` 为 `'float'`、容量为一的 pane，不绘制 tab 条。`applyOp(state, op)` 返回下一状态以及撤销它的操作，逆操作在执行时刻捕获，因为到 undo 时操作前状态已不存在。每个操作携带自己创建的 id，所以 `replay(initial, ops)` 从同一初态重现同一棵树；引擎不读时钟也不读随机源。`Sequencer` 维护线性历史，一个意图一条账——一次手势或命令产生的全部操作一起撤销与重做——连续的纯焦点条目合并为一步，后退后的新条目丢弃前向分支。planner 是纯意图层——`(state, mint, args) → LayoutOp[]`——`DockController` 是其上的薄可观察壳。`planSettle` 是可选的收尾 planner：合并掉意图留下的每个空停靠 pane，并经嵌入方的工厂重新种上被清空的根 pane。
+
+组件渲染快照并上报已落定的意图，每个手势一条：拖拽过程只在本地 state 预览、手势的事实住在它的闭包里，松手把净结果折成一条操作。手势基于 pointer 事件与 pointer capture，而非 HTML5 拖放。chip 是胶囊形，只带一个控件——关闭；右键打开上下文菜单（关闭加嵌入方的 `renderTabMenuItems`）。chip 之后是添加控件，经 `DockIntents.addTab` 请嵌入方种入它的种子 tab（`planAddTab`）。悬浮是把拖拽松手在面之外，复制则完全没有库控件——`DockIntents.duplicateTab` 留给嵌入方 API。分栏控件的图标是被竖线一分为二的方框，与分栏本身一致。四条交互规则修复了真实浏览器中发现的缺陷并被有意保留：手势开始即捕获指针；tab 条绝不做滚动容器；焦点落在 click 而非 press；可拖 chip 内嵌的控件自行拦截按下。tab 的操作菜单以 portal 渲染并对着它的按钮定位，因为 tab 条刻意裁切溢出，画在条内的菜单会被一起切掉。库不自带 undo/redo 控件，也不自带头部：嵌入方的面级控件经 `DockSurface` 的 `chrome` prop 传入，库把它们放在右上 pane 的 tab 条末端（`topRightPaneId`：每个行分裂取最后一个子节点、每个列分裂取第一个）。通用工具包默认允许四个窗格；Sidebar 传入产品的两格上限。
+
+### 框架的右列
+
+[响应式 Sidebar 与标签信息](../architecture/2026-09-07-sidebar-responsive-tab-info.zh.md)取代本记录中的无让步布局、覆盖模式与产品窗格上限。`ui-layout` 仍拥有三列几何与像素宽度偏好，Sidebar 占位项通过 `ctx.layout.openRightbar(track, fullscreen)` 和 `closeRightbar()` 报告呈现方式，框架不注入 Sidebar 包。具体宽度规则见 [ui-layout](../../../../packages/client/ui-layout/README.zh.md)。
+
+右栏在普通与全屏模式下使用同一棵已挂载内容树；隐藏保留标签状态，全屏覆盖视口并保留底层列占位。浮窗仍经 portal 使用视口坐标，不随右栏关闭。产品限制为两个水平窗格与 20–80% 分割比例，通用引擎保留自己的默认值。
+
+### 状态
+
+`ui-sidebar-right` 为每个会话 id 保存一份 `SurfaceState`——布局、历史与铸造计数——住在坑位注册时声明的 store 里。每个 action 先铸造意图所需的 id，向库的 planner 索取操作，对结果跑一遍 settle planner，把整个意图记为一条历史账，再把该会话的 surface 整体赋回；没有 action 就地改布局。settle 是产品规则：最后一个 tab 被关闭、拖走或悬浮出去的停靠 pane 会被合并掉；只剩根 pane 且为空时重新种上引导 tab——永远至少有一个 tab、永远没有空 pane，所以不存在"关闭 pane"手势。状态仅在内存：刷新使所有会话回到折叠默认态，切换会话时各 surface 保持原样。布局是呈现状态，永不进入会话日志。
+
+### 面之外
+
+这个面渲染的 tab 正文它自己并不认识：每个 tab 带一个 `kind`，面板向类型注册表询问该 kind 生效的实现，再派发到其 keyed 正文坑位。正文能依赖的一切——它的记录、所在格、是否可见、如何被导航到、中止信号、可做的动作——均通过框架注入的 `useTabInfo()` 从标签域读取。注册表、导航面 `ctx.sidebarRight`、坑位与 标签信息 在[tab 类型与导航](../architecture/2026-09-05-sidebar-tab-types-and-navigation.zh.md)里定；展示数据的正文经[客户端资源模型](../architecture/2026-09-05-client-resource-model.zh.md)读取。
+
+### 入口与删除
+
+`ui-chat` 的 `openFile(path, { line? })`——工具行路径链接、产出文件 chip 与收尾消息提及都经由它——现在经导航面把文件开进 Sidebar（见[tab 类型与导航](../architecture/2026-09-05-sidebar-tab-types-and-navigation.zh.md)）。`Show in folder` 动作及其 `canOpenWorkspacePath` 探针从 `ui-deliverables` 移除：Sidebar 没有目录形态，产品也不保留次级入口。`DetailsPanel`、`ToolDetails`、tool-node reader、chat store 的 selection、`ToolDetailsProps` 与 `CENTER_MIN` 一并删除。`session/openWorkspacePath` 留在 Host 上，已无 web 调用方。
+
+## Alternatives considered
+
+**采用停靠库。** 六个引擎按产品的状态所有权要求（布局是产品拥有的、可记录可回放的序列）评估。dockview 非受控，唯一外部入口是破坏性的 `fromJSON`，undo 划入付费层；react-mosaic 没有浮层，拖拽底座多年未维护；rc-dock、golden-layout、Lumino 在状态所有权上不可用。FlexLayout 0.10.x 是唯一可行候选——外置 Model、可否决的 `onAction`、保内容的 `fromJson`——被保留为已验证的降级预案，切换判定点是原型的五区 dock 与多浮层测试。两项自研均通过、无切换信号，且其 0.x minor 携带 breaking change，故未采用。
+
+**分层复用：`react-resizable-panels` 管尺寸、Pragmatic drag-and-drop 管手势。** 原型之前的规划主线。原型自己的尺寸层与手势层在真实浏览器中通过后即否决：计划要省下的两层已经写完并验证，剩余价值只在长尾边界处理。若将来需要 snap 或 priority 尺寸语义，它仍是可替换的一层。
+
+**挂在 `shell.overlay` 上的抽屉，或双层外壳（root rail、session 内容）。** 原型以抽屉形态交付以避免触碰框架。产品层面否决：抽屉不是一列，永不挤压会话区；双层外壳撞上 slot core 的 one-handle-one-scope 规则，会让折叠不可撤销。框架拥有一条真实的列；内容与状态仍绑定会话。
+
+**框架自有的 32px rail 作为折叠态、面板住在带动画的 grid 轨道里、覆盖态另走 portal。** 第一版交付形态。评审后否决：实体 rail 轨道为一条只在折叠态存在的条带把会话区滚动条向内挤；住在动画轨道里的面板被每次轨道过渡拉伸重排，Sidebar 自己在动而它本不该动；一个面板两条代码路径意味着切换呈现模式要重挂载它。现在面板是一个锚在边缘的盒子做平移，轨道只负责占位。
+
+**会话列内一条 40px 的 rail，带自己的 `sidebar.right.rail.item` 坑位。** 随后一试，好让 rail 能随面板离场。评审否决：为一个按钮加一个占位画一整条竖带，视觉太重。展开入口现在是头部的单个按钮，折叠态坑位推迟到有真实需求时再声明。
+
+**面板自带头部行。** 第一版在 tab 条上方有一条 40px 的标题加控件行。删除：tab 条本来就是面板的顶边，控件经库的 chrome 坑位坐到右上 pane 的条末端，标题说的也不比 tab 多。
+
+**展开按钮作为 `conversation.session.header.utilities` 的一个 list 条目。** rail 之后的一试。评审否决：作为 list 条目它坐在工具区行内，不在头部真正的角落，而且它的出现与消失会挪动旁边的 Session log 控件。专设一个保留占位宽度的角落坑位同时解决两点。
+
+**每个 chip 一个带复制与悬浮项的"更多"控件。** 第一版给每个 chip 一个 `⋯` 菜单，装关闭、复制、悬浮。评审否决：chip 现在只带关闭，菜单挪到右键且只剩关闭（加嵌入方条目），复制与悬浮整体离开面板——复制仍是 API（`open` 带 `duplicate: true`），悬浮仍是拖拽。库的 `duplicateTab` / `floatTab` 意图与 planner 不变。
+
+**面板头部的 undo 与 redo 按钮。** 先上后撤：序列是架构事实，步进它现在还不是产品动作。API 以 `@internal` 方法保留给测试与将来的导航控制器。
+
+**空 pane 作为一种持久状态。** 第一版允许 pane 在最后一个 tab 离开后带占位留下。否决，因为没有任何方式关掉这样的 pane；现在每个意图都会整理 surface，被清空的 pane 合并掉，被清空的根 pane 重新种上引导。
+
+**经 `packages/util` 与 `INLINE_SAFE` 清单内联库。** 构建探针证明可行，但 util 构建链没有 CSS 管线而库带样式表；在知晓改库须重建壳并刷新页面的前提下，选择静态链接的 client 包（`ui-primitives` 先例）。
+
+## Consequences
+
+- 停靠面自身不再溢出面板：`.surface` 与 `.pane` 收在列内（`min-width: 0`、`overflow: hidden`），长的不换行行在正文内滚动，tab 条控件在任何分栏下都可见。
+- 布局可撤销且按会话隔离，同时仅在内存；刷新使所有会话回到折叠态。undo 只能经 `@internal` 服务方法触达；产品不显示历史控件。
+- pane 不能留空、surface 不能没有 tab：关闭、拖走或悬浮出 pane 的最后一个 tab 会删掉该 pane，清空最后一个 pane 会让引导回来。
+- 一个 pane 最多持有一个引导 tab：第二个不能被添加、打开、复制或搬入；唯一性按 pane 算，所以分栏仍给新 pane 种引导。
+- pane 只有在等分后的两半都仍能容下不可收缩部分时才可分栏：tab 条的固定控件（条宽减去 chip 盒与填充，因此右上 pane 的面板控件只计在承载它的那一半）加一个最小宽度的 chip，由组件层在每次提交与尺寸变化后测量。否则分栏控件保留但禁用并带自己的文案，对应的边缘落区不再提供，用户拖窄的 pane 保持原尺寸；产品最多两个水平窗格，不因拉宽或拖分隔条而提高上限。
+- 切换呈现模式时 Sidebar 面板一动不动，两种模式的平移一模一样；切换时只有会话区在动。隐藏的面板保持 tab 挂载，预览在折叠后仍在。
+- 折叠时 Sidebar 只是头部角落的一个按钮：会话区保持全宽、滚动条停在自己的边缘，面板展开时按钮离场但占位保留，头部其余内容不动。
+- tab 从 chip 上关闭；复制与悬浮在面板上没有控件（复制仅 API、悬浮靠拖拽）。上下文菜单经右键打开，含关闭与嵌入方条目。
+- Detail 面板及其重复的卡片展示消失（净删约 1,400 行）；卡片就地阅读，`inspect` 打开 trajectory 视图。
+- 框架没有中列下限：视口窄于两侧列之和时会话区被挤向零，而不是关掉某一列。
+- 库由消费方编译，改库须重建壳并刷新页面；它没有 HMR。
+- 面板、浮层宿主与 portal 出去的 tab 菜单使用硬编码 z-index；客户端仍没有 z-index token 层。
+
+## Testing
+
+`ui-dockkit` 的规格钉住引擎不变量——每个操作的逆操作往返恒等、历史任意前缀的 `replay` 等于记录状态、一个复合意图作为一条账步进、焦点段对称合并、格数上限与宽度规则拒绝且零记账——并仅以 props 驱动组件，不用 scaffold。`ui-sidebar-right` 的规格覆盖 per-session store、座位的两种呈现与控件、按格唯一的引导、宽度感知分栏。Web e2e 套件在 Chromium 里经真实插件图驱动随包交付的 Sidebar：展开与收起、分到上限与置灰控件、浮窗、回坞、引导页。两套均无需密钥。
+
+## Deferred
+
+- z-index token 层，随后替换面板、浮层宿主与菜单的硬编码值。
+- 组合层的切换会话用例，受阻于 fixture 组合默认打开设置面。
+- 新包 README 与本次改动的英文文档的中文对。
+- snap 或 priority 面板尺寸语义、触屏调优，以及分栏/移动/悬浮的键盘路径。
+- 布局持久化、popout 窗口，以及内容导航栈（条目以 pane 与内容为键、相邻重复替换、`navigating` 守卫、已关 tab 留在栈中）。
+- 不可关闭的 tab（`TabRecord` 上的 `closable` 标志，画成固定的前置标记而非胶囊），等到有 tab 类型需要时再做。

.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.i18n.yaml

@@ -0,0 +1,6 @@
+# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
+# side as of the last confirmed-consistent state. Both languages carry equal authority;
+# after editing either side, bring the other along and re-record with:
+#   pnpm run verify-translation-pairing --write .agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.md
+2026-09-05-sidebar-text-preview-and-file-tree.md: a21946c73302561a2cb8539ca314e0a5d4fb25b8
+2026-09-05-sidebar-text-preview-and-file-tree.zh.md: dc02c159e0e052a21f2f1c80ac2e6f30bf5cf416

.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.md

@@ -0,0 +1,122 @@
+# Agent Note: Sidebar text preview and file tree
+
+Status: implemented
+
+English | [中文](2026-09-05-sidebar-text-preview-and-file-tree.zh.md)
+
+## Problem
+
+The right Sidebar's [docking infrastructure](2026-09-04-right-sidebar-docking-infrastructure.md) and its [tab type registry](../architecture/2026-09-05-sidebar-tab-types-and-navigation.md) give a plugin a place to register a tab type, but a surface with no types is an empty column. Three questions had to be answered by shipped code before anyone else could register a type: what a new pane shows before it holds content, how a file the agent produced or read is looked at without leaving the product, and how a reader finds a file the conversation never mentioned. The answers also had to demonstrate the type authoring model end to end — a static definition, a body in a keyed seat, a Slot store and inject face for the type's own state, `useResource` for live data behind an address — so that a type written outside `ui-sidebar-right` has a worked template rather than a contract alone.
+
+Each answer carries product rules that code alone does not explain: why a text file loads by page instead of whole, why a changed file is announced rather than refreshed, why the file tree is a page type that claims no address, why the guide gives its tab away instead of opening beside itself. This note records those decisions for the three shipped types.
+
+## Decision
+
+Three tab types ship with the Sidebar: the **guide** (`ui-sidebar-right`), the **text preview** (`ui-sidebar-textpreview`), and the **file tree** (`ui-sidebar-files`). Each registers a static definition into `ctx.sidebarRightTabs` and a body into the keyed `sidebar.right.pane.tab` seat under the definition's `id`, inside its own `ctx.effect`, so the type exists exactly as long as its plugin. The guide and the tree are page types opened by kind; the text preview is a viewer that claims every `file` resource address at the lowest band. A type's controls live in its own body; the pane's tab strip carries only the panel's actions. Copy is locale-owned in each package's namespace (`sidebarRight`, `sidebarTextpreview`, `sidebarFiles`).
+
+### The guide
+
+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 is a centred column — a lead line (`侧栏用来放你想一直看着的东西。` / `The sidebar holds what you want to keep looking at.`), one line of copy (`会话里的文件和产物会开在这一栏，也可以从下面的入口打开。` / `Files and artifacts from the conversation open in this column; the entries below open more.`), and a grid of entry boxes at most 480px wide, each box at least 160px, filling as many columns as fit. The boxes are projected from 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. A box shows the contributing type's glyph, title, and description, and picking it 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.
+
+A pane holds at most one guide, and the docking layer enforces it as product behaviour: the strip's add control hides while a guide is present, opening the guide into such a pane focuses it, a guide is never duplicated, and a guide dragged, dropped, or docked into a pane that already has one merges into it (the arriving tab closes). Settling a surface reseeds the guide when the root pane empties, so there is always at least one tab and never an empty pane.
+
+### The text preview
+
+`text` is the fallback viewer for every file. Its registration is `{ id: '@deepseek-ai/dsh-client-ui-sidebar-textpreview', kind: 'text', patterns: ['dsh-resource://file/**'], priority: 'fallback', title: basenameOf }`. The pattern contains `:` and so matches the whole address; `fallback` is the lowest band, so a type at `extension` or `builtin` with a narrower pattern (`*.png`, say) takes those addresses and everything else lands here, while the text type stays in the candidate list for any file. The `id` is the package name and doubles as the `key` of the body seat, so an extension that takes the `text` kind over cannot make the seat pick up this body by mistake. The title is the address's decoded last segment: the whole address stays the content identity — two files with one name in different directories, or one path under two sessions, are two tabs — and only the chip text is shortened.
+
+A tab's address is `dsh-resource://file/session/<sessionId>/<path relative to that session's workspace root>` or `dsh-resource://file/absolute/<absolute path>` ([Workspace Files](../architecture/2026-09-05-workspace-files-service.md) owns the grammar and the `fileAddressFor` / `parseFileAddress` helpers in `dsh-util-workspace-path`). The preview never splits the string itself: `hostFileOf` in `rpc.ts` calls `parseFileAddress` and yields the `{ sessionId, path }` the endpoint takes — a `session` address reads under the session it names with the relative path the Host resolves, an `absolute` address reads under the session the slot was mounted for with the absolute path — and a malformed address throws, a programming error, because the registry routes every `file` address to this type and a caller building one is expected to use the helper.
+
+Metadata and content come from different places. `useResource<'file'>(tab.contentId)`, the global standard hook from the [client resource model](../architecture/2026-09-05-client-resource-model.md), yields `{ absolutePath, version, bytes, changed }` from the `file` provider; the body reads `changed` and the resource's failed state. Content is the type's own business, read one page of lines at a time through `remote.workspaceFiles.read(sessionId, path, { offset }, signal)` with no `limit`, so the page length is the Host's configured cap (`maxLines`, 5000 lines by default, and a page may not exceed `maxBytes`, 2 MB by default). The first mount reads the first page; a **Load more** button at the end of the loaded text reads the next page until `eof`, disabled and reading `正在读取…` / `Reading…` while a read is in flight, and absent once the file has ended or a page failed. Pages are appended in file order with no separators and no line numbers, each carrying its line count (`lines`) so one empty line and a page past the end read differently. A first page from a newer file version replaces the pages of the older one; a later page from a newer version is not adopted and the walk restarts from the first page, so the body never shows two versions at once. The face keeps a request generation per tab: a reload bumps it, and a page settling from an older generation writes nothing. A tab switched away from and back reads nothing, because the pages live in the store, not the body.
+
+The store is Slot-standard: one exclusive instance per session, bucketed by tab id, holding `{ version, pages, eof, loading, failure, scrollTop, wrap, revision }`. Bucketing by tab, not by file, is deliberate — two tabs of one file scroll independently. The face (`loadPage`, `reloadPages`) is the only asynchronous half: it marks a read in flight, awaits the Remote result, and writes a page or a failure through the store's actions, writing nothing if the owner's `signal` has fired. The `signal` also ends the bucket: the face arms one abort listener per tab at the tab's first read, and that listener forgets the bucket — not the body, which mounts and unmounts as tabs switch; a tab that never read has no bucket and no listener, and a record can end while its body is unmounted behind another tab. Scroll offset, wrap, and the navigation already answered therefore outlive the body: a tab comes back where the reader left it rather than re-reading or jumping again. Nothing persists across a page reload.
+
+Navigation is a `line`. The `read` tool row passes its 1-based `offset` as `openResource(address, { params: { line } })`, and the produced-file chip passes nothing; the body narrows `navigation.params` to `SidebarRightResourceParamsMap['file']` (`{ line?: number }`, declared by the `file` type's owner) without runtime validation, because caller and body meet at a typed same-process boundary. If the loaded pages do not reach the line, the body reads the next page, again, until they do or the file ends — pages load in order; there is no seek — then scrolls the line to the top of the body and highlights it, once per `navigation.revision`. The store records the answered revision, so a body remounting for the same revision restores the scroll offset instead of jumping, and a new `openResource` for the same file (revealed, not duplicated) arrives as a new revision and jumps again. A line past the end of the file stops silently at `eof`; a page that fails while walking stops the walk and shows the failure line.
+
+A changed file is announced, not applied. When the `file` resource reports `changed` — the agent wrote the file through a tool after the last `stat` — a bar above the path row says `文件已被修改，显示的还是旧内容。` / `The file has changed; this is the older text.` with a `重新载入` / `Reload` button. Only the click does two things at once: `meta.reload()` (a fresh `stat`, which clears `changed`) and `reloadPages` (drop every page, read the first one again). The scroll offset is kept, so the reader stays where they were. Nothing else triggers a reload: the tree and the preview do not watch the filesystem, and an external edit is not announced. A resource that turns `failed` — the file deleted, or the Host refusing it — puts a failure bar in the same place, its line from `failure-line.ts` and the same reload button, ahead of any pending `changed`; the pages already read stay beneath it.
+
+The body's header is one row: the file's path as the address names it on the left (12px, tertiary colour, one line, ellipsis when it overflows, full path on hover) and two 24px controls at its right end — a wrap toggle (`自动换行` / `Wrap lines`, pressed state shown, **on by default** per tab: long lines wrap and never scroll horizontally until the reader turns it off, whereupon the file body scrolls horizontally on its own) and a reload button (`重新读取文件` / `Read the file again`) that does exactly what the change bar's button does. Neither control is ever disabled. The preview takes the pane body's full height (`height: 100%` against the pane body, which is a block scroller of definite height) so a short file leaves no separately styled space below it, and the file body — monospace, 13px, line height 1.6, 10px vertical padding — is the only scroller: the header and the change bar stay put while a long file scrolls under them.
+
+A failed page keeps the pages already shown and adds one sentence at the end of the loaded text, in terms of the file rather than the transport, with a `重试` / `Retry` button that reads the same page again: `workspace-file/not-found` `这个文件不在了。可能已被移动或删除。` / `That file is gone. It may have been moved or deleted.`; `workspace-file/outside-workspace` `这个文件在工作区之外，侧栏不会读取它。` / `That file is outside the workspace, so the sidebar will not read it.`; `workspace-file/too-large` `这一页太大，侧栏不读取超过 {limit} 的页。` / `That page is too large; the sidebar does not read pages above {limit}.` with the byte cap rendered as `2 MB`; `workspace-file/not-text` `这不是文本文件，没法在这里查看。` / `That is not a text file, so it cannot be shown here.`; `workspace-file/not-regular-file` `这不是一个普通文件，没有可显示的文本。` / `That is not a regular file, so it has no text to show.`; any other failure, carrier or unclassified, `读取失败：{message}` / `Read failed: {message}` with the failure's own message. The mapping lives in `failure-line.ts`, apart from the component so it is testable on its own; a code the reader does not name falls to the generic line carrying the carrier's message. A directory or a binary file therefore shows one failure line and nothing else; an empty file shows the header and an empty body with no marker.
+
+### 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: IconFolderClose16 }] }` — no `patterns`, because nothing navigates *to* a file tree by address; the guide's entry box opens the type itself. `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.
+
+The tree is not one resource, and that decides where its state lives. A directory listing per level, expanded lazily, is view state the type owns, so it sits in a Slot-standard exclusive store (one instance per session) bucketed by tab id: `{ root, levels, expanded }`, with `levels` keyed by absolute path to `loading | ready | failed` and `expanded` the absolute paths currently open, root included. A resource has one address and one current value; a tree that pins a resource per expanded level would make the resource model carry which directories a reader has opened, which is the type's business. `useResource` stays for content with a single address.
+
+The face is the tree's only asynchronous half. `start(tabId, root, signal)` seeds the bucket with the root expanded and lists it; `toggle(tabId, path, loaded, signal)` flips the expanded set and lists the level only the first time; `load(tabId, path, signal)` marks `loading`, calls `remote.workspaceFiles.list(sessionId, absolutePath, signal)`, and writes `ready` or `failed`. The adapter keeps the listing's `entries` and `truncated` and drops its workspace-relative `path`: every key in the tree is absolute, and a child's key is its parent joined with the entry name by `/`. Collapsing keeps the level, so reopening draws from memory without a request; a level that failed is likewise kept and not retried on reopen — reload is the retry. The owner's `signal` ends a bucket: on abort the tab is forgotten and a listing that settles afterwards writes nothing, and a mounted body never re-seeds a bucket whose signal has fired.
+
+Rows are the reader's order, not the endpoint's: directories first, then files and other entries, each group by `Intl.Collator(undefined, { numeric: true, sensitivity: 'base' })` so `file2` precedes `file10` and case does not split the list. Dotfiles are shown like any other name; the tree filters nothing the Host returned. The three entry types draw differently: `directory` is a button with `aria-expanded` and an open/closed folder glyph whose children indent by 14px per level; `file` is a button with the document glyph and no size column; `other` (a symlink, socket, or device) is a greyed, non-focusable span with `aria-disabled` and a tooltip saying it cannot be opened, so a directory is reported whole without offering a click that would fail. A level the Host cut at its `maxEntries` cap ends with a `truncated` marker after the entries; an empty level says `empty`; a listing in flight shows `loading` under its directory.
+
+A file click is `tabActions.openResource(fileAddressFor(sessionId, root, absolutePath))`: the entry's absolute path under the tree's root becomes the `dsh-resource://file/session/<sessionId>/<path relative to the root>` address, each segment percent-encoded. The tree never names a viewer: the registry's claim decides who draws the address (`text` today, at `fallback`), and an extension that claims `dsh-resource://file/**` above it takes the click without the tree changing. The open lands in the pane holding the files tab at call time, and an already-open tab for the same address is revealed rather than duplicated — both the navigation controller's defaults. The user's call was explicit: a file opened from the tree does not force a split; it takes a new tab where the tree is.
+
+Reload is the tree's one control, an icon button (`reload`) at the right of the root's header row. It resets every level and lists again exactly the paths in `expanded`; a level that was listed and then collapsed is dropped and fetched anew the next time it opens. The control lives in the body because a type's controls belong to its body: the pane's tab strip carries only the kit's and the panel's actions, and no per-type tools seat exists. The tree does not watch the filesystem; a level changes only when reloaded or first expanded, and the `changes` stream is the text viewer's concern.
+
+Copy is the `sidebarFiles` namespace, thirteen keys. Row states: `loading` 「正在读取…」/ "Reading…", `empty` 「空目录」/ "Empty directory", `truncated` 「条目太多，只显示了一部分。」/ "Too many entries; showing only some of them.", `noWorkspace` 「这个会话没有工作区目录。」/ "This session has no workspace directory.", `entry.other` 「这不是文件或目录，没法打开。」/ "Not a file or a directory, so it cannot be opened.", `reload` 「重新读取」/ "Reload". Failure lines are one per Host code, in terms of the directory: `workspace-file/not-found` 「这个目录不在了。可能已被移动或删除。」/ "That directory is gone. It may have been moved or deleted.", `workspace-file/outside-workspace` 「这个目录在工作区之外，侧栏不会读取它。」/ "That directory is outside the workspace, so the sidebar will not read it.", `workspace-file/not-directory` 「这不是一个目录。」/ "That is not a directory."; any other failure, carrier or unclassified, shows `error.unavailable` 「读取失败：{message}」/ "Read failed: {message}" with the failure's own message, because the tree has nothing useful to add to a transport-level error.
+
+## Alternatives considered
+
+**A per-pane tools seat for the active tab's controls (`sidebar.right.pane.tab.tools`).** Shipped for one review round for the text preview's wrap and reload and the tree's reload, then removed on the user's call: it put type-private buttons on the panel's strip beside the split and collapse controls, where they read as panel chrome. A type's controls belong in its own body; the preview's sit at the right end of its path row and the tree's at the right end of its root row.
+
+**Keep `Show in folder`.** A directory has no destination in the Sidebar, and the product decision was no secondary entry to the desktop opener. Removed, with the capability loss stated: `openFile('.')` names a directory, which the text preview refuses with `not-regular-file`, so the row offers nothing rather than a button that always fails.
+
+**Content in the resource stream.** Content can be arbitrarily large, so the `file` resource carries metadata (`version`, `bytes`, `changed`) and the preview reads content by page through `workspaceFiles.read`; the `changed` flag is a notice, not a payload.
+
+**Reload re-fetches every page that was loaded.** The alternative to the shipped rule (drop every page, read the first one again). Not taken: re-fetching the loaded range means several sequential reads before anything can be shown, and the loaded range after an agent edit no longer describes the same lines; the reader keeps their scroll offset and asks for more where the loaded text ends. The reader's place can land in empty space when the earlier view was deep in the file, which is stated as a consequence.
+
+**Refresh the text under the reader when the file changes.** Rejected: reloading under a reader loses their place, and a file the agent is writing changes repeatedly. The bar waits for a click.
+
+**Whole-file read, or seekable pages.** A whole-file read has no bound; seekable pages need a line index the Host does not keep. Pages load in order from the first, and a navigation to a deep line walks pages until it is covered — the cost is stated under Consequences and the seek is deferred.
+
+**Validate `line` at run time.** The first form accepted `unknown` params and treated anything but a positive integer as no request. Rejected once `params` became typed: the `file` type's owner declares `{ line?: number }` in `SidebarRightResourceParamsMap`, caller and body meet at a typed same-process boundary, and the repository rule is not to add runtime validation there.
+
+**The read's session from the slot for every address.** The first form read under the session the body was mounted for. Kept only for the `absolute` scope, which names no session: a `session` address carries its session precisely so that one relative path in two sessions means two files.
+
+**Wrap off by default.** The first form. Reversed on the user's review: a preview column is narrow, and long lines scrolling horizontally hide the text; wrap is on until the reader turns it off, per tab.
+
+**Fill the pane by changing the docking kit's `.paneBody`.** The pane body is a block scroller with a definite height, not a flex container, so the preview's `flex: 1` did nothing and the pane body scrolled a 30,000px-tall preview. Rejected in favour of `height: 100%` on the preview root: the fix is the type's, the kit stays unaware of its bodies, and the file body becomes the one scroller so the header stays put and line jumps scroll the right element.
+
+**Key the store by file, not by tab.** Rejected: two tabs of one file are two reading positions; the pages could be shared but the view could not, and the saving is one page read.
+
+**A package-local `file:///` address builder, and a package-local basename for the tree's root label.** Rejected: a file address must carry its scope — the session whose root resolves a relative path, or the absolute path itself — hence the shared `fileAddressFor`; one `workspaceTitleOf` serves every workspace-label surface.
+
+**Model the whole tree as one resource.** Rejected: a resource has one address and one current value, and a tree that pins a resource per expanded level would make the resource model carry which directories a reader has opened, which is the type's business.
+
+**The guide as a chain entry rather than the chain's fallback.** Rejected: with the shipped guide as an entry, a product's replacement and the shipped guide would both be candidates and the winner would depend on registration order; as the fallback there is always exactly one body and it cannot be outvoted by accident.
+
+**The guide opens the picked type beside itself.** Rejected: the guide is a doorway, and a pane holding the guide plus what it opened would show a doorway that leads nowhere further; `openTab(kind, { replaceTab: true })` hands the tab over.
+
+## Consequences
+
+- A type written outside `ui-sidebar-right` has a complete template: `ui-sidebar-textpreview` shows a viewer with an address-derived read, an exclusive Slot store bucketed by tab, an inject face, typed navigation params, and body-owned controls; `ui-sidebar-files` shows a page type with a guide entry and a lazily filled store; the guide shows a chain fallback.
+- Reading by page bounds every request (`maxLines` lines, `maxBytes` bytes) at the cost of a **Load more** control, no total line count, and sequential walks to a deep line; a navigation to line 40,000 of a large file reads eight pages first.
+- Announcing a change instead of applying it keeps the reader's place during an agent's repeated writes, at the cost of showing stale text until the reader clicks; an external edit is never announced.
+- Reload reads the first page only, so a reader deep in a file reloads into the top of it and pages forward again; the scroll offset is preserved but may point past the loaded text.
+- Per-tab view state survives tab switches and remounts and is gone with the tab or the page; nothing is persisted.
+- The file tree renders whatever the Host lists, so a large directory shows up to `maxEntries` rows plus a marker with no search or filter, and a reader finds a deep file by expanding levels one at a time.
+- Every user-facing string of the three types is locale-owned and listed in this note, so a copy review has one place to read them.
+
+## Testing
+
+The text preview's `tests/` cover the registry claim and yielding (through the real `SidebarRightTabRegistry`), the address translation (`sessionFileOf` accepting the `session` scope and throwing on others), the store's page, version, reset, view, and forget actions, the face's in-flight, failure, aborted, and reload paths, the page arithmetic (`linesOf`, `offsetsOf`, `lastLineLoaded`), the body's first read, load-more, retry, change bar, navigation walk, jump-once, remount, wrap default and toggle, header controls, and forget-on-abort, the failure-line mapping, and the plugin's registrations and their removal on dispose. A Chromium probe against the built app recorded the fill and scroll numbers (`.artifacts/sidebar-tab-types/app-probe.log`, `ROUND3`): a short file's preview is the pane body's content height, a long file scrolls inside the preview body, and the pane body never scrolls. The file tree's `tests/` cover ordering, lazy loading, collapse memory, reload, the three entry types, truncation and failure rows, and forget-on-abort. `apps/web/tests/sidebar-right.e2e.ts` opens a produced file from the conversation into the preview over the real Remote carrier.
+
+## Deferred
+
+- Virtualized or seekable page loading (pages load in order), a reload that restores the loaded range, throttled scroll persistence, and a wrap icon in `ui-primitives`.
+- Line numbers, syntax highlighting, rendered Markdown, images, and search in the text preview; a total line count or end-of-file marker.
+- Search, an artifact filter, drag-and-drop, rename, a context menu, current-file highlight, filesystem watching, and browsing above the workspace root in the file tree.
+- Product review of the guide's copy, and the guide's behaviour when a type contributes several entries.
+- Chinese README counterparts for `ui-sidebar-textpreview` and `ui-sidebar-files`.
+
+## Related
+
+- [Right Sidebar docking infrastructure](2026-09-04-right-sidebar-docking-infrastructure.md) — the panel, panes, and the guide's one-per-pane rule.
+- [Sidebar tab types and navigation](../architecture/2026-09-05-sidebar-tab-types-and-navigation.md) — the registry, bands, `id`, `openTab` / `openResource`, and owner props these types consume.
+- [Client resource model](../architecture/2026-09-05-client-resource-model.md) — `useResource` and the `file` protocol's metadata.
+- [Workspace Files service](../architecture/2026-09-05-workspace-files-service.md) — the address grammar, `stat` / `read` / `list` / `changes`, and the error codes the failure lines map.

.agents/notes/implemented/feature/2026-09-05-sidebar-text-preview-and-file-tree.zh.md

@@ -0,0 +1,122 @@
+# Agent Note: Sidebar 文本预览与文件树
+
+Status: implemented
+
+[English](2026-09-05-sidebar-text-preview-and-file-tree.md) | 中文
+
+## Problem
+
+右侧 Sidebar 的[停靠基础设施](2026-09-04-right-sidebar-docking-infrastructure.zh.md)与[tab 类型注册表](../architecture/2026-09-05-sidebar-tab-types-and-navigation.zh.md)给了插件一个注册 tab 类型的位置，但没有类型的停靠面只是一根空列。三个问题必须先由随包交付的代码答出来，别人才谈得上注册类型：一个新 pane 在承载内容之前显示什么；agent 产出或读过的文件如何不离开产品就能查看；读者如何找到会话从未提到的文件。这些答案还要把类型作者模型完整演示一遍——静态定义、keyed 坑位里的体、类型自有状态用的 Slot store 与 inject face、地址背后活数据用的 `useResource`——让 `ui-sidebar-right` 之外写的类型有一份可照抄的样板，而不只有一份契约。
+
+每个答案都带着代码本身解释不了的产品规则：文本文件为什么按页读而不是整读，文件变了为什么只提示不刷新，文件树为什么是不认领任何地址的页类型，引导页为什么交出自己的 tab 而不是在旁边再开一个。本文为三个随包交付的类型记下这些决定。
+
+## Decision
+
+Sidebar 随包交付三个 tab 类型：**引导页**（`ui-sidebar-right`）、**文本预览**（`ui-sidebar-textpreview`）与**文件树**（`ui-sidebar-files`）。每个类型都在自己的 `ctx.effect` 里把静态定义注册进 `ctx.sidebarRightTabs`、把体注册进 keyed 坑位 `sidebar.right.pane.tab`（键 = 定义的 `id`），因此类型的寿命恰等于其插件。引导页与文件树是按 kind 打开的页类型；文本预览是以最低档认领每个 `file` 资源地址的查看器。类型的控件住在自己的体里；pane 的 tab 条只承载面板自身的动作。文案由各包的命名空间（`sidebarRight`、`sidebarTextpreview`、`sidebarFiles`）以 locale 方式持有。
+
+### 引导页
+
+引导页是 pane 承载内容之前显示的东西。它的注册定义是 `{ id: '@deepseek-ai/dsh-client-ui-sidebar-right/guide', kind: 'guide', priority: 'builtin', title }`，没有 `patterns`：引导页不查看任何东西，所以经 `openTab` 按 kind 打开，并记在页地址 `sidebar://guide` 之下——那是注册表自己的记账，调用方从不拼它。tab 标题是 `开始` / `Start`，在 pane 播种时捕获进布局记录，于是之后切换语言只重标类型，不改已开着的 tab。
+
+体是一根居中的列——一句引导语（`侧栏用来放你想一直看着的东西。` / `The sidebar holds what you want to keep looking at.`）、一行文案（`会话里的文件和产物会开在这一栏，也可以从下面的入口打开。` / `Files and artifacts from the conversation open in this column; the entries below open more.`），以及一组最宽 480px 的入口框栅格，每框至少 160px，能放几列放几列。入口框按 `order` 从每个已注册类型的 `guide[]` 投影而来，经注册表可观察的 `guide()` 列表，因此后注册的类型不用引导页知道就能出现。一个框显示贡献类型的图标、标题与说明；点选它调用 `tabActions.openTab(entry.kind, { replaceTab: true })`：被选的类型在引导页自己的 tab 里打开，引导页随之消失。引导页是一扇门，不是留在被打开者旁边的一页。
+
+体同时也是替换接缝。它渲染 `sidebar.right.tab.guide` 链，并以随包交付的引导页作为链的 fallback，于是注册了自己入口的产品接管整个体，而没有入口、或每个入口都拒绝时，随包交付的引导页照常绘制。因为随包交付的引导页是 fallback 而不是链上的一个入口，所以永远恰有一个体，也不可能被意外投掉。
+
+一个 pane 最多持有一个引导页，停靠层把这条作为产品行为强制执行：有引导页时 tab 条的添加控件隐藏，往这样的 pane 打开引导页只是聚焦它，引导页永不复制，被拖拽、落下或回坞进已有引导页的 pane 的引导页并入它（来者关闭）。settle 一个 surface 时，根 pane 空了就重新播下引导页，于是永远至少有一个 tab、永远没有空 pane。
+
+### 文本预览
+
+`text` 是每个文件的兜底查看器。它的注册定义是 `{ id: '@deepseek-ai/dsh-client-ui-sidebar-textpreview', kind: 'text', patterns: ['dsh-resource://file/**'], priority: 'fallback', title: basenameOf }`。pattern 含 `:`，因此匹配整个地址；`fallback` 是最低档，所以 `extension` 或 `builtin` 档上一个 pattern 更窄的类型（比如 `*.png`）接走那些地址，其余一切落到这里，而 text 类型对任何文件都留在候选列表中。`id` 是包名，兼作体坑位的 `key`，于是一个接管了 `text` kind 的扩展不可能让坑位误拿到这个体。标题是地址解码后的最后一段：整个地址仍是内容身份——不同目录下同名的两个文件、或同一路径在两个会话之下，是两个 tab——只有 chip 上的文字被缩短。
+
+tab 的地址是 `dsh-resource://file/session/<sessionId>/<相对该会话工作区根的路径>` 或 `dsh-resource://file/absolute/<绝对路径>`（[Workspace Files](../architecture/2026-09-05-workspace-files-service.zh.md) 拥有这套语法及 `dsh-util-workspace-path` 里的 `fileAddressFor` / `parseFileAddress` 助手）。预览从不自己拆这个串：`rpc.ts` 里的 `hostFileOf` 调 `parseFileAddress` 得到端点所需的 `{ sessionId, path }`——`session` 地址在它命名的会话下以 Host 解析的相对路径读取，`absolute` 地址在坑位被挂载的会话下以绝对路径读取——畸形地址直接抛错，那是程序错误，因为注册表把每个 `file` 地址都路由给这个类型，而造地址的调用方本应使用助手。
+
+元数据与内容来自不同的地方。`useResource<'file'>(tab.contentId)`——[client 资源模型](../architecture/2026-09-05-client-resource-model.zh.md)提供的全局标准 hook——从 `file` 提供者得到 `{ absolutePath, version, bytes, changed }`；体读 `changed` 与资源的失败态。内容是类型自己的事，经 `remote.workspaceFiles.read(sessionId, path, { offset }, signal)` 一次读一页行，不传 `limit`，因此页长就是 Host 配置的上限（`maxLines`，默认 5000 行；且一页不得超过 `maxBytes`，默认 2 MB）。首次挂载读第 1 页；已加载文本末尾的 **加载更多** 按钮读下一页直到 `eof`，读取进行中它禁用并显示 `正在读取…` / `Reading…`，文件读完或某页失败后消失。页按文件顺序追加，没有分隔也没有行号，每页带着自己的行数（`lines`），单个空行与越过文件末尾的页由此区分。来自更新文件版本的第一页替换旧版本的页；更新版本的后续页不被采用，从第一页重新走一遍，于是体永不同时显示两个版本。face 按 tab 记请求代次：重载递增它，旧代次结算的页什么也不写。切走再切回的 tab 什么都不读，因为页住在 store 里而不是体里。
+
+store 是 Slot 标准件：每会话一个独占实例，按 tab id 分桶，持有 `{ version, pages, eof, loading, failure, scrollTop, wrap, revision }`。按 tab 而非按文件分桶是有意的——同一文件的两个 tab 各自滚动。face（`loadPage`、`reloadPages`）是唯一的异步半边：它标记读取进行中，等待 Remote 结果，再经 store 的 action 写入一页或一次失败；若 owner 的 `signal` 已触发则什么也不写。`signal` 同时终结这个桶：face 在 tab 首次读取时挂一个 abort 监听器，由它忘掉桶——不是体，体随 tab 切换反复挂载卸载；从未读过的 tab 没有桶也没有监听器，而 tab 记录可能在其体被另一 tab 挡住而卸载时结束。因此滚动位置、换行与已答过的导航都活得比体久：tab 回来时停在读者离开的地方，而不是重读或再跳一次。刷新页面后什么都不保留。
+
+导航是一个 `line`。`read` 工具行把它 1 起的 `offset` 以 `openResource(address, { params: { line } })` 传来，产物 chip 什么都不传；体把 `navigation.params` 收窄为 `SidebarRightResourceParamsMap['file']`（`{ line?: number }`，由 `file` 类型的拥有者声明），不做运行时校验，因为调用方与体相遇在同进程的类型化边界上。已加载的页够不到该行时，体读下一页，再读，直到覆盖它或文件结束——页按顺序加载，没有 seek——然后把该行滚到体顶部并高亮，每个 `navigation.revision` 一次。store 记下已答过的 revision，于是同一 revision 下重新挂载的体恢复滚动位置而不再跳；对同一文件再次 `openResource`（聚焦而非复制）以新 revision 到来并再跳一次。超出文件末尾的行在 `eof` 处静默停下；补页途中失败的页终止补页并显示失败行。
+
+文件变了只提示，不应用。当 `file` 资源报告 `changed`——agent 在上次 `stat` 之后经工具写了该文件——路径行上方出现一条提示 `文件已被修改，显示的还是旧内容。` / `The file has changed; this is the older text.`，带一个 `重新载入` / `Reload` 按钮。只有点击才同时做两件事：`meta.reload()`（重新 `stat`，清掉 `changed`）与 `reloadPages`（丢掉所有页，重读第 1 页）。滚动位置保留，读者停在原处。没有别的东西触发重载：树和预览都不监听文件系统，外部编辑不会被提示。资源变为 `failed`——文件被删，或 Host 拒绝——时，同一位置出现一条失败条，句子来自 `failure-line.ts`，带同一个重新载入按钮，并优先于尚未处理的 `changed`；已读的页留在它下方。
+
+体的头部是一行：左边是地址所命名的文件路径（12px、三级色、单行、溢出省略号、悬停显示完整路径），右端是两个 24px 控件——换行开关（`自动换行` / `Wrap lines`，显示按下态，**默认开**、按 tab 记：长行折行、绝不横向滚动，直到读者关掉它，此后文件体自己横向滚动）与一个重新读取按钮（`重新读取文件` / `Read the file again`），做的恰是变更提示条按钮做的事。两个控件都永不禁用。预览占满 pane 体的全部高度（对 pane 体取 `height: 100%`；pane 体是高度确定的块级滚动容器），于是短文件下方不留另一块样式不同的空白，而文件体——等宽、13px、行高 1.6、上下 10px 内边距——是唯一的滚动者：长文件在头部与变更提示条之下滚动，二者不动。
+
+某页失败时，已显示的页保留，并在已加载文本末尾加一句以文件而非传输为主语的说明，带一个重读同一页的 `重试` / `Retry` 按钮：`workspace-file/not-found` `这个文件不在了。可能已被移动或删除。` / `That file is gone. It may have been moved or deleted.`；`workspace-file/outside-workspace` `这个文件在工作区之外，侧栏不会读取它。` / `That file is outside the workspace, so the sidebar will not read it.`；`workspace-file/too-large` `这一页太大，侧栏不读取超过 {limit} 的页。` / `That page is too large; the sidebar does not read pages above {limit}.`，字节上限渲染为 `2 MB` 这样的形式；`workspace-file/not-text` `这不是文本文件，没法在这里查看。` / `That is not a text file, so it cannot be shown here.`；`workspace-file/not-regular-file` `这不是一个普通文件，没有可显示的文本。` / `That is not a regular file, so it has no text to show.`；其余任何失败，无论载体层还是未分类，`读取失败：{message}` / `Read failed: {message}` 并带上失败自身的消息。映射住在 `failure-line.ts` 里，与组件分开以便单独测试；读者未命名的错误码落到带传输层消息的通用句。目录或二进制文件因此只显示一行失败说明；空文件显示头部与一个空的体，没有任何标记。
+
+### 文件树
+
+`files` 是页类型，不是查看器：它不认领任何地址。注册定义是 `{ kind: 'files', id: '@deepseek-ai/dsh-client-ui-sidebar-files', priority: 'builtin', title, guide: [{ order: 10, title, description, icon: IconFolderClose16 }] }`——没有 `patterns`，因为没有谁按地址导航*到*一棵文件树；引导页的入口框打开的是类型本身。`id` 是这个实现在 Tab 系统里的唯一键，同时也是体坑位 `sidebar.right.pane.tab` 的 `key`，于是同一个串既命名类型也命名画它的组件。`register()` 返回 disposer 并经 `ctx.effect` 注册，与所有注册一致。
+
+根是 Host 在会话列表里上报的会话工作目录（`useSessions().byId[sessionId].cwd`），标签由 `dsh-util-workspace-path` 的 `workspaceTitleOf` 给出——路径最后一个非空段——路径只有分隔符时用根串本身作标签。没有工作目录的会话只显示一行（`noWorkspace`），不发请求。没有根选择器，也不能往上浏览：Host 的 `list` 拒绝会话工作区根之外的路径，所以客户端能列的那一个目录就是它显示的目录。
+
+树不是一个资源，这决定了它的状态住在哪。逐层懒加载的目录列表是类型自己拥有的视图状态，所以它住在 Slot 标准的独占 store（每会话一实例）里、按 tab id 分桶：`{ root, levels, expanded }`，`levels` 以绝对路径为键取 `loading | ready | failed`，`expanded` 是当前展开的绝对路径集合，含根。资源有一个地址和一个当前值；一棵为每个展开层钉一个资源的树，会让资源模型背上「读者展开了哪些目录」，而那是类型的事。`useResource` 留给只有一个地址的内容。
+
+face 是树唯一的异步半边。`start(tabId, root, signal)` 以根展开态播种桶并列出根；`toggle(tabId, path, loaded, signal)` 翻转展开集合并只在第一次列出该层；`load(tabId, path, signal)` 标 `loading`，调 `remote.workspaceFiles.list(sessionId, absolutePath, signal)`，写 `ready` 或 `failed`。适配层保留列表的 `entries` 与 `truncated`、丢弃其工作区相对 `path`：树里每个键都是绝对路径，子键 = 父路径以 `/` 拼上条目名。折叠保留该层，再展开直接从内存画不再请求；失败的层同样保留、再展开不重试——重试靠重新读取。owner 的 `signal` 终结一个桶：abort 时忘掉该 tab，其后才结算的列表什么也不写，已挂载的体也不会给 signal 已触发的桶重新播种。
+
+行序是读者的序，不是端点的序：目录在前，文件与其他条目在后，组内按 `Intl.Collator(undefined, { numeric: true, sensitivity: 'base' })`，于是 `file2` 排在 `file10` 前、大小写不拆开列表。dotfiles 与其他名字一样显示；Host 返回的东西树一个不过滤。三种条目类型画法不同：`directory` 是带 `aria-expanded` 的按钮、开/闭文件夹图标，子层每级缩进 14px；`file` 是带文档图标的按钮，没有大小列；`other`（符号链接、套接字、设备）是灰色、不可聚焦的 span，带 `aria-disabled` 与「不能打开」的提示，这样目录被完整报告，又不提供一个注定失败的点击。被 Host 按 `maxEntries` 上限截断的层在条目末尾以 `truncated` 标记收尾；空层显示 `empty`；进行中的列表在其目录下显示 `loading`。
+
+点文件即 `tabActions.openResource(fileAddressFor(sessionId, root, absolutePath))`：条目在树根之下的绝对路径成为每段百分号编码的 `dsh-resource://file/session/<sessionId>/<相对根的路径>` 地址。树从不指名查看器：由注册表的认领决定谁画这个地址（今天是 `fallback` 档的 `text`），一个在其上认领 `dsh-resource://file/**` 的扩展接走点击而树无需改动。打开落在点击时文件树 tab 所在的那个 pane，同地址已开着的 tab 被聚焦而不复制——两者都是导航控制器的缺省。用户明确拍过：从树里打开的文件不强制分格；它在树所在处开一个新 tab。
+
+重新读取是树唯一的控件，是根标题行右端的图标按钮（`reload`）。它重置所有层，并恰好重新列出 `expanded` 里的那些路径；曾列出后又折叠的层被丢弃，下次展开时重新拉取。控件住在体内，因为类型的控件属于它的体：pane 的 tab 条只承载布局库与面板自身的动作，不存在按类型的工具坑位。树不监听文件系统；一层只在重新读取或首次展开时变化，`changes` 流是文本查看器的事。
+
+文案是 `sidebarFiles` 命名空间，十三个键。行状态：`loading`「正在读取…」/ "Reading…"，`empty`「空目录」/ "Empty directory"，`truncated`「条目太多，只显示了一部分。」/ "Too many entries; showing only some of them."，`noWorkspace`「这个会话没有工作区目录。」/ "This session has no workspace directory."，`entry.other`「这不是文件或目录，没法打开。」/ "Not a file or a directory, so it cannot be opened."，`reload`「重新读取」/ "Reload"。失败行按 Host 错误码一码一句、以目录为主语：`workspace-file/not-found`「这个目录不在了。可能已被移动或删除。」/ "That directory is gone. It may have been moved or deleted."，`workspace-file/outside-workspace`「这个目录在工作区之外，侧栏不会读取它。」/ "That directory is outside the workspace, so the sidebar will not read it."，`workspace-file/not-directory`「这不是一个目录。」/ "That is not a directory."；其余任何失败，无论载体层还是未分类，显示 `error.unavailable`「读取失败：{message}」/ "Read failed: {message}" 并带上失败自身的消息，因为树对传输级错误没有什么有用的可补充。
+
+## Alternatives considered
+
+**给活跃 tab 的控件开一个按 pane 的工具坑位（`sidebar.right.pane.tab.tools`）。** 为文本预览的换行与重新读取、文件树的重新读取交付过一轮评审，随后按用户意见删除：它把类型私有的按钮放到面板 tab 条上、分栏与折叠控件旁边，读起来像面板自身的 chrome。类型的控件属于它自己的体；预览的在其路径行右端，树的在其根行右端。
+
+**保留 `Show in folder`。** 目录在 Sidebar 里没有去处，而产品决定是不给桌面打开器留次级入口。已删除，能力损失如实陈述：`openFile('.')` 命名的是目录，文本预览以 `not-regular-file` 拒绝它，于是该行什么都不提供，而不是给一个注定失败的按钮。
+
+**把内容放进资源流。** 内容可以任意大，所以 `file` 资源只携带元数据（`version`、`bytes`、`changed`），预览经 `workspaceFiles.read` 按页读内容；`changed` 是通知，不是载荷。
+
+**重新载入重取所有已加载过的页。** 相对于已交付规则（丢掉所有页、重读第 1 页）的另一条路。未采纳：重取已加载范围意味着显示任何东西之前要先做多次顺序读取，而 agent 编辑之后的已加载范围也不再描述同样的行；读者保留滚动位置，在已加载文本末尾继续要更多。先前视口在文件深处时读者的位置可能落到空白，这一点在 Consequences 里如实陈述。
+
+**文件变了就在读者眼前刷新文本。** 否决：在读者眼前重载会丢掉他的位置，而 agent 正在写的文件会反复变化。提示条等点击。
+
+**整文件读取，或可 seek 的页。** 整文件读取没有上界；可 seek 的页需要 Host 不维护的行索引。页从第 1 页起按顺序加载，导航到深处某行时逐页补到覆盖为止——代价在 Consequences 里陈述，seek 推迟。
+
+**在运行时校验 `line`。** 第一版接受 `unknown` 参数，非正整数一律视为没有请求。`params` 类型化之后否决：`file` 类型的拥有者在 `SidebarRightResourceParamsMap` 中声明 `{ line?: number }`，调用方与体相遇在同进程的类型化边界上，仓规是那里不加运行时校验。
+
+**每种地址都从坑位取读取的会话。** 第一版在体被挂载的会话下读取。只对不命名会话的 `absolute` 作用域保留：`session` 地址带着自己的会话，正是为了让同一相对路径在两个会话里是两个文件。
+
+**换行默认关。** 第一版。用户评审后反转：预览列很窄，长行横向滚动会把文字藏起来；换行默认开直到读者关掉，按 tab 记。
+
+**靠改布局库的 `.paneBody` 来撑满 pane。** pane 体是高度确定的块级滚动容器，不是 flex 容器，所以预览的 `flex: 1` 不起作用，pane 体滚动着一个 30,000px 高的预览。否决，改为在预览根上取 `height: 100%`：修复属于类型自己，布局库对其体保持无知，文件体成为唯一的滚动者，于是头部不动、跳行滚动的也是正确的元素。
+
+**store 按文件而非按 tab 分键。** 否决：同一文件的两个 tab 是两个阅读位置；页可以共享而视图不能，省下的只是一次页读取。
+
+**包内自造 `file:///` 地址，以及包内自写 basename 作树的根标签。** 否决：文件地址必须带自己的作用域——以其根解析相对路径的会话，或绝对路径本身——因此用共享的 `fileAddressFor`；一个 `workspaceTitleOf` 服务所有工作区标签面。
+
+**把整棵树建模为一个资源。** 否决：资源有一个地址和一个当前值，一棵为每个展开层钉一个资源的树，会让资源模型背上「读者展开了哪些目录」，而那是类型的事。
+
+**引导页作为链上的入口而非链的 fallback。** 否决：随包交付的引导页若是一个入口，产品的替换者与它会同为候选，胜者取决于注册顺序；作为 fallback 则永远恰有一个体，且不可能被意外投掉。
+
+**引导页在自己旁边打开被选的类型。** 否决：引导页是一扇门，一个同时持有引导页与它所打开内容的 pane 会显示一扇不再通向别处的门；`openTab(kind, { replaceTab: true })` 把 tab 交出去。
+
+## Consequences
+
+- `ui-sidebar-right` 之外写的类型有了一份完整样板：`ui-sidebar-textpreview` 演示一个查看器——由地址推出的读取、按 tab 分桶的独占 Slot store、inject face、类型化的导航参数与体内自有控件；`ui-sidebar-files` 演示一个带引导入口、懒填充 store 的页类型；引导页演示一个链 fallback。
+- 按页读取让每次请求都有界（`maxLines` 行、`maxBytes` 字节），代价是一个 **加载更多** 控件、没有总行数，以及到深处某行的顺序补页；导航到一个大文件的第 40,000 行要先读八页。
+- 只提示不应用，让读者在 agent 反复写入期间保住位置，代价是点击之前显示的是旧文本；外部编辑永不提示。
+- 重新载入只读第 1 页，所以身在文件深处的读者重载后回到文件开头再往后翻；滚动位置保留但可能指向已加载文本之外。
+- 按 tab 的视图状态跨 tab 切换与重新挂载存活，随 tab 或页面一起消失；什么都不持久化。
+- 文件树渲染 Host 列出的一切，因此大目录最多显示 `maxEntries` 行加一个标记，没有搜索或过滤，读者靠逐层展开找到深处的文件。
+- 三个类型面向用户的每条文案都由 locale 持有并列在本文中，文案评审只需读一处。
+
+## Testing
+
+文本预览的 `tests/` 覆盖：注册表认领与让位（经真实的 `SidebarRightTabRegistry`）、地址翻译（`sessionFileOf` 接受 `session` 作用域、其他一律抛错）、store 的页、版本、reset、视图与 forget 各 action、face 的进行中、失败、abort 与重载路径、页算术（`linesOf`、`offsetsOf`、`lastLineLoaded`）、体的首读、加载更多、重试、变更提示条、导航补页、只跳一次、重新挂载、换行默认与切换、头部控件与 abort 即忘、失败行映射，以及插件的各项注册与 dispose 时的撤销。针对已构建应用的 Chromium 探针记录了撑满与滚动的数字（`.artifacts/sidebar-tab-types/app-probe.log`，`ROUND3`）：短文件的预览高度等于 pane 体内容区高度，长文件在预览体内滚动，pane 体从不滚动。文件树的 `tests/` 覆盖排序、懒加载、折叠记忆、重新读取、三种条目类型、截断与失败行，以及 abort 即忘。`apps/web/tests/sidebar-right.e2e.ts` 经真实 Remote 载体把会话里的产物文件打开进预览。
+
+## Deferred
+
+- 虚拟化或可 seek 的分页加载（页按顺序加载）、恢复已加载范围的重新载入、节流的滚动位置持久化，以及 `ui-primitives` 里的换行图标。
+- 文本预览的行号、语法高亮、Markdown 渲染、图片与搜索；总行数或文件末尾标记。
+- 文件树的搜索、产物过滤、拖拽、重命名、右键菜单、高亮当前文件、文件系统监听，以及浏览到工作区根之上。
+- 引导页文案的产品评审，以及一个类型贡献多个入口时引导页的行为。
+- `ui-sidebar-textpreview` 与 `ui-sidebar-files` 的中文 README 对照。
+
+## Related
+
+- [右侧 Sidebar 停靠基础设施](2026-09-04-right-sidebar-docking-infrastructure.zh.md)——面板、pane 与引导页每 pane 一个的规则。
+- [Sidebar tab 类型与导航](../architecture/2026-09-05-sidebar-tab-types-and-navigation.zh.md)——这些类型消费的注册表、档位、`id`、`openTab` / `openResource` 与 owner props。
+- [Client 资源模型](../architecture/2026-09-05-client-resource-model.zh.md)——`useResource` 与 `file` 协议的元数据。
+- [Workspace Files 服务](../architecture/2026-09-05-workspace-files-service.zh.md)——地址语法、`stat` / `read` / `list` / `changes`，以及失败行所映射的错误码。

.gitattributes

@@ -1,10 +1,10 @@
 # The repo's canonical text form is LF, enforced at checkout too: no smudge
 # boundary between working tree and repo, so byte-level gates (verify-*
 # comparisons, blob hashing, coverage offsets) see one form on every host.
-# If a file class ever genuinely needs CRLF in the working tree (.bat/.cmd
-# for cmd.exe), add a `*.bat text eol=crlf` override AFTER this line — the
-# in-repo form stays LF; CRLF becomes checkout-time presentation only.
+# Windows command scripts require CRLF in the working tree for cmd.exe; the
+# override after the default keeps the in-repo form normalized as text.
 * text=auto eol=lf
+*.cmd text eol=crlf
 
 *.pdf binary
 

.gitignore

@@ -27,6 +27,8 @@ tmp/
 .idea
 mise.toml
 dist-exe/
+/dist/
+apps/desktop/.desktop-build/
 python/sdk-runtime/src/deepseek_harness_runtime/runtime/deepseek-harness-sdk-runtime-*
 python/sdk-runtime/src/deepseek_harness_runtime/runtime/node/
 python/**/__pycache__/

THIRD_PARTY_NOTICES.md

@@ -68,6 +68,7 @@ External packages that a workspace package resolves at runtime. The tier covers
 | [`compression`](https://github.com/expressjs/compression) | MIT |
 | [`diff`](https://github.com/kpdecker/jsdiff) | BSD-3-Clause |
 | [`e2b`](https://github.com/e2b-dev/e2b) | MIT |
+| [`electron-updater`](https://github.com/electron-userland/electron-builder) | MIT |
 | [`eventsource-parser`](https://github.com/rexxars/eventsource-parser) | MIT |
 | [`fflate`](https://github.com/101arrowz/fflate) | MIT |
 | [`fs-ext`](https://github.com/baudehlo/node-fs-ext) | MIT |
@@ -98,6 +99,7 @@ External packages that a workspace package resolves at runtime. The tier covers
 | [`react-dom`](https://github.com/facebook/react) | MIT |
 | [`readable-stream`](https://github.com/nodejs/readable-stream) | MIT |
 | [`resolve.exports`](https://github.com/lukeed/resolve.exports) | MIT |
+| [`semver`](https://github.com/npm/node-semver) | ISC |
 | [`sharp`](https://github.com/lovell/sharp) | Apache-2.0 |
 | [`shiki`](https://github.com/shikijs/shiki) | MIT |
 | [`supports-color`](https://github.com/chalk/supports-color) | MIT |
@@ -140,7 +142,9 @@ External packages **directly declared** only by repository tooling, test infrast
 
 | Package | License |
 | --- | --- |
+| [`@aws-sdk/client-s3`](https://github.com/aws/aws-sdk-js-v3) | Apache-2.0 |
 | [`@braintree/sanitize-url`](https://github.com/braintree/sanitize-url) | MIT |
+| [`@electron/notarize`](https://github.com/electron/notarize) | MIT |
 | [`@lexical/headless`](https://github.com/facebook/lexical) | MIT |
 | [`@modelcontextprotocol/server-everything`](https://github.com/modelcontextprotocol/servers) | MIT / Apache-2.0 |
 | [`@modelcontextprotocol/server-filesystem`](https://github.com/modelcontextprotocol/servers) | MIT / Apache-2.0 |
@@ -158,6 +162,7 @@ External packages **directly declared** only by repository tooling, test infrast
 | [`@types/react`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/react-dom`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/readable-stream`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
+| [`@types/semver`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/spdx-expression-parse`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/turndown`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
 | [`@types/use-sync-external-store`](https://github.com/DefinitelyTyped/DefinitelyTyped) | MIT |
@@ -166,13 +171,17 @@ External packages **directly declared** only by repository tooling, test infrast
 | [`@vitest/coverage-v8`](https://github.com/vitest-dev/vitest) | MIT |
 | [`@yao-pkg/pkg`](https://github.com/yao-pkg/pkg) | MIT |
 | [`@yarnpkg/cli-dist`](https://github.com/yarnpkg/berry) | BSD-2-Clause |
+| [`app-builder-lib`](https://github.com/electron-userland/electron-builder) | MIT |
 | [`cytoscape`](https://github.com/cytoscape/cytoscape.js) | MIT |
 | [`cytoscape-cose-bilkent`](https://github.com/cytoscape/cytoscape.js-cose-bilkent) | MIT |
 | [`dayjs`](https://github.com/iamkun/dayjs) | MIT |
 | [`debug`](https://github.com/debug-js/debug) | MIT |
+| [`electron`](https://github.com/electron/electron) | MIT |
+| [`electron-builder`](https://github.com/electron-userland/electron-builder) | MIT |
 | [`esbuild`](https://github.com/evanw/esbuild) | MIT |
 | [`eslint-plugin-sonarjs`](https://github.com/SonarSource/SonarJS) | LGPL-3.0-only |
 | [`execa`](https://github.com/sindresorhus/execa) | MIT |
+| [`extract-zip`](https://github.com/maxogden/extract-zip) | BSD-2-Clause |
 | [`fast-check`](https://github.com/dubzzz/fast-check) | MIT |
 | [`http-server`](https://github.com/http-party/http-server) | MIT |
 | [`istanbul-lib-report`](https://github.com/istanbuljs/istanbuljs) | BSD-3-Clause |
@@ -181,12 +190,15 @@ External packages **directly declared** only by repository tooling, test infrast
 | [`lefthook`](https://github.com/evilmartians/lefthook) | MIT |
 | [`lightningcss`](https://github.com/parcel-bundler/lightningcss) | MPL-2.0 |
 | [`mermaid`](https://github.com/mermaid-js/mermaid) | MIT |
+| [`msgpackr`](http://github.com/kriszyp/msgpackr) | MIT |
 | [`oxlint`](https://github.com/oxc-project/oxc) | MIT |
 | [`oxlint-tsgolint`](https://github.com/oxc-project/tsgolint) | MIT |
 | [`playwright`](https://github.com/microsoft/playwright) | Apache-2.0 |
+| [`pnpm`](https://github.com/pnpm/pnpm) | MIT |
 | [`publint`](https://github.com/publint/publint) | MIT |
 | [`smol-toml`](https://github.com/squirrelchat/smol-toml) | BSD-3-Clause |
 | [`spdx-expression-parse`](https://github.com/jslicense/spdx-expression-parse.js) | MIT |
+| [`tar`](https://github.com/isaacs/node-tar) | BlueOak-1.0.0 |
 | [`tsdown`](https://github.com/rolldown/tsdown) | MIT |
 | [`typescript-language-server`](https://github.com/typescript-language-server/typescript-language-server) | Apache-2.0 |
 | [`vite`](https://github.com/vitejs/vite) | MIT |

apps/cli/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/cli/README.md
-README.md: 850a9371c1515d1e0219e9a685b638063c498ff4
-README.zh.md: 02de213d7a7158971b445511a00661183b37234c
+README.md: adab66bb1d7ed46039248a57c8722964f5aebd33
+README.zh.md: 4887a67872a569a0a54f0378aaceffe51cdc43c1

apps/cli/README.md

@@ -16,7 +16,7 @@ The `dsh` command is the sole supported Node application launcher: profiles are
 | `dsh web` | Alias of `--profile web`. |
 | `dsh plugin --profile <name> <pnpm args>` | Manage a profile's plugins by forwarding to pnpm in the profile directory. |
 
-The invoking directory is the default workspace root. The `web`, `headless`, `sdk`, `sdk-minimal`, and `acp` profiles auto-initialize on first use from shipped templates; any other profile must be created through `dsh plugin`.
+The invoking directory is the default workspace root. The `web`, `headless`, `sdk`, `sdk-minimal`, and `acp` profiles auto-initialize on first use from shipped templates; any other profile must be created through `dsh plugin`. The `desktop` name is reserved for the Electron-owned profile, so the CLI rejects boot, config-dump, and plugin-management requests for it.
 
 ## App arguments
 

apps/cli/README.zh.md

@@ -16,7 +16,7 @@
 | `dsh web` | `--profile web` 的别名。 |
 | `dsh plugin --profile <name> <pnpm args>` | 通过在 profile 目录中转发给 pnpm 来管理该 profile 的插件。 |
 
-运行命令时所在的目录将作为默认 workspace 根目录。`web`、`headless`、`sdk`、`sdk-minimal` 和 `acp` profile 在首次使用时会从随附模板自动初始化；其他任何 profile 都必须通过 `dsh plugin` 创建。
+运行命令时所在的目录将作为默认 workspace 根目录。`web`、`headless`、`sdk`、`sdk-minimal` 和 `acp` profile 在首次使用时会从随附模板自动初始化；其他任何 profile 都必须通过 `dsh plugin` 创建。`desktop` 名称保留给 Electron 持有的 profile，因此 CLI 会拒绝针对它的启动、配置 dump 和插件管理请求。
 
 ## 应用参数
 

apps/cli/package.json

@@ -104,6 +104,8 @@
     "@agentclientprotocol/sdk": "1.4.0",
     "@deepseek-ai/dsh-acp": "workspace:^",
     "@deepseek-ai/dsh-agent": "workspace:^",
+    "@deepseek-ai/dsh-agent-loop": "workspace:^",
+    "@deepseek-ai/dsh-agent-loop-testkit": "workspace:^",
     "@deepseek-ai/dsh-attachment-local": "workspace:^",
     "@deepseek-ai/dsh-bash-local": "workspace:^",
     "@deepseek-ai/dsh-credentials-local": "workspace:^",

apps/cli/src/args.ts

@@ -60,6 +60,12 @@ interface BootOptions {
  */
 const collect = (value: string, previous: string[] = []): string[] => [...previous, value]
 
+function rejectElectronProfile(program: Command, profile: string): void {
+  if (profile.toLowerCase() === 'desktop') {
+    program.error('error: profile "desktop" is managed exclusively by the Electron application')
+  }
+}
+
 /** The launcher's own help text; each app prints its own. */
 const HELP_EXAMPLES = `
 Examples:
@@ -141,6 +147,7 @@ export function parseDshArgs(argv: readonly string[], version: string): DshInvoc
       }
       const profile = options.profile
       if (profile === '') program.error('error: --profile needs a name')
+      rejectElectronProfile(program, profile)
       resolved = resolveBoot(program, profile, options, args)
     })
 
@@ -176,6 +183,7 @@ export function parseDshArgs(argv: readonly string[], version: string): DshInvoc
     .action((args: string[], options: { profile: string }) => {
       rejectParentOptions('plugin')
       if (options.profile === '') program.error('error: --profile needs a name')
+      rejectElectronProfile(plugin, options.profile)
       if (args.length === 0) program.error('error: plugin needs pnpm arguments to forward (e.g. add <package>)')
       resolved = { mode: 'plugin', profile: options.profile, args }
     })

apps/cli/tests/args.spec.ts

@@ -95,6 +95,12 @@ describe('parseDshArgs', () => {
     expect(exitCode(['plugin', 'add', 'x'])).toBe(1) // --profile required
     expect(exitCode(['plugin', '--profile', 'tui'])).toBe(1) // nothing to forward
     expect(exitCode(['plugin', '--profile', ''])).toBe(1)
+    expect(exitCode(['--profile', 'desktop'])).toBe(1)
+    expect(exitCode(['--profile', 'Desktop'])).toBe(1)
+    expect(exitCode(['--profile', 'DESKTOP'])).toBe(1)
+    expect(exitCode(['--profile', 'desktop', '--dump-config'])).toBe(1)
+    expect(exitCode(['plugin', '--profile', 'desktop', 'add', 'x'])).toBe(1)
+    expect(exitCode(['plugin', '--profile', 'Desktop', 'add', 'x'])).toBe(1)
     expect(exitCode(['--profile', 'x', 'plugin', 'add', 'y'])).toBe(1)
   })
 

apps/cli/tests/fixtures/dsh-badge/snapshot.ts

@@ -1,10 +1,11 @@
 import { fileURLToPath } from 'node:url'
-import { agentEvents, Inbox, type Agent } from '@deepseek-ai/dsh-agent'
+import { agentEvents, type Agent } from '@deepseek-ai/dsh-agent'
 import { ToolCallId } from '@deepseek-ai/dsh-llm'
 import { boot, loadOverlayPatches } from '@deepseek-ai/dsh-app-boot'
 import { SessionId } from '@deepseek-ai/dsh-session'
 import type {} from '@deepseek-ai/dsh-skill'
 import type {} from '@deepseek-ai/dsh-tools'
+import { unsupportedInbox } from '@deepseek-ai/dsh-agent-loop-testkit'
 
 const overlayPath = process.argv[2]
 if (overlayPath === undefined) throw new Error('dsh-badge snapshot requires an overlay path')
@@ -23,7 +24,7 @@ try {
     id: agentId,
     options: {},
     session,
-    inbox: new Inbox(session, { inserted: () => {}, discarded: () => {}, claimed: () => {} }),
+    inbox: unsupportedInbox(),
     status: 'idle',
     send: () => {},
     followup: () => {},

apps/cli/tests/profiles/headless/tests/harness.ts

@@ -2,7 +2,6 @@ import { Context } from '@deepseek-ai/cordis'
 import type { SessionEvent } from '@deepseek-ai/dsh-session'
 import type { Agent } from '@deepseek-ai/dsh-agent'
 import AgentLoop from '@deepseek-ai/dsh-agent-loop'
-import SessionProjectionRegistry from '@deepseek-ai/dsh-session-projection'
 import { mountAgentLoopTestDependencies } from '@deepseek-ai/dsh-agent-loop-testkit'
 import { LocalBashExecutor } from '@deepseek-ai/dsh-bash-local'
 import * as BashEnvPlugin from '@deepseek-ai/dsh-shell-env'
@@ -56,7 +55,6 @@ export interface CodingHarnessOptions {
 
 export async function codingHarness(workdir: string, options: CodingHarnessOptions = {}): Promise<Context> {
   const ctx = new Context()
-  await ctx.plugin(SessionProjectionRegistry)
   await mountAgentLoopTestDependencies(ctx, {
     systemPrompt: { personaPrefix: options.personaPrefix ?? '' },
   })

apps/desktop-host/config/desktop.cordis.patch.yml

@@ -0,0 +1,34 @@
+# Electron reuses the browser composition without its network and browser-launch rows.
+
+- id: web-startup
+  disabled: true
+
+- id: webserver
+  disabled: true
+
+- id: web-runtime
+  disabled: true
+
+- id: client-hmr
+  disabled: true
+
+- id: open-in-app
+  disabled: true
+
+- id: ui-open-in-app
+  disabled: true
+
+- id: directory-picker
+  disabled: true
+
+- id: connection
+  inject:
+    - credentials
+  config: {}
+
+- insert:
+    - id: directory-picker-native
+      name: '@deepseek-ai/dsh-host-directory-picker-native'
+
+    - id: ui-directory-picker-native
+      name: '@deepseek-ai/dsh-client-ui-directory-picker-native'

apps/desktop-host/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@deepseek-ai/dsh-desktop-host",
+  "description": "Private upstream-Node host process for the Electron desktop application",
+  "version": "0.1.3-alpha.2",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "main": "lib/index.js",
+  "files": [
+    "lib/index.js",
+    "config/desktop.cordis.patch.yml"
+  ],
+  "dependencies": {
+    "@deepseek-ai/cordis": "workspace:^",
+    "@deepseek-ai/cordis-plugin-include": "workspace:^",
+    "@deepseek-ai/dsh": "workspace:^",
+    "@deepseek-ai/dsh-api-gateway": "workspace:^",
+    "@deepseek-ai/dsh-app-boot": "workspace:^",
+    "@deepseek-ai/dsh-client-connection": "workspace:^",
+    "@deepseek-ai/dsh-client-modules": "workspace:^",
+    "@deepseek-ai/dsh-client-ui-directory-picker-native": "workspace:^",
+    "@deepseek-ai/dsh-cmdline": "workspace:^",
+    "@deepseek-ai/dsh-host-directory-picker-native": "workspace:^",
+    "@deepseek-ai/dsh-host-webserver": "workspace:^",
+    "@deepseek-ai/dsh-launch-environment": "workspace:^",
+    "@deepseek-ai/dsh-web-frontend": "workspace:^"
+  }
+}

apps/desktop-host/src/index.ts

@@ -0,0 +1,587 @@
+/**
+ * Electron child-process entry: boots the desktop project without a listening
+ * socket and carries API plus validated Web assets over framed byte pipes.
+ * @module @deepseek-ai/dsh-desktop-host
+ */
+
+import { createRequire } from 'node:module'
+import { closeSync, createReadStream, createWriteStream, existsSync, mkdirSync, readFileSync, realpathSync, writeFileSync } from 'node:fs'
+import { once } from 'node:events'
+import { readFile } from 'node:fs/promises'
+import { dirname, extname, join, normalize, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import type { Context } from '@deepseek-ai/cordis'
+import type { PatchOptions } from '@deepseek-ai/cordis-plugin-include'
+import {
+  boot,
+  composeEntries,
+  loadLayeredEnv,
+  loadProfileDirectory,
+  loadOverlayPatches,
+} from '@deepseek-ai/dsh-app-boot'
+import { provideCmdline } from '@deepseek-ai/dsh-cmdline'
+import { DSH_LAUNCH_ENVIRONMENT_KEY } from '@deepseek-ai/dsh-launch-environment'
+import type {} from '@deepseek-ai/dsh-api-gateway'
+import type { ConnectionFetchHandler } from '@deepseek-ai/dsh-client-connection'
+import type {} from '@deepseek-ai/dsh-client-modules'
+import { renderIndexInjections, type IndexInjection } from '@deepseek-ai/dsh-host-webserver'
+import {
+  DESKTOP_HOST_PROTOCOL_VERSION,
+  DESKTOP_PIPE_CHUNK_BYTES,
+  DESKTOP_REQUEST_PIPE_FD,
+  DESKTOP_RESPONSE_PIPE_FD,
+  DesktopHostRequestDecoder,
+  encodeDesktopResponseData,
+  encodeDesktopResponseEnd,
+  encodeDesktopResponseError,
+  encodeDesktopResponseStart,
+  type DesktopHostRequestFrame,
+} from './wire.ts'
+
+export { DESKTOP_HOST_PROTOCOL_VERSION } from './wire.ts'
+
+/** One request forwarded from Electron's `dsh-app://` handler. */
+export interface DesktopHostFetchCommand {
+  readonly streamId: number
+  readonly request: {
+    readonly url: string
+    readonly method: string
+    readonly headers: readonly [string, string][]
+  }
+}
+
+/** Commands accepted by the desktop child process. */
+export type DesktopHostCommand = {
+  readonly type: 'shutdown'
+}
+
+/** Events emitted by the desktop child process. */
+export type DesktopHostEvent = {
+  readonly type: 'ready'
+  readonly protocolVersion: typeof DESKTOP_HOST_PROTOCOL_VERSION
+  readonly dshVersion: string
+} | {
+  readonly type: 'fatal'
+  readonly message: string
+}
+
+/** Controller returned to tests and the self-executing process entry. */
+export interface DesktopHostController {
+  /** Installed dsh version carried by this host. */
+  readonly dshVersion: string
+  /** Dispatch one custom-protocol request and stream its response to the response pipe. */
+  fetch(command: DesktopHostFetchCommand, body: ReadableStream<Uint8Array> | null): Promise<void>
+  /** Abort one in-flight request. */
+  cancel(streamId: number): void
+  /** Stop accepting messages and await complete host teardown. */
+  dispose(): Promise<void>
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function isDesktopHostCommand(message: unknown): message is DesktopHostCommand {
+  return typeof message === 'object' && message !== null && 'type' in message
+    && (message as Record<string, unknown>).type === 'shutdown'
+}
+
+interface PackageManifest {
+  readonly name?: string
+  readonly version?: string
+}
+
+const DESKTOP_PATCH = fileURLToPath(new URL('../config/desktop.cordis.patch.yml', import.meta.url))
+const ROOT_CONFIG = '# Electron desktop composition root; package transactions own this file.\n[]\n'
+const ROOT_CONFIG_FILENAME = 'desktop.cordis.yml'
+const DESKTOP_STREAM_PATH = '/.dsh/remote-stream'
+
+const DESKTOP_TRANSPORT_SCRIPT = `globalThis.__DSH_TRANSPORT__={
+  ownsHost:true,
+  async *openStream(endpoint,payload,signal){
+    const response=await fetch(${JSON.stringify(DESKTOP_STREAM_PATH)},{
+      method:'POST',headers:{'content-type':'application/json'},body:JSON.stringify({endpoint,payload}),signal
+    })
+    if(!response.ok||response.body===null)throw new Error('desktop stream transport failed: HTTP '+response.status)
+    const reader=response.body.getReader(),decoder=new TextDecoder()
+    let pending=''
+    for(;;){
+      const {done,value}=await reader.read()
+      pending+=decoder.decode(value,{stream:!done})
+      let newline
+      while((newline=pending.indexOf('\\n'))!==-1){
+        const line=pending.slice(0,newline);pending=pending.slice(newline+1)
+        if(line!=='')yield JSON.parse(line)
+      }
+      if(done)break
+    }
+    if(pending!=='')yield JSON.parse(pending)
+  }
+}`
+
+const MIME: Readonly<Record<string, string>> = {
+  '.css': 'text/css; charset=utf-8',
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.json': 'application/json',
+  '.svg': 'image/svg+xml',
+  '.webmanifest': 'application/manifest+json',
+}
+
+function readManifest(path: string): PackageManifest {
+  const value: unknown = JSON.parse(readFileSync(path, 'utf8'))
+  if (!isRecord(value)) throw new Error(`dsh desktop: ${path} must contain a package manifest`)
+  return {
+    ...(typeof value.name === 'string' ? { name: value.name } : {}),
+    ...(typeof value.version === 'string' ? { version: value.version } : {}),
+  }
+}
+
+function packageManifestPath(projectDir: string, packageName: string): string {
+  const path = join(projectDir, 'node_modules', ...packageName.split('/'), 'package.json')
+  if (!existsSync(path)) throw new Error(`dsh desktop: installed package ${JSON.stringify(packageName)} has no manifest`)
+  return path
+}
+
+function isProjectPath(projectDir: string, target: string): boolean {
+  const root = realpathSync(projectDir)
+  const path = realpathSync(target)
+  return path === root || path.startsWith(root + sep)
+}
+
+function desktopPatches(projectDir: string, allowLinkedPackages: boolean): PatchOptions[] {
+  const dshRoot = dirname(packageManifestPath(projectDir, '@deepseek-ai/dsh'))
+  const profile = loadProfileDirectory('dsh desktop', projectDir, join(dshRoot, 'package.json'))
+  for (const layer of profile.layers) {
+    if (!allowLinkedPackages && !isProjectPath(projectDir, layer.packageDir)) {
+      throw new Error(`dsh desktop: profile bundle ${JSON.stringify(layer.packageName)} resolved outside the desktop profile`)
+    }
+  }
+  const layers = [
+    ...profile.layers.map(layer => layer.patches),
+    profile.patches,
+    loadOverlayPatches('dsh desktop', DESKTOP_PATCH),
+  ]
+  const rows = new Map(composeEntries(layers).flatMap(row => typeof row.id === 'string' ? [[row.id, row] as const] : []))
+  const agentPresets = rows.get('agent-presets')
+  if (agentPresets !== undefined) {
+    layers.push([{
+      id: 'agent-presets',
+      config: {
+        ...(agentPresets.config ?? {}) as Record<string, unknown>,
+        roots: [{ path: join(dshRoot, 'config', 'agent-presets'), trust: 'system' }],
+      },
+    }])
+  }
+  return layers.flat()
+}
+
+function dshVersion(projectDir: string): string {
+  const manifest = readManifest(packageManifestPath(projectDir, '@deepseek-ai/dsh'))
+  if (typeof manifest.version !== 'string') throw new Error('dsh desktop: installed dsh manifest has no version')
+  return manifest.version
+}
+
+function assetHandler(ctx: Context, projectDir: string): ConnectionFetchHandler {
+  const require = createRequire(join(projectDir, 'package.json'))
+  const distIndex = require.resolve('@deepseek-ai/dsh-web-frontend/dist/index.html')
+  const distRoot = realpathSync(dirname(distIndex))
+  const renderIndex = async (): Promise<Response> => {
+    const rows: IndexInjection[] = [{ kind: 'script', placement: 'head', text: DESKTOP_TRANSPORT_SCRIPT }]
+    ctx.emit('webserver/index-inject', rows)
+    const body = renderIndexInjections(await readFile(distIndex, 'utf8'), rows)
+    return new Response(body, { headers: { 'content-type': MIME['.html'] ?? 'text/html; charset=utf-8' } })
+  }
+  return {
+    requestBodyMode: () => 'buffered',
+    async fetch(request): Promise<Response> {
+      if (request.method !== 'GET' && request.method !== 'HEAD') return new Response(null, { status: 405 })
+      const url = new URL(request.url)
+      if (url.pathname.startsWith('/plugins/')) return ctx.clientModules.fetchBundle(request)
+      let pathname: string
+      try {
+        pathname = decodeURIComponent(url.pathname)
+      } catch {
+        return new Response(null, { status: 400 })
+      }
+      if (pathname === '/' || pathname === '/index.html') return renderIndex()
+      const target = resolve(normalize(join(distRoot, pathname)))
+      if (target !== distRoot && !target.startsWith(distRoot + sep)) return new Response(null, { status: 403 })
+      try {
+        const realTarget = realpathSync(target)
+        if (realTarget !== distRoot && !realTarget.startsWith(distRoot + sep)) return new Response(null, { status: 403 })
+        return new Response(request.method === 'HEAD' ? null : await readFile(realTarget), {
+          headers: { 'content-type': MIME[extname(realTarget)] ?? 'application/octet-stream' },
+        })
+      } catch {
+        return renderIndex()
+      }
+    },
+  }
+}
+
+function remoteStreamHandler(ctx: Context): ConnectionFetchHandler {
+  return {
+    requestBodyMode: () => 'buffered',
+    async fetch(request): Promise<Response> {
+      if (request.method !== 'POST') return new Response(null, { status: 405 })
+      const gateway = ctx.get('typertGateway')
+      if (gateway === undefined) return new Response('gateway unavailable', { status: 503 })
+      let body: unknown
+      try {
+        body = await request.json()
+      } catch {
+        return new Response('body is not JSON', { status: 400 })
+      }
+      if (!isRecord(body) || typeof body.endpoint !== 'string') {
+        return new Response('invalid stream request', { status: 400 })
+      }
+      const abort = new AbortController()
+      const cancel = (): void => { abort.abort(request.signal.reason) }
+      request.signal.addEventListener('abort', cancel, { once: true })
+      const encoder = new TextEncoder()
+      const stream = new ReadableStream<Uint8Array>({
+        async start(controller) {
+          try {
+            const values = await gateway.wireStream.open(body.endpoint as string, body.payload, abort.signal)
+            for await (const value of values) {
+              controller.enqueue(encoder.encode(`${JSON.stringify(value)}\n`))
+            }
+            controller.close()
+          } catch (error) {
+            controller.error(error)
+          } finally {
+            request.signal.removeEventListener('abort', cancel)
+          }
+        },
+        cancel(reason) {
+          abort.abort(reason)
+          request.signal.removeEventListener('abort', cancel)
+        },
+      })
+      return new Response(stream, { headers: { 'content-type': 'application/x-ndjson' } })
+    },
+  }
+}
+
+interface NodeRequestInit extends RequestInit {
+  readonly duplex?: 'half'
+}
+
+/**
+ * Boot one installed desktop npm project.
+ * @param projectDir - active or staged Electron-owned desktop profile.
+ * @param writeResponse - serialized response-pipe writer that applies byte backpressure.
+ * @param options - development-only allowance for workspace-linked bundle packages.
+ * @returns controller after every Host and client-manifest row is active.
+ */
+export async function runDesktopHost(
+  projectDir: string,
+  writeResponse: (frame: Buffer) => Promise<void>,
+  options: { allowLinkedPackages?: boolean } = {},
+): Promise<DesktopHostController> {
+  const absoluteProject = resolve(projectDir)
+  mkdirSync(absoluteProject, { recursive: true })
+  const rootConfig = join(absoluteProject, ROOT_CONFIG_FILENAME)
+  writeFileSync(rootConfig, ROOT_CONFIG)
+  const environment = loadLayeredEnv('dsh desktop')
+  let current: Context | undefined
+  const ctx = await boot('dsh desktop', rootConfig, structuredClone(desktopPatches(
+    absoluteProject,
+    options.allowLinkedPackages === true,
+  )), (hostCtx) => {
+    current = hostCtx
+    hostCtx.provide(DSH_LAUNCH_ENVIRONMENT_KEY, environment)
+    provideCmdline(hostCtx, { args: [], exit: () => {} })
+  })
+  current = ctx
+  const connection = ctx.get('connection')
+  const clientModules = ctx.get('clientModules')
+  const gateway = ctx.get('typertGateway')
+  if (connection === undefined || clientModules === undefined || gateway === undefined) {
+    await ctx.fiber.dispose()
+    throw new Error('dsh desktop: composition did not provide connection, typertGateway, and clientModules')
+  }
+  const api = connection.createSharedFetchHandler('/api')
+  const assets = assetHandler(ctx, absoluteProject)
+  const streams = remoteStreamHandler(ctx)
+  const requests = new Map<number, AbortController>()
+  let disposing: Promise<void> | undefined
+
+  const dispose = async (): Promise<void> => {
+    disposing ??= (async () => {
+      for (const controller of requests.values()) controller.abort()
+      requests.clear()
+      await current?.fiber.dispose()
+      current = undefined
+    })()
+    await disposing
+  }
+
+  return {
+    dshVersion: dshVersion(absoluteProject),
+    cancel(streamId) {
+      requests.get(streamId)?.abort()
+    },
+    async fetch(command, body) {
+      if (disposing !== undefined) throw new Error('dsh desktop: host is disposing')
+      const controller = new AbortController()
+      requests.set(command.streamId, controller)
+      try {
+        const url = new URL(command.request.url)
+        const init: NodeRequestInit = {
+          method: command.request.method,
+          headers: new Headers(command.request.headers.map(([name, value]) => [name, value] as [string, string])),
+          ...(body === null ? {} : { body, duplex: 'half' }),
+          signal: controller.signal,
+        }
+        const request = new Request(url, init)
+        const response = url.pathname === DESKTOP_STREAM_PATH
+          ? await streams.fetch(request)
+          : url.pathname.startsWith('/api/')
+            ? await api.fetch(request)
+            : await assets.fetch(request)
+        await writeResponse(encodeDesktopResponseStart(command.streamId, {
+          status: response.status,
+          headers: [...response.headers.entries()],
+          hasBody: response.body !== null,
+        }))
+        if (response.body !== null) {
+          for await (const chunk of response.body) {
+            const bytes = Buffer.from(chunk)
+            for (let offset = 0; offset < bytes.byteLength; offset += DESKTOP_PIPE_CHUNK_BYTES) {
+              await writeResponse(encodeDesktopResponseData(
+                command.streamId,
+                bytes.subarray(offset, offset + DESKTOP_PIPE_CHUNK_BYTES),
+              ))
+            }
+          }
+        }
+        await writeResponse(encodeDesktopResponseEnd(command.streamId))
+      } catch (error) {
+        if (!controller.signal.aborted) {
+          await writeResponse(encodeDesktopResponseError(
+            command.streamId,
+            error instanceof Error ? error.message : String(error),
+          ))
+        }
+      } finally {
+        requests.delete(command.streamId)
+      }
+    },
+    dispose,
+  }
+}
+
+async function main(): Promise<void> {
+  const projectDir = process.argv[2]
+  if (projectDir === undefined || process.send === undefined) {
+    throw new Error('dsh desktop: expected project directory, byte pipes, and a Node IPC channel')
+  }
+  const option = process.argv[3]
+  if (option !== undefined && option !== '--allow-linked-profile') {
+    throw new Error(`dsh desktop: unsupported internal option ${JSON.stringify(option)}`)
+  }
+  const requestPipe = createReadStream('', { fd: DESKTOP_REQUEST_PIPE_FD, autoClose: false })
+  const responsePipe = createWriteStream('', { fd: DESKTOP_RESPONSE_PIPE_FD, autoClose: false })
+  let responseWriteTail: Promise<void> = Promise.resolve()
+  const writeResponse = (frame: Buffer): Promise<void> => {
+    const write = responseWriteTail.then(async () => {
+      if (responsePipe.destroyed) throw new Error('dsh desktop: Electron response pipe is unavailable')
+      if (!responsePipe.write(frame)) await once(responsePipe, 'drain')
+    })
+    responseWriteTail = write.catch(() => undefined)
+    return write
+  }
+  const send = (event: DesktopHostEvent): void => {
+    if (process.send === undefined || !process.connected) return
+    try {
+      process.send(event)
+    } catch (error) {
+      // A concurrent parent disconnect owns teardown; only that closed-channel
+      // condition is safe to discard while streamed responses unwind.
+      if ((error as NodeJS.ErrnoException).code !== 'ERR_IPC_CHANNEL_CLOSED') throw error
+    }
+  }
+  const controller = await runDesktopHost(projectDir, writeResponse, { allowLinkedPackages: option !== undefined })
+  send({
+    type: 'ready',
+    protocolVersion: DESKTOP_HOST_PROTOCOL_VERSION,
+    dshVersion: controller.dshVersion,
+  })
+  const decoder = new DesktopHostRequestDecoder()
+  const requestBodies = new Map<number, ReadableStreamDefaultController<Uint8Array>>()
+  const blockedRequests = new Set<number>()
+  const discardedRequestBodies = new Set<number>()
+  const runs = new Set<Promise<void>>()
+  let lastStreamId = 0
+  let requestedExitCode = 0
+  let stopping: Promise<void> | undefined
+
+  const resumeRequestPipe = (): void => {
+    if (blockedRequests.size === 0) requestPipe.resume()
+  }
+
+  const stop = (exitCode = 0): Promise<void> => {
+    requestedExitCode = Math.max(requestedExitCode, exitCode)
+    stopping ??= (async () => {
+      requestPipe.pause()
+      requestPipe.removeAllListeners('data')
+      const stopped = new Error('dsh desktop: Host is stopping')
+      for (const body of requestBodies.values()) body.error(stopped)
+      requestBodies.clear()
+      blockedRequests.clear()
+      discardedRequestBodies.clear()
+      requestPipe.destroy()
+      closeSync(DESKTOP_REQUEST_PIPE_FD)
+      await controller.dispose()
+      await Promise.allSettled([...runs])
+      await responseWriteTail.catch(() => undefined)
+      if (!responsePipe.destroyed) {
+        await new Promise<void>((resolvePromise) => { responsePipe.end(resolvePromise) })
+        responsePipe.destroy()
+      }
+      closeSync(DESKTOP_RESPONSE_PIPE_FD)
+      if (process.connected) process.disconnect()
+      process.exitCode = requestedExitCode
+    })()
+    return stopping
+  }
+
+  const failTransport = (error: unknown): void => {
+    const message = error instanceof Error ? error.message : String(error)
+    send({ type: 'fatal', message })
+    void stop(1)
+  }
+
+  const beginRequest = (frame: Extract<DesktopHostRequestFrame, { type: 'start' }>): void => {
+    if (frame.streamId <= lastStreamId) {
+      throw new Error(`dsh desktop: Electron reused or reordered request stream ${String(frame.streamId)}`)
+    }
+    lastStreamId = frame.streamId
+    let body: ReadableStream<Uint8Array> | null = null
+    if (frame.hasBody) {
+      body = new ReadableStream<Uint8Array>({
+        start(controllerOfBody) {
+          requestBodies.set(frame.streamId, controllerOfBody)
+        },
+        pull() {
+          blockedRequests.delete(frame.streamId)
+          resumeRequestPipe()
+        },
+        cancel() {
+          requestBodies.delete(frame.streamId)
+          blockedRequests.delete(frame.streamId)
+          controller.cancel(frame.streamId)
+          resumeRequestPipe()
+        },
+      })
+    }
+    const run = controller.fetch({
+      streamId: frame.streamId,
+      request: {
+        url: frame.url,
+        method: frame.method,
+        headers: frame.headers,
+      },
+    }, body)
+    runs.add(run)
+    void run.catch(failTransport).finally(() => {
+      runs.delete(run)
+      const openBody = requestBodies.get(frame.streamId)
+      if (openBody === undefined) return
+      openBody.error(new Error('dsh desktop: response completed before the request body ended'))
+      requestBodies.delete(frame.streamId)
+      blockedRequests.delete(frame.streamId)
+      discardedRequestBodies.add(frame.streamId)
+      resumeRequestPipe()
+    })
+  }
+
+  const handleRequestFrame = (frame: DesktopHostRequestFrame): void => {
+    switch (frame.type) {
+      case 'start':
+        beginRequest(frame)
+        return
+      case 'data': {
+        const body = requestBodies.get(frame.streamId)
+        if (body === undefined) {
+          if (discardedRequestBodies.has(frame.streamId)) return
+          throw new Error(`dsh desktop: Electron sent body data for inactive stream ${String(frame.streamId)}`)
+        }
+        body.enqueue(frame.data)
+        if ((body.desiredSize ?? 0) <= 0) {
+          blockedRequests.add(frame.streamId)
+          requestPipe.pause()
+        }
+        return
+      }
+      case 'end': {
+        const body = requestBodies.get(frame.streamId)
+        if (body === undefined) {
+          if (discardedRequestBodies.delete(frame.streamId)) return
+          throw new Error(`dsh desktop: Electron ended inactive body stream ${String(frame.streamId)}`)
+        }
+        body.close()
+        requestBodies.delete(frame.streamId)
+        blockedRequests.delete(frame.streamId)
+        resumeRequestPipe()
+        return
+      }
+      case 'cancel': {
+        if (frame.streamId > lastStreamId) {
+          throw new Error(`dsh desktop: Electron canceled unknown stream ${String(frame.streamId)}`)
+        }
+        const body = requestBodies.get(frame.streamId)
+        body?.error(new Error('dsh desktop: Electron canceled the request'))
+        requestBodies.delete(frame.streamId)
+        blockedRequests.delete(frame.streamId)
+        discardedRequestBodies.delete(frame.streamId)
+        controller.cancel(frame.streamId)
+        resumeRequestPipe()
+        return
+      }
+      default:
+        frame satisfies never
+    }
+  }
+
+  requestPipe.on('data', (chunk: string | Buffer) => {
+    try {
+      for (const frame of decoder.push(Buffer.from(chunk))) handleRequestFrame(frame)
+    } catch (error) {
+      failTransport(error)
+    }
+  })
+  requestPipe.once('end', () => {
+    if (stopping !== undefined) return
+    try {
+      decoder.finish()
+      failTransport(new Error('dsh desktop: Electron request pipe ended'))
+    } catch (error) {
+      failTransport(error)
+    }
+  })
+  requestPipe.once('error', failTransport)
+  responsePipe.once('error', failTransport)
+  process.on('message', (message: unknown) => {
+    if (!isDesktopHostCommand(message)) {
+      send({ type: 'fatal', message: 'dsh desktop: invalid Electron IPC command' })
+      void stop(1)
+      return
+    }
+    void stop()
+  })
+  process.once('disconnect', () => { void stop() })
+  process.once('SIGTERM', () => { void stop() })
+  process.once('SIGINT', () => { void stop() })
+}
+
+if (import.meta.main) {
+  main().catch((error: unknown) => {
+    const message = error instanceof Error ? error.message : String(error)
+    if (process.send !== undefined) process.send({ type: 'fatal', message } satisfies DesktopHostEvent)
+    else process.stderr.write(`dsh desktop: ${message}\n`)
+    process.exitCode = 1
+  })
+}

apps/desktop-host/src/wire.ts

@@ -0,0 +1,184 @@
+/** Framed request and response bytes for the Electron Desktop Host transport. */
+
+/** Protocol version shared with the Electron shell. */
+export const DESKTOP_HOST_PROTOCOL_VERSION = 3 as const
+
+/** Child descriptor that receives Electron request frames. */
+export const DESKTOP_REQUEST_PIPE_FD = 3
+
+/** Child descriptor that emits Host response frames. */
+export const DESKTOP_RESPONSE_PIPE_FD = 4
+
+/** Maximum raw body bytes carried by one data frame. */
+export const DESKTOP_PIPE_CHUNK_BYTES = 64 * 1024
+
+const FRAME_MAGIC = 0x44534833
+const FRAME_HEADER_BYTES = 13
+const MAX_CONTROL_PAYLOAD_BYTES = 1024 * 1024
+
+const REQUEST_FRAME_START = 1
+const REQUEST_FRAME_DATA = 2
+const REQUEST_FRAME_END = 3
+const REQUEST_FRAME_CANCEL = 4
+
+const RESPONSE_FRAME_START = 1
+const RESPONSE_FRAME_DATA = 2
+const RESPONSE_FRAME_END = 3
+const RESPONSE_FRAME_ERROR = 4
+type ResponseFrameType = typeof RESPONSE_FRAME_START | typeof RESPONSE_FRAME_DATA
+  | typeof RESPONSE_FRAME_END | typeof RESPONSE_FRAME_ERROR
+
+/** One validated request-pipe frame. */
+export type DesktopHostRequestFrame = {
+  readonly type: 'start'
+  readonly streamId: number
+  readonly url: string
+  readonly method: string
+  readonly headers: readonly [string, string][]
+  readonly hasBody: boolean
+} | {
+  readonly type: 'data'
+  readonly streamId: number
+  readonly data: Buffer
+} | {
+  readonly type: 'end' | 'cancel'
+  readonly streamId: number
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function isHeaders(value: unknown): value is readonly [string, string][] {
+  return Array.isArray(value) && value.every(header => Array.isArray(header) && header.length === 2
+    && typeof header[0] === 'string' && typeof header[1] === 'string')
+}
+
+function assertStreamId(streamId: number): void {
+  if (!Number.isInteger(streamId) || streamId < 1 || streamId > 0xffff_ffff) {
+    throw new Error(`dsh desktop: invalid pipe stream id ${String(streamId)}`)
+  }
+}
+
+function encodeFrame(type: ResponseFrameType, streamId: number, payload: Buffer): Buffer {
+  assertStreamId(streamId)
+  const limit = type === RESPONSE_FRAME_DATA ? DESKTOP_PIPE_CHUNK_BYTES : MAX_CONTROL_PAYLOAD_BYTES
+  if (payload.byteLength > limit) {
+    throw new Error(`dsh desktop: response pipe frame exceeds the ${String(limit)}-byte limit`)
+  }
+  const frame = Buffer.allocUnsafe(FRAME_HEADER_BYTES + payload.byteLength)
+  frame.writeUInt32BE(FRAME_MAGIC, 0)
+  frame.writeUInt8(type, 4)
+  frame.writeUInt32BE(streamId, 5)
+  frame.writeUInt32BE(payload.byteLength, 9)
+  payload.copy(frame, FRAME_HEADER_BYTES)
+  return frame
+}
+
+function encodeJsonFrame(type: ResponseFrameType, streamId: number, value: unknown): Buffer {
+  return encodeFrame(type, streamId, Buffer.from(JSON.stringify(value), 'utf8'))
+}
+
+/** Encode response metadata before any body frames. */
+export function encodeDesktopResponseStart(
+  streamId: number,
+  response: {
+    readonly status: number
+    readonly headers: readonly [string, string][]
+    readonly hasBody: boolean
+  },
+): Buffer {
+  return encodeJsonFrame(RESPONSE_FRAME_START, streamId, response)
+}
+
+/** Encode one bounded raw response-body chunk. */
+export function encodeDesktopResponseData(streamId: number, data: Uint8Array): Buffer {
+  return encodeFrame(RESPONSE_FRAME_DATA, streamId, Buffer.from(data))
+}
+
+/** Encode normal response completion. */
+export function encodeDesktopResponseEnd(streamId: number): Buffer {
+  return encodeFrame(RESPONSE_FRAME_END, streamId, Buffer.alloc(0))
+}
+
+/** Encode one response failure without exposing an Error object across processes. */
+export function encodeDesktopResponseError(streamId: number, message: string): Buffer {
+  return encodeJsonFrame(RESPONSE_FRAME_ERROR, streamId, { message })
+}
+
+/** Incrementally decode validated request frames from the Electron byte pipe. */
+export class DesktopHostRequestDecoder {
+  private buffer: Buffer = Buffer.alloc(0)
+
+  /**
+   * Append bytes and return every complete request frame.
+   * @param chunk - next bytes read from the Electron request pipe.
+   * @returns complete frames in pipe order.
+   */
+  push(chunk: Buffer): DesktopHostRequestFrame[] {
+    this.buffer = this.buffer.byteLength === 0 ? chunk : Buffer.concat([this.buffer, chunk])
+    const frames: DesktopHostRequestFrame[] = []
+    for (;;) {
+      const frame = this.next()
+      if (frame === undefined) return frames
+      frames.push(frame)
+    }
+  }
+
+  /** Reject EOF that splits a frame. */
+  finish(): void {
+    if (this.buffer.byteLength !== 0) throw new Error('dsh desktop: Electron request pipe ended inside a frame')
+  }
+
+  private next(): DesktopHostRequestFrame | undefined {
+    if (this.buffer.byteLength < FRAME_HEADER_BYTES) return undefined
+    if (this.buffer.readUInt32BE(0) !== FRAME_MAGIC) throw new Error('dsh desktop: invalid Electron request frame marker')
+    const rawType = this.buffer.readUInt8(4)
+    const streamId = this.buffer.readUInt32BE(5)
+    const payloadLength = this.buffer.readUInt32BE(9)
+    assertStreamId(streamId)
+    const limit = rawType === REQUEST_FRAME_DATA ? DESKTOP_PIPE_CHUNK_BYTES : MAX_CONTROL_PAYLOAD_BYTES
+    if (payloadLength > limit) {
+      throw new Error(`dsh desktop: Electron request frame exceeds the ${String(limit)}-byte limit`)
+    }
+    const frameLength = FRAME_HEADER_BYTES + payloadLength
+    if (this.buffer.byteLength < frameLength) return undefined
+    const payload = this.buffer.subarray(FRAME_HEADER_BYTES, frameLength)
+    this.buffer = this.buffer.subarray(frameLength)
+    switch (rawType) {
+      case REQUEST_FRAME_START:
+        return this.parseStart(streamId, payload)
+      case REQUEST_FRAME_DATA:
+        return { type: 'data', streamId, data: payload }
+      case REQUEST_FRAME_END:
+        if (payloadLength !== 0) throw new Error('dsh desktop: Electron request end frame carried a payload')
+        return { type: 'end', streamId }
+      case REQUEST_FRAME_CANCEL:
+        if (payloadLength !== 0) throw new Error('dsh desktop: Electron request cancel frame carried a payload')
+        return { type: 'cancel', streamId }
+      default:
+        throw new Error(`dsh desktop: unknown Electron request frame type ${String(rawType)}`)
+    }
+  }
+
+  private parseStart(streamId: number, payload: Buffer): DesktopHostRequestFrame {
+    let value: unknown
+    try {
+      value = JSON.parse(payload.toString('utf8')) as unknown
+    } catch (error) {
+      throw new Error(`dsh desktop: Electron request start payload is not JSON: ${error instanceof Error ? error.message : String(error)}`)
+    }
+    if (!isRecord(value) || typeof value.url !== 'string' || typeof value.method !== 'string'
+      || !isHeaders(value.headers) || typeof value.hasBody !== 'boolean') {
+      throw new Error('dsh desktop: invalid Electron request start payload')
+    }
+    return {
+      type: 'start',
+      streamId,
+      url: value.url,
+      method: value.method,
+      headers: value.headers,
+      hasBody: value.hasBody,
+    }
+  }
+}

apps/desktop-host/tsconfig.json

@@ -0,0 +1,19 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "rootDir": "src",
+    "outDir": "lib/types"
+  },
+  "include": ["src"],
+  "references": [
+    { "path": "../../vendor/cordis" },
+    { "path": "../../vendor/include" },
+    { "path": "../../packages/api/gateway/tsconfig.host.json" },
+    { "path": "../../packages/boot/app-boot" },
+    { "path": "../../packages/boot/cmdline" },
+    { "path": "../../packages/client/connection/tsconfig.host.json" },
+    { "path": "../../packages/client/modules" },
+    { "path": "../../packages/host/webserver" },
+    { "path": "../../packages/util/launch-environment" }
+  ]
+}

apps/desktop-host/tsdown.config.ts

@@ -0,0 +1,12 @@
+import { defineConfig } from 'tsdown'
+
+export default defineConfig({
+  entry: ['lib/types/index.js'],
+  outDir: 'lib',
+  format: ['esm'],
+  platform: 'node',
+  target: 'es2024',
+  fixedExtension: false,
+  dts: false,
+  clean: false,
+})

apps/desktop/README.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 apps/desktop/README.md
+README.md: cf350a9d5e9577f5cf52c4371b32f16e278133f9
+README.zh.md: df48eb5903e21cae9ff041626c28d41d12e5c632

apps/desktop/electron-builder.config.d.mts

@@ -0,0 +1,39 @@
+/** Electron-builder fields asserted by the Desktop release tests. */
+export interface DesktopElectronBuilderConfig {
+  readonly appId: string
+  readonly directories: {
+    readonly output: string
+  }
+  readonly extraResources: readonly [
+    { readonly from: string, readonly to: 'runtime' },
+    { readonly from: string, readonly to: 'seed' },
+  ]
+  readonly mac: {
+    readonly identity: string | undefined
+    readonly forceCodeSigning: boolean
+    readonly notarize: boolean
+  }
+  readonly dmg: {
+    readonly sign: boolean
+    readonly writeUpdateInfo: boolean
+  }
+  readonly artifactBuildCompleted: (artifact: { readonly file: string }) => Promise<void> | undefined
+  readonly publish: readonly [{ readonly provider: 'generic', readonly url: string }]
+}
+
+/**
+ * Create electron-builder configuration from one release environment.
+ * @param env - Packaging environment.
+ * @param hostPlatform - Build-host platform used when no explicit target is present.
+ * @param hostArch - Build-host architecture used when no explicit target is present.
+ * @returns electron-builder configuration.
+ */
+export function createElectronBuilderConfig(
+  env?: NodeJS.ProcessEnv,
+  hostPlatform?: NodeJS.Platform,
+  hostArch?: string,
+): DesktopElectronBuilderConfig
+
+declare const electronBuilderConfig: DesktopElectronBuilderConfig
+
+export default electronBuilderConfig

apps/desktop/electron-builder.config.mjs

@@ -0,0 +1,109 @@
+import {
+  resolveDesktopAppId,
+  resolveMacOSNotarizationEnvironment,
+  resolveMacOSSigningEnvironment,
+} from './scripts/desktop-release-environment.mjs'
+import { notarizeMacOSDiskImageArtifact } from './scripts/notarize-macos-disk-images.mjs'
+import { verifyMacOSSignatureAfterSign } from './scripts/verify-macos-signature.mjs'
+import {
+  createWindowsTokenSigner,
+  installWindowsNsisBootstrapSigner,
+} from './scripts/windows-sign.mjs'
+import { resolveDesktopAutoUpdateConfig } from './scripts/desktop-auto-update-environment.mjs'
+import { desktopTargetBuildPaths } from './scripts/desktop-build-paths.mjs'
+
+/**
+ * Create electron-builder configuration from one release environment.
+ * @param {NodeJS.ProcessEnv} env - Packaging environment.
+ * @param {NodeJS.Platform} hostPlatform - Build-host platform used when no explicit target is present.
+ * @param {string} hostArch - Build-host architecture used when no explicit target is present.
+ * @returns {object} electron-builder configuration.
+ */
+export function createElectronBuilderConfig(
+  env = process.env,
+  hostPlatform = process.platform,
+  hostArch = process.arch,
+) {
+  const appId = resolveDesktopAppId(env)
+  const targetPlatform = env.DSH_DESKTOP_TARGET_PLATFORM
+  const resolvedPlatform = targetPlatform ?? hostPlatform
+  const resolvedArch = env.DSH_DESKTOP_TARGET_ARCH ?? hostArch
+  const packagesMacOS = targetPlatform === 'darwin' || (targetPlatform === undefined && hostPlatform === 'darwin')
+  const packagesWindows = targetPlatform === 'win32'
+  const macOSSigning = packagesMacOS ? resolveMacOSSigningEnvironment(env) : undefined
+  if (packagesMacOS) resolveMacOSNotarizationEnvironment(env)
+  const windowsSigner = packagesWindows
+    ? 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,
+      })
+    : undefined
+  if (windowsSigner !== undefined) {
+    installWindowsNsisBootstrapSigner({ sign: windowsSigner })
+  }
+  const update = resolveDesktopAutoUpdateConfig(env, resolvedPlatform, resolvedArch)
+  const buildPaths = desktopTargetBuildPaths(update.target)
+  return {
+    appId,
+    productName: 'DeepSeek Harness',
+    artifactName: 'deepseek-harness-${version}-${os}-${arch}.${ext}',
+    directories: { output: buildPaths.artifacts },
+    asar: true,
+    files: [
+      'lib/*.js',
+      'lib/*.cjs',
+      'renderer/**/*',
+      'package.json',
+    ],
+    extraResources: [
+      { from: buildPaths.runtime, to: 'runtime' },
+      { from: buildPaths.seed, to: 'seed' },
+    ],
+    mac: {
+      category: 'public.app-category.developer-tools',
+      identity: macOSSigning?.signingIdentity,
+      forceCodeSigning: true,
+      hardenedRuntime: true,
+      notarize: true,
+      target: ['dmg', 'zip'],
+    },
+    dmg: {
+      sign: true,
+      writeUpdateInfo: false,
+    },
+    afterSign: context => {
+      if (context.electronPlatformName !== 'darwin') return
+      verifyMacOSSignatureAfterSign(context, macOSSigning ?? resolveMacOSSigningEnvironment(env))
+    },
+    artifactBuildCompleted: artifact => {
+      if (!artifact.file.endsWith('.dmg')) return
+      return notarizeMacOSDiskImageArtifact(
+        artifact,
+        env,
+        macOSSigning ?? resolveMacOSSigningEnvironment(env),
+      )
+    },
+    win: {
+      forceCodeSigning: true,
+      signtoolOptions: {
+        sign: windowsSigner,
+        signingHashAlgorithms: ['sha256'],
+      },
+      target: ['nsis'],
+    },
+    linux: {
+      category: 'Development',
+      target: ['AppImage'],
+    },
+    nsis: {
+      oneClick: false,
+      allowToChangeInstallationDirectory: true,
+      differentialPackage: true,
+    },
+    publish: [{ provider: 'generic', url: update.publicUrl }],
+  }
+}
+
+export default createElectronBuilderConfig()

apps/desktop/package.json

@@ -0,0 +1,51 @@
+{
+  "name": "@deepseek-ai/dsh-desktop",
+  "description": "Electron desktop shell for an isolated pnpm-installed dsh runtime",
+  "version": "0.1.3-alpha.2",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "main": "lib/main.js",
+  "scripts": {
+    "build": "tsc -b && tsdown",
+    "dev": "tsx scripts/dev.ts",
+    "start": "tsx scripts/dev.ts --skip-build",
+    "prepare:runtime": "tsx scripts/prepare-runtime.ts",
+    "prepare:packages": "tsx scripts/prepare-package-set.ts",
+    "prepare:seed": "tsx scripts/prepare-seed.ts",
+    "prepare:package": "tsx scripts/package-target.ts --prepare-only",
+    "verify:mac-signature": "node scripts/verify-macos-signature.mjs",
+    "package": "tsx scripts/package-target.ts",
+    "package:dir": "tsx scripts/package-target.ts --dir",
+    "package:mac:arm64": "tsx scripts/package-target.ts mac-arm64",
+    "package:mac:arm64:dir": "tsx scripts/package-target.ts mac-arm64 --dir",
+    "package:mac:x64": "tsx scripts/package-target.ts mac-x64",
+    "package:mac:x64:dir": "tsx scripts/package-target.ts mac-x64 --dir",
+    "package:win:x64": "tsx scripts/package-target.ts win-x64",
+    "package:win:x64:dir": "tsx scripts/package-target.ts win-x64 --dir",
+    "upload:mac:arm64": "tsx scripts/upload-target.ts mac-arm64",
+    "upload:mac:x64": "tsx scripts/upload-target.ts mac-x64",
+    "upload:win:x64": "tsx scripts/upload-target.ts win-x64"
+  },
+  "dependencies": {
+    "electron-updater": "^6.8.9",
+    "semver": "^7.8.5"
+  },
+  "devDependencies": {
+    "@aws-sdk/client-s3": "3.1067.0",
+    "@deepseek-ai/dsh-home-paths": "workspace:^",
+    "@electron/notarize": "2.5.0",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.20.0",
+    "@types/semver": "^7.8.0",
+    "app-builder-lib": "26.15.3",
+    "electron": "^44.0.0",
+    "electron-builder": "^26.15.3",
+    "extract-zip": "^2.0.1",
+    "js-yaml": "^4.2.0",
+    "msgpackr": "2.0.4",
+    "pnpm": "11.7.0",
+    "tar": "^7.5.0",
+    "typescript": "^6.0.3"
+  }
+}

apps/desktop/renderer/plugin-manager.css

@@ -0,0 +1,108 @@
+:root {
+  color-scheme: light dark;
+  font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+  background: Canvas;
+  color: CanvasText;
+}
+
+body {
+  margin: 0;
+}
+
+main {
+  max-width: 680px;
+  margin: 0 auto;
+  padding: 32px;
+}
+
+header,
+.install-row,
+li {
+  display: flex;
+  align-items: center;
+  gap: 12px;
+}
+
+header {
+  justify-content: space-between;
+}
+
+h1,
+h2,
+p {
+  margin-top: 0;
+}
+
+header p {
+  color: GrayText;
+}
+
+form,
+section {
+  margin-top: 28px;
+}
+
+label {
+  display: block;
+  margin-bottom: 8px;
+  font-weight: 600;
+}
+
+input {
+  flex: 1;
+  min-width: 0;
+  padding: 9px 11px;
+  border: 1px solid ButtonBorder;
+  border-radius: 7px;
+  background: Field;
+  color: FieldText;
+}
+
+button {
+  padding: 9px 14px;
+  border: 1px solid ButtonBorder;
+  border-radius: 7px;
+  background: AccentColor;
+  color: AccentColorText;
+  cursor: pointer;
+}
+
+button.quiet,
+li button {
+  background: ButtonFace;
+  color: ButtonText;
+}
+
+button:disabled,
+input:disabled {
+  opacity: 0.55;
+  cursor: wait;
+}
+
+#status {
+  min-height: 1.5em;
+  margin-top: 16px;
+  color: GrayText;
+}
+
+ul {
+  margin: 0;
+  padding: 0;
+  list-style: none;
+}
+
+li {
+  justify-content: space-between;
+  padding: 12px 0;
+  border-bottom: 1px solid ButtonBorder;
+}
+
+.package-version {
+  color: GrayText;
+  margin-left: 8px;
+}
+
+.package-actions {
+  display: flex;
+  gap: 8px;
+}

apps/desktop/renderer/plugin-manager.html

@@ -0,0 +1,35 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8">
+    <meta name="viewport" content="width=device-width, initial-scale=1.0">
+    <meta http-equiv="Content-Security-Policy" content="default-src 'self'; script-src 'self'; style-src 'self'; connect-src 'none'; img-src 'self' data:">
+    <title id="page-title"></title>
+    <link rel="stylesheet" href="plugin-manager.css">
+  </head>
+  <body>
+    <main>
+      <header>
+        <div>
+          <h1 id="title"></h1>
+          <p id="description"></p>
+        </div>
+        <button id="refresh" class="quiet" type="button"></button>
+      </header>
+      <form id="install-form">
+        <label id="package-label" for="package-spec"></label>
+        <div class="install-row">
+          <input id="package-spec" name="package-spec" autocomplete="off" placeholder="@scope/plugin@1.2.3" required>
+          <button id="install" type="submit"></button>
+        </div>
+      </form>
+      <p id="status" role="status" aria-live="polite"></p>
+      <section aria-labelledby="installed-heading">
+        <h2 id="installed-heading"></h2>
+        <ul id="plugins"></ul>
+        <p id="empty"></p>
+      </section>
+    </main>
+    <script src="plugin-manager.js"></script>
+  </body>
+</html>

apps/desktop/renderer/plugin-manager.js

@@ -0,0 +1,101 @@
+const api = window.dshDesktop
+
+async function main() {
+  const locale = await api.locale()
+  const messages = locale.messages
+  const message = (key, values = {}) => messages[key].replaceAll(/\{([^{}]+)\}/gu, (placeholder, name) => values[name] ?? placeholder)
+  document.documentElement.lang = locale.id
+  document.querySelector('#page-title').textContent = messages.pluginManagerTitle
+  document.querySelector('#title').textContent = messages.pluginManagerTitle
+  document.querySelector('#description').textContent = messages.pluginManagerDescription
+  document.querySelector('#refresh').textContent = messages.refresh
+  document.querySelector('#package-label').textContent = messages.npmPackage
+  document.querySelector('#install').textContent = messages.install
+  document.querySelector('#installed-heading').textContent = messages.installed
+  document.querySelector('#empty').textContent = messages.noPlugins
+
+  const list = document.querySelector('#plugins')
+  const empty = document.querySelector('#empty')
+  const status = document.querySelector('#status')
+  const form = document.querySelector('#install-form')
+  const input = document.querySelector('#package-spec')
+  const refresh = document.querySelector('#refresh')
+
+  function setBusy(busy, statusMessage = '') {
+    for (const control of document.querySelectorAll('button, input')) control.disabled = busy
+    status.textContent = statusMessage
+  }
+
+  async function render() {
+    const plugins = await api.plugins.list()
+    list.replaceChildren(...plugins.map(plugin => {
+      const item = document.createElement('li')
+      const identity = document.createElement('span')
+      const version = document.createElement('span')
+      version.className = 'package-version'
+      version.textContent = plugin.version
+      identity.append(document.createTextNode(plugin.name), version)
+      const remove = document.createElement('button')
+      remove.type = 'button'
+      remove.textContent = messages.remove
+      remove.addEventListener('click', () => void run(
+        () => api.plugins.remove(plugin.name),
+        message('removing', { name: plugin.name }),
+      ))
+      const update = document.createElement('button')
+      update.type = 'button'
+      update.textContent = messages.update
+      update.addEventListener('click', () => {
+        const next = window.prompt(message('targetVersion', { name: plugin.name }), plugin.version)?.trim()
+        if (next === undefined || next === '' || next === plugin.version) return
+        void run(() => api.plugins.update(plugin.name, next), message('updating', { name: plugin.name }))
+      })
+      const actions = document.createElement('span')
+      actions.className = 'package-actions'
+      actions.append(update, remove)
+      item.append(identity, actions)
+      return item
+    }))
+    empty.hidden = plugins.length !== 0
+  }
+
+  async function run(operation, statusMessage) {
+    setBusy(true, statusMessage)
+    try {
+      await operation()
+      await render()
+      status.textContent = messages.operationComplete
+    } catch (error) {
+      status.textContent = error instanceof Error ? error.message : String(error)
+    } finally {
+      setBusy(false, status.textContent)
+    }
+  }
+
+  async function load(statusMessage, success) {
+    setBusy(true, statusMessage)
+    try {
+      await render()
+      status.textContent = success
+    } catch (error) {
+      status.textContent = error instanceof Error ? error.message : String(error)
+    } finally {
+      setBusy(false, status.textContent)
+    }
+  }
+
+  form.addEventListener('submit', (event) => {
+    event.preventDefault()
+    const spec = input.value.trim()
+    if (spec === '') return
+    void run(async () => {
+      await api.plugins.add(spec)
+      input.value = ''
+    }, message('installing', { spec }))
+  })
+  refresh.addEventListener('click', () => void load(messages.refreshing, messages.refreshed))
+
+  await load(messages.loadingPlugins, '')
+}
+
+void main()

apps/desktop/scripts/desktop-auto-update-environment.d.mts

@@ -0,0 +1,90 @@
+/** Environment variable that selects the Desktop update deployment. */
+export const DESKTOP_AUTO_UPDATE_ENV: 'DSH_DESKTOP_AUTO_UPDATE_ENV'
+
+/** Supported Desktop update deployment. */
+export type DesktopAutoUpdateEnvironment = 'test' | 'production'
+
+/** Directory name of one supported Desktop release target. */
+export type DesktopAutoUpdateTarget = 'mac-arm64' | 'mac-x64' | 'win-x64'
+
+/** Public updater URL for one release target. */
+export interface DesktopAutoUpdateConfig {
+  readonly environment: DesktopAutoUpdateEnvironment
+  readonly target: DesktopAutoUpdateTarget
+  readonly origin: string
+  readonly publicUrl: string
+  readonly keyPrefix: string
+}
+
+/** Public updater URL and private COS destination for one upload target. */
+export interface DesktopUploadConfig extends DesktopAutoUpdateConfig {
+  readonly bucket: string
+  readonly secretIdEnvName: string
+  readonly secretKeyEnvName: string
+}
+
+/**
+ * Resolve the update deployment, defaulting local release work to test.
+ * @param env - Packaging or upload environment.
+ * @returns Validated deployment name.
+ */
+export function resolveDesktopAutoUpdateEnvironment(
+  env: NodeJS.ProcessEnv,
+): DesktopAutoUpdateEnvironment
+
+/**
+ * Resolve one supported platform and architecture to its update directory.
+ * @param platform - Target Node.js platform.
+ * @param arch - Target Node.js architecture.
+ * @returns Update target directory.
+ */
+export function resolveDesktopAutoUpdateTarget(
+  platform: NodeJS.Platform,
+  arch: string,
+): DesktopAutoUpdateTarget
+
+/**
+ * Return the local completion record filename for one packaged target.
+ * @param target - Supported release target.
+ * @returns Filename stored beside electron-builder artifacts.
+ */
+export function desktopBuildRecordFilename(target: DesktopAutoUpdateTarget): string
+
+/**
+ * Return the electron-builder channel metadata filename for an application version.
+ * @param version - Desktop semantic version.
+ * @param platform - Target platform.
+ * @returns Channel metadata filename emitted for the target.
+ */
+export function desktopUpdateMetadataFilename(
+  version: string,
+  platform: NodeJS.Platform,
+): string
+
+/**
+ * Resolve the public updater URL for one release target.
+ * @param env - Packaging or upload environment.
+ * @param platform - Target Node.js platform.
+ * @param arch - Target Node.js architecture.
+ * @returns Resolved updater configuration.
+ * @throws When the test deployment lacks a valid HTTPS origin.
+ */
+export function resolveDesktopAutoUpdateConfig(
+  env: NodeJS.ProcessEnv,
+  platform: NodeJS.Platform,
+  arch: string,
+): DesktopAutoUpdateConfig
+
+/**
+ * Resolve the public updater URL and private COS destination for one upload target.
+ * @param env - Upload environment.
+ * @param platform - Target Node.js platform.
+ * @param arch - Target Node.js architecture.
+ * @returns Resolved upload configuration.
+ * @throws When the selected deployment lacks a required origin or bucket, or the test origin is not HTTPS.
+ */
+export function resolveDesktopUploadConfig(
+  env: NodeJS.ProcessEnv,
+  platform: NodeJS.Platform,
+  arch: string,
+): DesktopUploadConfig

apps/desktop/scripts/desktop-auto-update-environment.mjs

@@ -0,0 +1,169 @@
+/** Resolve the Desktop auto-update channel and its Tencent COS destination. */
+
+import { prerelease, valid } from 'semver'
+
+/** Environment variable that selects the Desktop update deployment. */
+export const DESKTOP_AUTO_UPDATE_ENV = 'DSH_DESKTOP_AUTO_UPDATE_ENV'
+
+const UPDATE_ENVIRONMENTS = {
+  test: {
+    originEnvName: 'DOWNLOAD_TEST_ORIGIN',
+    fixedOrigin: undefined,
+    bucketEnvName: 'DOWNLOAD_TEST_COS_BUCKET',
+    secretIdEnvName: 'DOWNLOAD_TEST_COS_SECRET_ID',
+    secretKeyEnvName: 'DOWNLOAD_TEST_COS_SECRET_KEY',
+  },
+  production: {
+    originEnvName: undefined,
+    fixedOrigin: 'https://download.deepseek.com',
+    bucketEnvName: 'DOWNLOAD_PROD_COS_BUCKET',
+    secretIdEnvName: 'DOWNLOAD_PROD_COS_SECRET_ID',
+    secretKeyEnvName: 'DOWNLOAD_PROD_COS_SECRET_KEY',
+  },
+}
+
+const UPDATE_TARGETS = new Set(['mac-arm64', 'mac-x64', 'win-x64'])
+
+/**
+ * Resolve the update deployment, defaulting local release work to test.
+ * @param {NodeJS.ProcessEnv} env - Packaging or upload environment.
+ * @returns {'test' | 'production'} Validated deployment name.
+ */
+export function resolveDesktopAutoUpdateEnvironment(env) {
+  const value = env[DESKTOP_AUTO_UPDATE_ENV]?.trim() || 'test'
+  if (value !== 'test' && value !== 'production') {
+    throw new Error(`desktop auto-update: ${DESKTOP_AUTO_UPDATE_ENV} must be "test" or "production"`)
+  }
+  return value
+}
+
+/**
+ * Resolve one supported platform and architecture to its update directory.
+ * @param {NodeJS.Platform} platform - Target Node.js platform.
+ * @param {string} arch - Target Node.js architecture.
+ * @returns {'mac-arm64' | 'mac-x64' | 'win-x64'} Update target directory.
+ */
+export function resolveDesktopAutoUpdateTarget(platform, arch) {
+  const os = platform === 'darwin' ? 'mac' : platform === 'win32' ? 'win' : platform
+  const target = `${os}-${arch}`
+  if (!UPDATE_TARGETS.has(target)) {
+    throw new Error(`desktop auto-update: unsupported target ${target}`)
+  }
+  return target
+}
+
+/**
+ * Return the local completion record filename for one packaged target.
+ * @param {'mac-arm64' | 'mac-x64' | 'win-x64'} target - Supported release target.
+ * @returns {string} Filename stored beside electron-builder artifacts.
+ */
+export function desktopBuildRecordFilename(target) {
+  if (!UPDATE_TARGETS.has(target)) {
+    throw new Error(`desktop auto-update: unsupported target ${target}`)
+  }
+  return `${target}-release.json`
+}
+
+/**
+ * Return the electron-builder channel metadata filename for an application version.
+ * @param {string} version - Desktop semantic version.
+ * @param {NodeJS.Platform} platform - Target platform.
+ * @returns {string} Channel metadata filename emitted for the target.
+ */
+export function desktopUpdateMetadataFilename(version, platform) {
+  if (valid(version) === null) {
+    throw new Error(`desktop auto-update: invalid Desktop version ${JSON.stringify(version)}`)
+  }
+  if (platform !== 'darwin' && platform !== 'win32') {
+    throw new Error(`desktop auto-update: unsupported metadata platform ${platform}`)
+  }
+  const release = prerelease(version)
+  const channel = release === null ? 'latest' : String(release[0])
+  return `${channel}${platform === 'darwin' ? '-mac' : ''}.yml`
+}
+
+/**
+ * Read one required release setting without accepting whitespace-only values.
+ * @param {NodeJS.ProcessEnv} env - Packaging or upload environment.
+ * @param {string} name - Environment variable to read.
+ * @returns {string} Trimmed setting.
+ */
+function requiredEnvironmentValue(env, name) {
+  const value = env[name]?.trim()
+  if (value === undefined || value === '') {
+    throw new Error(`desktop auto-update: ${name} must be set to a non-empty value`)
+  }
+  return value
+}
+
+/**
+ * Normalize an HTTPS origin and reject paths or credentials.
+ * @param {string} value - Candidate origin.
+ * @param {string} name - Environment variable used in diagnostics.
+ * @returns {string} Normalized HTTPS origin without a trailing slash.
+ */
+function httpsOrigin(value, name) {
+  let parsed
+  try {
+    parsed = new URL(value)
+  }
+  catch {
+    throw new Error(`desktop auto-update: ${name} must be an absolute HTTPS origin`)
+  }
+  if (parsed.protocol !== 'https:'
+    || parsed.username !== ''
+    || parsed.password !== ''
+    || parsed.pathname !== '/'
+    || parsed.search !== ''
+    || parsed.hash !== '') {
+    throw new Error(`desktop auto-update: ${name} must be an absolute HTTPS origin without a path, credentials, query, or fragment`)
+  }
+  return parsed.origin
+}
+
+/**
+ * Resolve the public updater URL for one release target.
+ * @param {NodeJS.ProcessEnv} env - Packaging or upload environment.
+ * @param {NodeJS.Platform} platform - Target Node.js platform.
+ * @param {string} arch - Target Node.js architecture.
+ * @returns {{ environment: 'test' | 'production', target: 'mac-arm64' | 'mac-x64' | 'win-x64', origin: string, publicUrl: string, keyPrefix: string }} Resolved updater configuration.
+ * @throws {Error} When the test deployment lacks a valid HTTPS origin.
+ */
+export function resolveDesktopAutoUpdateConfig(env, platform, arch) {
+  const environment = resolveDesktopAutoUpdateEnvironment(env)
+  const target = resolveDesktopAutoUpdateTarget(platform, arch)
+  const deployment = UPDATE_ENVIRONMENTS[environment]
+  let origin = deployment.fixedOrigin
+  if (origin === undefined) {
+    const { originEnvName } = deployment
+    if (originEnvName === undefined) throw new Error('desktop auto-update: selected deployment has no origin')
+    origin = httpsOrigin(requiredEnvironmentValue(env, originEnvName), originEnvName)
+  }
+  const keyPrefix = `_/harness/desktop/stable/${target}`
+  return {
+    environment,
+    target,
+    origin,
+    keyPrefix,
+    publicUrl: `${origin}/${keyPrefix}/`,
+  }
+}
+
+/**
+ * Resolve the public updater URL and private COS destination for one upload target.
+ * @param {NodeJS.ProcessEnv} env - Upload environment.
+ * @param {NodeJS.Platform} platform - Target Node.js platform.
+ * @param {string} arch - Target Node.js architecture.
+ * @returns {{ environment: 'test' | 'production', target: 'mac-arm64' | 'mac-x64' | 'win-x64', origin: string, publicUrl: string, keyPrefix: string, bucket: string, secretIdEnvName: string, secretKeyEnvName: string }} Resolved upload configuration.
+ * @throws {Error} When the selected deployment lacks a required origin or bucket, or the test origin is not HTTPS.
+ */
+export function resolveDesktopUploadConfig(env, platform, arch) {
+  const update = resolveDesktopAutoUpdateConfig(env, platform, arch)
+  const deployment = UPDATE_ENVIRONMENTS[update.environment]
+  return {
+    ...update,
+    bucket: requiredEnvironmentValue(env, deployment.bucketEnvName),
+    secretIdEnvName: deployment.secretIdEnvName,
+    secretKeyEnvName: deployment.secretKeyEnvName,
+  }
+}

apps/desktop/scripts/desktop-build-paths.d.mts

@@ -0,0 +1,49 @@
+import type { DesktopAutoUpdateTarget } from './desktop-auto-update-environment.mjs'
+
+/** Mutable target directories plus the shared immutable download cache. */
+export interface DesktopTargetBuildPaths {
+  readonly root: string
+  readonly artifacts: string
+  readonly runtime: string
+  readonly packageSet: string
+  readonly seed: string
+  readonly seedPnpm: string
+  readonly nodeExtract: string
+  readonly packedDsh: string
+  readonly packedVendor: string
+  readonly packedLandlock: string
+  readonly downloads: string
+}
+
+/**
+ * Resolve the fixed build target selected by a packaging environment.
+ * @param env - Packaging environment.
+ * @param hostPlatform - Build-host platform used when no target override exists.
+ * @param hostArch - Build-host architecture used when no target override exists.
+ * @returns Supported Desktop target name.
+ */
+export function resolveDesktopBuildTarget(
+  env?: NodeJS.ProcessEnv,
+  hostPlatform?: NodeJS.Platform,
+  hostArch?: string,
+): DesktopAutoUpdateTarget
+
+/**
+ * Return the mutable preparation and artifact directories owned by one release target.
+ * @param target - Supported Desktop target name.
+ * @returns Target paths plus the shared immutable download cache.
+ */
+export function desktopTargetBuildPaths(target: DesktopAutoUpdateTarget): DesktopTargetBuildPaths
+
+/**
+ * Resolve the paths owned by the target selected in a packaging environment.
+ * @param env - Packaging environment.
+ * @param hostPlatform - Build-host platform used when no target override exists.
+ * @param hostArch - Build-host architecture used when no target override exists.
+ * @returns Selected target paths.
+ */
+export function resolveDesktopTargetBuildPaths(
+  env?: NodeJS.ProcessEnv,
+  hostPlatform?: NodeJS.Platform,
+  hostArch?: string,
+): DesktopTargetBuildPaths

apps/desktop/scripts/desktop-build-paths.mjs

@@ -0,0 +1,70 @@
+/** Resolve build-owned Desktop paths without sharing mutable state across release targets. */
+
+import { join, resolve } from 'node:path'
+
+const APP_ROOT = resolve(import.meta.dirname, '..')
+const BUILD_ROOT = join(APP_ROOT, '.desktop-build')
+const SUPPORTED_TARGETS = new Set(['mac-arm64', 'mac-x64', 'win-x64'])
+
+/**
+ * Resolve the fixed build target selected by a packaging environment.
+ * @param {NodeJS.ProcessEnv} env - Packaging environment.
+ * @param {NodeJS.Platform} hostPlatform - Build-host platform used when no target override exists.
+ * @param {string} hostArch - Build-host architecture used when no target override exists.
+ * @returns {'mac-arm64' | 'mac-x64' | 'win-x64'} Supported Desktop target name.
+ */
+export function resolveDesktopBuildTarget(
+  env = process.env,
+  hostPlatform = process.platform,
+  hostArch = process.arch,
+) {
+  const platform = env.DSH_DESKTOP_TARGET_PLATFORM ?? env.npm_config_platform ?? hostPlatform
+  const arch = env.DSH_DESKTOP_TARGET_ARCH ?? env.npm_config_arch ?? hostArch
+  const os = platform === 'darwin' ? 'mac' : platform === 'win32' || platform === 'win' ? 'win' : platform
+  const target = `${os}-${arch}`
+  if (!SUPPORTED_TARGETS.has(target)) {
+    throw new Error(`desktop build paths: unsupported target ${target}`)
+  }
+  return /** @type {'mac-arm64' | 'mac-x64' | 'win-x64'} */ (target)
+}
+
+/**
+ * Return the mutable preparation and artifact directories owned by one release target.
+ * @param {'mac-arm64' | 'mac-x64' | 'win-x64'} target - Supported Desktop target name.
+ * @returns {{ root: string, artifacts: string, runtime: string, packageSet: string, seed: string, seedPnpm: string, nodeExtract: string, packedDsh: string, packedVendor: string, packedLandlock: string, downloads: string }} Target paths plus the shared immutable download cache.
+ */
+export function desktopTargetBuildPaths(target) {
+  if (!SUPPORTED_TARGETS.has(target)) {
+    throw new Error(`desktop build paths: unsupported target ${String(target)}`)
+  }
+  const root = join(BUILD_ROOT, 'targets', target)
+  const packed = join(root, 'packed')
+  return {
+    root,
+    artifacts: join(root, 'artifacts'),
+    runtime: join(root, 'runtime'),
+    packageSet: join(root, 'package-set'),
+    seed: join(root, 'seed'),
+    seedPnpm: join(root, 'seed-pnpm'),
+    nodeExtract: join(root, 'node-extract'),
+    packedDsh: join(packed, 'dsh'),
+    packedVendor: join(packed, 'vendor'),
+    packedLandlock: join(packed, 'landlock'),
+    downloads: join(BUILD_ROOT, 'downloads'),
+  }
+}
+
+/**
+ * Resolve the paths owned by the target selected in a packaging environment.
+ * @param {NodeJS.ProcessEnv} env - Packaging environment.
+ * @param {NodeJS.Platform} hostPlatform - Build-host platform used when no target override exists.
+ * @param {string} hostArch - Build-host architecture used when no target override exists.
+ * @returns {ReturnType<typeof desktopTargetBuildPaths>} Selected target paths.
+ */
+export function resolveDesktopTargetBuildPaths(
+  env = process.env,
+  hostPlatform = process.platform,
+  hostArch = process.arch,
+) {
+  return desktopTargetBuildPaths(resolveDesktopBuildTarget(env, hostPlatform, hostArch))
+}

apps/desktop/scripts/desktop-release-environment.d.mts

@@ -0,0 +1,61 @@
+/** Environment variable that supplies the Electron application identifier. */
+export const DESKTOP_APP_ID_ENV: 'DSH_DESKTOP_APP_ID'
+
+/** Environment variable that supplies electron-builder's macOS certificate qualifier. */
+export const MACOS_SIGNING_IDENTITY_ENV: 'DSH_DESKTOP_MACOS_SIGNING_IDENTITY'
+
+/** Environment variable that supplies the expected Apple Developer Team ID. */
+export const MACOS_TEAM_ID_ENV: 'DSH_DESKTOP_MACOS_TEAM_ID'
+
+/** Public identity expected on a macOS release. */
+export interface MacOSSigningEnvironment {
+  readonly signingIdentity: string
+  readonly teamId: string
+}
+
+/** Apple ID credentials accepted by notarytool. */
+export interface MacOSAppleIdNotarizationEnvironment {
+  readonly appleId: string
+  readonly appleIdPassword: string
+  readonly teamId: string
+}
+
+/** App Store Connect API credentials accepted by notarytool. */
+export interface MacOSApiKeyNotarizationEnvironment {
+  readonly appleApiKey: string
+  readonly appleApiKeyId: string
+  readonly appleApiIssuer: string
+}
+
+/** Keychain profile accepted by notarytool. */
+export interface MacOSKeychainNotarizationEnvironment {
+  readonly keychainProfile: string
+  readonly keychain?: string
+}
+
+/** One complete credential strategy accepted by notarytool. */
+export type MacOSNotarizationEnvironment =
+  | MacOSAppleIdNotarizationEnvironment
+  | MacOSApiKeyNotarizationEnvironment
+  | MacOSKeychainNotarizationEnvironment
+
+/**
+ * Resolve and validate the application identifier shared by every platform target.
+ * @param env - Packaging environment.
+ * @returns Reverse-DNS application identifier.
+ */
+export function resolveDesktopAppId(env: NodeJS.ProcessEnv): string
+
+/**
+ * Resolve and validate the public identity expected on a macOS release.
+ * @param env - Packaging environment.
+ * @returns Expected certificate qualifier and Team ID.
+ */
+export function resolveMacOSSigningEnvironment(env: NodeJS.ProcessEnv): MacOSSigningEnvironment
+
+/**
+ * Resolve one complete credential set accepted by Apple's notary service.
+ * @param env - Packaging environment.
+ * @returns Notary credentials without the submitted artifact path.
+ */
+export function resolveMacOSNotarizationEnvironment(env: NodeJS.ProcessEnv): MacOSNotarizationEnvironment

apps/desktop/scripts/desktop-release-environment.mjs

@@ -0,0 +1,98 @@
+/** Resolve public release identifiers supplied by the packaging environment. */
+
+/** Environment variable that supplies the Electron application identifier. */
+export const DESKTOP_APP_ID_ENV = 'DSH_DESKTOP_APP_ID'
+
+/** Environment variable that supplies electron-builder's macOS certificate qualifier. */
+export const MACOS_SIGNING_IDENTITY_ENV = 'DSH_DESKTOP_MACOS_SIGNING_IDENTITY'
+
+/** Environment variable that supplies the expected Apple Developer Team ID. */
+export const MACOS_TEAM_ID_ENV = 'DSH_DESKTOP_MACOS_TEAM_ID'
+
+const APPLE_API_KEY_ENV = 'APPLE_API_KEY'
+const APPLE_API_KEY_ID_ENV = 'APPLE_API_KEY_ID'
+const APPLE_API_ISSUER_ENV = 'APPLE_API_ISSUER'
+const APPLE_ID_ENV = 'APPLE_ID'
+const APPLE_APP_SPECIFIC_PASSWORD_ENV = 'APPLE_APP_SPECIFIC_PASSWORD'
+const APPLE_TEAM_ID_ENV = 'APPLE_TEAM_ID'
+const APPLE_KEYCHAIN_ENV = 'APPLE_KEYCHAIN'
+const APPLE_KEYCHAIN_PROFILE_ENV = 'APPLE_KEYCHAIN_PROFILE'
+
+/**
+ * Read one required non-empty environment variable.
+ * @param {NodeJS.ProcessEnv} env - Packaging environment.
+ * @param {string} name - Required variable name.
+ * @returns {string} Trimmed variable value.
+ */
+function requireEnvironmentValue(env, name) {
+  const value = env[name]?.trim()
+  if (value === undefined || value === '') {
+    throw new Error(`desktop release environment: ${name} must be set to a non-empty value`)
+  }
+  return value
+}
+
+/**
+ * Resolve and validate the application identifier shared by every platform target.
+ * @param {NodeJS.ProcessEnv} env - Packaging environment.
+ * @returns {string} Reverse-DNS application identifier.
+ */
+export function resolveDesktopAppId(env) {
+  const appId = requireEnvironmentValue(env, DESKTOP_APP_ID_ENV)
+  if (!/^[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)+$/u.test(appId)) {
+    throw new Error(`desktop release environment: ${DESKTOP_APP_ID_ENV} must be a reverse-DNS identifier`)
+  }
+  return appId
+}
+
+/**
+ * Resolve and validate the public identity expected on a macOS release.
+ * @param {NodeJS.ProcessEnv} env - Packaging environment.
+ * @returns {{ signingIdentity: string, teamId: string }} Expected certificate qualifier and Team ID.
+ */
+export function resolveMacOSSigningEnvironment(env) {
+  const signingIdentity = requireEnvironmentValue(env, MACOS_SIGNING_IDENTITY_ENV)
+  if (signingIdentity.startsWith('Developer ID Application:')) {
+    throw new Error(`desktop release environment: ${MACOS_SIGNING_IDENTITY_ENV} must omit the "Developer ID Application:" prefix`)
+  }
+  const teamId = requireEnvironmentValue(env, MACOS_TEAM_ID_ENV)
+  if (!/^[A-Z0-9]{10}$/u.test(teamId)) {
+    throw new Error(`desktop release environment: ${MACOS_TEAM_ID_ENV} must contain 10 uppercase letters or digits`)
+  }
+  return { signingIdentity, teamId }
+}
+
+/**
+ * Resolve one complete credential set accepted by Apple's notary service.
+ * @param {NodeJS.ProcessEnv} env - Packaging environment.
+ * @returns {{ appleId: string, appleIdPassword: string, teamId: string } | { appleApiKey: string, appleApiKeyId: string, appleApiIssuer: string } | { keychainProfile: string, keychain?: string }} Notary credentials without the submitted artifact path.
+ */
+export function resolveMacOSNotarizationEnvironment(env) {
+  const appleIdValues = [env[APPLE_ID_ENV], env[APPLE_APP_SPECIFIC_PASSWORD_ENV], env[APPLE_TEAM_ID_ENV]]
+  if (appleIdValues.some(value => value !== undefined)) {
+    return {
+      appleId: requireEnvironmentValue(env, APPLE_ID_ENV),
+      appleIdPassword: requireEnvironmentValue(env, APPLE_APP_SPECIFIC_PASSWORD_ENV),
+      teamId: requireEnvironmentValue(env, APPLE_TEAM_ID_ENV),
+    }
+  }
+
+  const apiKeyValues = [env[APPLE_API_KEY_ENV], env[APPLE_API_KEY_ID_ENV], env[APPLE_API_ISSUER_ENV]]
+  if (apiKeyValues.some(value => value !== undefined)) {
+    return {
+      appleApiKey: requireEnvironmentValue(env, APPLE_API_KEY_ENV),
+      appleApiKeyId: requireEnvironmentValue(env, APPLE_API_KEY_ID_ENV),
+      appleApiIssuer: requireEnvironmentValue(env, APPLE_API_ISSUER_ENV),
+    }
+  }
+
+  const keychainProfile = env[APPLE_KEYCHAIN_PROFILE_ENV]?.trim()
+  if (keychainProfile !== undefined && keychainProfile !== '') {
+    const keychain = env[APPLE_KEYCHAIN_ENV]?.trim()
+    return keychain === undefined || keychain === ''
+      ? { keychainProfile }
+      : { keychainProfile, keychain }
+  }
+
+  throw new Error('desktop release environment: macOS packaging requires APPLE_API_KEY, APPLE_API_KEY_ID, and APPLE_API_ISSUER; APPLE_ID, APPLE_APP_SPECIFIC_PASSWORD, and APPLE_TEAM_ID; or APPLE_KEYCHAIN_PROFILE')
+}

apps/desktop/scripts/desktop-upload-plan.ts

@@ -0,0 +1,257 @@
+/** Validate packaged Desktop update artifacts before any network upload begins. */
+
+import { createHash } from 'node:crypto'
+import { createReadStream } from 'node:fs'
+import { readFile, stat } from 'node:fs/promises'
+import { basename, join, resolve } from 'node:path'
+import { load } from 'js-yaml'
+import type { DesktopPackageTargetName } from './package-target.ts'
+import {
+  desktopBuildRecordFilename,
+  desktopUpdateMetadataFilename,
+  resolveDesktopUploadConfig,
+} from './desktop-auto-update-environment.mjs'
+import { desktopTargetBuildPaths } from './desktop-build-paths.mjs'
+
+const APP_ROOT = resolve(import.meta.dirname, '..')
+const REPOSITORY_ROOT = resolve(APP_ROOT, '..', '..')
+const TARGETS = {
+  'mac-arm64': { platform: 'darwin', arch: 'arm64', os: 'mac' },
+  'mac-x64': { platform: 'darwin', arch: 'x64', os: 'mac' },
+  'win-x64': { platform: 'win32', arch: 'x64', os: 'win' },
+} as const satisfies Record<DesktopPackageTargetName, {
+  readonly platform: NodeJS.Platform
+  readonly arch: string
+  readonly os: string
+}>
+
+/** One local file and its final object metadata. */
+export interface DesktopUploadArtifact {
+  readonly path: string
+  readonly filename: string
+  readonly key: string
+  readonly contentType: string
+  readonly cacheControl: string
+  readonly channelMetadata: boolean
+}
+
+/** A fully validated upload operation with channel metadata ordered last. */
+export interface DesktopUploadPlan {
+  readonly environment: 'test' | 'production'
+  readonly target: DesktopPackageTargetName
+  readonly version: string
+  readonly publicUrl: string
+  readonly bucket: string
+  readonly secretIdEnvName: string
+  readonly secretKeyEnvName: string
+  readonly artifacts: readonly DesktopUploadArtifact[]
+}
+
+/** Filesystem and environment inputs used to validate one upload. */
+export interface DesktopUploadPlanOptions {
+  readonly environment?: NodeJS.ProcessEnv
+  readonly repositoryRoot?: string
+  readonly appRoot?: string
+  readonly artifactsRoot?: string
+}
+
+interface UpdateFileInfo {
+  readonly filename: string
+  readonly size: number
+  readonly sha512: string
+}
+
+function object(value: unknown, label: string): Record<string, unknown> {
+  if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+    throw new Error(`desktop upload: ${label} must be an object`)
+  }
+  return value as Record<string, unknown>
+}
+
+function stringField(value: unknown, label: string): string {
+  if (typeof value !== 'string' || value === '') {
+    throw new Error(`desktop upload: ${label} must be a non-empty string`)
+  }
+  return value
+}
+
+function numberField(value: unknown, label: string): number {
+  if (typeof value !== 'number' || !Number.isSafeInteger(value) || value <= 0) {
+    throw new Error(`desktop upload: ${label} must be a positive integer`)
+  }
+  return value
+}
+
+async function jsonFile(path: string, label: string): Promise<Record<string, unknown>> {
+  let parsed: unknown
+  try {
+    parsed = JSON.parse(await readFile(path, 'utf8'))
+  }
+  catch (error) {
+    throw new Error(`desktop upload: cannot read ${label} at ${path}: ${error instanceof Error ? error.message : String(error)}`)
+  }
+  return object(parsed, label)
+}
+
+async function manifestVersion(path: string, label: string): Promise<string> {
+  return stringField((await jsonFile(path, label)).version, `${label}.version`)
+}
+
+function updateFileInfo(value: unknown, label: string, expectedFilename: string): UpdateFileInfo {
+  const info = object(value, label)
+  const filename = stringField(info.url ?? info.path, `${label}.url`)
+  if (filename !== basename(filename) || filename !== expectedFilename) {
+    throw new Error(`desktop upload: ${label} must reference ${expectedFilename}, received ${filename}`)
+  }
+  return {
+    filename,
+    size: numberField(info.size, `${label}.size`),
+    sha512: stringField(info.sha512, `${label}.sha512`),
+  }
+}
+
+async function sha512(path: string): Promise<string> {
+  const hash = createHash('sha512')
+  for await (const chunk of createReadStream(path)) hash.update(chunk)
+  return hash.digest('base64')
+}
+
+async function verifyChecksummedArtifact(
+  artifactsRoot: string,
+  info: UpdateFileInfo,
+): Promise<string> {
+  const path = join(artifactsRoot, info.filename)
+  const details = await stat(path).catch(() => undefined)
+  if (details === undefined || !details.isFile()) {
+    throw new Error(`desktop upload: missing artifact ${path}`)
+  }
+  if (details.size !== info.size) {
+    throw new Error(`desktop upload: ${info.filename} size ${details.size} does not match update metadata ${info.size}`)
+  }
+  const actual = await sha512(path)
+  if (actual !== info.sha512) {
+    throw new Error(`desktop upload: ${info.filename} SHA-512 does not match update metadata`)
+  }
+  return path
+}
+
+async function requireArtifact(artifactsRoot: string, filename: string): Promise<string> {
+  const path = join(artifactsRoot, filename)
+  const details = await stat(path).catch(() => undefined)
+  if (details === undefined || !details.isFile() || details.size === 0) {
+    throw new Error(`desktop upload: missing or empty artifact ${path}`)
+  }
+  return path
+}
+
+function uploadArtifact(
+  path: string,
+  keyPrefix: string,
+  contentType: string,
+  channelMetadata = false,
+): DesktopUploadArtifact {
+  const filename = basename(path)
+  return {
+    path,
+    filename,
+    key: `${keyPrefix}/${filename}`,
+    contentType,
+    cacheControl: channelMetadata
+      ? 'no-cache'
+      : 'public, max-age=31536000, immutable',
+    channelMetadata,
+  }
+}
+
+/**
+ * Validate the completed package record, dsh version, update metadata, hashes, and target files.
+ * @param targetName - Fixed platform and architecture selected by the upload command.
+ * @param options - Optional filesystem roots and environment for tests or release automation.
+ * @returns An upload plan whose mutable channel metadata is the final entry.
+ */
+export async function createDesktopUploadPlan(
+  targetName: DesktopPackageTargetName,
+  options: DesktopUploadPlanOptions = {},
+): Promise<DesktopUploadPlan> {
+  const target = TARGETS[targetName]
+  if (target === undefined) {
+    throw new Error(`desktop upload: unsupported target ${String(targetName)}`)
+  }
+  const environment = options.environment ?? process.env
+  const repositoryRoot = options.repositoryRoot ?? REPOSITORY_ROOT
+  const appRoot = options.appRoot ?? APP_ROOT
+  const artifactsRoot = options.artifactsRoot ?? desktopTargetBuildPaths(targetName).artifacts
+  const dshVersion = await manifestVersion(join(repositoryRoot, 'package.json'), 'dsh package')
+  const desktopVersion = await manifestVersion(join(appRoot, 'package.json'), 'desktop package')
+  if (dshVersion !== desktopVersion) {
+    throw new Error(`desktop upload: desktop version ${desktopVersion} does not match current dsh version ${dshVersion}`)
+  }
+
+  const update = resolveDesktopUploadConfig(environment, target.platform, target.arch)
+  const buildRecord = await jsonFile(
+    join(artifactsRoot, desktopBuildRecordFilename(targetName)),
+    `${targetName} package completion record`,
+  )
+  if (buildRecord.schemaVersion !== 1
+    || buildRecord.target !== targetName
+    || buildRecord.version !== dshVersion
+    || buildRecord.environment !== update.environment
+    || buildRecord.publicUrl !== update.publicUrl) {
+    throw new Error(`desktop upload: ${targetName} package completion record does not match dsh ${dshVersion} and ${update.environment} update destination`)
+  }
+
+  const metadataFilename = desktopUpdateMetadataFilename(dshVersion, target.platform)
+  const metadataPath = join(artifactsRoot, metadataFilename)
+  let metadataValue: unknown
+  try {
+    metadataValue = load(await readFile(metadataPath, 'utf8'))
+  }
+  catch (error) {
+    throw new Error(`desktop upload: cannot read update metadata at ${metadataPath}: ${error instanceof Error ? error.message : String(error)}`)
+  }
+  const metadata = object(metadataValue, metadataFilename)
+  const metadataVersion = stringField(metadata.version, `${metadataFilename}.version`)
+  if (metadataVersion !== dshVersion) {
+    throw new Error(`desktop upload: ${metadataFilename} version ${metadataVersion} does not match current dsh version ${dshVersion}`)
+  }
+  if (!Array.isArray(metadata.files) || metadata.files.length !== 1) {
+    throw new Error(`desktop upload: ${metadataFilename}.files must contain exactly one target update file`)
+  }
+
+  const base = `deepseek-harness-${dshVersion}-${target.os}-${target.arch}`
+  const updaterExtension = target.platform === 'darwin' ? 'zip' : 'exe'
+  const updaterInfo = updateFileInfo(metadata.files[0], `${metadataFilename}.files[0]`, `${base}.${updaterExtension}`)
+  const updaterPath = await verifyChecksummedArtifact(artifactsRoot, updaterInfo)
+  const artifacts: DesktopUploadArtifact[] = []
+
+  if (target.platform === 'darwin') {
+    const dmgPath = await requireArtifact(artifactsRoot, `${base}.dmg`)
+    const blockmapPath = await requireArtifact(artifactsRoot, `${base}.zip.blockmap`)
+    artifacts.push(
+      uploadArtifact(dmgPath, update.keyPrefix, 'application/x-apple-diskimage'),
+      uploadArtifact(updaterPath, update.keyPrefix, 'application/zip'),
+      uploadArtifact(blockmapPath, update.keyPrefix, 'application/octet-stream'),
+    )
+  }
+  else {
+    const blockMapSize = object(metadata.files[0], `${metadataFilename}.files[0]`).blockMapSize
+    numberField(blockMapSize, `${metadataFilename}.files[0].blockMapSize`)
+    artifacts.push(uploadArtifact(
+      updaterPath,
+      update.keyPrefix,
+      'application/vnd.microsoft.portable-executable',
+    ))
+  }
+
+  artifacts.push(uploadArtifact(metadataPath, update.keyPrefix, 'application/yaml', true))
+  return {
+    environment: update.environment,
+    target: targetName,
+    version: dshVersion,
+    publicUrl: update.publicUrl,
+    bucket: update.bucket,
+    secretIdEnvName: update.secretIdEnvName,
+    secretKeyEnvName: update.secretKeyEnvName,
+    artifacts,
+  }
+}

apps/desktop/scripts/dev.ts

@@ -0,0 +1,118 @@
+/** Build and launch the unpackaged Electron shell against the current workspace. */
+
+import { spawn } from 'node:child_process'
+import { existsSync, readFileSync } from 'node:fs'
+import { createRequire } from 'node:module'
+import { join, resolve } from 'node:path'
+import { parseArgs } from 'node:util'
+import { DESKTOP_HOST_PROTOCOL_VERSION } from '../src/host-protocol.ts'
+import type { DesktopRelease } from '../src/release.ts'
+import { prepareDevelopmentProject } from './development-project.ts'
+
+const APP_ROOT = resolve(import.meta.dirname, '..')
+const REPOSITORY_ROOT = resolve(APP_ROOT, '..', '..')
+const BUILD_ROOT = join(APP_ROOT, '.desktop-build')
+const DEVELOPMENT_ROOT = join(BUILD_ROOT, 'development')
+
+interface PackageManifest {
+  readonly version?: string
+}
+
+function packageVersion(path: string, subject: string): string {
+  const manifest = JSON.parse(readFileSync(path, 'utf8')) as PackageManifest
+  if (typeof manifest.version !== 'string') throw new Error(`desktop development: ${subject} has no version`)
+  return manifest.version
+}
+
+function debugPort(name: string, fallback: number): number {
+  const value = process.env[name]
+  if (value === undefined || value === '') return fallback
+  const port = Number(value)
+  if (!Number.isSafeInteger(port) || port < 1 || port > 65_535) {
+    throw new Error(`desktop development: ${name} must be an integer from 1 through 65535`)
+  }
+  return port
+}
+
+async function run(command: string, args: readonly string[], cwd: string, environment = process.env): Promise<void> {
+  await new Promise<void>((resolvePromise, reject) => {
+    const child = spawn(command, args, { cwd, env: environment, stdio: 'inherit' })
+    child.once('error', reject)
+    child.once('exit', (code, signal) => {
+      if (code === 0) resolvePromise()
+      else reject(new Error(`desktop development: ${args.join(' ')} exited with ${String(code ?? signal)}`))
+    })
+  })
+}
+
+async function runPackageScript(script: string, cwd: string): Promise<void> {
+  const packageManager = process.env.npm_execpath
+  if (packageManager === undefined || packageManager === '') {
+    throw new Error('desktop development: invoke this launcher through pnpm run dev:desktop or start:desktop')
+  }
+  await run(process.execPath, [packageManager, 'run', script], cwd)
+}
+
+async function launchElectron(projectDir: string): Promise<void> {
+  const require = createRequire(import.meta.url)
+  const electron: unknown = require('electron')
+  if (typeof electron !== 'string') throw new Error('desktop development: electron executable is unavailable')
+  const mainPort = debugPort('DSH_DESKTOP_MAIN_INSPECT_PORT', 9229)
+  const rendererPort = debugPort('DSH_DESKTOP_RENDERER_DEBUG_PORT', 9222)
+  const hostPort = debugPort('DSH_DESKTOP_HOST_INSPECT_PORT', 9230)
+  const home = resolve(process.env.DSH_HOME ?? join(DEVELOPMENT_ROOT, 'home'))
+  const userData = join(DEVELOPMENT_ROOT, 'electron-user-data')
+  const environment: NodeJS.ProcessEnv = {
+    ...process.env,
+    DSH_HOME: home,
+    DSH_DESKTOP_DEV_PROJECT_DIR: projectDir,
+    DSH_DESKTOP_HOST_INSPECT_PORT: String(hostPort),
+    DSH_DESKTOP_NODE_BINARY: process.execPath,
+    DSH_DESKTOP_OPEN_DEVTOOLS: process.env.DSH_DESKTOP_OPEN_DEVTOOLS ?? '1',
+    ELECTRON_ENABLE_LOGGING: process.env.ELECTRON_ENABLE_LOGGING ?? '1',
+  }
+  console.log(`desktop development: DSH_HOME=${home}`)
+  console.log(`desktop development: inspectors main=${String(mainPort)}, renderer=${String(rendererPort)}, host=${String(hostPort)}`)
+  await run(electron, [
+    `--inspect=127.0.0.1:${String(mainPort)}`,
+    `--remote-debugging-port=${String(rendererPort)}`,
+    `--user-data-dir=${userData}`,
+    APP_ROOT,
+  ], APP_ROOT, environment)
+}
+
+async function main(): Promise<void> {
+  const { values } = parseArgs({ options: { 'skip-build': { type: 'boolean', default: false } } })
+  if (!values['skip-build']) {
+    await runPackageScript('build', REPOSITORY_ROOT)
+    await runPackageScript('build', APP_ROOT)
+  }
+  for (const path of [
+    join(APP_ROOT, 'lib', 'main.js'),
+    join(REPOSITORY_ROOT, 'apps', 'desktop-host', 'lib', 'index.js'),
+  ]) {
+    if (!existsSync(path)) throw new Error(`desktop development: missing built artifact ${path}`)
+  }
+  const version = packageVersion(join(APP_ROOT, 'package.json'), 'desktop package')
+  const pnpmVersion = packageVersion(join(APP_ROOT, 'node_modules', 'pnpm', 'package.json'), 'pnpm package')
+  const release: DesktopRelease = {
+    schemaVersion: 1,
+    version,
+    hostProtocolVersion: DESKTOP_HOST_PROTOCOL_VERSION,
+    nodeVersion: process.versions.node,
+    pnpmVersion,
+  }
+  const projectDir = prepareDevelopmentProject({
+    projectDir: join(DEVELOPMENT_ROOT, 'project'),
+    cliDir: join(REPOSITORY_ROOT, 'apps', 'cli'),
+    hostDir: join(REPOSITORY_ROOT, 'apps', 'desktop-host'),
+    dependencyDir: join(REPOSITORY_ROOT, 'node_modules', '.pnpm', 'node_modules'),
+    release,
+  })
+  await launchElectron(projectDir)
+}
+
+main().catch((error: unknown) => {
+  console.error(error instanceof Error ? error.message : error)
+  process.exitCode = 1
+})

apps/desktop/scripts/development-project.ts

@@ -0,0 +1,120 @@
+/** Prepare the disposable npm-project view used by an unpackaged Electron shell. */
+
+import {
+  existsSync,
+  lstatSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  realpathSync,
+  rmSync,
+  symlinkSync,
+  unlinkSync,
+} from 'node:fs'
+import { dirname, join } from 'node:path'
+import { createDevelopmentProjectMetadata } from '../src/project-manager.ts'
+import type { DesktopRelease } from '../src/release.ts'
+
+interface PackageManifest {
+  readonly name?: string
+  readonly version?: string
+}
+
+/** Inputs whose locations differ between the launcher and isolated tests. */
+export interface DevelopmentProjectOptions {
+  /** Directory replaced with the generated development project. */
+  readonly projectDir: string
+  /** Current workspace's `apps/cli` package directory. */
+  readonly cliDir: string
+  /** Current workspace's private Desktop Host application directory. */
+  readonly hostDir: string
+  /** pnpm's workspace-wide virtual-hoist directory. */
+  readonly dependencyDir: string
+  /** Release identity written into the disposable project metadata. */
+  readonly release: DesktopRelease
+}
+
+function readManifest(path: string): PackageManifest {
+  return JSON.parse(readFileSync(path, 'utf8')) as PackageManifest
+}
+
+function removeOwnedPath(path: string): void {
+  let stat: ReturnType<typeof lstatSync>
+  try {
+    stat = lstatSync(path)
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return
+    throw error
+  }
+  if (stat.isSymbolicLink()) {
+    unlinkSync(path)
+    return
+  }
+  if (stat.isDirectory()) {
+    rmSync(path, { recursive: true })
+    return
+  }
+  unlinkSync(path)
+}
+
+function linkDirectory(source: string, destination: string): void {
+  mkdirSync(dirname(destination), { recursive: true })
+  symlinkSync(realpathSync(source), destination, process.platform === 'win32' ? 'junction' : 'dir')
+}
+
+function mirrorDependencyLinks(sourceRoot: string, destinationRoot: string): void {
+  for (const entry of readdirSync(sourceRoot, { withFileTypes: true })) {
+    if (entry.name === '.bin') continue
+    const source = join(sourceRoot, entry.name)
+    if (entry.name.startsWith('@') && (entry.isDirectory() || entry.isSymbolicLink())) {
+      mkdirSync(join(destinationRoot, entry.name), { recursive: true })
+      for (const scoped of readdirSync(source, { withFileTypes: true })) {
+        if (!scoped.isDirectory() && !scoped.isSymbolicLink()) continue
+        linkDirectory(join(source, scoped.name), join(destinationRoot, entry.name, scoped.name))
+      }
+      continue
+    }
+    if (entry.isDirectory() || entry.isSymbolicLink()) linkDirectory(source, join(destinationRoot, entry.name))
+  }
+}
+
+/**
+ * Replace one disposable project with links to the current built workspace.
+ * @param options - Project destination, CLI package, and release identity.
+ * @returns the absolute project directory supplied by the caller.
+ */
+export function prepareDevelopmentProject(options: DevelopmentProjectOptions): string {
+  const cliManifest = readManifest(join(options.cliDir, 'package.json'))
+  if (cliManifest.name !== '@deepseek-ai/dsh' || cliManifest.version !== options.release.version) {
+    throw new Error(
+      `desktop development: apps/cli must be @deepseek-ai/dsh@${options.release.version}, found `
+      + `${String(cliManifest.name)}@${String(cliManifest.version)}`,
+    )
+  }
+  if (!existsSync(options.dependencyDir)) {
+    throw new Error('desktop development: workspace dependency links are missing; run pnpm install')
+  }
+  const hostManifest = readManifest(join(options.hostDir, 'package.json'))
+  if (hostManifest.name !== '@deepseek-ai/dsh-desktop-host' || hostManifest.version !== options.release.version) {
+    throw new Error(
+      `desktop development: apps/desktop-host must be @deepseek-ai/dsh-desktop-host@${options.release.version}, found `
+      + `${String(hostManifest.name)}@${String(hostManifest.version)}`,
+    )
+  }
+  if (!existsSync(join(options.hostDir, 'lib', 'index.js'))) {
+    throw new Error('desktop development: apps/desktop-host/lib/index.js is missing; run pnpm run build')
+  }
+
+  removeOwnedPath(options.projectDir)
+  createDevelopmentProjectMetadata(options.projectDir, options.release)
+  const destinationModules = join(options.projectDir, 'node_modules')
+  mkdirSync(destinationModules, { recursive: true })
+  mirrorDependencyLinks(options.dependencyDir, destinationModules)
+  const dshLink = join(destinationModules, '@deepseek-ai', 'dsh')
+  removeOwnedPath(dshLink)
+  linkDirectory(options.cliDir, dshLink)
+  const hostLink = join(destinationModules, '@deepseek-ai', 'dsh-desktop-host')
+  removeOwnedPath(hostLink)
+  linkDirectory(options.hostDir, hostLink)
+  return options.projectDir
+}

apps/desktop/scripts/macos-seed-store.ts

@@ -0,0 +1,413 @@
+/** Sign Mach-O content in a pnpm CAS without invalidating the store index. */
+
+import { createHash } from 'node:crypto'
+import {
+  chmodSync,
+  closeSync,
+  copyFileSync,
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  openSync,
+  readFileSync,
+  readSync,
+  readdirSync,
+  rmSync,
+  unlinkSync,
+  writeFileSync,
+} from 'node:fs'
+import { availableParallelism, tmpdir } from 'node:os'
+import { basename, dirname, join, relative, sep } from 'node:path'
+import { DatabaseSync } from 'node:sqlite'
+import { Packr } from 'msgpackr'
+import type { MacOSSigningEnvironment } from './desktop-release-environment.mjs'
+import { signMacOSSeedCode, verifyMacOSSeedCode } from './verify-macos-signature.mjs'
+
+const MACH_O_MAGICS = new Set([
+  'cafebabe',
+  'cafebabf',
+  'cefaedfe',
+  'cffaedfe',
+  'feedface',
+  'feedfacf',
+  'bebafeca',
+  'bfbafeca',
+])
+const CAS_PATH_PATTERN = /^([0-9a-f]{2})\/([0-9a-f]{126})(-exec)?$/u
+const MAX_CONCURRENT_CODE_SIGNERS = 4
+const packr = new Packr({ moreTypes: true, useRecords: true })
+
+interface PnpmStoreFileRecord {
+  checkedAt: number
+  digest: string
+  mode: number
+  size: number
+}
+
+interface PnpmSideEffectsRecord {
+  readonly added?: Map<string, PnpmStoreFileRecord>
+}
+
+interface PnpmPackageIndexRecord {
+  readonly algo?: string
+  readonly files?: Map<string, PnpmStoreFileRecord>
+  readonly sideEffects?: Map<string, PnpmSideEffectsRecord>
+}
+
+interface DecodedIndexRow {
+  readonly key: string
+  readonly value: PnpmPackageIndexRecord
+  changed: boolean
+}
+
+interface CasFile {
+  readonly path: string
+  readonly digest: string
+  readonly executable: boolean
+}
+
+interface FileReference {
+  readonly row: DecodedIndexRow
+  readonly record: PnpmStoreFileRecord
+}
+
+interface SigningWork {
+  readonly file: CasFile
+  readonly references: readonly FileReference[]
+  readonly temporaryPath: string
+}
+
+/** Summary of native code rewritten in one pnpm store. */
+export interface MacOSSeedStoreSigningResult {
+  readonly signedFiles: number
+  readonly prunedOrphans: number
+  readonly updatedIndexRows: number
+}
+
+/** A signer used to make one writable Mach-O copy release-valid. */
+export type MacOSSeedCodeSigner = (path: string, identifier: string) => Promise<void>
+
+/** A verifier used to check one Mach-O file after packaging transport. */
+export type MacOSSeedCodeVerifier = (path: string) => void
+
+/** Optional execution controls for seed-store code signing. */
+export interface MacOSSeedStoreSigningOptions {
+  readonly signer?: MacOSSeedCodeSigner
+  readonly concurrency?: number
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function isStoreFileRecord(value: unknown): value is PnpmStoreFileRecord {
+  if (!isRecord(value)) return false
+  return typeof value.checkedAt === 'number'
+    && typeof value.digest === 'string'
+    && /^[0-9a-f]{128}$/u.test(value.digest)
+    && Number.isSafeInteger(value.mode)
+    && Number.isSafeInteger(value.size)
+}
+
+function packageFileMaps(value: unknown, key: string): readonly Map<string, PnpmStoreFileRecord>[] {
+  if (!isRecord(value)) throw new Error(`desktop seed signing: invalid pnpm index record ${key}`)
+  const record = value as PnpmPackageIndexRecord
+  if (record.algo !== undefined && record.algo !== 'sha512') {
+    throw new Error(`desktop seed signing: unsupported pnpm index algorithm in ${key}`)
+  }
+  const maps: Map<string, PnpmStoreFileRecord>[] = []
+  if (record.files !== undefined) {
+    if (!(record.files instanceof Map)) throw new Error(`desktop seed signing: invalid pnpm file map in ${key}`)
+    maps.push(record.files)
+  }
+  if (record.sideEffects !== undefined) {
+    if (!(record.sideEffects instanceof Map)) {
+      throw new Error(`desktop seed signing: invalid pnpm side-effects map in ${key}`)
+    }
+    for (const effect of record.sideEffects.values()) {
+      if (!isRecord(effect)) throw new Error(`desktop seed signing: invalid pnpm side effect in ${key}`)
+      if (effect.added === undefined) continue
+      if (!(effect.added instanceof Map)) {
+        throw new Error(`desktop seed signing: invalid pnpm side-effect file map in ${key}`)
+      }
+      maps.push(effect.added)
+    }
+  }
+  for (const files of maps) {
+    for (const file of files.values()) {
+      if (!isStoreFileRecord(file)) throw new Error(`desktop seed signing: invalid pnpm file record in ${key}`)
+    }
+  }
+  return maps
+}
+
+function isExecutableMode(mode: number): boolean {
+  return (mode & 0o111) !== 0
+}
+
+function referenceKey(digest: string, executable: boolean): string {
+  return `${digest}:${executable ? 'exec' : 'nonexec'}`
+}
+
+function isMachO(path: string): boolean {
+  const descriptor = openSync(path, 'r')
+  try {
+    const header = Buffer.alloc(4)
+    return readSync(descriptor, header, 0, header.length, 0) === header.length
+      && MACH_O_MAGICS.has(header.toString('hex'))
+  } finally {
+    closeSync(descriptor)
+  }
+}
+
+function visitFiles(root: string): readonly string[] {
+  const files: string[] = []
+  const visit = (directory: string): void => {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      const path = join(directory, entry.name)
+      if (entry.isSymbolicLink()) {
+        throw new Error(`desktop seed signing: pnpm store contains a symbolic link: ${relative(root, path)}`)
+      }
+      if (entry.isDirectory()) visit(path)
+      else if (entry.isFile()) files.push(path)
+      else throw new Error(`desktop seed signing: unsupported pnpm store entry: ${relative(root, path)}`)
+    }
+  }
+  visit(root)
+  return files.sort((left, right) => left.localeCompare(right))
+}
+
+function versionRoots(storeRoot: string): readonly string[] {
+  return readdirSync(storeRoot, { withFileTypes: true })
+    .filter(entry => entry.isDirectory() && /^v\d+$/u.test(entry.name))
+    .map(entry => join(storeRoot, entry.name))
+    .filter(root => existsSync(join(root, 'files')))
+    .sort((left, right) => left.localeCompare(right))
+}
+
+function casFiles(versionRoot: string): readonly CasFile[] {
+  const filesRoot = join(versionRoot, 'files')
+  const result: CasFile[] = []
+  for (const path of visitFiles(filesRoot)) {
+    if (!isMachO(path)) continue
+    const normalized = relative(filesRoot, path).split(sep).join('/')
+    const match = CAS_PATH_PATTERN.exec(normalized)
+    if (match === null) {
+      throw new Error(`desktop seed signing: Mach-O content has an unsupported pnpm CAS path: ${normalized}`)
+    }
+    result.push({
+      path,
+      digest: `${match[1]}${match[2]}`,
+      executable: match[3] !== undefined,
+    })
+  }
+  return result
+}
+
+function readIndexRows(database: DatabaseSync): readonly DecodedIndexRow[] {
+  const rows: DecodedIndexRow[] = []
+  for (const row of database.prepare('SELECT key, data FROM package_index').iterate() as Iterable<{
+    key: string
+    data: Uint8Array
+  }>) {
+    rows.push({ key: row.key, value: packr.unpack(row.data) as PnpmPackageIndexRecord, changed: false })
+  }
+  return rows
+}
+
+function fileReferences(rows: readonly DecodedIndexRow[]): ReadonlyMap<string, readonly FileReference[]> {
+  const references = new Map<string, FileReference[]>()
+  for (const row of rows) {
+    for (const files of packageFileMaps(row.value, row.key)) {
+      for (const record of files.values()) {
+        const key = referenceKey(record.digest, isExecutableMode(record.mode))
+        const values = references.get(key) ?? []
+        values.push({ row, record })
+        references.set(key, values)
+      }
+    }
+  }
+  return references
+}
+
+function writeCasFile(path: string, body: Buffer, mode: number): void {
+  mkdirSync(dirname(path), { recursive: true })
+  try {
+    writeFileSync(path, body, { flag: 'wx', mode })
+  } catch (error) {
+    if (!isRecord(error) || error.code !== 'EEXIST' || !readFileSync(path).equals(body)) throw error
+  }
+  chmodSync(path, mode)
+}
+
+function signedCasPath(versionRoot: string, digest: string, executable: boolean): string {
+  return join(
+    versionRoot,
+    'files',
+    digest.slice(0, 2),
+    `${digest.slice(2)}${executable ? '-exec' : ''}`,
+  )
+}
+
+async function runConcurrent<T>(
+  values: readonly T[],
+  concurrency: number,
+  run: (value: T) => Promise<void>,
+): Promise<void> {
+  let next = 0
+  const failure: { error?: unknown; failed: boolean } = { failed: false }
+  const worker = async (): Promise<void> => {
+    while (!failure.failed) {
+      const index = next
+      if (index >= values.length) return
+      next += 1
+      try {
+        await run(values[index] as T)
+      } catch (error) {
+        if (!failure.failed) {
+          failure.failed = true
+          failure.error = error
+        }
+      }
+    }
+  }
+  const workers = Array.from(
+    { length: Math.min(concurrency, values.length) },
+    async () => worker(),
+  )
+  await Promise.all(workers)
+  if (failure.failed) throw failure.error
+}
+
+async function rewriteVersionStore(
+  versionRoot: string,
+  appId: string,
+  signer: MacOSSeedCodeSigner,
+  concurrency: number,
+): Promise<MacOSSeedStoreSigningResult> {
+  const databasePath = join(versionRoot, 'index.db')
+  if (!existsSync(databasePath)) {
+    throw new Error(`desktop seed signing: pnpm store has no package index: ${databasePath}`)
+  }
+  const database = new DatabaseSync(databasePath)
+  const workRoot = mkdtempSync(join(tmpdir(), 'dsh-desktop-seed-signing-'))
+  const obsoleteFiles = new Set<string>()
+  let prunedOrphans = 0
+  let rows: readonly DecodedIndexRow[] = []
+  try {
+    rows = readIndexRows(database)
+    const references = fileReferences(rows)
+    const signingWork: SigningWork[] = []
+    for (const file of casFiles(versionRoot)) {
+      const body = readFileSync(file.path)
+      const actualDigest = createHash('sha512').update(body).digest('hex')
+      if (actualDigest !== file.digest) {
+        throw new Error(`desktop seed signing: pnpm CAS digest mismatch at ${file.path}`)
+      }
+      const fileReferences = references.get(referenceKey(file.digest, file.executable)) ?? []
+      if (fileReferences.length === 0) {
+        obsoleteFiles.add(file.path)
+        prunedOrphans += 1
+        continue
+      }
+      const temporary = join(workRoot, `${signingWork.length.toString().padStart(4, '0')}-${basename(file.path)}`)
+      copyFileSync(file.path, temporary)
+      chmodSync(temporary, 0o755)
+      signingWork.push({ file, references: fileReferences, temporaryPath: temporary })
+    }
+    await runConcurrent(signingWork, concurrency, async (work) => {
+      await signer(work.temporaryPath, `${appId}.seed.${work.file.digest.slice(0, 32)}`)
+    })
+    for (const work of signingWork) {
+      const signedBody = readFileSync(work.temporaryPath)
+      if (!isMachO(work.temporaryPath)) {
+        throw new Error(`desktop seed signing: signer produced non-Mach-O content for ${work.file.path}`)
+      }
+      const signedDigest = createHash('sha512').update(signedBody).digest('hex')
+      const mode = work.file.executable ? 0o755 : 0o644
+      const destination = signedCasPath(versionRoot, signedDigest, work.file.executable)
+      writeCasFile(destination, signedBody, mode)
+      const checkedAt = Date.now()
+      for (const reference of work.references) {
+        reference.record.checkedAt = checkedAt
+        reference.record.digest = signedDigest
+        reference.record.mode = mode
+        reference.record.size = signedBody.length
+        reference.row.changed = true
+      }
+      if (destination !== work.file.path) obsoleteFiles.add(work.file.path)
+    }
+    const changedRows = rows.filter(row => row.changed)
+    database.exec('BEGIN IMMEDIATE')
+    let committed = false
+    try {
+      const statement = database.prepare('INSERT OR REPLACE INTO package_index (key, data) VALUES (?, ?)')
+      for (const row of changedRows) statement.run(row.key, packr.pack(row.value))
+      database.exec('COMMIT')
+      committed = true
+    } finally {
+      if (!committed) database.exec('ROLLBACK')
+    }
+    for (const path of obsoleteFiles) unlinkSync(path)
+    database.exec('VACUUM')
+    return { signedFiles: signingWork.length, prunedOrphans, updatedIndexRows: changedRows.length }
+  } finally {
+    database.close()
+    rmSync(workRoot, { recursive: true, force: true })
+  }
+}
+
+/**
+ * Replace every Mach-O CAS object with a Developer ID signed object and update pnpm's SHA-512 index.
+ * A signer rejection leaves the original CAS objects and package index unchanged.
+ * @param storeRoot - Loose pnpm store prepared for the packaged seed.
+ * @param appId - Electron application ID used as the signing identifier prefix.
+ * @param expected - Company Developer ID identity and Team ID.
+ * @param options - Optional signer and worker bound used by focused tests.
+ * @returns Counts for release diagnostics after every signer completes and the index transaction commits.
+ */
+export async function signMacOSSeedStore(
+  storeRoot: string,
+  appId: string,
+  expected: MacOSSigningEnvironment,
+  options: MacOSSeedStoreSigningOptions = {},
+): Promise<MacOSSeedStoreSigningResult> {
+  const roots = versionRoots(storeRoot)
+  if (roots.length === 0) throw new Error(`desktop seed signing: no pnpm store versions found in ${storeRoot}`)
+  const concurrency = options.concurrency ?? Math.min(MAX_CONCURRENT_CODE_SIGNERS, availableParallelism())
+  if (!Number.isSafeInteger(concurrency) || concurrency < 1) {
+    throw new Error(`desktop seed signing: concurrency must be a positive integer; received ${String(concurrency)}`)
+  }
+  const signer = options.signer ?? (async (path, identifier) => {
+    await signMacOSSeedCode(path, identifier, expected)
+  })
+  const results: MacOSSeedStoreSigningResult[] = []
+  for (const root of roots) results.push(await rewriteVersionStore(root, appId, signer, concurrency))
+  return results.reduce((total, current) => ({
+    signedFiles: total.signedFiles + current.signedFiles,
+    prunedOrphans: total.prunedOrphans + current.prunedOrphans,
+    updatedIndexRows: total.updatedIndexRows + current.updatedIndexRows,
+  }), { signedFiles: 0, prunedOrphans: 0, updatedIndexRows: 0 })
+}
+
+/**
+ * Verify that every Mach-O CAS object has the expected Developer ID, timestamp, and hardened runtime.
+ * @param storeRoot - Loose or extracted pnpm store.
+ * @param expected - Company Developer ID identity and Team ID.
+ * @param verifier - Injectable signature verifier used by focused tests.
+ * @returns Number of verified Mach-O files.
+ */
+export function verifyMacOSSeedStore(
+  storeRoot: string,
+  expected: MacOSSigningEnvironment,
+  verifier: MacOSSeedCodeVerifier = (path) => { verifyMacOSSeedCode(path, expected) },
+): number {
+  let count = 0
+  for (const root of versionRoots(storeRoot)) {
+    for (const file of casFiles(root)) {
+      verifier(file.path)
+      count += 1
+    }
+  }
+  return count
+}

apps/desktop/scripts/notarize-macos-disk-images.d.mts

@@ -0,0 +1,23 @@
+import type { NotarizeOptions } from '@electron/notarize'
+import type { MacOSSigningEnvironment } from './desktop-release-environment.mjs'
+
+/** Completed electron-builder artifact needed for disk-image notarization. */
+export interface DesktopBuildArtifact {
+  readonly file: string
+}
+
+/**
+ * Submit one generated DMG to Apple, staple its ticket, and verify Gatekeeper acceptance.
+ * @param artifact - Completed electron-builder artifact.
+ * @param env - Packaging environment.
+ * @param expected - Public release identity.
+ * @param submit - Notary submission implementation.
+ * @param verify - Disk-image qualification implementation.
+ */
+export function notarizeMacOSDiskImageArtifact(
+  artifact: DesktopBuildArtifact,
+  env: NodeJS.ProcessEnv,
+  expected: MacOSSigningEnvironment,
+  submit?: (options: NotarizeOptions) => Promise<void>,
+  verify?: (path: string, expected: MacOSSigningEnvironment) => void,
+): Promise<void>

apps/desktop/scripts/notarize-macos-disk-images.mjs

@@ -0,0 +1,30 @@
+/** Notarize and qualify macOS disk images after electron-builder creates them. */
+
+import { notarize } from '@electron/notarize'
+import { rmSync } from 'node:fs'
+import { resolveMacOSNotarizationEnvironment } from './desktop-release-environment.mjs'
+import { verifyMacOSDiskImage } from './verify-macos-signature.mjs'
+
+/**
+ * Submit one generated DMG to Apple, staple its ticket, and verify Gatekeeper acceptance.
+ * @param {{ file: string }} artifact - Completed electron-builder artifact.
+ * @param {NodeJS.ProcessEnv} env - Packaging environment.
+ * @param {{ signingIdentity: string, teamId: string }} expected - Public release identity.
+ * @param {(options: object) => Promise<void>} submit - Notary submission implementation.
+ * @param {(path: string, expected: object) => void} verify - Disk-image qualification implementation.
+ * @returns {Promise<void>}
+ */
+export async function notarizeMacOSDiskImageArtifact(
+  artifact,
+  env,
+  expected,
+  submit = notarize,
+  verify = verifyMacOSDiskImage,
+) {
+  if (!artifact.file.endsWith('.dmg')) return
+  rmSync(`${artifact.file}.blockmap`, { force: true })
+  const credentials = resolveMacOSNotarizationEnvironment(env)
+  await submit({ appPath: artifact.file, ...credentials })
+  verify(artifact.file, expected)
+  process.stdout.write(`desktop macOS notarization: verified disk image ${artifact.file}\n`)
+}

apps/desktop/scripts/package-target.ts

@@ -0,0 +1,285 @@
+/** Build one release target with matching Electron, Node.js, and seed architecture. */
+
+import { spawn } from 'node:child_process'
+import { mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from 'node:fs'
+import { parseArgs } from 'node:util'
+import { join, resolve } from 'node:path'
+import {
+  desktopBuildRecordFilename,
+  resolveDesktopAutoUpdateConfig,
+} from './desktop-auto-update-environment.mjs'
+import { desktopTargetBuildPaths } from './desktop-build-paths.mjs'
+
+const APP_ROOT = resolve(import.meta.dirname, '..')
+const REPOSITORY_ROOT = resolve(APP_ROOT, '..', '..')
+const WINDOWS_SIGNING_ENV_PREFIX = 'DSH_DESKTOP_WINDOWS_'
+const WINDOWS_SIGNING_ENV_NAMES = [
+  'DSH_DESKTOP_WINDOWS_CER_FILE',
+  'DSH_DESKTOP_WINDOWS_KEY_CONTAINER',
+  'DSH_DESKTOP_WINDOWS_SIGNTOOL',
+  'DSH_DESKTOP_WINDOWS_TOKEN_PIN',
+] as const
+const DESKTOP_UPLOAD_CREDENTIAL_ENV_NAMES = new Set([
+  'DOWNLOAD_TEST_COS_SECRET_ID',
+  'DOWNLOAD_TEST_COS_SECRET_KEY',
+  'DOWNLOAD_PROD_COS_SECRET_ID',
+  'DOWNLOAD_PROD_COS_SECRET_KEY',
+])
+
+/** Fixed platform and architecture identifiers exposed by package scripts. */
+export type DesktopPackageTargetName = 'mac-arm64' | 'mac-x64' | 'win-x64'
+
+/** One supported release target and its electron-builder selectors. */
+export interface DesktopPackageTarget {
+  readonly name: DesktopPackageTargetName
+  readonly platform: 'darwin' | 'win32'
+  readonly arch: 'arm64' | 'x64'
+  readonly builderPlatform: '--mac' | '--win'
+  readonly builderArch: '--arm64' | '--x64'
+}
+
+const TARGETS: Record<DesktopPackageTargetName, DesktopPackageTarget> = {
+  'mac-arm64': {
+    name: 'mac-arm64',
+    platform: 'darwin',
+    arch: 'arm64',
+    builderPlatform: '--mac',
+    builderArch: '--arm64',
+  },
+  'mac-x64': {
+    name: 'mac-x64',
+    platform: 'darwin',
+    arch: 'x64',
+    builderPlatform: '--mac',
+    builderArch: '--x64',
+  },
+  'win-x64': {
+    name: 'win-x64',
+    platform: 'win32',
+    arch: 'x64',
+    builderPlatform: '--win',
+    builderArch: '--x64',
+  },
+}
+
+/**
+ * Remove Windows signing configuration from package preparation subprocesses.
+ * @param environment - Packaging command environment.
+ * @returns A copy without Windows signing fields.
+ */
+export function withoutWindowsSigningEnvironment(environment: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  return Object.fromEntries(Object.entries(environment)
+    .filter(([name]) => !name.startsWith(WINDOWS_SIGNING_ENV_PREFIX)))
+}
+
+/**
+ * Remove upload-only COS credentials from every packaging subprocess.
+ * @param environment - Packaging command environment.
+ * @returns A copy without Desktop upload credentials.
+ */
+export function withoutDesktopUploadCredentials(environment: NodeJS.ProcessEnv): NodeJS.ProcessEnv {
+  return Object.fromEntries(Object.entries(environment)
+    .filter(([name]) => !DESKTOP_UPLOAD_CREDENTIAL_ENV_NAMES.has(name)))
+}
+
+function isTargetName(value: string): value is DesktopPackageTargetName {
+  return Object.hasOwn(TARGETS, value)
+}
+
+function packageVersion(path: string, label: string): string {
+  const manifest = JSON.parse(readFileSync(path, 'utf8')) as { version?: unknown }
+  if (typeof manifest.version !== 'string' || manifest.version === '') {
+    throw new Error(`desktop package: ${label} has no version`)
+  }
+  return manifest.version
+}
+
+function writeReleaseRecord(
+  target: DesktopPackageTarget,
+  environment: NodeJS.ProcessEnv,
+  artifactsRoot: string,
+): void {
+  const desktopVersion = packageVersion(join(APP_ROOT, 'package.json'), 'desktop package')
+  const dshVersion = packageVersion(join(REPOSITORY_ROOT, 'package.json'), 'dsh package')
+  if (desktopVersion !== dshVersion) {
+    throw new Error(`desktop package: desktop version ${desktopVersion} does not match dsh version ${dshVersion}`)
+  }
+  const update = resolveDesktopAutoUpdateConfig(environment, target.platform, target.arch)
+  const recordPath = join(artifactsRoot, desktopBuildRecordFilename(target.name))
+  const temporaryPath = `${recordPath}.tmp`
+  writeFileSync(temporaryPath, `${JSON.stringify({
+    schemaVersion: 1,
+    target: target.name,
+    version: dshVersion,
+    environment: update.environment,
+    publicUrl: update.publicUrl,
+  }, null, 2)}\n`)
+  renameSync(temporaryPath, recordPath)
+}
+
+/**
+ * Resolve a named release target and reject hosts that cannot execute its packaged runtime.
+ * @param name - One of the fixed Desktop release target names.
+ * @param hostPlatform - Build-host Node.js platform.
+ * @param hostArch - Build-host Node.js architecture.
+ * @returns The target selectors shared by runtime preparation and electron-builder.
+ */
+export function resolveDesktopPackageTarget(
+  name: string,
+  hostPlatform: NodeJS.Platform = process.platform,
+  hostArch: string = process.arch,
+): DesktopPackageTarget {
+  if (!isTargetName(name)) {
+    throw new Error(`desktop package: unsupported target ${JSON.stringify(name)}; expected ${Object.keys(TARGETS).join(', ')}`)
+  }
+  const target = TARGETS[name]
+  if (target.platform === 'win32' && (hostPlatform !== 'win32' || hostArch !== 'x64')) {
+    throw new Error('desktop package: win-x64 requires a Windows x64 build host')
+  }
+  if (target.platform === 'darwin' && hostPlatform !== 'darwin') {
+    throw new Error(`desktop package: ${name} requires a macOS build host`)
+  }
+  if (name === 'mac-arm64' && hostArch !== 'arm64') {
+    throw new Error('desktop package: mac-arm64 requires an Apple Silicon build host')
+  }
+  if (name === 'mac-x64' && hostArch !== 'arm64' && hostArch !== 'x64') {
+    throw new Error('desktop package: mac-x64 requires an Intel Mac or Apple Silicon with Rosetta')
+  }
+  return target
+}
+
+interface DesktopPackageInvocation {
+  readonly target: DesktopPackageTarget
+  readonly directory: boolean
+  readonly prepareOnly: boolean
+}
+
+function hostTargetName(platform: NodeJS.Platform, arch: string): DesktopPackageTargetName {
+  const name = `${platform === 'darwin' ? 'mac' : platform === 'win32' ? 'win' : platform}-${arch}`
+  if (!isTargetName(name)) throw new Error(`desktop package: unsupported build host ${platform}-${arch}`)
+  return name
+}
+
+/**
+ * Parse the fixed-target packaging command line.
+ * @param argv - Arguments after the script entry point.
+ * @param hostPlatform - Build-host Node.js platform.
+ * @param hostArch - Build-host Node.js architecture.
+ * @returns The validated target and whether to emit an unpacked directory.
+ */
+export function parseDesktopPackageInvocation(
+  argv: readonly string[],
+  hostPlatform: NodeJS.Platform = process.platform,
+  hostArch: string = process.arch,
+): DesktopPackageInvocation {
+  const { values, positionals } = parseArgs({
+    args: [...argv],
+    allowPositionals: true,
+    options: {
+      dir: { type: 'boolean', default: false },
+      'prepare-only': { type: 'boolean', default: false },
+    },
+  })
+  if (positionals.length > 1) throw new Error('desktop package: expected at most one target')
+  const name = positionals[0] ?? hostTargetName(hostPlatform, hostArch)
+  return {
+    target: resolveDesktopPackageTarget(name, hostPlatform, hostArch),
+    directory: values.dir,
+    prepareOnly: values['prepare-only'],
+  }
+}
+
+/**
+ * Build the electron-builder command arguments for one validated target.
+ * @param target - Supported release target.
+ * @param directory - Whether to stop at an unpacked application directory.
+ * @returns Arguments that keep publishing under the separate validated upload command.
+ */
+export function desktopElectronBuilderArguments(
+  target: DesktopPackageTarget,
+  directory: boolean,
+): readonly string[] {
+  return [
+    'exec',
+    'electron-builder',
+    '--config',
+    'electron-builder.config.mjs',
+    target.builderPlatform,
+    target.builderArch,
+    '--publish',
+    'never',
+    ...(directory ? ['--dir'] : []),
+  ]
+}
+
+function runPnpm(
+  args: readonly string[],
+  env: NodeJS.ProcessEnv = process.env,
+  cwd: string = APP_ROOT,
+): Promise<void> {
+  const pnpmEntry = process.env.npm_execpath
+  if (pnpmEntry === undefined || pnpmEntry === '') {
+    throw new Error('desktop package: invoke this script through a pnpm package command')
+  }
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(process.execPath, [pnpmEntry, ...args], {
+      cwd,
+      env,
+      stdio: 'inherit',
+    })
+    child.once('error', reject)
+    child.once('close', (code, signal) => {
+      if (code === 0) resolvePromise()
+      else reject(new Error(`desktop package: pnpm ${args.join(' ')} exited with ${String(code ?? signal)}`))
+    })
+  })
+}
+
+async function main(): Promise<void> {
+  const invocation = parseDesktopPackageInvocation(process.argv.slice(2))
+  const { target } = invocation
+  const buildPaths = desktopTargetBuildPaths(target.name)
+  const releaseRecordPath = join(buildPaths.artifacts, desktopBuildRecordFilename(target.name))
+  if (!invocation.prepareOnly) {
+    rmSync(releaseRecordPath, { force: true })
+    rmSync(`${releaseRecordPath}.tmp`, { force: true })
+  }
+  const buildEnv = withoutWindowsSigningEnvironment(withoutDesktopUploadCredentials(process.env))
+  const targetEnv: NodeJS.ProcessEnv = {
+    ...buildEnv,
+    DSH_DESKTOP_TARGET_PLATFORM: target.platform,
+    DSH_DESKTOP_TARGET_ARCH: target.arch,
+  }
+  const electronBuilderEnv = { ...targetEnv }
+  for (const name of WINDOWS_SIGNING_ENV_NAMES) {
+    if (process.env[name] !== undefined) electronBuilderEnv[name] = process.env[name]
+  }
+  await runPnpm(['run', 'build:official'], buildEnv, REPOSITORY_ROOT)
+  await runPnpm(['run', 'release:pack', '--family', 'dsh', '--out', buildPaths.packedDsh], buildEnv, REPOSITORY_ROOT)
+  await runPnpm([
+    '--dir',
+    'apps/desktop-host',
+    'pack',
+    '--pack-destination',
+    buildPaths.packedDsh,
+  ], buildEnv, REPOSITORY_ROOT)
+  await runPnpm(['run', 'release:pack', '--family', 'vendor', '--out', buildPaths.packedVendor], buildEnv, REPOSITORY_ROOT)
+  rmSync(buildPaths.packedLandlock, { recursive: true, force: true })
+  mkdirSync(buildPaths.packedLandlock, { recursive: true })
+  await runPnpm(['--dir', 'native/landlock-run', 'run', 'build:ts'], buildEnv, REPOSITORY_ROOT)
+  await runPnpm([
+    '--dir',
+    'native/landlock-run/packages/entry',
+    'pack',
+    '--pack-destination',
+    buildPaths.packedLandlock,
+  ], buildEnv, REPOSITORY_ROOT)
+  await runPnpm(['run', 'prepare:runtime'], targetEnv)
+  await runPnpm(['run', 'prepare:packages'], targetEnv)
+  await runPnpm(['run', 'prepare:seed'], targetEnv)
+  if (invocation.prepareOnly) return
+  await runPnpm(desktopElectronBuilderArguments(target, invocation.directory), electronBuilderEnv)
+  if (!invocation.directory) writeReleaseRecord(target, electronBuilderEnv, buildPaths.artifacts)
+}
+
+if (process.argv[1] !== undefined && import.meta.filename === resolve(process.argv[1])) await main()

apps/desktop/scripts/prepare-package-set.ts

@@ -0,0 +1,172 @@
+/** Select and copy the local npm tarball closures that supply Desktop dsh and its private Host. */
+
+import { createHash } from 'node:crypto'
+import {
+  constants,
+  copyFileSync,
+  mkdirSync,
+  readFileSync,
+  readdirSync,
+  rmSync,
+  statSync,
+  writeFileSync,
+} from 'node:fs'
+import { basename, join, resolve } from 'node:path'
+import { parseArgs } from 'node:util'
+import {
+  DESKTOP_HOST_PACKAGE,
+  DESKTOP_HOST_RUNTIME_FILES,
+  DESKTOP_PACKAGES_DIR,
+  DESKTOP_PACKAGE_SET_FILE,
+  parseDesktopCorePackageSet,
+  type DesktopCorePackageRecord,
+} from '../src/core-package-set.ts'
+import { capture } from '../../../scripts/release/process.ts'
+import { tarballFiles } from '../../../scripts/release/tarball.ts'
+import { resolveDesktopTargetBuildPaths } from './desktop-build-paths.mjs'
+
+const DSH_PACKAGE = '@deepseek-ai/dsh'
+const ROOT_PACKAGES = [DSH_PACKAGE, DESKTOP_HOST_PACKAGE] as const
+const APP_ROOT = resolve(import.meta.dirname, '..')
+const REPOSITORY_ROOT = resolve(APP_ROOT, '..', '..')
+
+const REQUIRED_DEPENDENCY_SECTIONS = ['dependencies', 'peerDependencies'] as const
+const OPTIONAL_DEPENDENCY_SECTION = 'optionalDependencies'
+
+/** Packed package information needed to form the local Desktop closure. */
+export interface PackedDesktopPackage {
+  readonly tarball: string
+  readonly manifest: Readonly<Record<string, unknown>>
+}
+
+function dependencyNames(manifest: Readonly<Record<string, unknown>>, section: string): string[] {
+  const value = manifest[section]
+  if (value === undefined) return []
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`desktop package set: ${String(manifest.name)} has invalid ${section}`)
+  }
+  return Object.keys(value).sort()
+}
+
+/**
+ * Select the complete available first-party dependency closures rooted at dsh and its private Host.
+ * @param available - Packed packages indexed by package name.
+ * @returns Selected packages sorted by name.
+ */
+export function selectDesktopPackageClosure(
+  available: ReadonlyMap<string, PackedDesktopPackage>,
+): PackedDesktopPackage[] {
+  const selected = new Map<string, PackedDesktopPackage>()
+  const visit = (name: string): void => {
+    if (selected.has(name)) return
+    const packed = available.get(name)
+    if (packed === undefined) throw new Error(`desktop package set: packed inputs omit required package ${name}`)
+    selected.set(name, packed)
+    for (const section of REQUIRED_DEPENDENCY_SECTIONS) {
+      for (const dependency of dependencyNames(packed.manifest, section)) {
+        if (available.has(dependency)) visit(dependency)
+        else if (dependency.startsWith('@deepseek-ai/')) {
+          throw new Error(`desktop package set: ${name} requires unpacked internal package ${dependency}`)
+        }
+      }
+    }
+    for (const dependency of dependencyNames(packed.manifest, OPTIONAL_DEPENDENCY_SECTION)) {
+      if (available.has(dependency)) visit(dependency)
+    }
+  }
+  for (const name of ROOT_PACKAGES) {
+    if (!available.has(name)) throw new Error(`desktop package set: packed inputs omit ${name}`)
+    visit(name)
+  }
+  return [...selected.entries()].sort(([left], [right]) => left.localeCompare(right)).map(([, packed]) => packed)
+}
+
+function packedManifest(tarball: string): Record<string, unknown> {
+  const value: unknown = JSON.parse(capture('tar', ['-xOzf', tarball, 'package/package.json']))
+  if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+    throw new Error(`desktop package set: ${tarball} has no package manifest`)
+  }
+  return value as Record<string, unknown>
+}
+
+function packedPackages(inputs: readonly string[]): Map<string, PackedDesktopPackage> {
+  const available = new Map<string, PackedDesktopPackage>()
+  for (const input of inputs) {
+    const tarballs = readdirSync(input).filter(file => file.endsWith('.tgz')).sort()
+    if (tarballs.length === 0) throw new Error(`desktop package set: ${input} contains no tarballs`)
+    for (const file of tarballs) {
+      const tarball = join(input, file)
+      const manifest = packedManifest(tarball)
+      const name = manifest.name
+      if (typeof name !== 'string' || name === '') throw new Error(`desktop package set: ${tarball} has no package name`)
+      if (available.has(name)) throw new Error(`desktop package set: duplicate packed package ${name}`)
+      available.set(name, { tarball, manifest })
+    }
+  }
+  return available
+}
+
+/**
+ * Require every private Host file used before the Desktop profile can pass its health check.
+ * @param files - Tarball paths rooted at `package/`.
+ * @returns Nothing.
+ */
+export function assertDesktopHostPackageFiles(files: readonly string[]): void {
+  const available = new Set(files)
+  const missing = DESKTOP_HOST_RUNTIME_FILES
+    .map(file => `package/${file}`)
+    .filter(file => !available.has(file))
+  if (missing.length > 0) {
+    throw new Error(`desktop package set: ${DESKTOP_HOST_PACKAGE} tarball omits required file(s): ${missing.join(', ')}`)
+  }
+}
+
+/** Prepare a package set from release tarball directories. */
+export function prepareDesktopPackageSet(inputs: readonly string[], output: string): void {
+  const selected = selectDesktopPackageClosure(packedPackages(inputs))
+  const host = selected.find(packed => packed.manifest.name === DESKTOP_HOST_PACKAGE)
+  if (host === undefined) throw new Error(`desktop package set: selected closure omits ${DESKTOP_HOST_PACKAGE}`)
+  assertDesktopHostPackageFiles(tarballFiles(host.tarball))
+  rmSync(output, { recursive: true, force: true })
+  const packageDir = join(output, DESKTOP_PACKAGES_DIR)
+  mkdirSync(packageDir, { recursive: true })
+  const records: DesktopCorePackageRecord[] = selected.map((packed) => {
+    const name = packed.manifest.name
+    const version = packed.manifest.version
+    if (typeof name !== 'string' || typeof version !== 'string') {
+      throw new Error(`desktop package set: ${packed.tarball} has no package identity`)
+    }
+    const file = basename(packed.tarball)
+    const destination = join(packageDir, file)
+    copyFileSync(packed.tarball, destination, constants.COPYFILE_EXCL)
+    const body = readFileSync(destination)
+    return {
+      name,
+      version,
+      file,
+      bytes: statSync(destination).size,
+      integrity: `sha512-${createHash('sha512').update(body).digest('base64')}`,
+    }
+  })
+  const packageSet = parseDesktopCorePackageSet({ schemaVersion: 1, packages: records })
+  writeFileSync(join(output, DESKTOP_PACKAGE_SET_FILE), `${JSON.stringify(packageSet, undefined, 2)}\n`, { mode: 0o600 })
+}
+
+function main(): void {
+  const buildPaths = resolveDesktopTargetBuildPaths()
+  const defaultInputs = [
+    buildPaths.packedDsh,
+    buildPaths.packedVendor,
+    buildPaths.packedLandlock,
+  ]
+  const { values } = parseArgs({
+    options: { from: { type: 'string', multiple: true }, out: { type: 'string' } },
+    allowPositionals: false,
+  })
+  const inputs = (values.from ?? defaultInputs).map(path => resolve(REPOSITORY_ROOT, path))
+  const output = values.out === undefined ? buildPaths.packageSet : resolve(REPOSITORY_ROOT, values.out)
+  prepareDesktopPackageSet(inputs, output)
+  console.log(`desktop package set: prepared ${output}`)
+}
+
+if (import.meta.main) main()

apps/desktop/scripts/prepare-runtime.ts

@@ -0,0 +1,107 @@
+/** Download and verify the upstream Node.js runtime and copy the pinned pnpm CLI. */
+
+import { createHash } from 'node:crypto'
+import { spawnSync } from 'node:child_process'
+import { cpSync, createReadStream, createWriteStream, existsSync, mkdirSync, readFileSync, rmSync, writeFileSync } from 'node:fs'
+import { chmod, readFile } from 'node:fs/promises'
+import { createRequire } from 'node:module'
+import { dirname, join } from 'node:path'
+import { pipeline } from 'node:stream/promises'
+import extractZip from 'extract-zip'
+import { extract } from 'tar'
+import { resolveDesktopTargetBuildPaths } from './desktop-build-paths.mjs'
+
+const NODE_VERSION = '24.17.0'
+const BUILD_PATHS = resolveDesktopTargetBuildPaths()
+const RUNTIME_ROOT = BUILD_PATHS.runtime
+const DOWNLOAD_ROOT = BUILD_PATHS.downloads
+
+type RuntimePlatform = 'darwin' | 'linux' | 'win'
+type RuntimeArch = 'arm64' | 'x64'
+
+function target(): { platform: RuntimePlatform; arch: RuntimeArch } {
+  const rawPlatform = process.env.DSH_DESKTOP_TARGET_PLATFORM ?? process.env.npm_config_platform ?? process.platform
+  const rawArch = process.env.DSH_DESKTOP_TARGET_ARCH ?? process.env.npm_config_arch ?? process.arch
+  const platform = rawPlatform === 'win32' ? 'win' : rawPlatform
+  if (platform !== 'darwin' && platform !== 'linux' && platform !== 'win') {
+    throw new Error(`desktop runtime: unsupported platform ${rawPlatform}`)
+  }
+  if (rawArch !== 'arm64' && rawArch !== 'x64') throw new Error(`desktop runtime: unsupported architecture ${rawArch}`)
+  return { platform, arch: rawArch }
+}
+
+async function download(url: string, path: string): Promise<void> {
+  const response = await fetch(url)
+  if (!response.ok) throw new Error(`desktop runtime: ${url} returned HTTP ${String(response.status)}`)
+  writeFileSync(path, new Uint8Array(await response.arrayBuffer()), { mode: 0o600 })
+}
+
+async function prepareNode(platform: RuntimePlatform, arch: RuntimeArch): Promise<void> {
+  const extension = platform === 'win' ? 'zip' : 'tar.gz'
+  const folder = `node-v${NODE_VERSION}-${platform}-${arch}`
+  const archiveName = `${folder}.${extension}`
+  const releaseRoot = `https://nodejs.org/download/release/v${NODE_VERSION}`
+  const archive = join(DOWNLOAD_ROOT, archiveName)
+  const sums = join(DOWNLOAD_ROOT, `node-v${NODE_VERSION}-SHASUMS256.txt`)
+  if (!existsSync(archive)) await download(`${releaseRoot}/${archiveName}`, archive)
+  if (!existsSync(sums)) await download(`${releaseRoot}/SHASUMS256.txt`, sums)
+  const line = (await readFile(sums, 'utf8')).split(/\r?\n/u)
+    .find(candidate => candidate.endsWith(`  ${archiveName}`))
+  if (line === undefined) throw new Error(`desktop runtime: ${archiveName} is absent from Node.js SHASUMS256.txt`)
+  const expected = line.split(/\s+/u)[0]
+  const actual = createHash('sha256').update(await readFile(archive)).digest('hex')
+  if (actual !== expected) throw new Error(`desktop runtime: checksum mismatch for ${archiveName}`)
+
+  const extraction = BUILD_PATHS.nodeExtract
+  rmSync(extraction, { recursive: true, force: true })
+  mkdirSync(extraction, { recursive: true })
+  if (platform === 'win') await extractZip(archive, { dir: extraction })
+  else await extract({ cwd: extraction, file: archive })
+  const source = join(extraction, folder, platform === 'win' ? 'node.exe' : 'bin/node')
+  const destinationRoot = join(RUNTIME_ROOT, 'node')
+  const destination = join(destinationRoot, platform === 'win' ? 'node.exe' : 'node')
+  rmSync(destinationRoot, { recursive: true, force: true })
+  mkdirSync(destinationRoot, { recursive: true })
+  // A fresh write prevents macOS from retaining invalid code-signature vnode state from a tar-extracted Mach-O clone.
+  await pipeline(createReadStream(source), createWriteStream(destination, { flags: 'wx' }))
+  if (platform !== 'win') await chmod(destination, 0o755)
+  const hostPlatform = process.platform === 'win32' ? 'win' : process.platform
+  const hostCanExecute = platform === hostPlatform
+    && (arch === process.arch || (platform === 'darwin' && arch === 'x64' && process.arch === 'arm64'))
+  if (hostCanExecute) {
+    const result = spawnSync(destination, ['--version'], { encoding: 'utf8' })
+    if (result.error !== undefined || result.status !== 0 || result.stdout.trim() !== `v${NODE_VERSION}`) {
+      const detail = result.error?.message ?? result.signal ?? result.stderr.trim()
+      const outcome = detail === '' ? `exit ${String(result.status)}` : detail
+      throw new Error(`desktop runtime: prepared Node.js ${NODE_VERSION} failed executable verification: ${outcome}`)
+    }
+  }
+  rmSync(extraction, { recursive: true, force: true })
+}
+
+function preparePnpm(): string {
+  const require = createRequire(import.meta.url)
+  const manifestPath = require.resolve('pnpm')
+  const manifest = JSON.parse(readFileSync(manifestPath, 'utf8')) as { version?: unknown }
+  if (typeof manifest.version !== 'string') throw new Error('desktop runtime: pnpm manifest has no version')
+  const packageDir = dirname(manifestPath)
+  const destination = join(RUNTIME_ROOT, 'pnpm')
+  rmSync(destination, { recursive: true, force: true })
+  cpSync(packageDir, destination, { recursive: true })
+  return manifest.version
+}
+
+async function main(): Promise<void> {
+  const { platform, arch } = target()
+  mkdirSync(DOWNLOAD_ROOT, { recursive: true })
+  mkdirSync(RUNTIME_ROOT, { recursive: true })
+  await prepareNode(platform, arch)
+  const pnpmVersion = preparePnpm()
+  writeFileSync(join(RUNTIME_ROOT, 'versions.json'), `${JSON.stringify({
+    schemaVersion: 1,
+    node: NODE_VERSION,
+    pnpm: pnpmVersion,
+  }, undefined, 2)}\n`)
+}
+
+await main()

apps/desktop/scripts/prepare-seed.ts

@@ -0,0 +1,200 @@
+/** Build the release seed through the same embedded pnpm used on first launch. */
+
+import { spawn } from 'node:child_process'
+import { createHash } from 'node:crypto'
+import { copyFileSync, cpSync, existsSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync } from 'node:fs'
+import { tmpdir } from 'node:os'
+import { delimiter, dirname, join, relative, resolve, sep } from 'node:path'
+import { createSeedMetadata } from '../src/project-manager.ts'
+import { DESKTOP_HOST_PROTOCOL_VERSION } from '../src/host-protocol.ts'
+import { parseDesktopRelease, type DesktopRelease } from '../src/release.ts'
+import {
+  DESKTOP_HOST_PACKAGE,
+  DESKTOP_HOST_RUNTIME_FILES,
+  DESKTOP_PACKAGES_DIR,
+  DESKTOP_PACKAGE_SET_FILE,
+  readDesktopCorePackageSet,
+  verifyDesktopCoreLockfile,
+} from '../src/core-package-set.ts'
+import {
+  archivePnpmStore,
+  extractPnpmStoreArchives,
+  removePnpmProjectRegistrations,
+} from '../src/seed-store.ts'
+import {
+  resolveDesktopAppId,
+  resolveMacOSSigningEnvironment,
+} from './desktop-release-environment.mjs'
+import {
+  signMacOSSeedStore,
+  verifyMacOSSeedStore,
+} from './macos-seed-store.ts'
+import { resolveDesktopTargetBuildPaths } from './desktop-build-paths.mjs'
+
+const APP_ROOT = resolve(import.meta.dirname, '..')
+const BUILD_PATHS = resolveDesktopTargetBuildPaths()
+const SEED_OUTPUT_ROOT = BUILD_PATHS.seed
+const SEED_ROOT = mkdtempSync(join(tmpdir(), 'dsh-desktop-seed-'))
+const STORE_ROOT = join(SEED_ROOT, 'store')
+const RUNTIME_ROOT = BUILD_PATHS.runtime
+const PNPM_BUILD_STATE = BUILD_PATHS.seedPnpm
+const PACKAGE_SET_ROOT = BUILD_PATHS.packageSet
+const NODE = join(RUNTIME_ROOT, 'node', process.platform === 'win32' ? 'node.exe' : 'node')
+const PNPM = join(RUNTIME_ROOT, 'pnpm', 'bin', 'pnpm.mjs')
+
+function manifestVersion(path: string, subject: string): string {
+  const manifest = JSON.parse(readFileSync(path, 'utf8')) as { version?: unknown }
+  if (typeof manifest.version !== 'string') throw new Error(`desktop seed: ${subject} has no version`)
+  return manifest.version
+}
+
+function desktopRelease(): DesktopRelease {
+  const version = manifestVersion(join(APP_ROOT, 'package.json'), 'desktop package')
+  const dshVersion = manifestVersion(resolve(APP_ROOT, '..', '..', 'package.json'), 'root dsh package')
+  if (version !== dshVersion) {
+    throw new Error(`desktop seed: Electron ${version} must bind the same version of @deepseek-ai/dsh, found ${dshVersion}`)
+  }
+  const runtime = JSON.parse(readFileSync(join(RUNTIME_ROOT, 'versions.json'), 'utf8')) as Record<string, unknown>
+  return parseDesktopRelease({
+    schemaVersion: 1,
+    version,
+    hostProtocolVersion: DESKTOP_HOST_PROTOCOL_VERSION,
+    nodeVersion: runtime.node,
+    pnpmVersion: runtime.pnpm,
+  })
+}
+
+function runPnpm(args: readonly string[]): Promise<void> {
+  return new Promise((resolvePromise, reject) => {
+    const [command, ...commandArgs] = args
+    if (command === undefined) throw new Error('desktop seed: pnpm command is required')
+    const config = join(PNPM_BUILD_STATE, 'config')
+    const userConfig = join(config, 'npmrc')
+    mkdirSync(config, { recursive: true })
+    writeFileSync(userConfig, '')
+    const child = spawn(NODE, [
+      PNPM,
+      '--config.registry=https://registry.npmjs.org/',
+      `--config.store-dir=${STORE_ROOT}`,
+      '--config.enable-global-virtual-store=false',
+      `--config.userconfig=${userConfig}`,
+      command,
+      ...commandArgs,
+    ], {
+      cwd: SEED_ROOT,
+      env: {
+        ...Object.fromEntries(Object.entries(process.env).filter(([name]) => (
+          !/^DSH_DESKTOP_/u.test(name) && !/^(?:npm|pnpm|corepack)_/iu.test(name)
+        ))),
+        NPM_CONFIG_REGISTRY: 'https://registry.npmjs.org/',
+        NPM_CONFIG_STORE_DIR: STORE_ROOT,
+        NPM_CONFIG_USERCONFIG: userConfig,
+        PATH: `${dirname(NODE)}${delimiter}${process.env.PATH ?? ''}`,
+        XDG_CACHE_HOME: join(PNPM_BUILD_STATE, 'cache'),
+        XDG_CONFIG_HOME: config,
+        XDG_STATE_HOME: join(PNPM_BUILD_STATE, 'state'),
+      },
+      stdio: 'inherit',
+    })
+    child.once('error', reject)
+    child.once('close', (code, signal) => {
+      if (code === 0) resolvePromise()
+      else reject(new Error(`desktop seed: pnpm exited with ${String(code ?? signal)}`))
+    })
+  })
+}
+
+function inventory(root: string): readonly { path: string; bytes: number; sha256: string }[] {
+  const files: string[] = []
+  const visit = (dir: string): void => {
+    for (const entry of readdirSync(dir, { withFileTypes: true })) {
+      const path = join(dir, entry.name)
+      if (entry.isDirectory()) visit(path)
+      else if (entry.isFile()) files.push(path)
+      else throw new Error(`desktop seed: unsupported filesystem entry ${relative(root, path)}`)
+    }
+  }
+  visit(root)
+  return files.sort().map((path) => {
+    const body = readFileSync(path)
+    return {
+      path: relative(root, path).split(sep).join('/'),
+      bytes: statSync(path).size,
+      sha256: createHash('sha256').update(body).digest('hex'),
+    }
+  })
+}
+
+async function verifyOfflineInstallation(release: DesktopRelease): Promise<void> {
+  const installedModules = join(SEED_ROOT, 'node_modules')
+  try {
+    await runPnpm(['install', '--offline', '--frozen-lockfile', '--trust-lockfile'])
+    const hostRoot = join(installedModules, ...DESKTOP_HOST_PACKAGE.split('/'))
+    for (const file of DESKTOP_HOST_RUNTIME_FILES) {
+      if (!existsSync(join(hostRoot, file))) {
+        throw new Error(`desktop seed: local ${DESKTOP_HOST_PACKAGE}@${release.version} does not contain ${file}`)
+      }
+    }
+  } finally {
+    rmSync(installedModules, { recursive: true, force: true })
+  }
+}
+
+async function main(): Promise<void> {
+  rmSync(SEED_OUTPUT_ROOT, { recursive: true, force: true })
+  rmSync(PNPM_BUILD_STATE, { recursive: true, force: true })
+  mkdirSync(STORE_ROOT, { recursive: true })
+  try {
+    const release = desktopRelease()
+    copyFileSync(join(PACKAGE_SET_ROOT, DESKTOP_PACKAGE_SET_FILE), join(SEED_ROOT, DESKTOP_PACKAGE_SET_FILE))
+    cpSync(join(PACKAGE_SET_ROOT, DESKTOP_PACKAGES_DIR), join(SEED_ROOT, DESKTOP_PACKAGES_DIR), { recursive: true })
+    createSeedMetadata(SEED_ROOT, release)
+    await runPnpm(['install', '--lockfile-only'])
+    verifyDesktopCoreLockfile(
+      readFileSync(join(SEED_ROOT, 'pnpm-lock.yaml'), 'utf8'),
+      readDesktopCorePackageSet(SEED_ROOT, release.version),
+    )
+    const installedModules = join(SEED_ROOT, 'node_modules')
+    await runPnpm(['install', '--prod', '--frozen-lockfile', '--trust-lockfile', '--ignore-scripts'])
+    rmSync(installedModules, { recursive: true, force: true })
+    rmSync(PNPM_BUILD_STATE, { recursive: true, force: true })
+    await verifyOfflineInstallation(release)
+    const targetPlatform = process.env.DSH_DESKTOP_TARGET_PLATFORM ?? process.platform
+    let signedMachOFiles: number | undefined
+    let macOSSigning: ReturnType<typeof resolveMacOSSigningEnvironment> | undefined
+    if (targetPlatform === 'darwin') {
+      macOSSigning = resolveMacOSSigningEnvironment(process.env)
+      const signing = await signMacOSSeedStore(
+        STORE_ROOT,
+        resolveDesktopAppId(process.env),
+        macOSSigning,
+      )
+      signedMachOFiles = signing.signedFiles
+      process.stdout.write(
+        `desktop seed: signed ${signing.signedFiles} Mach-O files, updated ${signing.updatedIndexRows} pnpm index records, and pruned ${signing.prunedOrphans} native orphans\n`,
+      )
+      await verifyOfflineInstallation(release)
+    }
+    removePnpmProjectRegistrations(STORE_ROOT)
+    archivePnpmStore(SEED_ROOT, STORE_ROOT)
+    if (macOSSigning !== undefined && signedMachOFiles !== undefined) {
+      const extractedStore = mkdtempSync(join(tmpdir(), 'dsh-desktop-seed-verification-'))
+      try {
+        extractPnpmStoreArchives(SEED_ROOT, extractedStore)
+        const verified = verifyMacOSSeedStore(extractedStore, macOSSigning)
+        if (verified !== signedMachOFiles) {
+          throw new Error(`desktop seed: archived store contains ${verified} signed Mach-O files; expected ${signedMachOFiles}`)
+        }
+      } finally {
+        rmSync(extractedStore, { recursive: true, force: true })
+      }
+    }
+    const records = inventory(SEED_ROOT).filter(entry => entry.path !== 'integrity.json')
+    writeFileSync(join(SEED_ROOT, 'integrity.json'), `${JSON.stringify({ schemaVersion: 2, files: records }, undefined, 2)}\n`)
+    cpSync(SEED_ROOT, SEED_OUTPUT_ROOT, { recursive: true })
+  } finally {
+    rmSync(SEED_ROOT, { recursive: true, force: true })
+  }
+}
+
+await main()

apps/desktop/scripts/upload-target.ts

@@ -0,0 +1,83 @@
+/** Upload one validated Desktop release to its Tencent COS update directory. */
+
+import { createReadStream } from 'node:fs'
+import { stat } from 'node:fs/promises'
+import { resolve } from 'node:path'
+import { parseArgs } from 'node:util'
+import { PutObjectCommand, S3Client } from '@aws-sdk/client-s3'
+import type { DesktopPackageTargetName } from './package-target.ts'
+import {
+  createDesktopUploadPlan,
+  type DesktopUploadArtifact,
+} from './desktop-upload-plan.ts'
+
+const SUPPORTED_TARGETS = new Set<DesktopPackageTargetName>(['mac-arm64', 'mac-x64', 'win-x64'])
+
+function targetName(value: string): DesktopPackageTargetName {
+  if (!SUPPORTED_TARGETS.has(value as DesktopPackageTargetName)) {
+    throw new Error(`desktop upload: unsupported target ${JSON.stringify(value)}; expected ${[...SUPPORTED_TARGETS].join(', ')}`)
+  }
+  return value as DesktopPackageTargetName
+}
+
+function requiredEnvironmentValue(environment: NodeJS.ProcessEnv, name: string): string {
+  const value = environment[name]?.trim()
+  if (value === undefined || value === '') {
+    throw new Error(`desktop upload: ${name} must be set to a non-empty value`)
+  }
+  return value
+}
+
+async function putArtifact(
+  client: S3Client,
+  bucket: string,
+  artifact: DesktopUploadArtifact,
+): Promise<void> {
+  const details = await stat(artifact.path)
+  const body = createReadStream(artifact.path)
+  try {
+    await client.send(new PutObjectCommand({
+      Bucket: bucket,
+      Key: artifact.key,
+      Body: body,
+      ContentLength: details.size,
+      ContentType: artifact.contentType,
+      CacheControl: artifact.cacheControl,
+    }))
+  }
+  finally {
+    body.destroy()
+  }
+  process.stdout.write(`desktop upload: uploaded ${artifact.key}\n`)
+}
+
+async function main(): Promise<void> {
+  const { positionals } = parseArgs({ args: process.argv.slice(2), allowPositionals: true })
+  const target = positionals[0]
+  if (target === undefined || positionals.length !== 1) {
+    throw new Error('desktop upload: expected exactly one target')
+  }
+  const plan = await createDesktopUploadPlan(targetName(target))
+  const client = new S3Client({
+    region: 'Auto',
+    endpoint: 'https://cos.ap-beijing.myqcloud.com',
+    credentials: {
+      accessKeyId: requiredEnvironmentValue(process.env, plan.secretIdEnvName),
+      secretAccessKey: requiredEnvironmentValue(process.env, plan.secretKeyEnvName),
+    },
+  })
+  process.stdout.write(`desktop upload: ${plan.target} ${plan.version} -> ${plan.publicUrl}\n`)
+  try {
+    for (const artifact of plan.artifacts) await putArtifact(client, plan.bucket, artifact)
+  }
+  finally {
+    client.destroy()
+  }
+}
+
+if (process.argv[1] !== undefined && import.meta.filename === resolve(process.argv[1])) {
+  main().catch((error: unknown) => {
+    process.stderr.write(`${error instanceof Error ? error.stack ?? error.message : String(error)}\n`)
+    process.exitCode = 1
+  })
+}

apps/desktop/scripts/verify-macos-signature.d.mts

@@ -0,0 +1,73 @@
+import type { MacOSSigningEnvironment } from './desktop-release-environment.mjs'
+
+/**
+ * Reject signature metadata that does not name the company release authority and team.
+ * @param details - Output from `codesign --display --verbose=4`.
+ * @param expected - Public release identity.
+ */
+export function assertMacOSSignatureDetails(details: string, expected: MacOSSigningEnvironment): void
+
+/**
+ * Require the signature properties Apple validates for executable seed content.
+ * @param details - Output from `codesign --display --verbose=4`.
+ * @param expected - Public release identity.
+ */
+export function assertMacOSSeedSignatureDetails(details: string, expected: MacOSSigningEnvironment): void
+
+/**
+ * Sign one Mach-O file embedded in the seed store.
+ * @param path - Writable standalone Mach-O file.
+ * @param identifier - Stable code-signing identifier derived from the release app ID and CAS digest.
+ * @param expected - Public release identity.
+ * @returns Resolves after codesign exits successfully.
+ */
+export function signMacOSSeedCode(
+  path: string,
+  identifier: string,
+  expected: MacOSSigningEnvironment,
+): Promise<void>
+
+/**
+ * Verify one Mach-O file embedded in the seed store.
+ * @param path - Mach-O file to inspect.
+ * @param expected - Public release identity.
+ */
+export function verifyMacOSSeedCode(path: string, expected: MacOSSigningEnvironment): void
+
+/**
+ * Verify the full application signature and its release owner.
+ * @param appPath - Path to the packaged `.app` directory.
+ * @param expected - Public release identity.
+ */
+export function verifyMacOSSignature(appPath: string, expected: MacOSSigningEnvironment): void
+
+/**
+ * Verify the release identity, stapled ticket, and Gatekeeper acceptance of one disk image.
+ * @param diskImagePath - Path to the packaged `.dmg` file.
+ * @param expected - Public release identity.
+ */
+export function verifyMacOSDiskImage(
+  diskImagePath: string,
+  expected: MacOSSigningEnvironment,
+): void
+
+/** Electron-builder fields required to locate a signed macOS application. */
+export interface MacOSAfterSignContext {
+  readonly electronPlatformName: string
+  readonly appOutDir: string
+  readonly packager: {
+    readonly appInfo: {
+      readonly productFilename: string
+    }
+  }
+}
+
+/**
+ * Verify the macOS application produced by electron-builder's signing phase.
+ * @param context - electron-builder hook context.
+ * @param expected - Public release identity.
+ */
+export function verifyMacOSSignatureAfterSign(
+  context: MacOSAfterSignContext,
+  expected: MacOSSigningEnvironment,
+): void

apps/desktop/scripts/verify-macos-signature.mjs

@@ -0,0 +1,186 @@
+/** Sign seed code and verify that packaged macOS artifacts carry the company release identity. */
+
+import { spawn, spawnSync } from 'node:child_process'
+import { resolve } from 'node:path'
+import { resolveMacOSSigningEnvironment } from './desktop-release-environment.mjs'
+
+/**
+ * Reject signature metadata that does not name the company release authority and team.
+ * @param {string} details - Output from `codesign --display --verbose=4`.
+ * @param {{ signingIdentity: string, teamId: string }} expected - Public release identity.
+ * @returns {void}
+ */
+export function assertMacOSSignatureDetails(details, expected) {
+  const fields = new Set(details.split(/\r?\n/u).map(line => line.trim()))
+  const expectedAuthority = `Authority=Developer ID Application: ${expected.signingIdentity}`
+  const expectedTeam = `TeamIdentifier=${expected.teamId}`
+  const missing = [expectedAuthority, expectedTeam].filter(field => !fields.has(field))
+  if (missing.length > 0) {
+    throw new Error(`desktop macOS signing: signature does not match the release identity; missing ${missing.join(', ')}`)
+  }
+}
+
+/**
+ * Require the signature properties Apple validates for executable seed content.
+ * @param {string} details - Output from `codesign --display --verbose=4`.
+ * @param {{ signingIdentity: string, teamId: string }} expected - Public release identity.
+ * @returns {void}
+ */
+export function assertMacOSSeedSignatureDetails(details, expected) {
+  assertMacOSSignatureDetails(details, expected)
+  const fields = details.split(/\r?\n/u).map(line => line.trim())
+  if (!fields.some(line => /^Timestamp=.+/u.test(line))) {
+    throw new Error('desktop macOS signing: seed signature has no secure timestamp')
+  }
+  if (!fields.some(line => /\bflags=0x[0-9a-f]+\(runtime\)(?:\s|$)/iu.test(line))) {
+    throw new Error('desktop macOS signing: seed signature does not enable hardened runtime')
+  }
+}
+
+/**
+ * Execute one Apple release tool and return its diagnostic streams.
+ * @param {string} command - Absolute executable path.
+ * @param {readonly string[]} args - Tool arguments.
+ * @param {string} label - Stable diagnostic name.
+ * @returns {string} Combined stdout and stderr.
+ */
+function runAppleCommand(command, args, label) {
+  const result = spawnSync(command, args, { encoding: 'utf8' })
+  if (result.error !== undefined) {
+    throw new Error(`desktop macOS signing: could not execute ${label}: ${result.error.message}`)
+  }
+  if (result.signal !== null) {
+    throw new Error(`desktop macOS signing: ${label} was terminated by ${result.signal}`)
+  }
+  if (result.status !== 0) {
+    const diagnostic = `${result.stdout}${result.stderr}`.trim()
+    throw new Error(`desktop macOS signing: ${label} exited with ${String(result.status)}${diagnostic === '' ? '' : `: ${diagnostic}`}`)
+  }
+  return `${result.stdout}${result.stderr}`
+}
+
+/**
+ * Execute one Apple release tool without blocking other independent seed signers.
+ * @param {string} command - Absolute executable path.
+ * @param {readonly string[]} args - Tool arguments.
+ * @param {string} label - Stable diagnostic name.
+ * @returns {Promise<string>} Combined stdout and stderr after process exit.
+ */
+function runAppleCommandAsync(command, args, label) {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(command, args, { stdio: ['ignore', 'pipe', 'pipe'] })
+    let stdout = ''
+    let stderr = ''
+    let spawnError
+    child.stdout.setEncoding('utf8')
+    child.stderr.setEncoding('utf8')
+    child.stdout.on('data', chunk => { stdout += chunk })
+    child.stderr.on('data', chunk => { stderr += chunk })
+    child.once('error', error => { spawnError = error })
+    child.once('close', (code, signal) => {
+      if (spawnError !== undefined) {
+        reject(new Error(`desktop macOS signing: could not execute ${label}: ${spawnError.message}`))
+        return
+      }
+      if (signal !== null) {
+        reject(new Error(`desktop macOS signing: ${label} was terminated by ${signal}`))
+        return
+      }
+      if (code !== 0) {
+        const diagnostic = `${stdout}${stderr}`.trim()
+        reject(new Error(`desktop macOS signing: ${label} exited with ${String(code)}${diagnostic === '' ? '' : `: ${diagnostic}`}`))
+        return
+      }
+      resolvePromise(`${stdout}${stderr}`)
+    })
+  })
+}
+
+/**
+ * Execute Apple's code-signing tool and return its diagnostic streams.
+ * @param {readonly string[]} args - Arguments passed to `/usr/bin/codesign`.
+ * @returns {string} Combined stdout and stderr.
+ */
+function runCodeSign(args) {
+  return runAppleCommand('/usr/bin/codesign', args, 'codesign')
+}
+
+/**
+ * Sign one Mach-O file embedded in the seed store.
+ * @param {string} path - Writable standalone Mach-O file.
+ * @param {string} identifier - Stable code-signing identifier derived from the release app ID and CAS digest.
+ * @param {{ signingIdentity: string, teamId: string }} expected - Public release identity.
+ * @returns {Promise<void>} Resolves after codesign exits successfully.
+ */
+export async function signMacOSSeedCode(path, identifier, expected) {
+  await runAppleCommandAsync('/usr/bin/codesign', [
+    '--force',
+    '--sign', expected.signingIdentity,
+    '--identifier', identifier,
+    '--timestamp',
+    '--options', 'runtime',
+    path,
+  ], 'codesign')
+}
+
+/**
+ * Verify one Mach-O file embedded in the seed store.
+ * @param {string} path - Mach-O file to inspect.
+ * @param {{ signingIdentity: string, teamId: string }} expected - Public release identity.
+ * @returns {void}
+ */
+export function verifyMacOSSeedCode(path, expected) {
+  runCodeSign(['--verify', '--strict', '--verbose=2', path])
+  const details = runCodeSign(['--display', '--verbose=4', path])
+  assertMacOSSeedSignatureDetails(details, expected)
+}
+
+/**
+ * Verify the full application signature and its release owner.
+ * @param {string} appPath - Path to the packaged `.app` directory.
+ * @param {{ signingIdentity: string, teamId: string }} expected - Public release identity.
+ * @returns {void}
+ */
+export function verifyMacOSSignature(appPath, expected) {
+  runCodeSign(['--verify', '--deep', '--strict', '--verbose=2', appPath])
+  const details = runCodeSign(['--display', '--verbose=4', appPath])
+  assertMacOSSignatureDetails(details, expected)
+}
+
+/**
+ * Verify the release identity, stapled ticket, and Gatekeeper acceptance of one disk image.
+ * @param {string} diskImagePath - Path to the packaged `.dmg` file.
+ * @param {{ signingIdentity: string, teamId: string }} expected - Public release identity.
+ * @returns {void}
+ */
+export function verifyMacOSDiskImage(diskImagePath, expected) {
+  runCodeSign(['--verify', '--strict', '--verbose=2', diskImagePath])
+  const details = runCodeSign(['--display', '--verbose=4', diskImagePath])
+  assertMacOSSignatureDetails(details, expected)
+  runAppleCommand('/usr/bin/xcrun', ['stapler', 'validate', diskImagePath], 'stapler validate')
+  runAppleCommand('/usr/sbin/spctl', ['--assess', '--type', 'install', '--verbose=4', diskImagePath], 'spctl')
+}
+
+/**
+ * Verify the macOS application produced by electron-builder's signing phase.
+ * @param {{ electronPlatformName: string, appOutDir: string, packager: { appInfo: { productFilename: string } } }} context - electron-builder hook context.
+ * @param {{ signingIdentity: string, teamId: string }} expected - Public release identity.
+ * @returns {void}
+ */
+export function verifyMacOSSignatureAfterSign(context, expected) {
+  if (context.electronPlatformName !== 'darwin') return
+  const appPath = resolve(context.appOutDir, `${context.packager.appInfo.productFilename}.app`)
+  verifyMacOSSignature(appPath, expected)
+  process.stdout.write(`desktop macOS signing: verified Developer ID Application: ${expected.signingIdentity} (${expected.teamId})\n`)
+}
+
+if (process.argv[1] !== undefined && import.meta.filename === resolve(process.argv[1])) {
+  const cliArgs = process.argv[2] === '--' ? process.argv.slice(3) : process.argv.slice(2)
+  const appPath = cliArgs[0]
+  if (appPath === undefined || cliArgs.length !== 1) {
+    throw new Error('usage: node scripts/verify-macos-signature.mjs <path-to-app>')
+  }
+  const expected = resolveMacOSSigningEnvironment(process.env)
+  verifyMacOSSignature(resolve(appPath), expected)
+  process.stdout.write(`desktop macOS signing: verified Developer ID Application: ${expected.signingIdentity} (${expected.teamId})\n`)
+}

apps/desktop/scripts/windows-sign.cmd

@@ -0,0 +1,17 @@
+@echo off
+setlocal DisableDelayedExpansion
+set "signTool=%DSH_DESKTOP_WINDOWS_SIGNTOOL%"
+set "certificateFile=%DSH_DESKTOP_WINDOWS_CER_FILE%"
+set "tokenPin=%DSH_DESKTOP_WINDOWS_TOKEN_PIN%"
+set "keyContainer=%DSH_DESKTOP_WINDOWS_KEY_CONTAINER%"
+set "targetFile=%DSH_DESKTOP_WINDOWS_SIGN_TARGET%"
+set "appendSignature="
+if "%DSH_DESKTOP_WINDOWS_SIGN_APPEND%"=="1" set "appendSignature=/as"
+set "DSH_DESKTOP_WINDOWS_SIGNTOOL="
+set "DSH_DESKTOP_WINDOWS_CER_FILE="
+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%"
+exit /b %errorlevel%

apps/desktop/scripts/windows-sign.d.mts

@@ -0,0 +1,91 @@
+/**
+ * Build the minimal CMD environment for one Electron artifact.
+ *
+ * @param environment Parent environment.
+ * @param input Validated signing identity and task.
+ * @returns Scrubbed environment plus the fields consumed and cleared by the signing CMD.
+ */
+export function buildWindowsSigningEnvironment(environment: NodeJS.ProcessEnv, input: {
+  certificateFile: string
+  signTool: string
+  path: string
+  isNest: boolean
+  tokenPin: string
+  keyContainer: string
+}): NodeJS.ProcessEnv
+
+/**
+ * Create the electron-builder hook for a hardware-backed Windows code-signing certificate.
+ *
+ * @param options Release signing configuration.
+ * @returns The signing hook.
+ */
+export function createWindowsTokenSigner(options: {
+  certificateFile?: string | undefined
+  signTool?: string | undefined
+  tokenPin?: string | undefined
+  keyContainer?: string | undefined
+  commandInterpreter?: string | undefined
+}): (
+  configuration: {
+    path: string
+    hash: string
+    isNest: boolean
+  },
+) => Promise<void>
+
+/**
+ * Remove inherited credentials before starting a signing-related subprocess.
+ *
+ * @param environment Parent environment.
+ * @returns Environment without credential-shaped names.
+ */
+export function scrubWindowsSigningEnvironment(environment: NodeJS.ProcessEnv): NodeJS.ProcessEnv
+
+/**
+ * Replace a SignTool failure with a diagnostic that cannot retain its command line.
+ *
+ * @param error SignTool process failure.
+ * @param path Artifact that failed signing.
+ * @param secrets Values that must not appear in the diagnostic.
+ * @returns Sanitized signing failure without the original error as its cause.
+ */
+export function createRedactedWindowsSigningError(
+  error: unknown,
+  path: string,
+  secrets: readonly string[],
+): Error
+
+/**
+ * Clear a certificate-table entry that points beyond the end of a generated executable.
+ *
+ * @param path Executable to inspect.
+ * @returns Whether an invalid certificate-table entry was cleared.
+ */
+export function repairDanglingAuthenticodeDirectory(path: string): Promise<boolean>
+
+/**
+ * Sign electron-builder's temporary NSIS executable before enterprise code integrity evaluates it.
+ *
+ * @param options Signing hook and injectable host values.
+ * @returns Nothing.
+ */
+export function installWindowsNsisBootstrapSigner(options: {
+  sign: (configuration: {
+    path: string
+    hash: string
+    isNest: boolean
+  }) => Promise<void>
+  wineVmManager?: {
+    prototype: {
+      exec: (
+        file: string,
+        args: string[],
+        options?: { env?: NodeJS.ProcessEnv },
+        isLogOutIfDebug?: boolean,
+      ) => unknown
+    }
+  }
+  platform?: NodeJS.Platform
+  environment?: NodeJS.ProcessEnv
+}): void

apps/desktop/scripts/windows-sign.mjs

@@ -0,0 +1,266 @@
+import { execFile } from 'node:child_process'
+import { X509Certificate } from 'node:crypto'
+import { readFileSync, realpathSync, statSync } from 'node:fs'
+import { open } from 'node:fs/promises'
+import { dirname, join } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import { promisify } from 'node:util'
+import wineVmModule from 'app-builder-lib/out/vm/WineVm.js'
+
+const execFileAsync = promisify(execFile)
+const { WineVmManager } = wineVmModule
+const CODE_SIGNING_EKU = '1.3.6.1.5.5.7.3.3'
+const NSIS_RUN_AS_INVOKER = 'RunAsInvoker'
+const NSIS_BOOTSTRAP_PATCH = Symbol.for('@deepseek-ai/dsh-desktop/nsis-bootstrap-signing')
+const WINDOWS_SIGN_SCRIPT = 'windows-sign.cmd'
+const WINDOWS_SIGN_SCRIPT_DIRECTORY = dirname(fileURLToPath(import.meta.url))
+const PE_HEADER_READ_SIZE = 4096
+const PE32_MAGIC = 0x10B
+const PE32_PLUS_MAGIC = 0x20B
+const SENSITIVE_ENVIRONMENT_NAME = /(?:KEY|SECRET|TOKEN|PASSWORD)/iu
+const WINDOWS_SIGNING_ENVIRONMENT_PREFIX = 'DSH_DESKTOP_WINDOWS_'
+
+/**
+ * Remove inherited credentials before starting a signing-related subprocess.
+ *
+ * @param {NodeJS.ProcessEnv} environment Parent environment.
+ * @returns {NodeJS.ProcessEnv} Environment without credential-shaped names.
+ */
+export function scrubWindowsSigningEnvironment(environment) {
+  return Object.fromEntries(Object.entries(environment)
+    .filter(([name]) => !SENSITIVE_ENVIRONMENT_NAME.test(name)
+      && !name.startsWith(WINDOWS_SIGNING_ENVIRONMENT_PREFIX)))
+}
+
+function resolveTokenIdentity(input) {
+  const keyContainer = input.keyContainer?.trim()
+  if (!keyContainer) {
+    throw new Error('DSH_DESKTOP_WINDOWS_KEY_CONTAINER must contain the SafeNet private-key container name')
+  }
+  if (/["\r\n]/u.test(keyContainer)) {
+    throw new Error('DSH_DESKTOP_WINDOWS_KEY_CONTAINER cannot contain quotes or line breaks')
+  }
+  const tokenPin = input.tokenPin
+  if (tokenPin === undefined || tokenPin.length === 0) {
+    throw new Error('DSH_DESKTOP_WINDOWS_TOKEN_PIN must contain the SafeNet Token Password')
+  }
+  if (/[\]"\r\n]/u.test(tokenPin)) {
+    throw new Error('DSH_DESKTOP_WINDOWS_TOKEN_PIN cannot contain "]", quotes, or line breaks because the SafeNet key-container syntax uses them as delimiters')
+  }
+  return { keyContainer, tokenPin }
+}
+
+function resolveCertificateFile(value) {
+  const candidate = value?.trim()
+  if (!candidate) {
+    throw new Error('DSH_DESKTOP_WINDOWS_CER_FILE must identify the public X.509 leaf certificate file')
+  }
+  let path
+  let certificate
+  try {
+    path = realpathSync(candidate)
+    certificate = new X509Certificate(readFileSync(path))
+  }
+  catch {
+    throw new Error(`Windows code-signing certificate file is missing or invalid: ${candidate}`)
+  }
+  if (certificate.ca || !certificate.keyUsage?.includes(CODE_SIGNING_EKU)) {
+    throw new Error(`Windows code-signing certificate file must contain a non-CA Code Signing certificate: ${path}`)
+  }
+  return path
+}
+
+function resolveSignTool(value) {
+  const candidate = value?.trim()
+  if (!candidate) {
+    throw new Error('DSH_DESKTOP_WINDOWS_SIGNTOOL must identify the SafeNet-compatible SignTool executable')
+  }
+  let path
+  try {
+    path = realpathSync(candidate)
+    if (!statSync(path).isFile() || !path.toLowerCase().endsWith('.exe')) throw new Error('not an executable file')
+  }
+  catch {
+    throw new Error(`DSH_DESKTOP_WINDOWS_SIGNTOOL is missing or is not an executable file: ${candidate}`)
+  }
+  return path
+}
+
+function redactedSigningOutput(value, secrets) {
+  let output = Buffer.isBuffer(value) ? value.toString('utf8') : typeof value === 'string' ? value : ''
+  for (const secret of secrets) {
+    if (secret !== '') output = output.replaceAll(secret, '<redacted>')
+  }
+  return output
+}
+
+/**
+ * Replace a SignTool failure with a diagnostic that cannot retain its command line.
+ *
+ * @param {unknown} error SignTool process failure.
+ * @param {string} path Artifact that failed signing.
+ * @param {readonly string[]} secrets Values that must not appear in the diagnostic.
+ * @returns {Error} Sanitized signing failure without the original error as its cause.
+ */
+export function createRedactedWindowsSigningError(error, path, secrets) {
+  const record = error !== null && typeof error === 'object' ? error : undefined
+  const code = record !== undefined && 'code' in record
+    && (typeof record.code === 'number' || typeof record.code === 'string')
+    ? ` (exit ${String(record.code)})`
+    : ''
+  const stderr = record !== undefined && 'stderr' in record
+    ? redactedSigningOutput(record.stderr, secrets).trim()
+    : ''
+  return new Error(`Windows release signing failed for ${path}${code}${stderr === '' ? '' : `: ${stderr}`}`)
+}
+
+/**
+ * Build the minimal CMD environment for one Electron artifact.
+ *
+ * @param {NodeJS.ProcessEnv} environment Parent environment.
+ * @param {{ certificateFile: string, signTool: string, path: string, isNest: boolean, tokenPin: string, keyContainer: string }} input Validated signing identity and task.
+ * @returns {NodeJS.ProcessEnv} Scrubbed environment plus fields consumed and cleared by the signing CMD.
+ */
+export function buildWindowsSigningEnvironment(environment, input) {
+  return {
+    ...scrubWindowsSigningEnvironment(environment),
+    DSH_DESKTOP_WINDOWS_SIGNTOOL: input.signTool,
+    DSH_DESKTOP_WINDOWS_CER_FILE: input.certificateFile,
+    DSH_DESKTOP_WINDOWS_TOKEN_PIN: input.tokenPin,
+    DSH_DESKTOP_WINDOWS_KEY_CONTAINER: input.keyContainer,
+    DSH_DESKTOP_WINDOWS_SIGN_TARGET: input.path,
+    DSH_DESKTOP_WINDOWS_SIGN_APPEND: input.isNest ? '1' : '',
+  }
+}
+
+/**
+ * Create the electron-builder hook for a SafeNet-backed Windows code-signing certificate.
+ *
+ * @param {{ certificateFile?: string, signTool?: string, tokenPin?: string, keyContainer?: string, commandInterpreter?: string }} options Release signing configuration.
+ * @returns {(configuration: { path: string, hash: string, isNest: boolean }) => Promise<void>} The signing hook.
+ */
+export function createWindowsTokenSigner(options) {
+  const certificateFile = resolveCertificateFile(options.certificateFile)
+  const signTool = resolveSignTool(options.signTool)
+  const { keyContainer, tokenPin } = resolveTokenIdentity(options)
+  const commandInterpreter = options.commandInterpreter
+    ?? process.env.ComSpec
+    ?? join(process.env.SystemRoot ?? 'C:\\Windows', 'System32', 'cmd.exe')
+  return async (configuration) => {
+    if (configuration.hash !== 'sha256') {
+      throw new Error(`Windows release signing requires SHA-256, received ${configuration.hash}`)
+    }
+    await repairDanglingAuthenticodeDirectory(configuration.path)
+    const secrets = [tokenPin]
+    let result
+    try {
+      result = await 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: false,
+      })
+    }
+    catch (error) {
+      throw createRedactedWindowsSigningError(error, configuration.path, secrets)
+    }
+    const stdout = redactedSigningOutput(result.stdout, secrets)
+    const stderr = redactedSigningOutput(result.stderr, secrets)
+    if (stdout !== '') process.stdout.write(stdout)
+    if (stderr !== '') process.stderr.write(stderr)
+  }
+}
+
+/**
+ * Clear a certificate-table entry that points beyond the end of a generated executable.
+ *
+ * @param {string} path Executable to inspect.
+ * @returns {Promise<boolean>} Whether an invalid certificate-table entry was cleared.
+ */
+export async function repairDanglingAuthenticodeDirectory(path) {
+  const file = await open(path, 'r+')
+  try {
+    const { size } = await file.stat()
+    const header = Buffer.alloc(Math.min(PE_HEADER_READ_SIZE, size))
+    await file.read(header, 0, header.length, 0)
+    const directoryOffset = findDanglingAuthenticodeDirectory(header, size)
+    if (directoryOffset === undefined) return false
+    await file.write(Buffer.alloc(8), 0, 8, directoryOffset)
+    return true
+  }
+  finally {
+    await file.close()
+  }
+}
+
+/**
+ * Locate an Authenticode certificate-table entry whose declared bytes are outside the file.
+ *
+ * @param {Buffer} header Initial executable bytes.
+ * @param {number} fileSize Complete file size.
+ * @returns {number | undefined} File offset of the invalid data-directory entry.
+ */
+function findDanglingAuthenticodeDirectory(header, fileSize) {
+  if (header.length < 64 || header.toString('ascii', 0, 2) !== 'MZ') return undefined
+  const peOffset = header.readUInt32LE(60)
+  const optionalHeaderOffset = peOffset + 24
+  if (optionalHeaderOffset + 2 > header.length
+    || header.toString('ascii', peOffset, peOffset + 4) !== 'PE\0\0') return undefined
+  const magic = header.readUInt16LE(optionalHeaderOffset)
+  const dataDirectoryOffset = magic === PE32_MAGIC
+    ? optionalHeaderOffset + 96
+    : magic === PE32_PLUS_MAGIC
+      ? optionalHeaderOffset + 112
+      : undefined
+  if (dataDirectoryOffset === undefined) return undefined
+  const certificateDirectoryOffset = dataDirectoryOffset + (4 * 8)
+  if (certificateDirectoryOffset + 8 > header.length) return undefined
+  const certificateOffset = header.readUInt32LE(certificateDirectoryOffset)
+  const certificateSize = header.readUInt32LE(certificateDirectoryOffset + 4)
+  if (certificateOffset === 0 && certificateSize === 0) return undefined
+  return certificateOffset > 0
+    && certificateSize > 0
+    && certificateOffset + certificateSize <= fileSize
+    ? undefined
+    : certificateDirectoryOffset
+}
+
+/**
+ * Sign electron-builder's temporary NSIS executable before enterprise code integrity evaluates it.
+ *
+ * @param {{ sign: (configuration: { path: string, hash: string, isNest: boolean }) => Promise<void>, wineVmManager?: typeof WineVmManager, platform?: NodeJS.Platform, environment?: NodeJS.ProcessEnv }} options Signing hook and injectable host values.
+ * @returns {void}
+ */
+export function installWindowsNsisBootstrapSigner(options) {
+  if ((options.platform ?? process.platform) !== 'win32') return
+  const prototype = (options.wineVmManager ?? WineVmManager).prototype
+  if (prototype[NSIS_BOOTSTRAP_PATCH] === true) return
+  const originalExec = prototype.exec
+  prototype.exec = async function (file, args, execOptions, isLogOutIfDebug) {
+    const isNsisBootstrap = file.toLowerCase().endsWith('.exe')
+      && execOptions?.env?.__COMPAT_LAYER === NSIS_RUN_AS_INVOKER
+    if (!isNsisBootstrap) {
+      return originalExec.call(this, file, args, execOptions, isLogOutIfDebug)
+    }
+    await options.sign({ path: file, hash: 'sha256', isNest: false })
+    return originalExec.call(this, file, args, {
+      ...execOptions,
+      env: scrubWindowsSigningEnvironment({
+        ...(options.environment ?? process.env),
+        ...execOptions.env,
+      }),
+    }, isLogOutIfDebug)
+  }
+  Object.defineProperty(prototype, NSIS_BOOTSTRAP_PATCH, { value: true })
+}

apps/desktop/src/core-package-set.ts

@@ -0,0 +1,183 @@
+/** Signed local npm package set that supplies the Desktop-owned dsh runtime and private Host. */
+
+import { createHash } from 'node:crypto'
+import { existsSync, lstatSync, readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+/** Descriptor copied beside every Desktop profile's local core tarballs. */
+export const DESKTOP_PACKAGE_SET_FILE = 'desktop-packages.json'
+
+/** Profile-relative directory containing immutable core npm tarballs. */
+export const DESKTOP_PACKAGES_DIR = 'desktop-packages'
+
+/** Private package installed beside dsh to boot the Desktop Host process. */
+export const DESKTOP_HOST_PACKAGE = '@deepseek-ai/dsh-desktop-host'
+
+/** Package-relative Desktop Host files required before a profile can boot. */
+export const DESKTOP_HOST_RUNTIME_FILES = [
+  'lib/index.js',
+  'config/desktop.cordis.patch.yml',
+] as const
+
+/** One immutable npm tarball in the Desktop core package set. */
+export interface DesktopCorePackageRecord {
+  readonly name: string
+  readonly version: string
+  readonly file: string
+  readonly bytes: number
+  readonly integrity: string
+}
+
+/** Complete union of the first-party package closures rooted at dsh and its private Desktop Host. */
+export interface DesktopCorePackageSet {
+  readonly schemaVersion: 1
+  readonly packages: readonly DesktopCorePackageRecord[]
+}
+
+const PACKAGE_NAME_PATTERN = /^(?:@[a-z0-9][a-z0-9._~-]*\/[a-z0-9][a-z0-9._~-]*|[a-z0-9][a-z0-9._~-]*)$/u
+const VERSION_PATTERN = /^[0-9A-Za-z][0-9A-Za-z.+_-]*$/u
+const FILE_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9._-]*\.tgz$/u
+const INTEGRITY_PATTERN = /^sha512-[A-Za-z0-9+/]+={0,2}$/u
+const DSH_PACKAGE = '@deepseek-ai/dsh'
+const RELEASE_PACKAGES = [DSH_PACKAGE, DESKTOP_HOST_PACKAGE] as const
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value)
+}
+
+/**
+ * Validate package-set data read from a release artifact or active profile.
+ * @param value - Parsed descriptor JSON.
+ * @param expectedReleaseVersion - Required dsh and Desktop Host version when validating one release.
+ * @returns The normalized package set in deterministic name order.
+ */
+export function parseDesktopCorePackageSet(
+  value: unknown,
+  expectedReleaseVersion?: string,
+): DesktopCorePackageSet {
+  if (!isRecord(value) || value.schemaVersion !== 1 || !Array.isArray(value.packages)) {
+    throw new Error('desktop package set: invalid descriptor')
+  }
+  const packages = value.packages.map((entry): DesktopCorePackageRecord => {
+    if (!isRecord(entry) || typeof entry.name !== 'string' || !PACKAGE_NAME_PATTERN.test(entry.name)
+      || typeof entry.version !== 'string' || !VERSION_PATTERN.test(entry.version)
+      || typeof entry.file !== 'string' || !FILE_PATTERN.test(entry.file)
+      || typeof entry.bytes !== 'number' || !Number.isSafeInteger(entry.bytes) || entry.bytes < 0
+      || typeof entry.integrity !== 'string' || !INTEGRITY_PATTERN.test(entry.integrity)) {
+      throw new Error('desktop package set: invalid package record')
+    }
+    return {
+      name: entry.name,
+      version: entry.version,
+      file: entry.file,
+      bytes: entry.bytes,
+      integrity: entry.integrity,
+    }
+  })
+  const names = new Set(packages.map(entry => entry.name))
+  const files = new Set(packages.map(entry => entry.file))
+  if (names.size !== packages.length || files.size !== packages.length) {
+    throw new Error('desktop package set: duplicate package name or filename')
+  }
+  const sorted = [...packages].sort((left, right) => left.name.localeCompare(right.name))
+  if (JSON.stringify(sorted) !== JSON.stringify(packages)) {
+    throw new Error('desktop package set: packages must be sorted by name')
+  }
+  for (const name of RELEASE_PACKAGES) {
+    const entry = packages.find(candidate => candidate.name === name)
+    if (entry === undefined) throw new Error(`desktop package set: missing ${name}`)
+    if (expectedReleaseVersion !== undefined && entry.version !== expectedReleaseVersion) {
+      throw new Error(`desktop package set: ${name}@${entry.version} does not match Desktop ${expectedReleaseVersion}`)
+    }
+  }
+  return { schemaVersion: 1, packages }
+}
+
+/** Read and structurally validate one profile's core package descriptor. */
+export function readDesktopCorePackageSet(projectDir: string, expectedReleaseVersion?: string): DesktopCorePackageSet {
+  const path = join(projectDir, DESKTOP_PACKAGE_SET_FILE)
+  let value: unknown
+  try {
+    value = JSON.parse(readFileSync(path, 'utf8'))
+  } catch (error) {
+    throw new Error(`desktop package set: failed to read ${path}: ${String(error)}`)
+  }
+  return parseDesktopCorePackageSet(value, expectedReleaseVersion)
+}
+
+/** Return the project-relative `file:` spec for one local core tarball. */
+export function desktopCorePackageSpec(record: DesktopCorePackageRecord): string {
+  return `file:./${DESKTOP_PACKAGES_DIR}/${record.file}`
+}
+
+/** Return the exact pnpm override map that keeps every core package off registries. */
+export function desktopCorePackageOverrides(packageSet: DesktopCorePackageSet): Record<string, string> {
+  return Object.fromEntries(packageSet.packages.map(record => [record.name, desktopCorePackageSpec(record)]))
+}
+
+/** Return the local direct dependency spec for the dsh package. */
+export function desktopDshPackageSpec(packageSet: DesktopCorePackageSet): string {
+  const record = packageSet.packages.find(entry => entry.name === DSH_PACKAGE)
+  if (record === undefined) throw new Error(`desktop package set: missing ${DSH_PACKAGE}`)
+  return desktopCorePackageSpec(record)
+}
+
+/**
+ * Verify every local tarball and reject extra package files before pnpm executes them.
+ * @param projectDir - Seed or profile directory containing the package set.
+ * @param expectedReleaseVersion - Exact dsh and Desktop Host version bound to Electron.
+ * @returns The verified package set.
+ */
+export function verifyDesktopCorePackageSet(
+  projectDir: string,
+  expectedReleaseVersion: string,
+): DesktopCorePackageSet {
+  const packageSet = readDesktopCorePackageSet(projectDir, expectedReleaseVersion)
+  const packageDir = join(projectDir, DESKTOP_PACKAGES_DIR)
+  const expectedFiles = packageSet.packages.map(entry => entry.file).sort()
+  let actualFiles: string[]
+  try {
+    actualFiles = readdirSync(packageDir).sort()
+  } catch (error) {
+    throw new Error(`desktop package set: failed to read ${packageDir}: ${String(error)}`)
+  }
+  if (JSON.stringify(actualFiles) !== JSON.stringify(expectedFiles)) {
+    throw new Error('desktop package set: package directory does not match its descriptor')
+  }
+  for (const record of packageSet.packages) {
+    const path = join(packageDir, record.file)
+    if (!existsSync(path) || !lstatSync(path).isFile()) {
+      throw new Error(`desktop package set: ${record.file} is not a regular file`)
+    }
+    const body = readFileSync(path)
+    const integrity = `sha512-${createHash('sha512').update(body).digest('base64')}`
+    if (body.byteLength !== record.bytes || integrity !== record.integrity) {
+      throw new Error(`desktop package set: integrity check failed for ${record.file}`)
+    }
+  }
+  return packageSet
+}
+
+function escapeRegExp(value: string): string {
+  return value.replace(/[.*+?^${}()|[\]\\]/gu, '\\$&')
+}
+
+/**
+ * Reject a lockfile that resolved any packaged core name through a registry version.
+ * @param lockfile - Generated pnpm lockfile text.
+ * @param packageSet - Verified local core package set.
+ */
+export function verifyDesktopCoreLockfile(
+  lockfile: string,
+  packageSet: DesktopCorePackageSet,
+): void {
+  for (const record of packageSet.packages) {
+    const registryResolution = new RegExp(
+      `^  ['"]?${escapeRegExp(record.name)}@${escapeRegExp(record.version)}(?:\\([^\\r\\n]*\\))?['"]?:`,
+      'mu',
+    )
+    if (registryResolution.test(lockfile)) {
+      throw new Error(`desktop package set: lockfile resolved ${record.name}@${record.version} outside the local package set`)
+    }
+  }
+}

apps/desktop/src/host-process.ts

@@ -0,0 +1,413 @@
+/** Upstream-Node child lifecycle and streaming custom-protocol carrier. */
+
+import { spawn, type ChildProcess } from 'node:child_process'
+import { once } from 'node:events'
+import { join } from 'node:path'
+import { Readable, Writable } from 'node:stream'
+import {
+  DESKTOP_HOST_PROTOCOL_VERSION,
+  DESKTOP_PIPE_CHUNK_BYTES,
+  DESKTOP_REQUEST_PIPE_FD,
+  DESKTOP_RESPONSE_PIPE_FD,
+  DesktopHostResponseDecoder,
+  encodeDesktopRequestCancel,
+  encodeDesktopRequestData,
+  encodeDesktopRequestEnd,
+  encodeDesktopRequestStart,
+  type DesktopHostCommand,
+  type DesktopHostEvent,
+  type DesktopHostResponseFrame,
+} from './host-protocol.ts'
+
+interface PendingResponse {
+  readonly resolve: (response: Response) => void
+  readonly reject: (error: Error) => void
+  responseStarted: boolean
+  uploadOpen: boolean
+  controller?: ReadableStreamDefaultController<Uint8Array>
+  requestReader?: ReadableStreamDefaultReader<Uint8Array>
+  removeAbort?: () => void
+}
+
+function isDesktopHostEvent(message: unknown): message is DesktopHostEvent {
+  if (typeof message !== 'object' || message === null || !('type' in message)) return false
+  const candidate = message as Record<string, unknown>
+  switch (candidate.type) {
+    case 'ready':
+      return candidate.protocolVersion === DESKTOP_HOST_PROTOCOL_VERSION && typeof candidate.dshVersion === 'string'
+    case 'fatal':
+      return typeof candidate.message === 'string'
+    default:
+      return false
+  }
+}
+
+function errorOf(reason: unknown, fallback: string): Error {
+  return reason instanceof Error ? reason : new Error(fallback)
+}
+
+async function exitsWithin(exit: Promise<void>, milliseconds: number): Promise<boolean> {
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const timeout = new Promise<false>((resolve) => {
+    timer = setTimeout(() => { resolve(false) }, milliseconds)
+    timer.unref()
+  })
+  try {
+    return await Promise.race([exit.then(() => true), timeout])
+  } finally {
+    if (timer !== undefined) clearTimeout(timer)
+  }
+}
+
+/** Ready facts reported by one installed dsh child. */
+export interface DesktopHostReady {
+  readonly protocolVersion: typeof DESKTOP_HOST_PROTOCOL_VERSION
+  readonly dshVersion: string
+}
+
+/** One dsh backend running under the bundled upstream Node.js executable. */
+export class DesktopHostProcess {
+  private child: ChildProcess | undefined
+  private requestPipe: Writable | undefined
+  private responsePipe: Readable | undefined
+  private readonly responseDecoder = new DesktopHostResponseDecoder()
+  private requestWriteTail: Promise<void> = Promise.resolve()
+  private nextStreamId = 1
+  private readonly pending = new Map<number, PendingResponse>()
+  private readonly blockedResponses = new Set<number>()
+  private readyResolve!: (ready: DesktopHostReady) => void
+  private readyReject!: (error: Error) => void
+  private readonly readyPromise = new Promise<DesktopHostReady>((resolve, reject) => {
+    this.readyResolve = resolve
+    this.readyReject = reject
+  })
+  private exitPromise: Promise<void> | undefined
+  private stderr = ''
+
+  /**
+   * @param node - absolute bundled upstream Node.js executable.
+   * @param projectDir - active or staged desktop npm project.
+   * @param inspectPort - optional loopback inspector port for workspace development.
+   */
+  constructor(
+    private readonly node: string,
+    private readonly projectDir: string,
+    private readonly inspectPort?: number,
+  ) {}
+
+  /** Start the child once and resolve only after its complete composition is active. */
+  async start(): Promise<DesktopHostReady> {
+    if (this.child !== undefined) return this.readyPromise
+    const entry = join(this.projectDir, 'node_modules', '@deepseek-ai', 'dsh-desktop-host', 'lib', 'index.js')
+    const child = spawn(this.node, [
+      ...(this.inspectPort === undefined ? [] : [`--inspect=127.0.0.1:${String(this.inspectPort)}`]),
+      entry,
+      this.projectDir,
+      ...(this.inspectPort === undefined ? [] : ['--allow-linked-profile']),
+    ], {
+      cwd: this.projectDir,
+      env: Object.fromEntries(Object.entries(process.env).filter(([name]) => (
+        name !== 'NODE_OPTIONS' && !/^DSH_DESKTOP_/u.test(name) && !/^(?:npm|pnpm|corepack)_/iu.test(name)
+      ))),
+      stdio: ['ignore', 'pipe', 'pipe', 'pipe', 'pipe', 'ipc'],
+    })
+    const requestPipe = child.stdio[DESKTOP_REQUEST_PIPE_FD]
+    const responsePipe = child.stdio[DESKTOP_RESPONSE_PIPE_FD]
+    if (!(requestPipe instanceof Writable) || !(responsePipe instanceof Readable)) {
+      child.kill('SIGTERM')
+      throw new Error('dsh desktop host did not expose the required byte pipes and IPC channel')
+    }
+    this.child = child
+    this.requestPipe = requestPipe
+    this.responsePipe = responsePipe
+    child.stderr?.setEncoding('utf8')
+    child.stderr?.on('data', (chunk: string) => { this.stderr += chunk })
+    child.stdout?.pipe(process.stdout)
+    responsePipe.on('data', (chunk: Buffer) => { this.acceptResponseBytes(chunk) })
+    responsePipe.once('end', () => {
+      try {
+        this.responseDecoder.finish()
+        this.fail(new Error('dsh desktop host response pipe ended'))
+      } catch (error) {
+        this.fail(errorOf(error, 'dsh desktop host response pipe failed'))
+      }
+    })
+    requestPipe.once('error', (error) => { this.fail(error) })
+    responsePipe.once('error', (error) => { this.fail(error) })
+    child.on('message', (message: unknown) => {
+      if (!isDesktopHostEvent(message)) {
+        this.fail(new Error('dsh desktop host sent an invalid IPC event'))
+        child.kill('SIGTERM')
+        return
+      }
+      this.handleMessage(message)
+    })
+    child.once('error', (error) => { this.fail(error) })
+    this.exitPromise = new Promise<void>((resolve) => {
+      child.once('exit', (code) => {
+        const suffix = this.stderr.trim() === '' ? '' : `: ${this.stderr.trim()}`
+        if (code !== 0 && code !== null) this.fail(new Error(`dsh desktop host exited with ${String(code)}${suffix}`))
+        else this.fail(new Error(`dsh desktop host stopped${suffix}`))
+        resolve()
+      })
+    })
+    return this.readyPromise
+  }
+
+  /** Forward one `dsh-app://app` request to the child without buffering its body. */
+  async fetch(request: Request): Promise<Response> {
+    await this.start()
+    const child = this.child
+    if (child === undefined || !child.connected || this.requestPipe === undefined) {
+      throw new Error('dsh desktop host is unavailable')
+    }
+    if (this.nextStreamId > 0xffff_ffff) throw new Error('dsh desktop host exhausted its request stream ids')
+    const streamId = this.nextStreamId++
+    const method = request.method.toUpperCase()
+    const hasBody = method !== 'GET' && method !== 'HEAD' && request.body !== null
+    return new Promise<Response>((resolve, reject) => {
+      const pending: PendingResponse = {
+        resolve,
+        reject,
+        responseStarted: false,
+        uploadOpen: hasBody,
+      }
+      const abort = (): void => {
+        if (!this.pending.has(streamId)) return
+        const error = errorOf(request.signal.reason, 'request aborted')
+        pending.uploadOpen = false
+        void pending.requestReader?.cancel(error).catch(() => undefined)
+        this.enqueueRequestFrame(encodeDesktopRequestCancel(streamId)).catch((pipeError: unknown) => {
+          this.fail(errorOf(pipeError, 'dsh desktop request pipe failed'))
+        })
+        if (pending.controller === undefined) pending.reject(error)
+        else pending.controller.error(error)
+        this.finishPending(streamId, false)
+      }
+      if (request.signal.aborted) {
+        reject(errorOf(request.signal.reason, 'request aborted'))
+        return
+      }
+      request.signal.addEventListener('abort', abort, { once: true })
+      pending.removeAbort = () => { request.signal.removeEventListener('abort', abort) }
+      this.pending.set(streamId, pending)
+      this.pumpRequest(streamId, request, hasBody).catch((error: unknown) => {
+        this.failPending(streamId, errorOf(error, 'dsh desktop request upload failed'))
+      })
+    })
+  }
+
+  /** Request graceful teardown, then wait for child exit. */
+  async stop(): Promise<void> {
+    const child = this.child
+    if (child === undefined) return
+    this.blockedResponses.clear()
+    this.responsePipe?.resume()
+    if (child.connected) this.send({ type: 'shutdown' })
+    // Closing the parent-owned write end releases the Host's pending Windows pipe read.
+    this.requestPipe?.destroy()
+    const exited = this.exitPromise ?? Promise.resolve()
+    if (!await exitsWithin(exited, 10_000)) child.kill('SIGTERM')
+    if (!await exitsWithin(exited, 5_000)) {
+      child.kill('SIGKILL')
+      if (!await exitsWithin(exited, 5_000)) {
+        throw new Error('dsh desktop host did not exit after SIGKILL')
+      }
+    }
+    this.child = undefined
+    this.requestPipe = undefined
+    this.responsePipe = undefined
+  }
+
+  private async pumpRequest(streamId: number, request: Request, hasBody: boolean): Promise<void> {
+    await this.enqueueRequestFrame(encodeDesktopRequestStart(streamId, {
+      url: request.url,
+      method: request.method.toUpperCase(),
+      headers: [...request.headers.entries()],
+      hasBody,
+    }))
+    if (!hasBody) return
+    const body = request.body
+    if (body === null) throw new Error('dsh desktop request body disappeared before upload')
+    const reader = body.getReader()
+    const pending = this.pending.get(streamId)
+    if (pending === undefined) {
+      await reader.cancel()
+      return
+    }
+    pending.requestReader = reader
+    try {
+      for (;;) {
+        const next = await reader.read()
+        if (next.done) break
+        for (let offset = 0; offset < next.value.byteLength; offset += DESKTOP_PIPE_CHUNK_BYTES) {
+          if (!this.pending.has(streamId)) return
+          await this.enqueueRequestFrame(encodeDesktopRequestData(
+            streamId,
+            next.value.subarray(offset, offset + DESKTOP_PIPE_CHUNK_BYTES),
+          ))
+        }
+      }
+      const live = this.pending.get(streamId)
+      if (live !== undefined) {
+        await this.enqueueRequestFrame(encodeDesktopRequestEnd(streamId))
+        live.uploadOpen = false
+      }
+    } finally {
+      reader.releaseLock()
+      const live = this.pending.get(streamId)
+      if (live?.requestReader === reader) delete live.requestReader
+    }
+  }
+
+  private enqueueRequestFrame(frame: Buffer): Promise<void> {
+    const write = this.requestWriteTail.then(async () => {
+      const pipe = this.requestPipe
+      if (pipe === undefined || pipe.destroyed) throw new Error('dsh desktop host request pipe is unavailable')
+      if (!pipe.write(frame)) await once(pipe, 'drain')
+    })
+    this.requestWriteTail = write.catch(() => undefined)
+    return write
+  }
+
+  private send(message: DesktopHostCommand): void {
+    const child = this.child
+    if (child === undefined || !child.connected) throw new Error('dsh desktop host IPC is unavailable')
+    child.send(message)
+  }
+
+  private acceptResponseBytes(chunk: Buffer): void {
+    try {
+      for (const frame of this.responseDecoder.push(chunk)) this.handleResponseFrame(frame)
+    } catch (error) {
+      this.fail(errorOf(error, 'dsh desktop host response pipe failed'))
+      this.child?.kill('SIGTERM')
+    }
+  }
+
+  private handleResponseFrame(frame: DesktopHostResponseFrame): void {
+    const pending = this.pending.get(frame.streamId)
+    if (pending === undefined) {
+      if (frame.streamId >= this.nextStreamId) {
+        throw new Error(`dsh desktop host responded for unknown stream ${String(frame.streamId)}`)
+      }
+      return
+    }
+    switch (frame.type) {
+      case 'start': {
+        if (pending.responseStarted) throw new Error(`dsh desktop host started stream ${String(frame.streamId)} twice`)
+        pending.responseStarted = true
+        let body: ReadableStream<Uint8Array> | null = null
+        if (frame.hasBody) {
+          body = new ReadableStream<Uint8Array>({
+            start: (controller) => { pending.controller = controller },
+            pull: () => {
+              this.blockedResponses.delete(frame.streamId)
+              this.resumeResponsePipe()
+            },
+            cancel: (reason) => { this.cancelResponse(frame.streamId, reason) },
+          })
+        }
+        pending.resolve(new Response(body, {
+          status: frame.status,
+          headers: new Headers(frame.headers.map(([name, value]) => [name, value] as [string, string])),
+        }))
+        return
+      }
+      case 'data': {
+        const controller = pending.controller
+        if (!pending.responseStarted || controller === undefined) {
+          throw new Error(`dsh desktop host sent body data before a body start for stream ${String(frame.streamId)}`)
+        }
+        controller.enqueue(frame.data)
+        if ((controller.desiredSize ?? 0) <= 0) {
+          this.blockedResponses.add(frame.streamId)
+          this.responsePipe?.pause()
+        }
+        return
+      }
+      case 'end':
+        if (!pending.responseStarted) {
+          throw new Error(`dsh desktop host ended stream ${String(frame.streamId)} before its response start`)
+        }
+        pending.controller?.close()
+        this.finishPending(frame.streamId, true)
+        return
+      case 'error':
+        this.failPending(frame.streamId, new Error(frame.message))
+        return
+      default:
+        frame satisfies never
+    }
+  }
+
+  private cancelResponse(streamId: number, reason: unknown): void {
+    const pending = this.pending.get(streamId)
+    if (pending === undefined) return
+    pending.uploadOpen = false
+    void pending.requestReader?.cancel(reason).catch(() => undefined)
+    this.enqueueRequestFrame(encodeDesktopRequestCancel(streamId)).catch((error: unknown) => {
+      this.fail(errorOf(error, 'dsh desktop request pipe failed'))
+    })
+    this.finishPending(streamId, false)
+  }
+
+  private failPending(streamId: number, error: Error): void {
+    const pending = this.pending.get(streamId)
+    if (pending === undefined) return
+    pending.uploadOpen = false
+    void pending.requestReader?.cancel(error).catch(() => undefined)
+    if (pending.controller === undefined) pending.reject(error)
+    else pending.controller.error(error)
+    this.enqueueRequestFrame(encodeDesktopRequestCancel(streamId)).catch((pipeError: unknown) => {
+      this.fail(errorOf(pipeError, 'dsh desktop request pipe failed'))
+    })
+    this.finishPending(streamId, false)
+  }
+
+  private finishPending(streamId: number, cancelOpenUpload: boolean): void {
+    const pending = this.pending.get(streamId)
+    if (pending === undefined) return
+    if (cancelOpenUpload && pending.uploadOpen) {
+      pending.uploadOpen = false
+      void pending.requestReader?.cancel().catch(() => undefined)
+      this.enqueueRequestFrame(encodeDesktopRequestCancel(streamId)).catch((error: unknown) => {
+        this.fail(errorOf(error, 'dsh desktop request pipe failed'))
+      })
+    }
+    pending.removeAbort?.()
+    this.pending.delete(streamId)
+    this.blockedResponses.delete(streamId)
+    this.resumeResponsePipe()
+  }
+
+  private resumeResponsePipe(): void {
+    if (this.blockedResponses.size === 0) this.responsePipe?.resume()
+  }
+
+  private handleMessage(message: DesktopHostEvent): void {
+    switch (message.type) {
+      case 'ready':
+        this.readyResolve(message)
+        return
+      case 'fatal':
+        this.fail(new Error(message.message))
+        return
+      default:
+        message satisfies never
+    }
+  }
+
+  private fail(error: Error): void {
+    this.readyReject(error)
+    for (const pending of this.pending.values()) {
+      void pending.requestReader?.cancel(error).catch(() => undefined)
+      if (pending.controller === undefined) pending.reject(error)
+      else pending.controller.error(error)
+      pending.removeAbort?.()
+    }
+    this.pending.clear()
+    this.blockedResponses.clear()
+    this.responsePipe?.resume()
+  }
+}

apps/desktop/src/host-protocol.ts

@@ -0,0 +1,215 @@
+/** Versioned control messages and framed byte transport for the Desktop Host child. */
+
+/** Protocol version implemented by the Electron shell and installed dsh Host. */
+export const DESKTOP_HOST_PROTOCOL_VERSION = 3 as const
+
+/** Child descriptor Electron writes request frames to. */
+export const DESKTOP_REQUEST_PIPE_FD = 3
+
+/** Child descriptor Electron reads response frames from. */
+export const DESKTOP_RESPONSE_PIPE_FD = 4
+
+/** Child descriptor reserved for Node's lifecycle IPC channel. */
+export const DESKTOP_CONTROL_IPC_FD = 5
+
+/** Maximum raw body bytes carried by one data frame. */
+export const DESKTOP_PIPE_CHUNK_BYTES = 64 * 1024
+
+const FRAME_MAGIC = 0x44534833
+const FRAME_HEADER_BYTES = 13
+const MAX_CONTROL_PAYLOAD_BYTES = 1024 * 1024
+
+const REQUEST_FRAME_START = 1
+const REQUEST_FRAME_DATA = 2
+const REQUEST_FRAME_END = 3
+const REQUEST_FRAME_CANCEL = 4
+type RequestFrameType = typeof REQUEST_FRAME_START | typeof REQUEST_FRAME_DATA
+  | typeof REQUEST_FRAME_END | typeof REQUEST_FRAME_CANCEL
+
+const RESPONSE_FRAME_START = 1
+const RESPONSE_FRAME_DATA = 2
+const RESPONSE_FRAME_END = 3
+const RESPONSE_FRAME_ERROR = 4
+
+/** Metadata that precedes one optional request body on the request pipe. */
+export interface DesktopHostRequestStart {
+  readonly url: string
+  readonly method: string
+  readonly headers: readonly [string, string][]
+  readonly hasBody: boolean
+}
+
+/** Commands retained on Node IPC because they do not carry Fetch payload bytes. */
+export type DesktopHostCommand = {
+  readonly type: 'shutdown'
+}
+
+/** Lifecycle events retained on Node IPC. */
+export type DesktopHostEvent = {
+  readonly type: 'ready'
+  readonly protocolVersion: typeof DESKTOP_HOST_PROTOCOL_VERSION
+  readonly dshVersion: string
+} | {
+  readonly type: 'fatal'
+  readonly message: string
+}
+
+/** One decoded response-pipe frame. */
+export type DesktopHostResponseFrame = {
+  readonly type: 'start'
+  readonly streamId: number
+  readonly status: number
+  readonly headers: readonly [string, string][]
+  readonly hasBody: boolean
+} | {
+  readonly type: 'data'
+  readonly streamId: number
+  readonly data: Buffer
+} | {
+  readonly type: 'end'
+  readonly streamId: number
+} | {
+  readonly type: 'error'
+  readonly streamId: number
+  readonly message: string
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function isHeaders(value: unknown): value is readonly [string, string][] {
+  return Array.isArray(value) && value.every(header => Array.isArray(header) && header.length === 2
+    && typeof header[0] === 'string' && typeof header[1] === 'string')
+}
+
+function assertStreamId(streamId: number): void {
+  if (!Number.isInteger(streamId) || streamId < 1 || streamId > 0xffff_ffff) {
+    throw new Error(`dsh desktop: invalid pipe stream id ${String(streamId)}`)
+  }
+}
+
+function encodeFrame(type: RequestFrameType, streamId: number, payload: Buffer): Buffer {
+  assertStreamId(streamId)
+  const limit = type === REQUEST_FRAME_DATA ? DESKTOP_PIPE_CHUNK_BYTES : MAX_CONTROL_PAYLOAD_BYTES
+  if (payload.byteLength > limit) {
+    throw new Error(`dsh desktop: request pipe frame exceeds the ${String(limit)}-byte limit`)
+  }
+  const frame = Buffer.allocUnsafe(FRAME_HEADER_BYTES + payload.byteLength)
+  frame.writeUInt32BE(FRAME_MAGIC, 0)
+  frame.writeUInt8(type, 4)
+  frame.writeUInt32BE(streamId, 5)
+  frame.writeUInt32BE(payload.byteLength, 9)
+  payload.copy(frame, FRAME_HEADER_BYTES)
+  return frame
+}
+
+function encodeJsonFrame(type: RequestFrameType, streamId: number, value: unknown): Buffer {
+  return encodeFrame(type, streamId, Buffer.from(JSON.stringify(value), 'utf8'))
+}
+
+/** Encode the metadata opening one request stream. */
+export function encodeDesktopRequestStart(streamId: number, request: DesktopHostRequestStart): Buffer {
+  return encodeJsonFrame(REQUEST_FRAME_START, streamId, request)
+}
+
+/** Encode one bounded raw request-body chunk. */
+export function encodeDesktopRequestData(streamId: number, data: Uint8Array): Buffer {
+  return encodeFrame(REQUEST_FRAME_DATA, streamId, Buffer.from(data))
+}
+
+/** Encode normal request-body completion. */
+export function encodeDesktopRequestEnd(streamId: number): Buffer {
+  return encodeFrame(REQUEST_FRAME_END, streamId, Buffer.alloc(0))
+}
+
+/** Encode cancellation of one request and its response. */
+export function encodeDesktopRequestCancel(streamId: number): Buffer {
+  return encodeFrame(REQUEST_FRAME_CANCEL, streamId, Buffer.alloc(0))
+}
+
+/** Incrementally decode validated response frames from the Host byte pipe. */
+export class DesktopHostResponseDecoder {
+  private buffer: Buffer = Buffer.alloc(0)
+
+  /**
+   * Append bytes and return every complete response frame.
+   * @param chunk - next bytes read from the Host response pipe.
+   * @returns complete frames in pipe order.
+   */
+  push(chunk: Buffer): DesktopHostResponseFrame[] {
+    this.buffer = this.buffer.byteLength === 0 ? chunk : Buffer.concat([this.buffer, chunk])
+    const frames: DesktopHostResponseFrame[] = []
+    for (;;) {
+      const frame = this.next()
+      if (frame === undefined) return frames
+      frames.push(frame)
+    }
+  }
+
+  /** Reject EOF that splits a frame. */
+  finish(): void {
+    if (this.buffer.byteLength !== 0) throw new Error('dsh desktop: Host response pipe ended inside a frame')
+  }
+
+  private next(): DesktopHostResponseFrame | undefined {
+    if (this.buffer.byteLength < FRAME_HEADER_BYTES) return undefined
+    if (this.buffer.readUInt32BE(0) !== FRAME_MAGIC) throw new Error('dsh desktop: invalid Host response frame marker')
+    const rawType = this.buffer.readUInt8(4)
+    const streamId = this.buffer.readUInt32BE(5)
+    const payloadLength = this.buffer.readUInt32BE(9)
+    assertStreamId(streamId)
+    const limit = rawType === RESPONSE_FRAME_DATA ? DESKTOP_PIPE_CHUNK_BYTES : MAX_CONTROL_PAYLOAD_BYTES
+    if (payloadLength > limit) {
+      throw new Error(`dsh desktop: Host response frame exceeds the ${String(limit)}-byte limit`)
+    }
+    const frameLength = FRAME_HEADER_BYTES + payloadLength
+    if (this.buffer.byteLength < frameLength) return undefined
+    const payload = this.buffer.subarray(FRAME_HEADER_BYTES, frameLength)
+    this.buffer = this.buffer.subarray(frameLength)
+    switch (rawType) {
+      case RESPONSE_FRAME_START:
+        return this.parseStart(streamId, payload)
+      case RESPONSE_FRAME_DATA:
+        return { type: 'data', streamId, data: payload }
+      case RESPONSE_FRAME_END:
+        if (payloadLength !== 0) throw new Error('dsh desktop: Host response end frame carried a payload')
+        return { type: 'end', streamId }
+      case RESPONSE_FRAME_ERROR:
+        return this.parseError(streamId, payload)
+      default:
+        throw new Error(`dsh desktop: unknown Host response frame type ${String(rawType)}`)
+    }
+  }
+
+  private parseStart(streamId: number, payload: Buffer): DesktopHostResponseFrame {
+    const value = this.parseJson(payload, 'start')
+    if (!isRecord(value) || !Number.isInteger(value.status) || (value.status as number) < 100
+      || (value.status as number) > 599 || !isHeaders(value.headers) || typeof value.hasBody !== 'boolean') {
+      throw new Error('dsh desktop: invalid Host response start payload')
+    }
+    return {
+      type: 'start',
+      streamId,
+      status: value.status as number,
+      headers: value.headers,
+      hasBody: value.hasBody,
+    }
+  }
+
+  private parseError(streamId: number, payload: Buffer): DesktopHostResponseFrame {
+    const value = this.parseJson(payload, 'error')
+    if (!isRecord(value) || typeof value.message !== 'string') {
+      throw new Error('dsh desktop: invalid Host response error payload')
+    }
+    return { type: 'error', streamId, message: value.message }
+  }
+
+  private parseJson(payload: Buffer, subject: string): unknown {
+    try {
+      return JSON.parse(payload.toString('utf8')) as unknown
+    } catch (error) {
+      throw new Error(`dsh desktop: Host response ${subject} payload is not JSON: ${error instanceof Error ? error.message : String(error)}`)
+    }
+  }
+}

apps/desktop/src/ipc.ts

@@ -0,0 +1,40 @@
+/** Typed preload operations exposed only by the Electron shell. */
+
+import type { DesktopPluginRecord } from './project-manager.ts'
+import type { DesktopLocale } from './locale.ts'
+
+/** IPC channel names kept private to the desktop application bundle. */
+export const DESKTOP_IPC = {
+  localeGet: 'dsh-desktop:locale-get',
+  pluginsList: 'dsh-desktop:plugins-list',
+  pluginsAdd: 'dsh-desktop:plugins-add',
+  pluginsRemove: 'dsh-desktop:plugins-remove',
+  pluginsUpdate: 'dsh-desktop:plugins-update',
+  updatesCheck: 'dsh-desktop:updates-check',
+  updatesInstall: 'dsh-desktop:updates-install',
+  updatesState: 'dsh-desktop:updates-state',
+} as const
+
+/** Desktop release update state rendered by desktop-owned UI. */
+export interface DesktopUpdateState {
+  readonly phase: 'idle' | 'checking' | 'available' | 'installing' | 'ready' | 'error'
+  readonly version?: string
+  readonly message?: string
+}
+
+/** Narrow bridge exposed through context isolation. */
+export interface DshDesktopApi {
+  readonly protocolVersion: 1
+  locale(): Promise<DesktopLocale>
+  readonly plugins: {
+    list(): Promise<readonly DesktopPluginRecord[]>
+    add(spec: string): Promise<void>
+    remove(name: string): Promise<void>
+    update(name: string, version: string): Promise<void>
+  }
+  readonly updates: {
+    check(): Promise<DesktopUpdateState>
+    install(): Promise<void>
+    subscribe(listener: (state: DesktopUpdateState) => void): () => void
+  }
+}

apps/desktop/src/locale.ts

@@ -0,0 +1,97 @@
+/** Typed English and Chinese copy owned by the Electron shell. */
+
+export const en = {
+  application: 'Application',
+  startupFailed: 'DeepSeek Harness could not start',
+  pluginsMenu: 'Desktop Plugins…',
+  pluginsMenuPackagedOnly: 'Desktop Plugins… (available in packaged applications)',
+  checkUpdatesMenu: 'Check for Updates…',
+  updateCheckFailedTitle: 'Update Check Failed',
+  unknownError: 'Unknown error',
+  updateCheckTitle: 'Check for Updates',
+  updateCurrent: 'You already have the latest version.',
+  updateTitle: 'DeepSeek Harness Update',
+  updateAvailable: 'An update is available',
+  updateDetail: 'DeepSeek Harness {version}\n\nThis release includes its matching dsh version. The application will restart after installation.',
+  installAndRestart: 'Install and Restart',
+  later: 'Later',
+  updateFailedTitle: 'Update Failed',
+  pluginManagerTitle: 'Desktop Plugins',
+  pluginWindowTitle: 'DeepSeek Harness — Desktop Plugins',
+  pluginManagerDescription: 'Plugins are installed only in the Desktop node_modules and are managed by the bundled pnpm.',
+  refresh: 'Refresh',
+  npmPackage: 'npm package',
+  install: 'Install',
+  installed: 'Installed',
+  noPlugins: 'No Desktop plugins are installed.',
+  remove: 'Remove',
+  update: 'Update',
+  targetVersion: 'Enter the target version for {name}',
+  removing: 'Removing {name}…',
+  updating: 'Updating {name}…',
+  installing: 'Installing {spec}…',
+  operationComplete: 'Done. The Desktop backend has restarted.',
+  refreshing: 'Refreshing…',
+  refreshed: 'Plugin list refreshed.',
+  loadingPlugins: 'Reading Desktop plugins…',
+} as const
+
+/** Every Desktop locale supplies the complete English key set. */
+export type DesktopMessages = { readonly [Key in keyof typeof en]: string }
+
+export const zh = {
+  application: '应用',
+  startupFailed: 'DeepSeek Harness 无法启动',
+  pluginsMenu: '桌面插件…',
+  pluginsMenuPackagedOnly: '桌面插件…（打包应用中可用）',
+  checkUpdatesMenu: '检查更新…',
+  updateCheckFailedTitle: '更新检查失败',
+  unknownError: '未知错误',
+  updateCheckTitle: '检查更新',
+  updateCurrent: '当前已是最新版本。',
+  updateTitle: 'DeepSeek Harness 更新',
+  updateAvailable: '发现可用更新',
+  updateDetail: 'DeepSeek Harness {version}\n\n新版本绑定匹配的 dsh，安装后将重新启动。',
+  installAndRestart: '安装并重启',
+  later: '稍后',
+  updateFailedTitle: '更新失败',
+  pluginManagerTitle: '桌面插件',
+  pluginWindowTitle: 'DeepSeek Harness — 桌面插件',
+  pluginManagerDescription: '插件只安装到桌面端自己的 node_modules，并由内置 pnpm 管理。',
+  refresh: '刷新',
+  npmPackage: 'npm 包',
+  install: '安装',
+  installed: '已安装',
+  noPlugins: '还没有安装桌面插件。',
+  remove: '移除',
+  update: '更新',
+  targetVersion: '输入 {name} 的目标版本',
+  removing: '正在移除 {name}…',
+  updating: '正在更新 {name}…',
+  installing: '正在安装 {spec}…',
+  operationComplete: '操作完成，桌面后端已重新启动。',
+  refreshing: '正在刷新…',
+  refreshed: '插件列表已刷新。',
+  loadingPlugins: '正在读取桌面插件…',
+} as const satisfies DesktopMessages
+
+/** Locale payload exposed to the Desktop-owned renderer. */
+export interface DesktopLocale {
+  readonly id: 'en' | 'zh-CN'
+  readonly messages: DesktopMessages
+}
+
+/** Resolve Electron's locale to one shipped Desktop dictionary. */
+export function resolveDesktopLocale(locale: string): DesktopLocale {
+  return locale.toLowerCase().startsWith('zh')
+    ? { id: 'zh-CN', messages: zh }
+    : { id: 'en', messages: en }
+}
+
+/** Replace named placeholders in one locale-owned message. */
+export function formatDesktopMessage(
+  message: string,
+  values: Readonly<Record<string, string>>,
+): string {
+  return message.replaceAll(/\{([^{}]+)\}/gu, (placeholder, key: string) => values[key] ?? placeholder)
+}

apps/desktop/src/main.ts

@@ -0,0 +1,397 @@
+/** Electron shell: desktop project ownership, custom protocol, windows, and lifecycle. */
+
+import { readFile, writeFile } from 'node:fs/promises'
+import { extname, join, normalize, resolve, sep } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+  app,
+  BrowserWindow,
+  dialog,
+  ipcMain,
+  Menu,
+  protocol,
+  type IpcMainInvokeEvent,
+} from 'electron'
+import { resolveDesktopPaths } from './paths.ts'
+import { DesktopProjectManager, type DesktopProjectHooks } from './project-manager.ts'
+import { DesktopHostProcess } from './host-process.ts'
+import { DESKTOP_IPC, type DesktopUpdateState } from './ipc.ts'
+import { formatDesktopMessage, resolveDesktopLocale } from './locale.ts'
+import { claimDesktopSingleInstance } from './single-instance.ts'
+import { DesktopUpdateCoordinator } from './update-coordinator.ts'
+
+const SCHEME = 'dsh-app'
+let focusPrimaryWindow = (): void => {}
+
+function errorOf(reason: unknown, fallback: string): Error {
+  return reason instanceof Error ? reason : new Error(fallback)
+}
+
+protocol.registerSchemesAsPrivileged([{
+  scheme: SCHEME,
+  privileges: {
+    standard: true,
+    secure: true,
+    supportFetchAPI: true,
+    corsEnabled: false,
+    stream: true,
+    codeCache: true,
+  },
+}])
+
+const MIME: Readonly<Record<string, string>> = {
+  '.css': 'text/css; charset=utf-8',
+  '.html': 'text/html; charset=utf-8',
+  '.js': 'text/javascript; charset=utf-8',
+  '.svg': 'image/svg+xml',
+}
+
+interface RuntimeResources {
+  readonly node: string
+  readonly pnpm: string
+  readonly seed: string
+}
+
+function runtimeResources(): RuntimeResources {
+  const development = !app.isPackaged
+  const node = (development ? process.env.DSH_DESKTOP_NODE_BINARY : undefined)
+    ?? join(process.resourcesPath, 'runtime', 'node', process.platform === 'win32' ? 'node.exe' : 'node')
+  const pnpm = (development ? process.env.DSH_DESKTOP_PNPM_ENTRY : undefined)
+    ?? join(process.resourcesPath, 'runtime', 'pnpm', 'bin', 'pnpm.mjs')
+  const seed = (development ? process.env.DSH_DESKTOP_SEED_DIR : undefined) ?? join(process.resourcesPath, 'seed')
+  return { node, pnpm, seed }
+}
+
+function developmentProject(): string | undefined {
+  const configured = process.env.DSH_DESKTOP_DEV_PROJECT_DIR
+  if (configured === undefined || configured === '') return undefined
+  if (app.isPackaged) throw new Error('dsh desktop: development project override is unavailable in packaged applications')
+  return resolve(configured)
+}
+
+function developmentHostInspectPort(enabled: boolean): number | undefined {
+  const configured = process.env.DSH_DESKTOP_HOST_INSPECT_PORT
+  if (!enabled || configured === undefined || configured === '') return undefined
+  const port = Number(configured)
+  if (!Number.isSafeInteger(port) || port < 1 || port > 65_535) {
+    throw new Error('dsh desktop: DSH_DESKTOP_HOST_INSPECT_PORT must be an integer from 1 through 65535')
+  }
+  return port
+}
+
+function createWindow(preload: string): BrowserWindow {
+  const window = new BrowserWindow({
+    width: 1280,
+    height: 840,
+    minWidth: 880,
+    minHeight: 600,
+    show: false,
+    webPreferences: {
+      preload,
+      nodeIntegration: false,
+      contextIsolation: true,
+      sandbox: true,
+      webSecurity: true,
+    },
+  })
+  window.webContents.setWindowOpenHandler(() => ({ action: 'deny' }))
+  window.webContents.on('will-navigate', (event, url) => {
+    if (new URL(url).protocol !== `${SCHEME}:`) event.preventDefault()
+  })
+  return window
+}
+
+function assertDesktopSender(event: IpcMainInvokeEvent, hostnames: readonly string[]): void {
+  const senderFrame = event.senderFrame
+  if (senderFrame === null) throw new Error('dsh desktop: rejected IPC without a sender frame')
+  const url = new URL(senderFrame.url)
+  if (url.protocol !== `${SCHEME}:` || !hostnames.includes(url.hostname)) {
+    throw new Error('dsh desktop: rejected IPC from an unowned renderer')
+  }
+}
+
+async function serveShellAsset(request: Request): Promise<Response> {
+  if (request.method !== 'GET' && request.method !== 'HEAD') return new Response(null, { status: 405 })
+  const root = resolve(app.getAppPath(), 'renderer')
+  const url = new URL(request.url)
+  let pathname: string
+  try {
+    pathname = decodeURIComponent(url.pathname)
+  } catch {
+    return new Response(null, { status: 400 })
+  }
+  const target = resolve(normalize(join(root, pathname)))
+  if (target !== root && !target.startsWith(root + sep)) return new Response(null, { status: 403 })
+  try {
+    const body = request.method === 'HEAD' ? null : await readFile(target)
+    return new Response(body, { headers: { 'content-type': MIME[extname(target)] ?? 'application/octet-stream' } })
+  } catch {
+    return new Response(null, { status: 404 })
+  }
+}
+
+async function main(): Promise<void> {
+  const resources = runtimeResources()
+  const paths = resolveDesktopPaths()
+  const development = developmentProject()
+  const activeProject = development ?? paths.profile
+  const hostInspectPort = developmentHostInspectPort(development !== undefined)
+  const manager = new DesktopProjectManager(paths, resources)
+  if (development === undefined) manager.recover()
+  let host: DesktopHostProcess | undefined
+  let mainWindow: BrowserWindow | undefined
+  let pluginWindow: BrowserWindow | undefined
+  let shellInstallerOwnsQuit = false
+  let updateState: DesktopUpdateState = { phase: 'idle' }
+  const locale = resolveDesktopLocale(app.getLocale())
+  const messages = locale.messages
+  const appPreload = fileURLToPath(new URL('./preload-app.cjs', import.meta.url))
+  const managementPreload = fileURLToPath(new URL('./preload.cjs', import.meta.url))
+
+  const publishUpdate = (state: DesktopUpdateState): DesktopUpdateState => {
+    updateState = state
+    for (const window of BrowserWindow.getAllWindows()) {
+      window.webContents.send(DESKTOP_IPC.updatesState, state)
+    }
+    return state
+  }
+
+  const startHost = async (projectDir = activeProject): Promise<DesktopHostProcess> => {
+    const next = new DesktopHostProcess(resources.node, projectDir, hostInspectPort)
+    await next.start()
+    return next
+  }
+  const hooks: DesktopProjectHooks = {
+    healthCheck: async (projectDir) => {
+      const active = host
+      host = undefined
+      await active?.stop()
+      let healthFailure: unknown
+      let probe: DesktopHostProcess | undefined
+      try {
+        probe = await startHost(projectDir)
+        await probe.stop()
+      } catch (error) {
+        healthFailure = error
+        await probe?.stop().catch(() => undefined)
+      }
+      let restartFailure: unknown
+      if (active !== undefined) {
+        try {
+          host = await startHost()
+        } catch (error) {
+          restartFailure = error
+        }
+      }
+      if (healthFailure !== undefined && restartFailure !== undefined) {
+        throw new AggregateError([
+          errorOf(healthFailure, 'desktop project: staged health check failed'),
+          errorOf(restartFailure, 'desktop project: active backend restart failed'),
+        ], 'desktop project: staged health check and active backend restart failed')
+      }
+      if (healthFailure !== undefined) throw errorOf(healthFailure, 'desktop project: staged health check failed')
+      if (restartFailure !== undefined) throw errorOf(restartFailure, 'desktop project: active backend restart failed')
+    },
+    beforeActivate: async () => {
+      const active = host
+      host = undefined
+      await active?.stop()
+    },
+    afterActivate: async () => {
+      host = await startHost()
+    },
+  }
+
+  if (development === undefined) {
+    await manager.applyRelease(resources.seed, app.getVersion(), {
+      ...hooks,
+      beforeActivate: async () => {},
+      afterActivate: async () => {},
+    })
+  }
+  host = await startHost()
+
+  const updates = new DesktopUpdateCoordinator(
+    publishUpdate,
+    async () => {
+      shellInstallerOwnsQuit = true
+      const active = host
+      host = undefined
+      await active?.stop()
+    },
+  )
+
+  protocol.handle(SCHEME, (request) => {
+    const url = new URL(request.url)
+    if (url.hostname === 'shell') return serveShellAsset(request)
+    if (url.hostname !== 'app') return Promise.resolve(new Response(null, { status: 404 }))
+    const active = host
+    if (active === undefined) return Promise.resolve(new Response('backend unavailable', { status: 503 }))
+    return active.fetch(request)
+  })
+
+  const mutate = async (event: IpcMainInvokeEvent, mutation: Parameters<DesktopProjectManager['mutate']>[0]): Promise<void> => {
+    assertDesktopSender(event, ['shell'])
+    if (development !== undefined) {
+      throw new Error('dsh desktop: plugin package changes require a packaged application')
+    }
+    await manager.mutate(mutation, hooks)
+    if (mainWindow !== undefined && !mainWindow.isDestroyed()) mainWindow.webContents.reload()
+  }
+  ipcMain.handle(DESKTOP_IPC.localeGet, (event) => {
+    assertDesktopSender(event, ['shell'])
+    return locale
+  })
+  ipcMain.handle(DESKTOP_IPC.pluginsList, (event) => {
+    assertDesktopSender(event, ['shell'])
+    if (development !== undefined) return []
+    return manager.listPlugins()
+  })
+  ipcMain.handle(DESKTOP_IPC.pluginsAdd, (event, spec: unknown) => {
+    if (typeof spec !== 'string') throw new Error('dsh desktop: plugin spec must be a string')
+    return mutate(event, { type: 'plugin-add', spec })
+  })
+  ipcMain.handle(DESKTOP_IPC.pluginsRemove, (event, name: unknown) => {
+    if (typeof name !== 'string') throw new Error('dsh desktop: plugin name must be a string')
+    return mutate(event, { type: 'plugin-remove', name })
+  })
+  ipcMain.handle(DESKTOP_IPC.pluginsUpdate, (event, name: unknown, version: unknown) => {
+    if (typeof name !== 'string' || typeof version !== 'string') {
+      throw new Error('dsh desktop: plugin name and version must be strings')
+    }
+    return mutate(event, { type: 'plugin-update', name, version })
+  })
+  ipcMain.handle(DESKTOP_IPC.updatesCheck, async (event) => {
+    assertDesktopSender(event, ['shell'])
+    return updates.check()
+  })
+  ipcMain.handle(DESKTOP_IPC.updatesInstall, async (event) => {
+    assertDesktopSender(event, ['shell'])
+    await updates.install()
+  })
+
+  const checkAndPrompt = async (manual: boolean): Promise<void> => {
+    const state = await updates.check()
+    if (state.phase === 'error') {
+      if (manual) {
+        await dialog.showMessageBox({
+          type: 'error',
+          title: messages.updateCheckFailedTitle,
+          message: state.message ?? messages.unknownError,
+        })
+      }
+      return
+    }
+    if (state.phase !== 'available') {
+      if (manual) {
+        await dialog.showMessageBox({
+          type: 'info',
+          title: messages.updateCheckTitle,
+          message: state.message ?? messages.updateCurrent,
+        })
+      }
+      return
+    }
+    const result = await dialog.showMessageBox({
+      type: 'info',
+      title: messages.updateTitle,
+      message: messages.updateAvailable,
+      detail: formatDesktopMessage(messages.updateDetail, { version: state.version ?? '' }),
+      buttons: [messages.installAndRestart, messages.later],
+      defaultId: 0,
+      cancelId: 1,
+    })
+    if (result.response !== 0) return
+    const installed = await updates.install()
+    if (installed.phase === 'error') {
+      await dialog.showMessageBox({
+        type: 'error',
+        title: messages.updateFailedTitle,
+        message: installed.message ?? messages.unknownError,
+      })
+    }
+  }
+
+  const openPluginWindow = (): void => {
+    if (pluginWindow !== undefined && !pluginWindow.isDestroyed()) {
+      pluginWindow.focus()
+      return
+    }
+    pluginWindow = createWindow(managementPreload)
+    pluginWindow.setSize(900, 620)
+    pluginWindow.setTitle(messages.pluginWindowTitle)
+    pluginWindow.once('ready-to-show', () => { pluginWindow?.show() })
+    pluginWindow.once('closed', () => { pluginWindow = undefined })
+    void pluginWindow.loadURL(`${SCHEME}://shell/plugin-manager.html`)
+  }
+
+  Menu.setApplicationMenu(Menu.buildFromTemplate([{
+    label: process.platform === 'darwin' ? app.name : messages.application,
+    submenu: [
+      {
+        label: development === undefined ? messages.pluginsMenu : messages.pluginsMenuPackagedOnly,
+        accelerator: 'CmdOrCtrl+,',
+        enabled: development === undefined,
+        click: openPluginWindow,
+      },
+      { label: messages.checkUpdatesMenu, click: () => { void checkAndPrompt(true) } },
+      { type: 'separator' },
+      { role: 'quit' },
+    ],
+  }]))
+
+  const createMainWindow = (): BrowserWindow => {
+    const window = createWindow(appPreload)
+    mainWindow = window
+    window.once('ready-to-show', () => { if (!window.isDestroyed()) window.show() })
+    window.on('closed', () => { if (mainWindow === window) mainWindow = undefined })
+    return window
+  }
+  focusPrimaryWindow = () => {
+    const window = mainWindow
+    if (window === undefined || window.isDestroyed()) {
+      const replacement = createMainWindow()
+      void replacement.loadURL(`${SCHEME}://app/index.html`)
+      return
+    }
+    if (window.isMinimized()) window.restore()
+    window.show()
+    window.focus()
+  }
+
+  mainWindow = createMainWindow()
+  await mainWindow.loadURL(`${SCHEME}://app/index.html`)
+  if (development !== undefined && process.env.DSH_DESKTOP_OPEN_DEVTOOLS !== '0') {
+    mainWindow.webContents.openDevTools({ mode: 'detach' })
+  }
+  publishUpdate(updateState)
+  setTimeout(() => { void checkAndPrompt(false) }, 10_000)
+
+  app.on('activate', () => {
+    if (BrowserWindow.getAllWindows().length === 0) focusPrimaryWindow()
+  })
+  app.on('window-all-closed', () => {
+    if (process.platform !== 'darwin') app.quit()
+  })
+  app.on('before-quit', (event) => {
+    if (shellInstallerOwnsQuit) return
+    if (host === undefined) return
+    event.preventDefault()
+    const active = host
+    host = undefined
+    void active.stop().finally(() => { app.quit() })
+  })
+}
+
+const ownsDesktopInstance = claimDesktopSingleInstance(app, () => { focusPrimaryWindow() })
+
+if (ownsDesktopInstance) void app.whenReady().then(main).catch(async (error: unknown) => {
+  const message = error instanceof Error ? error.message : String(error)
+  console.error(error)
+  const diagnosticFile = process.env.DSH_DESKTOP_DIAGNOSTIC_FILE
+  if (diagnosticFile !== undefined) {
+    await writeFile(diagnosticFile, `${error instanceof Error ? error.stack ?? message : message}\n`).catch(() => undefined)
+  }
+  dialog.showErrorBox(resolveDesktopLocale(app.getLocale()).messages.startupFailed, message)
+  app.exit(1)
+})

apps/desktop/src/paths.ts

@@ -0,0 +1,48 @@
+/** Filesystem ownership for the Electron-managed desktop installation. */
+
+import { join } from 'node:path'
+import { resolveDshHome } from '@deepseek-ai/dsh-home-paths'
+
+/** Stable desktop installation paths under the shared Harness home. */
+export interface DesktopPaths {
+  readonly root: string
+  readonly profile: string
+  readonly staging: string
+  readonly rollback: string
+  readonly pending: string
+  readonly lock: string
+  readonly pnpm: {
+    readonly root: string
+    readonly store: string
+    readonly cache: string
+    readonly state: string
+    readonly config: string
+    readonly home: string
+  }
+}
+
+/**
+ * Resolve every Electron-owned path without changing the shared data roots.
+ * @param dshHome - Harness home shared with npm-installed dsh.
+ * @returns immutable desktop path set.
+ */
+export function resolveDesktopPaths(dshHome: string = resolveDshHome()): DesktopPaths {
+  const root = join(dshHome, 'desktop')
+  const pnpm = join(root, 'pnpm')
+  return {
+    root,
+    profile: join(dshHome, 'profiles', 'desktop'),
+    staging: join(root, 'staging'),
+    rollback: join(root, 'rollback', 'profile'),
+    pending: join(root, 'pending.json'),
+    lock: join(root, 'lock'),
+    pnpm: {
+      root: pnpm,
+      store: join(pnpm, 'store'),
+      cache: join(pnpm, 'cache'),
+      state: join(pnpm, 'state'),
+      config: join(pnpm, 'config'),
+      home: join(pnpm, 'home'),
+    },
+  }
+}

apps/desktop/src/preload-app.ts

@@ -0,0 +1,5 @@
+/** Minimal marker that selects the desktop custom-protocol API carrier. */
+
+import { contextBridge } from 'electron'
+
+contextBridge.exposeInMainWorld('dshDesktop', { protocolVersion: 1 })

apps/desktop/src/preload.ts

@@ -0,0 +1,26 @@
+/** Context-isolated renderer bridge for desktop package and update operations. */
+
+import { contextBridge, ipcRenderer } from 'electron'
+import { DESKTOP_IPC, type DshDesktopApi, type DesktopUpdateState } from './ipc.ts'
+
+const api: DshDesktopApi = {
+  protocolVersion: 1,
+  locale: () => ipcRenderer.invoke(DESKTOP_IPC.localeGet) as Promise<ReturnType<DshDesktopApi['locale']> extends Promise<infer T> ? T : never>,
+  plugins: {
+    list: () => ipcRenderer.invoke(DESKTOP_IPC.pluginsList) as Promise<ReturnType<DshDesktopApi['plugins']['list']> extends Promise<infer T> ? T : never>,
+    add: spec => ipcRenderer.invoke(DESKTOP_IPC.pluginsAdd, spec) as Promise<void>,
+    remove: name => ipcRenderer.invoke(DESKTOP_IPC.pluginsRemove, name) as Promise<void>,
+    update: (name, version) => ipcRenderer.invoke(DESKTOP_IPC.pluginsUpdate, name, version) as Promise<void>,
+  },
+  updates: {
+    check: () => ipcRenderer.invoke(DESKTOP_IPC.updatesCheck) as Promise<DesktopUpdateState>,
+    install: () => ipcRenderer.invoke(DESKTOP_IPC.updatesInstall) as Promise<void>,
+    subscribe(listener) {
+      const handle = (_event: Electron.IpcRendererEvent, state: DesktopUpdateState): void => { listener(state) }
+      ipcRenderer.on(DESKTOP_IPC.updatesState, handle)
+      return () => { ipcRenderer.off(DESKTOP_IPC.updatesState, handle) }
+    },
+  },
+}
+
+contextBridge.exposeInMainWorld('dshDesktop', api)

apps/desktop/src/project-manager.ts

@@ -0,0 +1,725 @@
+/** Transactional owner of the reserved desktop profile and its private pnpm state. */
+
+import { spawn } from 'node:child_process'
+import { createHash, randomUUID } from 'node:crypto'
+import {
+  constants,
+  copyFileSync,
+  cpSync,
+  existsSync,
+  fsyncSync,
+  ftruncateSync,
+  lstatSync,
+  mkdirSync,
+  openSync,
+  closeSync,
+  readdirSync,
+  readFileSync,
+  renameSync,
+  rmSync,
+  unlinkSync,
+  writeFileSync,
+  writeSync,
+} from 'node:fs'
+import { basename, delimiter, dirname, isAbsolute, join, relative, resolve, sep } from 'node:path'
+import {
+  DESKTOP_PACKAGES_DIR,
+  DESKTOP_PACKAGE_SET_FILE,
+  DESKTOP_HOST_PACKAGE,
+  desktopCorePackageOverrides,
+  desktopDshPackageSpec,
+  readDesktopCorePackageSet,
+  verifyDesktopCorePackageSet,
+} from './core-package-set.ts'
+import type { DesktopPaths } from './paths.ts'
+import { parseDesktopRelease, type DesktopRelease } from './release.ts'
+import { extractPnpmStoreArchives, mergePnpmStore } from './seed-store.ts'
+
+/** Files the package transaction copies between active and staging projects. */
+const DESKTOP_PROJECT_FILES = [
+  'package.json',
+  'pnpm-lock.yaml',
+  'pnpm-workspace.yaml',
+  'desktop-release.json',
+  DESKTOP_PACKAGE_SET_FILE,
+] as const
+
+/** Desktop plugin record derived from the installed profile. */
+export interface DesktopPluginRecord {
+  readonly name: string
+  readonly version: string
+}
+
+/** Installed desktop project manifest slice. */
+interface DesktopProjectManifest {
+  readonly name: string
+  readonly private: true
+  readonly version: string
+  readonly dependencies: Record<string, string>
+  readonly dsh: {
+    readonly profile: {
+      readonly bundles: string[]
+    }
+  }
+}
+
+/** Journaled activation step used for crash recovery. */
+interface DesktopPendingTransaction {
+  readonly schemaVersion: 1
+  readonly id: string
+  readonly stagingProfile: string
+  readonly step: 'prepared' | 'active-moved' | 'staging-activated'
+}
+
+/** Exact executables the desktop shell bundles. */
+export interface DesktopRuntimeExecutables {
+  readonly node: string
+  readonly pnpm: string
+}
+
+/** Hooks that bind project replacement to backend lifecycle and health. */
+export interface DesktopProjectHooks {
+  /** Prove the staged dependency graph while the active backend is stopped. */
+  healthCheck(projectDir: string): Promise<void>
+  /** Stop the active backend and await process exit before directory moves. */
+  beforeActivate(): Promise<void>
+  /** Start the selected active project after commit or rollback. */
+  afterActivate(): Promise<void>
+}
+
+/** Supported dependency mutation. */
+export type DesktopProjectMutation =
+  | { readonly type: 'plugin-add'; readonly spec: string }
+  | { readonly type: 'plugin-remove'; readonly name: string }
+  | { readonly type: 'plugin-update'; readonly name: string; readonly version: string }
+
+interface DesktopSeedIntegrityRecord {
+  readonly path: string
+  readonly bytes: number
+  readonly sha256: string
+}
+
+const PROJECT_NAME = '@deepseek-ai/dsh-desktop-runtime'
+const DSH_PACKAGE = '@deepseek-ai/dsh'
+const CORE_BUILD_PACKAGE = '@deepseek-ai/dsh-subprocess-local'
+const DESKTOP_PROFILE_BUNDLES = ['@deepseek-ai/dsh-base', '@deepseek-ai/dsh-web-app'] as const
+const WORKSPACE_SETTINGS = 'nodeLinker: hoisted\nautoInstallPeers: false\nstrictDepBuilds: true\n'
+const PACKAGE_NAME_PATTERN = /^(?:@[a-z0-9][a-z0-9._~-]*\/[a-z0-9][a-z0-9._~-]*|[a-z0-9][a-z0-9._~-]*)$/u
+const VERSION_PATTERN = /^[0-9A-Za-z][0-9A-Za-z.+_-]*$/u
+const MAX_PNPM_DIAGNOSTIC_BYTES = 64 * 1024
+const DESKTOP_REGISTRY = 'https://registry.npmjs.org/'
+
+function errorOf(reason: unknown, fallback: string): Error {
+  return reason instanceof Error ? reason : new Error(fallback)
+}
+
+function writeJson(path: string, value: unknown): void {
+  writeFileSync(path, `${JSON.stringify(value, undefined, 2)}\n`, { mode: 0o600 })
+}
+
+function readJson(path: string): unknown {
+  return JSON.parse(readFileSync(path, 'utf8'))
+}
+
+function workspaceFile(overrides: Readonly<Record<string, string>> = {}): string {
+  const entries = Object.entries(overrides).sort(([left], [right]) => left.localeCompare(right))
+  const overrideSection = entries.length === 0
+    ? ''
+    : `overrides:\n${entries.map(([name, spec]) => `  ${JSON.stringify(name)}: ${JSON.stringify(spec)}`).join('\n')}\n`
+  const coreBuildSpec = overrides[CORE_BUILD_PACKAGE]
+  const coreBuildKey = coreBuildSpec === undefined
+    ? CORE_BUILD_PACKAGE
+    : `${CORE_BUILD_PACKAGE}@${coreBuildSpec.replace('file:./', 'file:')}`
+  return `packages:\n  - .\n\n${overrideSection}${WORKSPACE_SETTINGS}allowBuilds:\n  node-pty: true\n  koffi: true\n  fs-ext: true\n  ${JSON.stringify(coreBuildKey)}: true\n  '@google/genai': false\n  protobufjs: false\n  node-addon-require-builtin: false\n`
+}
+
+function releaseFile(projectDir: string): DesktopRelease {
+  return parseDesktopRelease(readJson(join(projectDir, 'desktop-release.json')))
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+function isDescendant(root: string, target: string): boolean {
+  const child = relative(root, target)
+  return child !== '' && child !== '..' && !child.startsWith(`..${sep}`) && !isAbsolute(child)
+}
+
+function assertPackageName(name: string): void {
+  if (!PACKAGE_NAME_PATTERN.test(name)) throw new Error(`desktop project: invalid npm package name ${JSON.stringify(name)}`)
+}
+
+function assertVersion(version: string): void {
+  if (!VERSION_PATTERN.test(version)) throw new Error(`desktop project: invalid exact version ${JSON.stringify(version)}`)
+}
+
+/**
+ * Validate one registry package spec and return its requested package name when explicit.
+ * @param spec - npm registry name with an optional version or tag.
+ * @returns package name, or undefined when the spec's final name is registry-resolved.
+ */
+export function packageNameFromSpec(spec: string): string | undefined {
+  if (spec === '' || spec.startsWith('-') || /[\s\\]/u.test(spec) || spec.includes('://') || spec.startsWith('file:')) {
+    throw new Error(`desktop project: unsupported npm package spec ${JSON.stringify(spec)}`)
+  }
+  if (spec.startsWith('@')) {
+    const slash = spec.indexOf('/')
+    if (slash === -1) throw new Error(`desktop project: invalid scoped package spec ${JSON.stringify(spec)}`)
+    const versionAt = spec.indexOf('@', slash)
+    const name = versionAt === -1 ? spec : spec.slice(0, versionAt)
+    assertPackageName(name)
+    if (versionAt !== -1) assertVersion(spec.slice(versionAt + 1))
+    return name
+  }
+  const versionAt = spec.indexOf('@')
+  const name = versionAt === -1 ? spec : spec.slice(0, versionAt)
+  assertPackageName(name)
+  if (versionAt !== -1) assertVersion(spec.slice(versionAt + 1))
+  return name
+}
+
+function removeOwnedDirectory(path: string): void {
+  if (!existsSync(path)) return
+  const stat = lstatSync(path)
+  if (stat.isSymbolicLink()) {
+    unlinkSync(path)
+    return
+  }
+  if (!stat.isDirectory()) throw new Error(`desktop project: owned directory path is not a directory: ${path}`)
+  rmSync(path, { recursive: true })
+}
+
+function copyMetadata(source: string, target: string): void {
+  mkdirSync(target, { recursive: true, mode: 0o700 })
+  for (const filename of DESKTOP_PROJECT_FILES) {
+    const from = join(source, filename)
+    if (existsSync(from)) copyFileSync(from, join(target, filename), constants.COPYFILE_EXCL)
+  }
+  cpSync(join(source, DESKTOP_PACKAGES_DIR), join(target, DESKTOP_PACKAGES_DIR), {
+    recursive: true,
+    force: false,
+    errorOnExist: true,
+  })
+}
+
+function seedFiles(root: string): readonly DesktopSeedIntegrityRecord[] {
+  const files: DesktopSeedIntegrityRecord[] = []
+  const visit = (directory: string): void => {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      const path = join(directory, entry.name)
+      const relativePath = path.slice(root.length + 1).split(sep).join('/')
+      if (relativePath === 'integrity.json') continue
+      if (entry.isSymbolicLink()) throw new Error(`desktop seed: symbolic link is not allowed: ${relativePath}`)
+      if (entry.isDirectory()) {
+        visit(path)
+        continue
+      }
+      if (!entry.isFile()) throw new Error(`desktop seed: unsupported file type: ${relativePath}`)
+      const body = readFileSync(path)
+      files.push({
+        path: relativePath,
+        bytes: body.byteLength,
+        sha256: createHash('sha256').update(body).digest('hex'),
+      })
+    }
+  }
+  visit(root)
+  return files.sort((left, right) => left.path.localeCompare(right.path))
+}
+
+/** Verify the packaged offline seed before any content enters writable desktop state. */
+export function verifySeedIntegrity(seedDir: string): void {
+  const integrityPath = join(seedDir, 'integrity.json')
+  const integrity = readJson(integrityPath)
+  if (!isRecord(integrity) || integrity.schemaVersion !== 2 || !Array.isArray(integrity.files)) {
+    throw new Error(`desktop seed: invalid integrity inventory ${integrityPath}`)
+  }
+  const expected: DesktopSeedIntegrityRecord[] = integrity.files.map((record) => {
+    if (!isRecord(record) || typeof record.path !== 'string' || record.path === '' || record.path.startsWith('/')
+      || record.path.split('/').includes('..') || typeof record.bytes !== 'number'
+      || !Number.isSafeInteger(record.bytes) || record.bytes < 0
+      || typeof record.sha256 !== 'string' || !/^[a-f0-9]{64}$/u.test(record.sha256)) {
+      throw new Error(`desktop seed: invalid integrity record in ${integrityPath}`)
+    }
+    return { path: record.path, bytes: record.bytes, sha256: record.sha256 }
+  }).sort((left, right) => left.path.localeCompare(right.path))
+  const actual = seedFiles(seedDir)
+  if (JSON.stringify(actual) !== JSON.stringify(expected)) {
+    throw new Error('desktop seed: integrity verification failed')
+  }
+}
+
+function projectManifest(projectDir: string): DesktopProjectManifest {
+  const path = join(projectDir, 'package.json')
+  const value = readJson(path)
+  const dsh = isRecord(value) && isRecord(value.dsh) ? value.dsh : undefined
+  const profile = isRecord(dsh?.profile) ? dsh.profile : undefined
+  if (!isRecord(value) || value.name !== PROJECT_NAME || value.private !== true
+    || typeof value.version !== 'string' || !isRecord(value.dependencies)
+    || !Array.isArray(profile?.bundles) || !profile.bundles.every(bundle => typeof bundle === 'string')) {
+    throw new Error(`desktop project: invalid desktop profile manifest ${path}`)
+  }
+  const manifest = value as unknown as DesktopProjectManifest
+  const packageSet = readDesktopCorePackageSet(projectDir, releaseFile(projectDir).version)
+  const expectedOverrides = desktopCorePackageOverrides(packageSet)
+  if (manifest.dependencies[DSH_PACKAGE] !== desktopDshPackageSpec(packageSet)
+    || Object.entries(expectedOverrides).some(([name, spec]) => manifest.dependencies[name] !== spec)
+    || readFileSync(join(projectDir, 'pnpm-workspace.yaml'), 'utf8') !== workspaceFile(expectedOverrides)) {
+    throw new Error(`desktop project: core package mapping does not match ${DESKTOP_PACKAGE_SET_FILE}`)
+  }
+  return manifest
+}
+
+function profilePluginNames(projectDir: string): readonly string[] {
+  const bundles = projectManifest(projectDir).dsh.profile.bundles
+  if (!DESKTOP_PROFILE_BUNDLES.every((bundle, index) => bundles[index] === bundle)) {
+    throw new Error('desktop project: profile must begin with the built-in desktop bundle list')
+  }
+  const plugins = bundles.slice(DESKTOP_PROFILE_BUNDLES.length)
+  if (new Set(bundles).size !== bundles.length) {
+    throw new Error('desktop project: profile bundle list contains a duplicate package')
+  }
+  for (const plugin of plugins) assertPackageName(plugin)
+  return plugins
+}
+
+function pluginRecords(projectDir: string): readonly DesktopPluginRecord[] {
+  return profilePluginNames(projectDir).map(name => inspectPlugin(projectDir, name))
+}
+
+function writeProfilePlugins(projectDir: string, plugins: readonly DesktopPluginRecord[]): void {
+  const manifest = projectManifest(projectDir)
+  writeJson(join(projectDir, 'package.json'), {
+    ...manifest,
+    dsh: {
+      ...manifest.dsh,
+      profile: {
+        ...manifest.dsh.profile,
+        bundles: [...DESKTOP_PROFILE_BUNDLES, ...plugins.map(plugin => plugin.name)],
+      },
+    },
+  } satisfies DesktopProjectManifest)
+}
+
+function inspectPlugin(projectDir: string, requestedName: string): DesktopPluginRecord {
+  const manifestPath = join(projectDir, 'node_modules', ...requestedName.split('/'), 'package.json')
+  if (!existsSync(manifestPath)) {
+    throw new Error(`desktop project: installed package ${JSON.stringify(requestedName)} has no manifest`)
+  }
+  const manifest = readJson(manifestPath)
+  if (!isRecord(manifest) || manifest.name !== requestedName || typeof manifest.version !== 'string') {
+    throw new Error(`desktop project: installed package ${JSON.stringify(requestedName)} has inconsistent name or version`)
+  }
+  const dsh = manifest.dsh
+  const bundle = isRecord(dsh) ? dsh.bundle : undefined
+  const patch = isRecord(bundle) ? bundle.patch : undefined
+  if (typeof patch !== 'string' || patch === '') {
+    throw new Error(`desktop project: ${requestedName}@${manifest.version} does not declare dsh.bundle.patch`)
+  }
+  const packageDir = dirname(manifestPath)
+  const patchPath = resolve(packageDir, patch)
+  if ((patchPath !== packageDir && !patchPath.startsWith(packageDir + sep)) || !existsSync(patchPath)) {
+    throw new Error(`desktop project: ${requestedName}@${manifest.version} declares an invalid bundle patch`)
+  }
+  return { name: requestedName, version: manifest.version }
+}
+
+/** Transactional desktop npm project manager. */
+export class DesktopProjectManager {
+  private lockDescriptor: number | undefined
+
+  /**
+   * @param paths - Electron-owned package state and reserved desktop profile paths.
+   * @param runtime - absolute bundled Node.js and pnpm entry paths.
+   */
+  constructor(
+    readonly paths: DesktopPaths,
+    readonly runtime: DesktopRuntimeExecutables,
+  ) {}
+
+  /** Recover an interrupted directory replacement before reading the active project. */
+  recover(): void {
+    if (!existsSync(this.paths.pending)) return
+    const value = readJson(this.paths.pending)
+    if (!isRecord(value) || value.schemaVersion !== 1
+      || typeof value.id !== 'string' || typeof value.stagingProfile !== 'string'
+      || !isDescendant(this.paths.staging, value.stagingProfile)
+      || (value.step !== 'prepared' && value.step !== 'active-moved' && value.step !== 'staging-activated')) {
+      throw new Error(`desktop project: invalid activation journal ${this.paths.pending}`)
+    }
+    const pending: DesktopPendingTransaction = {
+      schemaVersion: 1,
+      id: value.id,
+      stagingProfile: value.stagingProfile,
+      step: value.step,
+    }
+    if (!existsSync(this.paths.profile) && existsSync(this.paths.rollback)) {
+      mkdirSync(dirname(this.paths.profile), { recursive: true })
+      renameSync(this.paths.rollback, this.paths.profile)
+    }
+    removeOwnedDirectory(pending.stagingProfile)
+    unlinkSync(this.paths.pending)
+  }
+
+  /** Read the active desktop plugin inventory. */
+  listPlugins(): readonly DesktopPluginRecord[] {
+    if (!existsSync(this.paths.profile)) return []
+    return pluginRecords(this.paths.profile)
+  }
+
+  /** Read the exact dsh version installed in the active desktop project. */
+  dshVersion(): string {
+    if (!existsSync(this.paths.profile)) throw new Error('desktop project: active profile is not installed')
+    return this.installedPackageVersion(DSH_PACKAGE)
+  }
+
+  private installedPackageVersion(packageName: string): string {
+    const manifestPath = join(this.paths.profile, 'node_modules', ...packageName.split('/'), 'package.json')
+    const manifest = readJson(manifestPath)
+    if (!isRecord(manifest) || typeof manifest.version !== 'string') {
+      throw new Error(`desktop project: installed ${packageName} package has no version`)
+    }
+    assertVersion(manifest.version)
+    return manifest.version
+  }
+
+  /** Read the release version applied to the active desktop project. */
+  releaseVersion(): string {
+    if (!existsSync(this.paths.profile)) throw new Error('desktop project: active profile is not installed')
+    return releaseFile(this.paths.profile).version
+  }
+
+  /** Install or reconcile the active project to the Electron package's exact release. */
+  async applyRelease(seedDir: string, electronVersion: string, hooks: DesktopProjectHooks): Promise<boolean> {
+    return this.withLock(async () => {
+      this.recover()
+      verifySeedIntegrity(seedDir)
+      const target = releaseFile(seedDir)
+      verifyDesktopCorePackageSet(seedDir, target.version)
+      if (target.version !== electronVersion) {
+        throw new Error(`desktop project: seed ${target.version} does not match Electron ${electronVersion}`)
+      }
+      if (existsSync(this.paths.profile) && this.releaseVersion() === target.version
+        && this.dshVersion() === target.version
+        && this.installedPackageVersion(DESKTOP_HOST_PACKAGE) === target.version) {
+        verifyDesktopCorePackageSet(this.paths.profile, target.version)
+        return false
+      }
+      this.mergeSeedPnpmState(seedDir)
+      const stagingProfile = this.newStagingProfile()
+      try {
+        if (existsSync(this.paths.profile)) {
+          const plugins = pluginRecords(this.paths.profile)
+          copyMetadata(seedDir, stagingProfile)
+          await this.runPnpm(stagingProfile, ['install', '--offline', '--frozen-lockfile', '--trust-lockfile'])
+          if (plugins.length > 0) {
+            await this.runPnpm(stagingProfile, [
+              'add',
+              ...plugins.map(plugin => `${plugin.name}@${plugin.version}`),
+              '--save-exact',
+              '--offline',
+            ])
+            writeProfilePlugins(stagingProfile, plugins)
+          }
+        } else {
+          copyMetadata(seedDir, stagingProfile)
+          await this.runPnpm(stagingProfile, ['install', '--offline', '--frozen-lockfile', '--trust-lockfile'])
+        }
+        await hooks.healthCheck(stagingProfile)
+        await this.activate(stagingProfile, hooks)
+        return true
+      } catch (error) {
+        removeOwnedDirectory(stagingProfile)
+        throw error
+      }
+    })
+  }
+
+  /** Apply one exact dependency mutation through a staging project. */
+  async mutate(mutation: DesktopProjectMutation, hooks: DesktopProjectHooks): Promise<void> {
+    await this.withLock(async () => {
+      this.recover()
+      if (!existsSync(this.paths.profile)) throw new Error('desktop project: active profile is not installed')
+      verifyDesktopCorePackageSet(this.paths.profile, this.releaseVersion())
+      const stagingProfile = this.newStagingProfile()
+      try {
+        copyMetadata(this.paths.profile, stagingProfile)
+        await this.applyMutation(stagingProfile, mutation)
+        await hooks.healthCheck(stagingProfile)
+        await this.activate(stagingProfile, hooks)
+      } catch (error) {
+        removeOwnedDirectory(stagingProfile)
+        throw error
+      }
+    })
+  }
+
+  private newStagingProfile(): string {
+    const path = join(this.paths.staging, randomUUID(), 'profile')
+    mkdirSync(path, { recursive: true, mode: 0o700 })
+    return path
+  }
+
+  private async applyMutation(projectDir: string, mutation: DesktopProjectMutation): Promise<void> {
+    switch (mutation.type) {
+      case 'plugin-add': {
+        const requestedName = packageNameFromSpec(mutation.spec)
+        if (requestedName === undefined) throw new Error('desktop project: plugin package name is required')
+        await this.runPnpm(projectDir, ['add', mutation.spec, '--save-exact'])
+        const installed = inspectPlugin(projectDir, requestedName)
+        const current = pluginRecords(projectDir).filter(plugin => plugin.name !== installed.name)
+        writeProfilePlugins(
+          projectDir,
+          [...current, installed].sort((left, right) => left.name.localeCompare(right.name)),
+        )
+        return
+      }
+      case 'plugin-remove': {
+        assertPackageName(mutation.name)
+        if (!profilePluginNames(projectDir).includes(mutation.name)) {
+          throw new Error(`desktop project: plugin ${JSON.stringify(mutation.name)} is not installed`)
+        }
+        const remaining = pluginRecords(projectDir).filter(plugin => plugin.name !== mutation.name)
+        await this.runPnpm(projectDir, ['remove', mutation.name])
+        writeProfilePlugins(projectDir, remaining)
+        return
+      }
+      case 'plugin-update':
+        assertPackageName(mutation.name)
+        assertVersion(mutation.version)
+        if (!profilePluginNames(projectDir).includes(mutation.name)) {
+          throw new Error(`desktop project: plugin ${JSON.stringify(mutation.name)} is not installed`)
+        }
+        await this.runPnpm(projectDir, ['add', `${mutation.name}@${mutation.version}`, '--save-exact'])
+        {
+          const installed = inspectPlugin(projectDir, mutation.name)
+          writeProfilePlugins(
+            projectDir,
+            pluginRecords(projectDir).map(plugin => plugin.name === installed.name ? installed : plugin),
+          )
+        }
+        return
+      default:
+        mutation satisfies never
+    }
+  }
+
+  private mergeSeedPnpmState(seedDir: string): void {
+    const transactionRoot = join(this.paths.staging, randomUUID())
+    const extractedStore = join(transactionRoot, 'store')
+    try {
+      extractPnpmStoreArchives(seedDir, extractedStore)
+      mergePnpmStore(extractedStore, this.paths.pnpm.store)
+    } finally {
+      removeOwnedDirectory(transactionRoot)
+    }
+  }
+
+  private async activate(stagingProfile: string, hooks: DesktopProjectHooks): Promise<void> {
+    const pending: DesktopPendingTransaction = {
+      schemaVersion: 1,
+      id: basename(dirname(stagingProfile)),
+      stagingProfile,
+      step: 'prepared',
+    }
+    writeJson(this.paths.pending, pending)
+    await hooks.beforeActivate()
+    let activeMoved = false
+    try {
+      removeOwnedDirectory(this.paths.rollback)
+      mkdirSync(dirname(this.paths.rollback), { recursive: true, mode: 0o700 })
+      writeJson(this.paths.pending, { ...pending, step: 'active-moved' } satisfies DesktopPendingTransaction)
+      if (existsSync(this.paths.profile)) {
+        renameSync(this.paths.profile, this.paths.rollback)
+        activeMoved = true
+      }
+      mkdirSync(dirname(this.paths.profile), { recursive: true, mode: 0o700 })
+      writeJson(this.paths.pending, { ...pending, step: 'staging-activated' } satisfies DesktopPendingTransaction)
+      renameSync(stagingProfile, this.paths.profile)
+      await hooks.afterActivate()
+      unlinkSync(this.paths.pending)
+    } catch (error) {
+      if (existsSync(this.paths.profile)) removeOwnedDirectory(this.paths.profile)
+      if (activeMoved && existsSync(this.paths.rollback)) renameSync(this.paths.rollback, this.paths.profile)
+      if (existsSync(this.paths.pending)) unlinkSync(this.paths.pending)
+      await hooks.afterActivate().catch(() => undefined)
+      throw error
+    }
+  }
+
+  private async runPnpm(projectDir: string, args: readonly string[]): Promise<void> {
+    const [command, ...commandArgs] = args
+    if (command === undefined) throw new Error('desktop project: pnpm command is required')
+    for (const path of [this.paths.root, this.paths.pnpm.store, this.paths.pnpm.cache,
+      this.paths.pnpm.state, this.paths.pnpm.config, this.paths.pnpm.home]) {
+      mkdirSync(path, { recursive: true, mode: 0o700 })
+    }
+    const npmrc = join(this.paths.pnpm.config, 'npmrc')
+    if (!existsSync(npmrc)) writeFileSync(npmrc, '', { mode: 0o600 })
+    const inherited = Object.fromEntries(Object.entries(process.env).filter(([name]) => (
+      !/^DSH_DESKTOP_/u.test(name) && !/^(?:npm|pnpm|corepack)_/iu.test(name)
+    )))
+    await new Promise<void>((settle, reject) => {
+      const child = spawn(this.runtime.node, [
+        this.runtime.pnpm,
+        `--config.registry=${DESKTOP_REGISTRY}`,
+        `--config.store-dir=${this.paths.pnpm.store}`,
+        '--config.enable-global-virtual-store=false',
+        `--config.userconfig=${npmrc}`,
+        command,
+        ...commandArgs,
+      ], {
+        cwd: projectDir,
+        env: {
+          ...inherited,
+          COREPACK_HOME: this.paths.pnpm.home,
+          NPM_CONFIG_REGISTRY: DESKTOP_REGISTRY,
+          NPM_CONFIG_STORE_DIR: this.paths.pnpm.store,
+          NPM_CONFIG_USERCONFIG: npmrc,
+          PATH: `${dirname(this.runtime.node)}${delimiter}${process.env.PATH ?? ''}`,
+          PNPM_HOME: this.paths.pnpm.home,
+          XDG_CACHE_HOME: this.paths.pnpm.cache,
+          XDG_CONFIG_HOME: this.paths.pnpm.config,
+          XDG_STATE_HOME: this.paths.pnpm.state,
+        },
+        stdio: ['ignore', 'pipe', 'pipe'],
+      })
+      const childPid = child.pid
+      if (childPid === undefined) {
+        child.kill('SIGKILL')
+        reject(new Error('desktop project: pnpm did not report a process id'))
+        return
+      }
+      try {
+        this.writeLockOwner(childPid)
+      } catch (error) {
+        child.kill('SIGKILL')
+        reject(errorOf(error, 'desktop project: failed to assign the package transaction lock to pnpm'))
+        return
+      }
+      let diagnostics = ''
+      let completed = false
+      const appendDiagnostics = (chunk: string): void => {
+        diagnostics = (diagnostics + chunk).slice(-MAX_PNPM_DIAGNOSTIC_BYTES)
+      }
+      child.stdout.setEncoding('utf8')
+      child.stdout.on('data', appendDiagnostics)
+      child.stderr.setEncoding('utf8')
+      child.stderr.on('data', appendDiagnostics)
+      const complete = (settleChild: () => void): void => {
+        if (completed) return
+        completed = true
+        try {
+          this.writeLockOwner(process.pid)
+        } catch (error) {
+          reject(errorOf(error, 'desktop project: failed to return the package transaction lock to Electron'))
+          return
+        }
+        settleChild()
+      }
+      child.once('error', (error) => { complete(() => { reject(error) }) })
+      child.once('close', (code, signal) => {
+        complete(() => {
+          if (code === 0) {
+            settle()
+            return
+          }
+          reject(new Error(
+            `desktop project: pnpm exited with ${String(code ?? signal)}${diagnostics.trim() === '' ? '' : `: ${diagnostics.trim()}`}`,
+          ))
+        })
+      })
+    })
+  }
+
+  private writeLockOwner(pid: number): void {
+    const descriptor = this.lockDescriptor
+    if (descriptor === undefined) throw new Error('desktop project: package transaction lost its lock')
+    const content = Buffer.from(`${String(pid)}\n`)
+    ftruncateSync(descriptor, 0)
+    writeSync(descriptor, content, 0, content.byteLength, 0)
+    fsyncSync(descriptor)
+  }
+
+  private async withLock<T>(operation: () => Promise<T>): Promise<T> {
+    mkdirSync(this.paths.root, { recursive: true, mode: 0o700 })
+    let descriptor: number
+    try {
+      descriptor = openSync(this.paths.lock, 'wx', 0o600)
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'EEXIST') {
+        const lock = lstatSync(this.paths.lock)
+        if (lock.isSymbolicLink() || !lock.isFile()) {
+          throw new Error('desktop project: package transaction lock is not a regular file')
+        }
+        const owner = Number.parseInt(readFileSync(this.paths.lock, 'utf8').trim(), 10)
+        let active = !Number.isSafeInteger(owner) || owner <= 0
+        if (!active) {
+          try {
+            process.kill(owner, 0)
+            active = true
+          } catch (signalError) {
+            active = (signalError as NodeJS.ErrnoException).code !== 'ESRCH'
+          }
+        }
+        if (active) throw new Error('desktop project: another package transaction is active')
+        unlinkSync(this.paths.lock)
+        descriptor = openSync(this.paths.lock, 'wx', 0o600)
+      } else {
+        throw error
+      }
+    }
+    try {
+      this.lockDescriptor = descriptor
+      this.writeLockOwner(process.pid)
+      return await operation()
+    } finally {
+      this.lockDescriptor = undefined
+      closeSync(descriptor)
+      unlinkSync(this.paths.lock)
+    }
+  }
+}
+
+/** Create seed metadata for one exact Electron and dsh release. */
+export function createSeedMetadata(seedDir: string, release: DesktopRelease): void {
+  mkdirSync(seedDir, { recursive: true, mode: 0o700 })
+  const packageSet = verifyDesktopCorePackageSet(seedDir, release.version)
+  const manifest: DesktopProjectManifest = {
+    name: PROJECT_NAME,
+    private: true,
+    version: '0.0.0',
+    dependencies: desktopCorePackageOverrides(packageSet),
+    dsh: { profile: { bundles: [...DESKTOP_PROFILE_BUNDLES] } },
+  }
+  writeJson(join(seedDir, 'package.json'), manifest)
+  writeFileSync(
+    join(seedDir, 'pnpm-workspace.yaml'),
+    workspaceFile(desktopCorePackageOverrides(packageSet)),
+    { mode: 0o600 },
+  )
+  writeJson(join(seedDir, 'desktop-release.json'), release)
+}
+
+/**
+ * Create metadata for the unpackaged development project that links the current workspace.
+ * @param projectDir - Disposable development profile directory.
+ * @param release - Release identity shared by the linked CLI package and Electron shell.
+ */
+export function createDevelopmentProjectMetadata(projectDir: string, release: DesktopRelease): void {
+  mkdirSync(projectDir, { recursive: true, mode: 0o700 })
+  const manifest = {
+    name: PROJECT_NAME,
+    private: true,
+    version: '0.0.0',
+    dependencies: {
+      [DSH_PACKAGE]: release.version,
+      [DESKTOP_HOST_PACKAGE]: release.version,
+    },
+    dsh: { profile: { bundles: [...DESKTOP_PROFILE_BUNDLES] } },
+  }
+  writeJson(join(projectDir, 'package.json'), manifest)
+  writeFileSync(join(projectDir, 'pnpm-workspace.yaml'), workspaceFile(), { mode: 0o600 })
+  writeJson(join(projectDir, 'desktop-release.json'), release)
+}

apps/desktop/src/release.ts

@@ -0,0 +1,35 @@
+/** Immutable version identity shared by one Electron shell and its dsh seed. */
+
+import { valid } from 'semver'
+import { DESKTOP_HOST_PROTOCOL_VERSION } from './host-protocol.ts'
+
+/** Release facts embedded in the seed and copied into the active desktop project. */
+export interface DesktopRelease {
+  readonly schemaVersion: 1
+  /** Exact version used by both Electron and `@deepseek-ai/dsh`. */
+  readonly version: string
+  readonly hostProtocolVersion: typeof DESKTOP_HOST_PROTOCOL_VERSION
+  readonly nodeVersion: string
+  readonly pnpmVersion: string
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null
+}
+
+/** Validate release data read from an installed or packaged filesystem resource. */
+export function parseDesktopRelease(value: unknown): DesktopRelease {
+  if (!isRecord(value) || value.schemaVersion !== 1 || typeof value.version !== 'string'
+    || valid(value.version) === null || value.hostProtocolVersion !== DESKTOP_HOST_PROTOCOL_VERSION
+    || typeof value.nodeVersion !== 'string' || valid(value.nodeVersion) === null
+    || typeof value.pnpmVersion !== 'string' || valid(value.pnpmVersion) === null) {
+    throw new Error('dsh desktop: invalid desktop release metadata')
+  }
+  return {
+    schemaVersion: 1,
+    version: value.version,
+    hostProtocolVersion: DESKTOP_HOST_PROTOCOL_VERSION,
+    nodeVersion: value.nodeVersion,
+    pnpmVersion: value.pnpmVersion,
+  }
+}

apps/desktop/src/seed-store.ts

@@ -0,0 +1,271 @@
+/** Deterministic archive transport for the desktop seed's pnpm store. */
+
+import { createHash } from 'node:crypto'
+import {
+  chmodSync,
+  copyFileSync,
+  cpSync,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs'
+import { join, relative, sep } from 'node:path'
+import { DatabaseSync } from 'node:sqlite'
+import { create, extract, list } from 'tar'
+
+/** Directory containing the seed's uncompressed pnpm store archives. */
+export const SEED_STORE_ARCHIVE_DIR = 'store-archives'
+
+/** Manifest describing the deterministic pnpm store archive set. */
+export const SEED_STORE_ARCHIVE_MANIFEST = 'store-archives.json'
+
+const DEFAULT_SHARD_COUNT = 16
+const ARCHIVE_NAME_PATTERN = /^store-[0-9a-f]{2}\.tar$/u
+const STORE_VERSION_PATTERN = /^v\d+$/u
+
+interface SeedStoreArchiveRecord {
+  readonly file: string
+  readonly entries: number
+}
+
+interface SeedStoreArchiveManifest {
+  readonly schemaVersion: 1
+  readonly shardCount: number
+  readonly archives: readonly SeedStoreArchiveRecord[]
+}
+
+function storeFiles(storeRoot: string): readonly string[] {
+  const files: string[] = []
+  const visit = (directory: string): void => {
+    for (const entry of readdirSync(directory, { withFileTypes: true })) {
+      const path = join(directory, entry.name)
+      if (entry.isSymbolicLink()) {
+        throw new Error(`desktop seed: pnpm store contains a symbolic link: ${relative(storeRoot, path)}`)
+      }
+      if (entry.isDirectory()) {
+        visit(path)
+        continue
+      }
+      if (!entry.isFile()) {
+        throw new Error(`desktop seed: pnpm store contains an unsupported file: ${relative(storeRoot, path)}`)
+      }
+      files.push(relative(storeRoot, path).split(sep).join('/'))
+    }
+  }
+  visit(storeRoot)
+  return files.sort((left, right) => left.localeCompare(right))
+}
+
+function shardFor(path: string, shardCount: number): number {
+  return createHash('sha256').update(path).digest().readUInt32BE(0) % shardCount
+}
+
+function readArchiveManifest(seedRoot: string): SeedStoreArchiveManifest {
+  const path = join(seedRoot, SEED_STORE_ARCHIVE_MANIFEST)
+  const value = JSON.parse(readFileSync(path, 'utf8')) as unknown
+  if (typeof value !== 'object' || value === null) {
+    throw new Error(`desktop seed: invalid pnpm store archive manifest ${path}`)
+  }
+  const candidate = value as Record<string, unknown>
+  if (candidate.schemaVersion !== 1 || !Number.isSafeInteger(candidate.shardCount)
+    || (candidate.shardCount as number) < 1 || (candidate.shardCount as number) > 256
+    || !Array.isArray(candidate.archives) || candidate.archives.length === 0) {
+    throw new Error(`desktop seed: invalid pnpm store archive manifest ${path}`)
+  }
+  const names = new Set<string>()
+  const archives = candidate.archives.map((entry): SeedStoreArchiveRecord => {
+    if (typeof entry !== 'object' || entry === null) {
+      throw new Error(`desktop seed: invalid pnpm store archive record in ${path}`)
+    }
+    const record = entry as Record<string, unknown>
+    if (typeof record.file !== 'string' || !ARCHIVE_NAME_PATTERN.test(record.file)
+      || names.has(record.file) || !Number.isSafeInteger(record.entries) || (record.entries as number) < 1) {
+      throw new Error(`desktop seed: invalid pnpm store archive record in ${path}`)
+    }
+    const shard = Number.parseInt(record.file.slice('store-'.length, -'.tar'.length), 16)
+    if (shard >= (candidate.shardCount as number)) {
+      throw new Error(`desktop seed: pnpm store archive shard is outside the manifest range in ${path}`)
+    }
+    names.add(record.file)
+    return { file: record.file, entries: record.entries as number }
+  })
+  return {
+    schemaVersion: 1,
+    shardCount: candidate.shardCount as number,
+    archives,
+  }
+}
+
+function assertArchivePath(path: string): void {
+  if (path === '' || path.startsWith('/') || path.includes('\\') || path.includes('\0')
+    || path.split('/').some(part => part === '' || part === '.' || part === '..')) {
+    throw new Error(`desktop seed: unsafe pnpm store archive path ${JSON.stringify(path)}`)
+  }
+}
+
+/**
+ * Remove pnpm's registrations for projects that populated the seed store.
+ * @param storeRoot - pnpm store directory included in the desktop seed.
+ */
+export function removePnpmProjectRegistrations(storeRoot: string): void {
+  for (const entry of readdirSync(storeRoot, { withFileTypes: true })) {
+    if (!entry.isDirectory() || !/^v\d+$/u.test(entry.name)) continue
+    rmSync(join(storeRoot, entry.name, 'projects'), { recursive: true, force: true })
+  }
+}
+
+function mergeStoreIndex(source: string, destination: string): void {
+  if (!existsSync(destination)) {
+    copyFileSync(source, destination)
+    return
+  }
+  const database = new DatabaseSync(destination)
+  let attached = false
+  try {
+    database.exec('PRAGMA busy_timeout=5000')
+    database.prepare('ATTACH DATABASE ? AS seed').run(source)
+    attached = true
+    database.exec('BEGIN IMMEDIATE')
+    let committed = false
+    try {
+      database.exec('INSERT OR REPLACE INTO package_index (key, data) SELECT key, data FROM seed.package_index')
+      database.exec('COMMIT')
+      committed = true
+    } finally {
+      if (!committed) database.exec('ROLLBACK')
+    }
+  } finally {
+    if (attached) database.exec('DETACH DATABASE seed')
+    database.close()
+  }
+}
+
+/**
+ * Merge a completely extracted seed store into Desktop's persistent pnpm store.
+ * @param source - Verified temporary store extraction.
+ * @param destination - Desktop-owned persistent pnpm store.
+ */
+export function mergePnpmStore(source: string, destination: string): void {
+  mkdirSync(destination, { recursive: true, mode: 0o700 })
+  const indexPaths = readdirSync(source, { withFileTypes: true })
+    .filter(entry => entry.isDirectory() && STORE_VERSION_PATTERN.test(entry.name)
+      && existsSync(join(source, entry.name, 'index.db')))
+    .map(entry => `${entry.name}/index.db`)
+  const indexes = new Set(indexPaths)
+  cpSync(source, destination, {
+    recursive: true,
+    force: true,
+    filter: path => !indexes.has(relative(source, path).split(sep).join('/')),
+  })
+  for (const path of indexPaths) {
+    mergeStoreIndex(join(source, ...path.split('/')), join(destination, ...path.split('/')))
+  }
+}
+
+/**
+ * Replace a prepared loose pnpm store with deterministic uncompressed archive shards.
+ * @param seedRoot - seed directory that owns the archive output.
+ * @param storeRoot - populated pnpm store to archive and remove after success.
+ * @param shardCount - stable shard count used to limit update churn.
+ */
+export function archivePnpmStore(
+  seedRoot: string,
+  storeRoot: string,
+  shardCount = DEFAULT_SHARD_COUNT,
+): void {
+  if (!Number.isSafeInteger(shardCount) || shardCount < 1 || shardCount > 256) {
+    throw new Error(`desktop seed: invalid pnpm store shard count ${shardCount}`)
+  }
+  const archiveRoot = join(seedRoot, SEED_STORE_ARCHIVE_DIR)
+  const manifestPath = join(seedRoot, SEED_STORE_ARCHIVE_MANIFEST)
+  rmSync(archiveRoot, { recursive: true, force: true })
+  rmSync(manifestPath, { force: true })
+  mkdirSync(archiveRoot, { recursive: true })
+  const shards = Array.from({ length: shardCount }, (): string[] => [])
+  for (const path of storeFiles(storeRoot)) (shards[shardFor(path, shardCount)] as string[]).push(path)
+  const archives: SeedStoreArchiveRecord[] = []
+  for (const [index, paths] of shards.entries()) {
+    if (paths.length === 0) continue
+    const file = `store-${index.toString(16).padStart(2, '0')}.tar`
+    create({
+      cwd: storeRoot,
+      file: join(archiveRoot, file),
+      noDirRecurse: true,
+      noMtime: true,
+      portable: true,
+      sync: true,
+    }, paths)
+    chmodSync(join(archiveRoot, file), 0o644)
+    archives.push({ file, entries: paths.length })
+  }
+  if (archives.length === 0) throw new Error('desktop seed: pnpm store is empty')
+  writeFileSync(manifestPath, `${JSON.stringify({ schemaVersion: 1, shardCount, archives }, undefined, 2)}\n`)
+  rmSync(storeRoot, { recursive: true })
+}
+
+/**
+ * Validate and extract a packaged pnpm store archive set into an empty directory.
+ * @param seedRoot - verified packaged seed directory.
+ * @param destination - empty Desktop-owned temporary extraction directory.
+ */
+export function extractPnpmStoreArchives(seedRoot: string, destination: string): void {
+  const manifest = readArchiveManifest(seedRoot)
+  const archiveRoot = join(seedRoot, SEED_STORE_ARCHIVE_DIR)
+  const actualFiles = readdirSync(archiveRoot, { withFileTypes: true }).map((entry) => {
+    if (!entry.isFile() || entry.isSymbolicLink()) {
+      throw new Error(`desktop seed: invalid pnpm store archive entry ${entry.name}`)
+    }
+    return entry.name
+  }).sort()
+  const expectedFiles = manifest.archives.map(archive => archive.file).sort()
+  if (JSON.stringify(actualFiles) !== JSON.stringify(expectedFiles)) {
+    throw new Error('desktop seed: pnpm store archive set does not match its manifest')
+  }
+  if (existsSync(destination) && readdirSync(destination).length !== 0) {
+    throw new Error(`desktop seed: pnpm store extraction directory is not empty: ${destination}`)
+  }
+  mkdirSync(destination, { recursive: true, mode: 0o700 })
+  const paths = new Set<string>()
+  for (const archive of manifest.archives) {
+    const archivePath = join(archiveRoot, archive.file)
+    const archiveShard = Number.parseInt(archive.file.slice('store-'.length, -'.tar'.length), 16)
+    let entries = 0
+    list({
+      file: archivePath,
+      onReadEntry: (entry) => {
+        if (entry.type !== 'File' && entry.type !== 'OldFile') {
+          throw new Error(`desktop seed: unsupported pnpm store archive entry type ${entry.type}`)
+        }
+        assertArchivePath(entry.path)
+        if (shardFor(entry.path, manifest.shardCount) !== archiveShard) {
+          throw new Error(`desktop seed: pnpm store path is assigned to the wrong archive shard: ${entry.path}`)
+        }
+        if (paths.has(entry.path)) {
+          throw new Error(`desktop seed: duplicate pnpm store archive path ${entry.path}`)
+        }
+        paths.add(entry.path)
+        entries += 1
+      },
+      strict: true,
+      sync: true,
+    })
+    if (entries !== archive.entries) {
+      throw new Error(`desktop seed: pnpm store archive ${archive.file} has an unexpected entry count`)
+    }
+  }
+  for (const archive of manifest.archives) {
+    extract({
+      chmod: true,
+      cwd: destination,
+      file: join(archiveRoot, archive.file),
+      noMtime: true,
+      preservePaths: false,
+      processUmask: 0,
+      strict: true,
+      sync: true,
+    })
+  }
+}

apps/desktop/src/single-instance.ts

@@ -0,0 +1,26 @@
+/** Electron single-instance ownership before any Desktop profile lifecycle begins. */
+
+/** Minimal Electron application operations needed for instance ownership. */
+export interface DesktopSingleInstanceApplication {
+  requestSingleInstanceLock(): boolean
+  quit(): void
+  on(event: 'second-instance', listener: () => void): unknown
+}
+
+/**
+ * Claim the process-lifetime Desktop lock and route later launches to the owner.
+ * @param application - Electron application singleton.
+ * @param focusOwner - focus or recreate the primary window after a later launch.
+ * @returns true only in the process that may access the Desktop profile.
+ */
+export function claimDesktopSingleInstance(
+  application: DesktopSingleInstanceApplication,
+  focusOwner: () => void,
+): boolean {
+  if (!application.requestSingleInstanceLock()) {
+    application.quit()
+    return false
+  }
+  application.on('second-instance', focusOwner)
+  return true
+}